|
1 The Isabelle webpage |
|
2 ==================== |
|
3 |
|
4 (1) Philosophy |
|
5 ============== |
|
6 |
|
7 The webpage sources consists of three differnt layers: |
|
8 |
|
9 a) the presentation layer |
|
10 ------------------------- |
|
11 |
|
12 This is was the user actually sees; the slogan is |
|
13 |
|
14 "structural XHTML plus with CSS" |
|
15 |
|
16 There are three different groups of end-user agents (browsers) |
|
17 |
|
18 1) "practical non-CSS" browsers (lynx, netscape4) |
|
19 These just display plain HTML |
|
20 2) "more-or-less-w3c-CSS" browsers (KHTML/Konqueror/Safari, Internet Explorer) |
|
21 These are able to display the pages almost as they should be, |
|
22 but perhaps with some minor warts. |
|
23 3) "almost-w3-CSS" browsers (Mozilla/Firefox/Galeone) |
|
24 These are the "reference implementation" for the layout |
|
25 |
|
26 b) the project layer |
|
27 -------------------- |
|
28 |
|
29 This manages the dependencies between files; the tool of choice |
|
30 is |
|
31 |
|
32 "make plus shell scripting" |
|
33 |
|
34 Project settings may be configured using a seperate configuration |
|
35 file |
|
36 |
|
37 c) the preprocessing layer |
|
38 -------------------------- |
|
39 |
|
40 This allows to use things like includes, current date and so on: |
|
41 |
|
42 "XHTML plus processing instructions" |
|
43 |
|
44 Note that this is almosz not interwoven with b), to keep it as robust |
|
45 and simple as possible. |
|
46 |
|
47 The layer itself is implemented by a small tool "pypager", written in python. |
|
48 |
|
49 |
|
50 (2) writing your own pages |
|
51 ========================== |
|
52 |
|
53 You may add arbitrary files to the dir structure, but adhere to the following: |
|
54 * use XHTML, not loose HTML |
|
55 * no structural markup; of you need layout effects, use CSS |
|
56 * any files ending with .html are considered as HTML files and are implicitly |
|
57 processed by the preprocessing layer |
|
58 * for HTML includes, it is most convenient to name them *.include.html |
|
59 * whole dirs maybe selected for statically copying them to the target destination |
|
60 by configuring the project layer |
|
61 |
|
62 |
|
63 (3) using the project layer framework |
|
64 ===================================== |
|
65 |
|
66 To configure it the first time after checkout, just type |
|
67 > make phase=init |
|
68 |
|
69 Then, you may edit the project configuration file conf/localconf.mak. |
|
70 After a correct configuration, the build process may be started by |
|
71 > make |
|
72 |
|
73 The project layer tries to be smart about dependencies, but inlucdes, |
|
74 embedded images and so on are not tracked; to built dependencies anew, |
|
75 do |
|
76 > make depends |
|
77 |
|
78 After adding or deleting files, an |
|
79 > make depends |
|
80 may also be neccessary. The same after changing something in the configuration. |
|
81 |
|
82 If nothing seems to be sensible any more, try |
|
83 > make clean |
|
84 > make depends |
|
85 > make |
|
86 |
|
87 |
|
88 (4) project-specific remarks |
|
89 ============================ |
|
90 |
|
91 * the site is not monolithic |
|
92 * it must fit neatlessly into the Isabelle distribution and regression framework |