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 \
$USER@wald.intevation.org:/skencil/htdocs/

rsync your whole repository:
rsync -r /path/to/my/generated/files/ \
$USER@wald.intevation.org:/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.