How to Edit this Web Site

This web site is meant to be editable by any member of the development team. The site is intended for use by both users, developers, and the curious. Note that some users may only be interested in part of the site, such as that detailing Jonathan Shneier's pure Java MPEG-1 decoder or writing data in the video metadata file format. When google crawls the site, it will see it as plain text. It is a good idea to test the site using Lynx.

This web site is written using Apache's server-side include mechanism, described in their SSI reference document and introduced in their SSI tutorial. The basic system uses a single index page, which is symlinked in in each directory. The index file loads three pages: config, head, and body. Config is loaded before the others, and may include setting variables and other things that don't involve direct generation of content. The head page is included within the HTML header block, and includes the title tag and any additional required meta, link, and script tags ¹. Finally, the body page is loaded inside the frame.

To start editing the web site, you must first check it out from CVS, following the instructions on sourceforge for using CVS. To create a new page, use the mkhtml script in the bin directory. (To get it, add ``PATH=$PATH:~/workspace/bin`` to your .bash_profile or .cshrc file. To use it, from the directory above the one you wish to add, invoke mkhtml foo.

If you want to write the body.shtml page in reStructuredText, name it body.rst instead of body.shtml. The publish script, run every night at one o'clock in whatever time zone the sourceforge servers are located, knows to convert the body.rst file to a body.shtml file. For information about reStructuredText, see the docutils web site. Unfortunately, it isn't quite up-to-date with the latest HTML standards, and doesn't include support for things like arbitrary ids and titles. Remember to run ²:

rm body.shtml
cvs rm body.shtml
cvs ci body.shtml -m"Switched to RST"
cvs add body.rst -m'(some kind of web page) in RST"
cvs ci body.rst -m'(some kind of web page) in RST"

One of the problems with using the .rst extension is that it is very finicky, especially when compared to other wiki-like systems. So, it might be a good idea to check your changes before nightfall. Log into the viper toolkit website: ssh username@viper-toolkit.sourceforge.net . From here, you'll have to add some stuff from the web directory to your path. I put a link to in my home directory to the web directory to make this easier. So:

ln -s /homes/group/v/vi/viper-toolkit web
cat >> .bashrc
PATH=$PATH:~/web/bin
PYTHONPATH=${PYTHONPATH-.}:~/web/bin/lib/python
umask 003

After that last one, type contrl-D to end the file. The path modifier adds the site making scripts. The pythonpath line is necessary for rst conversion. The umask will be allow other viper-toolkit members to continue editing your files. After that, log back into bash or run:

. .bashrc

This will get the changes to your environment. From here, change directories (cd) to ~/web/htdocs/staging . From here, you can find the directory containing the text you modified. For example, if you were editing this document, you would then cd developers\webhowto. Once in you subdirectory, run cvs up . If you made a new directory, run cvs up -Pd from the parent directory; this gets changes to the directory structure (P for prune, d for new directories). To test your changes, run:

rst2html.py body.rst > body.shtml

This will (try to) generate the new body.shtml file. In your browser, go to staging/path-to-your-file/ to see the changes. The rst2html.py script may give some helpful, or not so helpful, error messages. The most important part is often the line number, although that isn't much help in some formatting cases.

Some other pages on the site use HTTP/1.1 content negotiation to decide on the format. For example, the AppLoader schema serves as html, rdf+xml, or n3 depending on what the client requires. This currently involves making a var file, as opposed to using multiviews. To do this, just add an index.var file to the directory, in the format described in Apache's content negotiation documentation.