Using WML

WML stands for web site meta language. This means that WML takes input .wml files, processes whatever is inside them (it can be anything from basic HTML to Perl code!), and outputs whatever you want it to output, for example .html or .php.

The documentation for WML is not easy to learn from. It is actually quite complete, but until you begin to understand how it works (and it is quite powerful) it is easiest to learn from examples. You may find template files used for the Debian site useful. They can be found in webwml/english/template/debian/.

This assumes that you have WML installed on your machine. WML is available as a Debian package.

Editing WML sources

One thing all .wml files will have is one or more opening #use lines. You must not change or translate their syntax, only the quoted strings such as those after title=, which would change the <title> element in the output files.

Other than the header lines, most of our .wml pages contain simple HTML. If you encounter tags such as <define-tag> or <: ... :>, be careful, because those delimit code that's processed by one of WML's special passes. See below for more information.

Building Debian web pages

Simply type make in webwml/<lang>. We have set up makefiles that call wml with all the right arguments.

If you do a make install then the HTML files will be built and placed in the directory ../../www/.

Extra WML features we use

One of the features of WML that we make extensive use of is the use of Perl. Remember, these are not dynamic pages. Perl is used at the time the HTML pages are generated to do, well, whatever you like. Two good examples of how we are using Perl in the pages is to create the list of most recent news items for the main page and to generate the links to translations at the end of the page.

To rebuild the templates of our web site, wml version >= 2.0.6 is needed. To rebuild the gettext templates for non-English translations, mp4h >= 1.3.0 is necessary.

Specific issues with WML

Multi-byte languages may need special pre- or post-processing of the .wml files in order to handle the character set properly. This can be done by changing the variables WMLPROLOG and WMLEPILOG in webwml/<lang>/Make.lang appropriately. Depending on how your WMLEPILOG program works, you may need to change the value of WMLOUTFILE.
See the Japanese or Chinese translations for an example.