How to work on the Debian web pages

General information

Resource requirements

If you want to work on our web site, please be prepared to store at least 740 MB of data on your disk. This reflects the current size of the source archive. If you (accidentally) rebuild all of the pages, you will need at least three times as much space.

What are these lines beginning with `#'?

In WML, a line beginning with a `#' is a comment. These are preferred to normal HTML comments as they don't show up on the final page.

Please read the page on using WML for more information on WML.

Etiquette for editors

Can I modify this page?

That depends. If you see a small mistake, like a typo, just fix it.

If you notice that some bit of information is missing, feel free to fix it, too.

If you feel that something is awful and needs to be rewritten, bring it up on debian-www so it can be discussed. We'll probably agree with you.

If you notice there's a problem in a template (i.e. a file in webwml/english/template/debian directory), please think about the change before committing it, because changes to templates often cause large portions of the site to get rebuilt.

When adding new directories, also add the Makefile!

Some care should be taken when adding a new directory to git. If the current directory is listed in ../Makefile then you must create a Makefile in it — otherwise make will give an error message.

Use clear and simple English

Since the Debian web pages are read by non-native speakers of English and are translated into other languages, it is best to write in clear and simple English and avoid the use of slang, emoticons and obscure idioms.

If you do use any of this, add a comment to the file explaining the meaning.

If any doubt, or in order to proofread your proposal, please contact the English localization team.

Look for READMEs

Some of the directories contain a README to help you understand how that directory is organized. These should provide any special information needed when working in that area.

Separate the changes in content from the changes in formatting

Always make separate patches or commits for content changes and for changes in formatting. When they are combined, it's much harder for translators to find the differences. If you run git diff -u with such mixed changes, you can see the mess for yourself.

In general, avoid random formatting changes. Making older parts of pages XHTML/XML-compliant shouldn't be done in the same commit with other changes. (New stuff can and should be done properly from the start, of course.)

Update translations, too, if possible

Some changes are independent of the language used in a WML file, like changes to URLs or embedded Perl code. Fixing typos also falls in the same category, because translators have usually ignored them while translating. With such language-independent changes, you can do the same change in all the translated files without actually knowing the other languages, and safely increase the version in the translation-check headers.

It's not terribly hard for translators to do the same work themselves, and it can be inconvenient for English-speaking editors to have a full checkout in which to operate. However, we still encourage people to do this in order to avoid bothering two dozen people for something that can be done quickly by a single person.

In addition, to make such changes easier to apply, you can use the smart_change.pl script from the top-level directory in the webwml git module.

Links

This link doesn't look right. Should I change it?

Because of the way the web servers are set up (using content negotiation), you should not have to change any of the internal links. In fact we suggest you don't. Write to debian-www if you feel a link is incorrect before changing it.

Fixing links

If you notice a link to an external web site results in a redirection (301, 302, a <meta> redirect, or a page saying This page has moved.) please tell debian-www about it.

If you find a broken link (404, 403, or a page that's not what the link says it is), please fix it and tell debian-www about it so translators are aware. Even better, fix the link in all the other translations, and update translation-check headers if possible.

Separation of text from data

What are these foo.def and foo.data files?

To make it easier to keep the translations up to date, we separate the generic parts (data) from the textual parts (text) of some pages. The translators only need to copy and translate the textual parts of those, the generic parts will be added automatically.

An example may help in understanding this. It takes several files to generate the page of vendor listings in CD/vendors:

index.wml:
The text at the top of the vendors page is in this file. A translated copy of this should be placed in each language directory.
vendors.CD.def:
This contains all the pieces of text which are needed for each vendor entry. Translations are added via <language>/po/vendors.xy.po.
vendors.CD:
This file contains the actual vendor entries which are independent on the language, so a translator doesn't need to touch this file.

When one of the people behind [email protected] adds a new vendor, they add it to debiancd.db, convert it into WML format as vendors.CD (using getvendors.pl), and then let WML and the makefiles do their magic. All the translations get rebuilt using the existing translated text but with the new vendor data. (An updated translation for free!)

Adding a new page

Adding new pages to Debian is quite easy. All the work of getting the header and footer right are done using WML. All you need to do is to include a line such as the following at the top of the new file:

#use wml::debian::template title="TITLE OF PAGE"

followed by the body. All pages should use the wml::debian::template template file unless they are using a special one created just for that section, e.g. the News or security items.

The templates we have allow you to define certain variables which will affect the pages created. This should avoid having to create different templates for every situation and allow improvements to be easier to implement. The variables currently available and their purpose are:

BARETITLE="true"
Removes the "Debian --" part that is usually prepended to all the <title> tags.
NOHEADER="true"
Removes the initial header from the page. A custom header can, of course, be included in the body.
NOMIRRORS="true"
Removes the mirror dropdown list from the page. It is generally not recommended to be used, except for a handful of pages.
NOHOMELINK="true"
Removes the link back to the main Debian page, which is normally added to the bottom of the page.
NOLANGUAGES="true"
Removes the links to versions in other languages, which are normally added to the bottom of the page.
GEN_TIME="true"
Sets the date on the resulting files to the timestamp of the generated files, instead of the timestamp of the source file.
NOCOPYRIGHT="true"
Removes the copyright notice at the bottom of the page.

Note that you can use any string as the value of these variables, true, yes, foo, it doesn't matter.

An example of the use of this is in the ports pages which have their own headers. ports/arm/index.wml uses:

#use wml::debian::template title="ARM Port" NOHEADER="yes"

If you want to do something that can't be done using the existing templates, first consider extending one of them. If it isn't possible to extend one in a backward compatible way, try to make the new template a superset of an existing one so the pages can be converted to it at the next major upgrade (hopefully never more than every 6 months).

If you are creating a page that is generated by a script or has little prose, consider using the <gettext> tags to ease the task of keeping translations up to date.

Including other files

If you want to separate some parts of your page into a distinct file (which is then included by your main file) use the extension .src if your file contains content which should be translated because then your included file is tracked for changes as any ordinary .wml file. If you use any other extension, like .inc, translators will not notice your updates and different languages might ship different content.

Adding a new directory

Note: do not create a directory with the name install. This confuses make and the pages in that directory will not be updated automatically.

Below is an annotated example of adding a new directory to the web site. 

   mkdir foo
   git add foo
   cd foo
   cp ../intro/Makefile .
   git add Makefile

Edit the Makefile in the parent directory and add the directory you just created to the SUBS variable. This will add the directory to the build for when make is run.

Finally, commit all the changes just made to the repository with 

  git commit Makefile foo