Admin/website/README
author haftmann
Mon, 06 Jun 2005 14:12:07 +0200
changeset 16301 f9f2e1643593
parent 16249 7fefdd1a40a2
child 16312 d13addf9101e
permissions -rw-r--r--
migrated scripts to new webiste
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
     1
The Isabelle webpage
e634d33deb86 added new website
haftmann
parents:
diff changeset
     2
====================
e634d33deb86 added new website
haftmann
parents:
diff changeset
     3
e634d33deb86 added new website
haftmann
parents:
diff changeset
     4
(1) Philosophy
e634d33deb86 added new website
haftmann
parents:
diff changeset
     5
==============
e634d33deb86 added new website
haftmann
parents:
diff changeset
     6
e634d33deb86 added new website
haftmann
parents:
diff changeset
     7
The webpage sources consists of three differnt layers:
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
e634d33deb86 added new website
haftmann
parents:
diff changeset
    14
    "structural XHTML plus with CSS"
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)
e634d33deb86 added new website
haftmann
parents:
diff changeset
    19
    These just display plain HTML
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)
e634d33deb86 added new website
haftmann
parents:
diff changeset
    24
    These are the "reference implementation" for the layout
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
e634d33deb86 added new website
haftmann
parents:
diff changeset
    35
file
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
e634d33deb86 added new website
haftmann
parents:
diff changeset
    40
This allows to use things like includes, current date and so on:
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
e634d33deb86 added new website
haftmann
parents:
diff changeset
    44
Note that this is almosz not interwoven with b), to keep it as robust
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
e634d33deb86 added new website
haftmann
parents:
diff changeset
    55
* no structural markup; of you need layout effects, use CSS
e634d33deb86 added new website
haftmann
parents:
diff changeset
    56
* any files ending with .html are considered as HTML files and are implicitly
e634d33deb86 added new website
haftmann
parents:
diff changeset
    57
  processed by the preprocessing layer
e634d33deb86 added new website
haftmann
parents:
diff changeset
    58
* for HTML includes, it is most convenient to name them *.include.html
e634d33deb86 added new website
haftmann
parents:
diff changeset
    59
* whole dirs maybe selected for statically copying them to the target destination
16249
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    60
  by configuring the project layer
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    61
* for attributes etc. referencing file locations, there is a convenient
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    62
  abbreviation: "//" at the beginning of a path is translated to the root,
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    63
  but expressed relatively to the current location, e. g.
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    64
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    65
  in abc/def/itsme.html: <a href="//abc/ghi/itsyou.html">
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    66
                becomes: <a href="../def/itsyou.html">
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    67
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    68
  Further, targets are checked for existances.
7fefdd1a40a2 added README
haftmann
parents: 16233
diff changeset
    69
  This is a simple but powerful thing easing to keep the pages consistent.
16233
e634d33deb86 added new website
haftmann
parents:
diff changeset
    70
e634d33deb86 added new website
haftmann
parents:
diff changeset
    71
e634d33deb86 added new website
haftmann
parents:
diff changeset
    72
(3) using the project layer framework
e634d33deb86 added new website
haftmann
parents:
diff changeset
    73
=====================================
e634d33deb86 added new website
haftmann
parents:
diff changeset
    74
e634d33deb86 added new website
haftmann
parents:
diff changeset
    75
To configure it the first time after checkout, just type
e634d33deb86 added new website
haftmann
parents:
diff changeset
    76
> make phase=init
e634d33deb86 added new website
haftmann
parents:
diff changeset
    77
e634d33deb86 added new website
haftmann
parents:
diff changeset
    78
Then, you may edit the project configuration file conf/localconf.mak.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    79
After a correct configuration, the build process may be started by
e634d33deb86 added new website
haftmann
parents:
diff changeset
    80
> make
e634d33deb86 added new website
haftmann
parents:
diff changeset
    81
e634d33deb86 added new website
haftmann
parents:
diff changeset
    82
The project layer tries to be smart about dependencies, but inlucdes,
e634d33deb86 added new website
haftmann
parents:
diff changeset
    83
embedded images and so on are not tracked; to built dependencies anew,
e634d33deb86 added new website
haftmann
parents:
diff changeset
    84
do
e634d33deb86 added new website
haftmann
parents:
diff changeset
    85
> make depends
e634d33deb86 added new website
haftmann
parents:
diff changeset
    86
e634d33deb86 added new website
haftmann
parents:
diff changeset
    87
After adding or deleting files, an
e634d33deb86 added new website
haftmann
parents:
diff changeset
    88
> make depends
e634d33deb86 added new website
haftmann
parents:
diff changeset
    89
may also be neccessary. The same after changing something in the configuration.
e634d33deb86 added new website
haftmann
parents:
diff changeset
    90
e634d33deb86 added new website
haftmann
parents:
diff changeset
    91
If nothing seems to be sensible any more, try
e634d33deb86 added new website
haftmann
parents:
diff changeset
    92
> make clean
e634d33deb86 added new website
haftmann
parents:
diff changeset
    93
> make depends
e634d33deb86 added new website
haftmann
parents:
diff changeset
    94
> make
e634d33deb86 added new website
haftmann
parents:
diff changeset
    95
e634d33deb86 added new website
haftmann
parents:
diff changeset
    96
e634d33deb86 added new website
haftmann
parents:
diff changeset
    97
(4) project-specific remarks
e634d33deb86 added new website
haftmann
parents:
diff changeset
    98
============================
e634d33deb86 added new website
haftmann
parents:
diff changeset
    99
e634d33deb86 added new website
haftmann
parents:
diff changeset
   100
* the site is not monolithic
e634d33deb86 added new website
haftmann
parents:
diff changeset
   101
* it must fit neatlessly into the Isabelle distribution and regression framework