1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
#use wml::debian::template title="Debian Web Pages HTML Usage" BARETITLE=true
#use wml::debian::common_tags
#use wml::debian::acronyms
#use wml::debian::toc
#use wml::debian::translation-check translation="648de6ad5bea60540e41a5733da0b761a34c7927" maintainer="galaxico"
<p>
This page is still a draft.
</p>
<toc-display/>
<toc-add-entry name="preface">Preface</toc-add-entry>
<p>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.</p>
<toc-add-entry name="general">Some general hints</toc-add-entry>
<p>For new pages or translations here's a list of general advice</p>
<dl>
<dt>do not use long lines</dt>
<dd>
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.
</dd>
<dt>keep tags in separate lines if possible</dt>
<dd>
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.
</dd>
<dt>do not use spaces or line breaks in inline tags</dt>
<dd>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.
</dd>
</dl>
<toc-add-entry name="abbreviations">Abbreviations and Acronyms</toc-add-entry>
<p>
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.
</p>
<p>
An acronym is added to the page in the following syntax:
<code><acronym lang="language code" title="Full definition of
acronym">ACRONYM</acronym></code>. 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.
</p>
<p>
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
<code>acronyms</code> in the wml file. For example the wml tag for DD is
<acronym_DD />.
</p>
<toc-add-entry name="citations">Citations and Quotes</toc-add-entry>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<toc-add-entry name="code">Program Names and Code</toc-add-entry>
<p>
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.
</p>
<toc-add-entry name="samp">Samples of Computer Output</toc-add-entry>
<p>
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.
</p>
<toc-add-entry name="kbd">Keyboard Input</toc-add-entry>
<p>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 <a href="#var">variables</a> for how to tag the variable input.
</p>
<toc-add-entry name="var">Variables</toc-add-entry>
<p>
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.
</p>
<toc-add-entry name="pre">Preformatted Content</toc-add-entry>
<p>
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.
</p>
<toc-add-entry name="img">Images</toc-add-entry>
<p>
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 <code>alt</code> attribute
should
be added. The size is added by wml if not present, but that needs compile
time. The <code>alt</code> attribute should contain something that tells users browsing
with lynx and blind people what is in the image.
</p>
# <toc-add-entry name=""></toc-add-entry>
|
