Debian Web Pages HTML Usage

This page is still a draft.

Preface

This page is built to help editors and translators to form well-tagged pages. It contains hints about tag usage and how to create new pages and make them more easy to translate.

Some general hints

For new pages or translations here's a list of general advice

do not use long lines
The wml files and other files should have lines fitting in a normal terminal window. This is easier to edit in vi, better searchable and easier to translate. It's also important because it's harder to resolve conflicts in long lines.
keep tags in separate lines if possible
Most HTML tags can be kept in separate lines. Some of them are <div>, <p>, <table>, <ul>. To make things easier for translators, you should keep all tags that can be used this way in separate lines. Otherwise translators may delete tags accidentally and forget to restore them after translating.
do not use spaces or line breaks in inline tags
Some tags produce a space, if they are kept in separate lines. One of those is the <q>tag for small citations or quotes. You may only separate them as a whole with content in one line. Else there might be a space between content and tag in the HTML page afterwards. Between words in these tags you may have as many line breaks or spaces as you want.

Abbreviations and Acronyms

For abbreviations and acronyms the HTML tag <acronym> should be used. There are two reasons why the use of the <abbr> tag is not recommended: First not all browsers do support it and second there are inconsistent definitions about what is an acronym and what is an abbreviation.

An acronym is added to the page in the following syntax: <acronym lang="language code" title="Full definition of acronym">ACRONYM</acronym>. The title contains the full spoken words. If the acronym is built from initial letters of words, those letters should be upper case in the title. The lang attribute is only needed if the acronym or abbreviation is in a foreign language.

There is already a set of common acronyms in the wml templates included to use it in your page, you have to add a line to use acronyms in the wml file. For example the wml tag for DD is <acronym_DD />.

Citations and Quotes

There are several different rules what a citation or quote is for different languages. If you have a short inline citation you have to use the <q> tag. The rendering of the content is handled by language CSS. <q> tags must not have a space or line break between the opening and closing tag and the content.

For longer citations the tag <blockquote> is used. A <blockquote> encloses one or more paragraphs of text, which are marked with <p>. Please do not use the <blockquote> tags for centering any block of text which is not a citation. Blockquotes are exclusively for citations and will be rendered by language specific CSS code in the future.

There is also a <cite> tag in HTML. The <cite> tag is not used for the citation text itself. It is used for the source of a citation. This can be the name of the person the citation is from and is added as attribute to a <blockquote> as URL.

Program Names and Code

For program names and computer code there is a tag named <code>. Browsers normally know about displaying code and program names, but rendering can also be changed by CSS. It is not a good idea to use <tt> instead as this does not say anything about the content.

Samples of Computer Output

For computer output on the screen there is a special tag named <samp>. If you have a larger block of computer output, you should also have a look into the CSS file, if there is a special class for it.

Keyboard Input

If there are examples where the user has to type something on the keyboard, the <kbd> tag is used for the user input. See also the chapter about variables for how to tag the variable input.

Variables

Sometimes it is necessary to emphasize a variable input such as a special IP address or the users name which has to be given in a program call on command line. For these variable inputs the <var> tag is used.

Preformatted Content

The <pre> tag is use for preformatted text only. Line length, spaces and other things will be preserved. Naturally this tag cannot contain most of the other HTML tags.

Images

If there are images added in the page, there is no need to add an invalid border=0 as attribute. But if possible the image size and an alt attribute should be added. The size is added by wml if not present, but that needs compile time. The alt attribute should contain something that tells users browsing with lynx and blind people what is in the image.

Links

If you intend to link to a page within https://www.debian.org in the documentation, please use variables defined in the .wmlrc file for each language. For e.g. the URL in the tag
<a href="https://www.debian.org/devel/website/htmlediting">htmlediting</a>
should be replaced using the variable DEVEL like this <a href="$(DEVEL)/website/htmlediting">htmlediting</a>.