Admin/website/README
author wenzelm
Wed, 15 Feb 2006 21:34:55 +0100
changeset 19046 bc5c6c9b114e
parent 18214 857444b28267
child 19094 968e95fdbf8a
permissions -rw-r--r--
removed distinct, renamed gen_distinct to distinct;
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
16572
81778a796290 some corrections
haftmann
parents: 16312
diff changeset
     1
The Isabelle Webpage
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
     2
====================
e634d33deb86 added new website
haftmann
parents:
diff changeset
     3
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
     4
(1) philosophy
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
     5
==============
e634d33deb86 added new website
haftmann
parents:
diff changeset
     6
16952
9ce755a0d613 corrected some typos
haftmann
parents: 16572
diff changeset
     7
The webpage sources consist of three different layers:
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
     8
e634d33deb86 added new website
haftmann
parents:
diff changeset
     9
a) the presentation layer
e634d33deb86 added new website
haftmann
parents:
diff changeset
    10
-------------------------
e634d33deb86 added new website
haftmann
parents:
diff changeset
    11
e634d33deb86 added new website
haftmann
parents:
diff changeset
    12
This is was the user actually sees; the slogan is
e634d33deb86 added new website
haftmann
parents:
diff changeset
    13
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    14
    "structural XHTML plus CSS"
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    15
e634d33deb86 added new website
haftmann
parents:
diff changeset
    16
There are three different groups of end-user agents (browsers)
e634d33deb86 added new website
haftmann
parents:
diff changeset
    17
e634d33deb86 added new website
haftmann
parents:
diff changeset
    18
 1) "practical non-CSS" browsers (lynx, netscape4)
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    19
    These just display plain HTML.
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    20
 2) "more-or-less-w3c-CSS" browsers (KHTML/Konqueror/Safari, Internet Explorer)
e634d33deb86 added new website
haftmann
parents:
diff changeset
    21
    These are able to display the pages almost as they should be,
e634d33deb86 added new website
haftmann
parents:
diff changeset
    22
    but perhaps with some minor warts.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    23
 3) "almost-w3-CSS" browsers (Mozilla/Firefox/Galeone)
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    24
    These are the "reference implementation" for the layout.
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    25
e634d33deb86 added new website
haftmann
parents:
diff changeset
    26
b) the project layer
e634d33deb86 added new website
haftmann
parents:
diff changeset
    27
--------------------
e634d33deb86 added new website
haftmann
parents:
diff changeset
    28
e634d33deb86 added new website
haftmann
parents:
diff changeset
    29
This manages the dependencies between files; the tool of choice
e634d33deb86 added new website
haftmann
parents:
diff changeset
    30
is
e634d33deb86 added new website
haftmann
parents:
diff changeset
    31
e634d33deb86 added new website
haftmann
parents:
diff changeset
    32
    "make plus shell scripting"
e634d33deb86 added new website
haftmann
parents:
diff changeset
    33
e634d33deb86 added new website
haftmann
parents:
diff changeset
    34
Project settings may be configured using a seperate configuration
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    35
file.
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    36
e634d33deb86 added new website
haftmann
parents:
diff changeset
    37
c) the preprocessing layer
e634d33deb86 added new website
haftmann
parents:
diff changeset
    38
--------------------------
e634d33deb86 added new website
haftmann
parents:
diff changeset
    39
16952
9ce755a0d613 corrected some typos
haftmann
parents: 16572
diff changeset
    40
This allows to use things like includes, current date, and so on:
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    41
e634d33deb86 added new website
haftmann
parents:
diff changeset
    42
    "XHTML plus processing instructions"
e634d33deb86 added new website
haftmann
parents:
diff changeset
    43
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    44
Note that this is almost not interwoven with b), to keep it as robust
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    45
and simple as possible.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    46
e634d33deb86 added new website
haftmann
parents:
diff changeset
    47
The layer itself is implemented by a small tool "pypager", written in python.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    48
e634d33deb86 added new website
haftmann
parents:
diff changeset
    49
e634d33deb86 added new website
haftmann
parents:
diff changeset
    50
(2) writing your own pages
e634d33deb86 added new website
haftmann
parents:
diff changeset
    51
==========================
e634d33deb86 added new website
haftmann
parents:
diff changeset
    52
e634d33deb86 added new website
haftmann
parents:
diff changeset
    53
You may add arbitrary files to the dir structure, but adhere to the following:
e634d33deb86 added new website
haftmann
parents:
diff changeset
    54
* use XHTML, not loose HTML
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    55
* only structural markup; if you need layout effects, use CSS
16952
9ce755a0d613 corrected some typos
haftmann
parents: 16572
diff changeset
    56
  (browse the exiting files to get some inspirations)
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    57
* any files ending with .html are considered as HTML files and are implicitly
e634d33deb86 added new website
haftmann
parents:
diff changeset
    58
  processed by the preprocessing layer
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    59
* for HTML includes, it is most convenient to name them *.include.html to
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    60
  avoid them to be processed stand-alone by the preprocessing layer
16572
81778a796290 some corrections
haftmann
parents: 16312
diff changeset
    61
