Annotation of /website/trunk/README

The Skencil Website
===================

Overview
--------

The Skencil website consists of a bunch of static html files that are generated
from a page layout file and files that contain the bodies of every page.

FAQ and Release Notes sections of the website are generated by scripts that are
in folders faq/ and relnotes/, respectively. The whole build process
is managed by the updatepages.py script. The rest of the pages are just
plain html files in folder pages/.


Required Software
-----------------

Roughly these software packages are required to build the html files of the
Skencil website.

- Python version 2.2 or above is required.

- Docutils (http://docutils.sf.net) (for Release Notes)

- Python XML (http://pyxml.sf.net) (for the FAQ)

- The following are needed if you want to build the gallery files:

  * Skencil 0.6.13. More precisely, any Skencil version that contains
    sk2ppm which was first shipped with 0.6.13

  * cjpeg. In Debian woody package: libjpeg-progs

  * pnmscale. In Debian woody package: netpbm

  * Fonts to generate the Gallery images in the Skencil's font_path.

    (If you get warning messages like:
    I cannot find the metrics for the font URWChanceryL-MediItal.
    The file z003034l.afm is not in the font_path.
    I'll use the metrics for Times-Roman instead.
    you can ignore this or add a path to font_path which has "z003034l.afm".)


Required accounts
-----------------

The sources of the website are kept in folder "website" in Skencil's
"Software" SVN repository on wald.intevation.org. To make changes to them you 
either have to send us patches or get commit permission from us which 
requires a wald account and becoming a member of the Skencil 
project at Savannah
(https://wald.intevation.org/projects/skencil/).

The actual hosted html files are rsynced to Skencil's project website
at wald.


Building the Website
--------------------
1. Checkout sources of the Skencil website.

1.1 Simple way
Most users might want to checkout the whole sources for the website
regardless the fact that they might want to change only a small part
of the site.

        * create a directory which will contain the sources
        * checkout the whole sources here using:

        svn checkout \
        svn+ssh://developername@scm.wald.intevation.org/skencil/website/trunk
        
        or for annonymous access:

        svn checkout
        https://scm.wald.intevation.org/svn/skencil/website/trunk

1.2 Advanced way
If you do not want to check out the whole site because you are about
to change only a one page. You have the option to checkout only the
files you need. So here is a short guide:
        
        * create a directory which will contain the sources.
        * enter this diretory.
        * checkout updatepages.py script here.
        * checkout the "modules" (pages,screenshots,gallery) you need.
        
2. Generate html pages from the sources.
Generation of the pages is done by the updatepages.py script. You will
find it under the root folder of the source directory.
You can control the behavior of the script providing some options.
Please refer the build in help for more information.

On default the website will be generated in a subfolder of your source
directory named "skencil-website" but this is considered as
depreciated. You should provide an alternative directory for the
generated files with the -d option.

3. Test your changes
Check for all kind of errors. In example format and spelling errors.

4. Checkin your changes
To avoid conflicts that someone already changed the site at the same
time, you should checkin your changes back to the repository.
If there are no conflicts chances are very good that you won't mess up
the site.

5. Rsync generated files to make them public
After successfull generation of the website you can rsync the
generated files to the project website on wald. For general
information on how to do this please refer:
http://wald.intevation.org/docman/view.php/1/34/project-websites.txt

Some examples:

rsync a new index.html page to the server:
rsync /path/to/my/generated/files/index.html \
[email protected]:/skencil/htdocs/

rsync your whole repository:
rsync -r /path/to/my/generated/files/ \
[email protected]:/skencil/htdocs/

You might want to add the "-z" option on slow networks to compress the
files before transmitting. For general help on rsync please refer the
rsyn man page.

1	jpaalasm	607	The Skencil Website
2			===================
3
4			Overview
5			--------
6
7			The Skencil website consists of a bunch of static html files that are generated
8			from a page layout file and files that contain the bodies of every page.
9
10			FAQ and Release Notes sections of the website are generated by scripts that are
11	torsten	667	in folders faq/ and relnotes/, respectively. The whole build process
12			is managed by the updatepages.py script. The rest of the pages are just
13	jpaalasm	607	plain html files in folder pages/.
14
15
16			Required Software
17			-----------------
18
19			Roughly these software packages are required to build the html files of the
20			Skencil website.
21
22	jpaalasm	608	- Python version 2.2 or above is required.
23	jpaalasm	607
24			- Docutils (http://docutils.sf.net) (for Release Notes)
25
26			- Python XML (http://pyxml.sf.net) (for the FAQ)
27
28			- The following are needed if you want to build the gallery files:
29
30			* Skencil 0.6.13. More precisely, any Skencil version that contains
31			sk2ppm which was first shipped with 0.6.13
32
33			* cjpeg. In Debian woody package: libjpeg-progs
34
35			* pnmscale. In Debian woody package: netpbm
36
37			* Fonts to generate the Gallery images in the Skencil's font_path.
38
39			(If you get warning messages like:
40			I cannot find the metrics for the font URWChanceryL-MediItal.
41			The file z003034l.afm is not in the font_path.
42			I'll use the metrics for Times-Roman instead.
43			you can ignore this or add a path to font_path which has "z003034l.afm".)
44
45
46			Required accounts
47			-----------------
48
49	torsten	667	The sources of the website are kept in folder "website" in Skencil's
50			"Software" SVN repository on wald.intevation.org. To make changes to them you
51			either have to send us patches or get commit permission from us which
52			requires a wald account and becoming a member of the Skencil
53			project at Savannah
54			(https://wald.intevation.org/projects/skencil/).
55	jpaalasm	607
56	torsten	667	The actual hosted html files are rsynced to Skencil's project website
57			at wald.
58	jpaalasm	607
59
60			Building the Website
61			--------------------
62	torsten	667	1. Checkout sources of the Skencil website.
63	jpaalasm	607
64	torsten	667	1.1 Simple way
65			Most users might want to checkout the whole sources for the website
66			regardless the fact that they might want to change only a small part
67			of the site.
68	jpaalasm	607
69	torsten	667	* create a directory which will contain the sources
70			* checkout the whole sources here using:
71	jpaalasm	607
72	torsten	667	svn checkout \
73			svn+ssh://developername@scm.wald.intevation.org/skencil/website/trunk
74
75			or for annonymous access:
76
77			svn checkout
78			https://scm.wald.intevation.org/svn/skencil/website/trunk
79
80			1.2 Advanced way
81			If you do not want to check out the whole site because you are about
82			to change only a one page. You have the option to checkout only the
83			files you need. So here is a short guide:
84
85			* create a directory which will contain the sources.
86			* enter this diretory.
87			* checkout updatepages.py script here.
88			* checkout the "modules" (pages,screenshots,gallery) you need.
89
90			2. Generate html pages from the sources.
91			Generation of the pages is done by the updatepages.py script. You will
92			find it under the root folder of the source directory.
93			You can control the behavior of the script providing some options.
94			Please refer the build in help for more information.
95
96			On default the website will be generated in a subfolder of your source
97			directory named "skencil-website" but this is considered as
98			depreciated. You should provide an alternative directory for the
99			generated files with the -d option.
100
101			3. Test your changes
102			Check for all kind of errors. In example format and spelling errors.
103
104			4. Checkin your changes
105			To avoid conflicts that someone already changed the site at the same
106			time, you should checkin your changes back to the repository.
107			If there are no conflicts chances are very good that you won't mess up
108			the site.
109
110			5. Rsync generated files to make them public
111			After successfull generation of the website you can rsync the
112			generated files to the project website on wald. For general
113			information on how to do this please refer:
114			http://wald.intevation.org/docman/view.php/1/34/project-websites.txt
115
116			Some examples:
117
118			rsync a new index.html page to the server:
119			rsync /path/to/my/generated/files/index.html \
120			[email protected]:/skencil/htdocs/
121
122			rsync your whole repository:
123			rsync -r /path/to/my/generated/files/ \
124			[email protected]:/skencil/htdocs/
125
126			You might want to add the "-z" option on slow networks to compress the
127			files before transmitting. For general help on rsync please refer the
128			rsyn man page.
129
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision