Debian Web Pages HTML Usage
This page is still a draft.
- Some general hints
- Abbreviations and Acronyms
- Citations and Quotes
- Program Names and Code
- Samples of Computer Output
- Keyboard Input
- Preformatted Content
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
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.
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.
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.
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.
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
be added. The size is added by wml if not present, but that needs compile
alt attribute should contain something that tells users browsing
with lynx and blind people what is in the image.