Admin/website/README

support for setting local permissions

+
−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 "make perms" to set file owner group (isabelle) and permissions
+
−  (rw-rw-r--, rwxrwsr-x)
+
−* do your changes
+
−* just type make - the website is builded 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