Contents 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	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	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	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	- Python version 2.2 or above is required.
23
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	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
56	The actual hosted html files are rsynced to Skencil's project website
57	at wald.
58
59
60	Building the Website
61	--------------------
62	1. Checkout sources of the Skencil website.
63
64	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
69	* create a directory which will contain the sources
70	* checkout the whole sources here using:
71
72	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