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 site is not monolithic
* it must fit neatlessly into the Isabelle distribution and regression framework
(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 your changes
* just type make - the website is builded to the website synchronization cache
* for sure, check groups (isabelle) and permissions (rw-/rwx)
* 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