Admin/website/README

fixed some inconveniencies in website

The Isabelle Webpage
====================

(1) philosophy
==============

The webpage sources consist of three different layers:

a) the presentation layer
-------------------------

This is was the user actually sees; the slogan is

    "structural XHTML plus CSS"

There are three different groups of end-user agents (browsers)

 1) "practical non-CSS" browsers (lynx, netscape4)
    These just display plain HTML.
 2) "more-or-less-w3c-CSS" browsers (KHTML/Konqueror/Safari, Internet Explorer)
    These are able to display the pages almost as they should be,
    but perhaps with some minor warts.
 3) "almost-w3-CSS" browsers (Mozilla/Firefox/Galeone)
    These are the "reference implementation" for the layout.

b) the project layer
--------------------

This manages the dependencies between files; the tool of choice
is

    "make plus shell scripting"

Project settings may be configured using a seperate configuration
file.

c) the preprocessing layer
--------------------------

This allows to use things like includes, current date, and so on:

    "XHTML plus processing instructions"

Note that this is almost not interwoven with b), to keep it as robust
and simple as possible.

The layer itself is implemented by a small tool "pypager", written in python.


(2) writing your own pages
==========================

You may add arbitrary files to the dir structure, but adhere to the following:
* use XHTML, not loose HTML
* only structural markup; if you need layout effects, use CSS
  (browse the exiting files to get some inspirations)
* any files ending with .html are considered as HTML files and are implicitly
  processed by the preprocessing layer
* for HTML includes, it is most convenient to name them *.include.html to
  avoid them to be processed stand-alone by the preprocessing layer
* whole dirs maybe selected for statically copying them to the
  target destination by configuring the project layer
* for attributes etc. referencing file locations, there is a convenient
  abbreviation: "//" at the beginning of a path is translated to the root,
  but expressed relatively to the current location, e. g.

  in abc/def/itsme.html: <a href="//abc/ghi/itsyou.html">
                becomes: <a href="../def/itsyou.html">

  Further, targets are checked for existance.
  This is a simple yet powerful thing easing to keep the pages consistent.
* for the semantics of the processing instructions, see build/pypager.py
  source code


(3) using the project layer framework
=====================================

To configure it the first time after checkout, just type
> make phase=init

Then, you may edit the project configuration file conf/localconf.mak.
After a correct configuration, the build process may be started by
> make

The project layer tries to be smart about dependencies, but includes,
embedded images and so on are not tracked; to built dependencies anew,
do
> make depends

After adding or deleting files, an
> make depends
may also be neccessary. The same after changing something in the configuration.

If nothing seems to be sensible any more, try
> make clean
> make depends
> make


(4) project-specific remarks
============================

The whole thing should fit neatlessly into the Isabelle distribution and
regression framework; this may explain some "features" which seem to be
enigmatic.


(5) the website build bed on sunbroy2
=====================================

For convenience, there is a completely configured
website build bed on sunbroy2:
* log in to sunbroy2
* go to ~/isabelle/website_build
* there do an CVS update if desired
* do "make perms" to set file owner group (isabelle) and permissions
  (rw-rw-r--, rwxrwsr-x)
* do your changes
* just type make - the website is built to the website synchronization cache
* then do CVS commit
* for updating the webpage in Munich, just use Admin/mirror-website
* if the Isabelle distribution files themselves change, some handwired updating
  is neceassary; however, for casual content changes the build bed should work
  properly