* whole dirs maybe selected for statically copying them to the
81778a796290 some corrections
haftmann
parents: 16312
diff changeset
    62
  target destination by configuring the project layer
16249
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    63
* for attributes etc. referencing file locations, there is a convenient
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    64
  abbreviation: "//" at the beginning of a path is translated to the root,
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    65
  but expressed relatively to the current location, e. g.
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    66
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    67
  in abc/def/itsme.html: <a href="//abc/ghi/itsyou.html">
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    68
                becomes: <a href="../def/itsyou.html">
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    69
16952
9ce755a0d613 corrected some typos
haftmann
parents: 16572
diff changeset
    70
  Further, targets are checked for existance.
16572
81778a796290 some corrections
haftmann
parents: 16312
diff changeset
    71
  This is a simple yet powerful thing easing to keep the pages consistent.
16312
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    72
* for the semantics of the processing instructions, see build/pypager.py
d13addf9101e extended readme
haftmann
parents: 16249
diff changeset
    73
  source code
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    74
16572
81778a796290 some corrections
haftmann
parents: 16312
diff changeset
    75
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    76
(3) using the project layer framework
e634d33deb86 added new website
haftmann
parents:
diff changeset
    77
=====================================
e634d33deb86 added new website
haftmann
parents:
diff changeset
    78
e634d33deb86 added new website
haftmann
parents:
diff changeset
    79
To configure it the first time after checkout, just type
e634d33deb86 added new website
haftmann
parents:
diff changeset
    80
> make phase=init
e634d33deb86 added new website
haftmann
parents:
diff changeset
    81
e634d33deb86 added new website
haftmann
parents:
diff changeset
    82
Then, you may edit the project configuration file conf/localconf.mak.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    83
After a correct configuration, the build process may be started by
e634d33deb86 added new website
haftmann
parents:
diff changeset
    84
> make
e634d33deb86 added new website
haftmann
parents:
diff changeset
    85
16952
9ce755a0d613 corrected some typos
haftmann
parents: 16572
diff changeset
    86
The project layer tries to be smart about dependencies, but includes,
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    87
embedded images and so on are not tracked; to built dependencies anew,
e634d33deb86 added new website
haftmann
parents:
diff changeset
    88
do
e634d33deb86 added new website
haftmann
parents:
diff changeset
    89
> make depends
e634d33deb86 added new website
haftmann
parents:
diff changeset
    90
e634d33deb86 added new website
haftmann
parents:
diff changeset
    91
After adding or deleting files, an
e634d33deb86 added new website
haftmann
parents:
diff changeset
    92
> make depends
e634d33deb86 added new website
haftmann
parents:
diff changeset
    93
may also be neccessary. The same after changing something in the configuration.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    94
e634d33deb86 added new website
haftmann
parents:
diff changeset
    95
If nothing seems to be sensible any more, try
e634d33deb86 added new website
haftmann
parents:
diff changeset
    96
> make clean
e634d33deb86 added new website
haftmann
parents:
diff changeset
    97
> make depends
e634d33deb86 added new website
haftmann
parents:
diff changeset
    98
> make
e634d33deb86 added new website
haftmann
parents:
diff changeset
    99
e634d33deb86 added new website
haftmann
parents:
diff changeset
   100
e634d33deb86 added new website
haftmann
parents:
diff changeset
   101
(4) project-specific remarks
e634d33deb86 added new website
haftmann
parents:
diff changeset
   102
============================
e634d33deb86 added new website
haftmann
parents:
diff changeset
   103
17944
f5ff234ce6b3 towards an improved website/makedist integration
haftmann
parents: 17743
diff changeset
   104
The whole thing should fit neatlessly into the Isabelle distribution and
f5ff234ce6b3 towards an improved website/makedist integration
haftmann
parents: 17743
diff changeset
   105
regression framework; this may explain some "features" which seem to be
f5ff234ce6b3 towards an improved website/makedist integration
haftmann
parents: 17743
diff changeset
   106
enigmatic.
17681
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   107
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   108
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   109
(5) the website build bed on sunbroy2
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   110
=====================================
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   111
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   112
For convenience, there is a completely configured
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   113
website build bed on sunbroy2:
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   114
* log in to sunbroy2
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   115
* go to ~/isabelle/website_build
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   116
* there do an CVS update if desired
17743
f546af04142a support for setting local permissions
haftmann
parents: 17682
diff changeset
   117
* do "make perms" to set file owner group (isabelle) and permissions
f546af04142a support for setting local permissions
haftmann
parents: 17682
diff changeset
   118
  (rw-rw-r--, rwxrwsr-x)
17681
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   119
* do your changes
18214
857444b28267 fixed some inconveniencies in website
haftmann
parents: 17944
diff changeset
   120
* just type make - the website is built to the website synchronization cache
17681
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   121
* then do CVS commit
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   122
* for updating the webpage in Munich, just use Admin/mirror-website
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   123
* if the Isabelle distribution files themselves change, some handwired updating
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   124
  is neceassary; however, for casual content changes the build bed should work
442e7bec1d49 build bed
haftmann
parents: 16952
diff changeset
   125
  properly