How to work on the Debian web pages
- General information
- Etiquette for editors
- Separation of text from data
- Adding a new page
- Including other files
- Adding a new directory
If you want to work on our web site, please be prepared to store at least 250 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 twice as much space. If you make a partial checkout, you'll need much less space, e.g. 50 MB for english/.
Lots of people won't have the whole
webwml CVS tree checked
out, which sometimes leads to missing files and broken builds, in case a
crucial new file is added and one doesn't do a full cvs update in
the directory. Remember to verify that you have all the required files (like
.wmlrc files) before complaining to us.
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.
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 CVS. 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 cvs diff 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 CVS module.
Usage of smart_change.pl
smart_change.pl [options] origfile
Currently only files in
/english/ are allowed as
smart_change.pl takes the
- Specify a Perl regular expression applied to source files (may be used
more than once). Example:
$> ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml $> cvs diff -u */devel/index.wml | less $> cvs ci -m "1.23: Updated oldurl to current location" */devel/index.wmlThe first command does the change, the second command is for checking the English original file and every translation of it. You should do this to review the actual changes before committing. If everything looks like you expected, commit your changes with the third command.
- Process this language (may be used more than once). If no language is specified, all available ones are processed.
- Do not bump versions in translation-check headers.
Normally, the version in each translation-check header is increased
by one in the translated files that are up-to-date, and left
untouched in those that are out-of-date.
If this option is specified, no
translation-check headers are touched. See
keeping translations up to datefor an explanation on translation-check headers.
- Show the previous CVS revision. This is mainly useful when the English file is already committed and you want to check the translation-check headers against the previous version.
- Display short usage information.
- Display verbose messages while running.
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.
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.
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
- 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.
- This contains all the pieces of text which are needed for each
vendor entry. Translations are added via
- 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@example.com adds a
new vendor, they add it to
debiancd.db, convert it into WML
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 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:
- Removes the "Debian --" part that is usually prepended to all the <title> tags.
- Removes the initial header from the page. A custom header can, of course, be included in the body.
- Removes the mirror dropdown list from the page. It is generally not recommended to be used, except for a handful of pages.
- Removes the link back to the main Debian page, which is normally added to the bottom of the page.
- Removes the links to versions in other languages, which are normally added to the bottom of the page.
- Sets the date on the resulting files to the timestamp of the generated files, instead of the timestamp of the source file.
- Removes the copyright notice at the bottom of the page.
Note that you can use any string as the value of these variables,
foo, it doesn't matter.
An example of the use of this is in the ports pages which have
their own headers.
#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.
If you want to separate some parts of your page into a distinct file
(which is then included by your main file) use
.src if your file contains content which should
be translated because then your included file is tracked for changes as
.wml file. If you use any other extension, like
.inc, translators will not notice your updates and different
languages might ship different content.
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 cvs add foo cd foo cp ../intro/Makefile . cvs 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
cvs commit Makefile foo