| 2 |
- |
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
|
2 |
"http://www.w3.org/TR/html4/loose.dtd">
|
|
|
3 |
<html>
|
|
|
4 |
<head>
|
|
|
5 |
<title>HTML coding and style guidelines for Ghostscript documentation</title>
|
|
|
6 |
<!-- $Id: Htmstyle.htm,v 1.44 2005/10/20 19:46:23 ray Exp $ -->
|
|
|
7 |
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
|
|
|
8 |
</head>
|
|
|
9 |
|
|
|
10 |
<body>
|
|
|
11 |
<!-- [1.0 begin visible header] ============================================ -->
|
|
|
12 |
|
|
|
13 |
<!-- [1.1 begin headline] ================================================== -->
|
|
|
14 |
|
|
|
15 |
<h1>HTML coding and style guidelines for Ghostscript documentation</h1>
|
|
|
16 |
|
|
|
17 |
<!-- [1.1 end headline] ==================================================== -->
|
|
|
18 |
|
|
|
19 |
<!-- [1.2 begin table of contents] ========================================= -->
|
|
|
20 |
|
|
|
21 |
<h2>Table of contents</h2>
|
|
|
22 |
|
|
|
23 |
<blockquote><ul>
|
|
|
24 |
<li><a href="#Introduction">Introduction</a>
|
|
|
25 |
<li><a href="#Appearance">Appearance and contents</a>
|
|
|
26 |
<ul>
|
|
|
27 |
<li><a href="#Page_structure">Page structure</a>
|
|
|
28 |
<li><a href="#Links_outside">Links to outside the Ghostscript documentation</a>
|
|
|
29 |
<li><a href="#Images">Images and graphics</a>
|
|
|
30 |
<li><a href="#index.html"><b><tt>index.html</tt></b></a>
|
|
|
31 |
</ul>
|
|
|
32 |
<li><a href="#Large_structure">HTML large structure</a>
|
|
|
33 |
<ul>
|
|
|
34 |
<li><a href="#HTML_head">HTML <b><tt><head></tt></b></a>
|
|
|
35 |
<li><a href="#HTML_body">HTML <b><tt><body></tt></b></a>
|
|
|
36 |
</ul>
|
|
|
37 |
<li><a href="#Inner_structure">HTML inner structure</a>
|
|
|
38 |
<ul>
|
|
|
39 |
<li><a href="#Structuring_comments">Structuring comments</a>
|
|
|
40 |
<li><a href="#Headers">Headers: <b><tt><Hn></tt></b></a>
|
|
|
41 |
<li><a href="#Anchors">Anchors: <b><tt><a name="..."></tt></b></a>
|
|
|
42 |
</ul>
|
|
|
43 |
<li><a href="#Text">The presentation of text</a>
|
|
|
44 |
<ul>
|
|
|
45 |
<li><a href="#Text_sections">Sections of text</a>
|
|
|
46 |
<ul>
|
|
|
47 |
<li><a href="#Paragraphs">Paragraphs: <b><tt><p></tt></b></a>
|
|
|
48 |
<li><a href="#Blockquote">Indented paragraphs: <b><tt><blockquote></tt></b></a>
|
|
|
49 |
<li><a href="#Line_breaks">Explicit line breaks: <b><tt><br></tt></b></a>
|
|
|
50 |
<li><a href="#Preformatted_text">Preformatted text: <b><tt><pre></tt></b></a>
|
|
|
51 |
</ul>
|
|
|
52 |
<li><a href="#Use_of_fonts">The use of different font faces</a>
|
|
|
53 |
</ul>
|
|
|
54 |
<li><a href="#Lists">Lists: <b><tt><ul>, <ol>, <dl></tt></b></a>
|
|
|
55 |
<li><a href="#Tables">Tables: <b><tt><table></tt></b></a>
|
|
|
56 |
<ul>
|
|
|
57 |
<li><a href="#Readability">Readability for the user and the HTML writer</a>
|
|
|
58 |
<li><a href="#Table_guidelines">Specific guidelines for coding tables</a>
|
|
|
59 |
<li><a href="#Typical_table">HTML code for typical tables</a>
|
|
|
60 |
</ul>
|
|
|
61 |
<li><a href="#Unused_tags">Tags not used</a>
|
|
|
62 |
<li><a href="#New_document">Creating a new document</a>
|
|
|
63 |
<ul>
|
|
|
64 |
<li><a href="#File_name">Name the new document in 8+3 format</a>
|
|
|
65 |
<li><a href="#Plagiarize">Use an existing document as a model</a>
|
|
|
66 |
<li><a href="#Readme_material">Write new references to go in <b><tt>Readme.htm</tt></b></a>
|
|
|
67 |
<li><a href="#New_doc_other">Other considerations</a>
|
|
|
68 |
</ul>
|
|
|
69 |
<li><a href="#Miscellany">Miscellany</a>
|
|
|
70 |
</ul></blockquote>
|
|
|
71 |
|
|
|
72 |
<!-- [1.2 end table of contents] =========================================== -->
|
|
|
73 |
|
|
|
74 |
<!-- [1.3 begin hint] ====================================================== -->
|
|
|
75 |
|
|
|
76 |
<p>For other information, see the <a href="Readme.htm">Ghostscript
|
|
|
77 |
overview</a>.
|
|
|
78 |
|
|
|
79 |
<!-- [1.3 end hint] ======================================================== -->
|
|
|
80 |
|
|
|
81 |
<hr>
|
|
|
82 |
|
|
|
83 |
<!-- [1.0 end visible header] ============================================== -->
|
|
|
84 |
|
|
|
85 |
<!-- [2.0 begin contents] ================================================== -->
|
|
|
86 |
|
|
|
87 |
<h2><a name="Introduction"></a>Introduction</h2>
|
|
|
88 |
|
|
|
89 |
<p>
|
|
|
90 |
The most important intention in casting Ghostscript's documentation into
|
|
|
91 |
Hypertext Markup Language (HTML) from simple text form is to improve its
|
|
|
92 |
usefulness greatly to those who use, install, and build Ghostscript:
|
|
|
93 |
everything else is details. The wide spread of World Wide Web browsers now
|
|
|
94 |
makes it possible to distribute documents which are not only readable as
|
|
|
95 |
text, but also richly cross-linked as hypertext. Using hypertext through a
|
|
|
96 |
browser can reduce the effort required to find and use the information
|
|
|
97 |
people often need in order to use Ghostscript.
|
|
|
98 |
|
|
|
99 |
<p>
|
|
|
100 |
The remainder of this document expresses the guidelines used to create the
|
|
|
101 |
HTML form of the Ghostscript documentation. The guidelines are intended to
|
|
|
102 |
encourage
|
|
|
103 |
|
|
|
104 |
<ul>
|
|
|
105 |
<li>documents that are easy to read and understand in all of the most-used
|
|
|
106 |
forms: on screen with a browser, printed by a browser, or as plain text;
|
|
|
107 |
|
|
|
108 |
<li>correct HTML that conforms to prevailing standards;
|
|
|
109 |
|
|
|
110 |
<li>consistent HTML coding among all Ghostscript's documents; and
|
|
|
111 |
|
|
|
112 |
<li>HTML documents that are as simple as possible in light of their
|
|
|
113 |
contents; free of difficult, little-used, or proprietary constructs; and
|
|
|
114 |
easy to understand and modify.
|
|
|
115 |
</ul>
|
|
|
116 |
|
|
|
117 |
<p>
|
|
|
118 |
Here are those guidelines.
|
|
|
119 |
|
|
|
120 |
<hr>
|
|
|
121 |
|
|
|
122 |
<h2><a name="Appearance"></a>Appearance and contents</h2>
|
|
|
123 |
|
|
|
124 |
<p>
|
|
|
125 |
What the user sees browsing the documentation, and what a document
|
|
|
126 |
developer or editor sees working with it, are different. This section is
|
|
|
127 |
about what the user sees.
|
|
|
128 |
|
|
|
129 |
<h3><a name="Page_structure"></a>Page structure</h3>
|
|
|
130 |
|
|
|
131 |
<p>
|
|
|
132 |
A Ghostscript document in HTML form should consist of
|
|
|
133 |
|
|
|
134 |
<ol>
|
|
|
135 |
<li>a visual header containing
|
|
|
136 |
<ol type=a>
|
|
|
137 |
<li>a conspicuous highlighted headline;
|
|
|
138 |
<li>a table of contents;
|
|
|
139 |
<li>"hints": references to other useful documents, always including
|
|
|
140 |
<a href="Readme.htm">Readme.htm</a>;
|
|
|
141 |
</ol>
|
|
|
142 |
<li>the substantive contents;
|
|
|
143 |
<li>a visual trailer consisting entirely of
|
|
|
144 |
<ol type=a>
|
|
|
145 |
<li>standard copyright and licensing text;
|
|
|
146 |
<li>the Ghostscript version number; and
|
|
|
147 |
<li>the date when the document was last modified.
|
|
|
148 |
</ol>
|
|
|
149 |
</ol>
|
|
|
150 |
|
|
|
151 |
<p>
|
|
|
152 |
This document is an example of this standard visible structure. Also see
|
|
|
153 |
below about "<a href="#Structuring_comments">Structuring comments</a>" in
|
|
|
154 |
HTML source code.
|
|
|
155 |
|
|
|
156 |
<p>
|
|
|
157 |
Where it makes sense to modify the standard structure to make the document
|
|
|
158 |
more usable, do that. See
|
|
|
159 |
<a href="Readme.htm"><b><tt>Readme.htm</tt></b></a> for an example: the
|
|
|
160 |
introductory material at the beginning of the visible header, before the
|
|
|
161 |
table of contents.
|
|
|
162 |
|
|
|
163 |
<h3><a name="Links_outside"></a>Links to outside the Ghostscript documentation</h3>
|
|
|
164 |
|
|
|
165 |
<p>
|
|
|
166 |
Links to sites and documents outside the ghostscript distribution
|
|
|
167 |
must carry the <code>class="offsite"</code> attribute and value. This signals special
|
|
|
168 |
formatting to the stylesheet to assist users reading offline.
|
|
|
169 |
|
|
|
170 |
<p>
|
|
|
171 |
Avoid gratuitous commercial links; for instance, link the title of a book
|
|
|
172 |
to its publisher, not to one particular on-line bookseller. See
|
|
|
173 |
<a href="Language.htm#Capabilities"><b><tt>Language.htm</tt></b></a> for an
|
|
|
174 |
example, the reference to the <em>PostScript Language Reference
|
|
|
175 |
Manual</em>.
|
|
|
176 |
|
|
|
177 |
<p>
|
|
|
178 |
Similarly, where you have a choice, refer to free software rather than
|
|
|
179 |
commercial products. See
|
|
|
180 |
<a href="Make.htm#Third-party_libraries">Make.htm</a> for an example, the
|
|
|
181 |
reference to <a href="Make.htm#Third-party_libraries">InfoZip
|
|
|
182 |
<b><tt>unzip</tt></b></a> (where many commercial products provide similar
|
|
|
183 |
functions).
|
|
|
184 |
|
|
|
185 |
<h3><a name="Images"></a>Images and graphics</h3>
|
|
|
186 |
|
|
|
187 |
<p>
|
|
|
188 |
Use no graphics or images. The documents are text-only, so nothing is lost
|
|
|
189 |
when a document is converted into ASCII text. This is an explicit initial
|
|
|
190 |
design goal of the HTML documentation.
|
|
|
191 |
|
|
|
192 |
<h3><a name="index.html"></a><b><tt>index.html</tt></b></h3>
|
|
|
193 |
|
|
|
194 |
<p>
|
|
|
195 |
<b><tt>index.html</tt></b> is not a part of the visible Ghostscript
|
|
|
196 |
documentation itself, but when it is placed with all the
|
|
|
197 |
<b><tt>*.htm</tt></b> files in a directory and a browser refers to the
|
|
|
198 |
directory name alone, most servers are configured to deliver a file named
|
|
|
199 |
<b><tt>index.html</tt></b> by default. This one does nothing except
|
|
|
200 |
immediately to open the introductory Ghostscript document
|
|
|
201 |
<a href="index.html"><b><tt>Readme.htm</tt></b></a>. This is intended to
|
|
|
202 |
make life easier for both webmasters and users.
|
|
|
203 |
|
|
|
204 |
<hr>
|
|
|
205 |
|
|
|
206 |
<h2><a name="Large_structure"></a>HTML large structure</h2>
|
|
|
207 |
|
|
|
208 |
<h3><a name="HTML_head"></a>HTML <b><tt><head></tt></b></h3>
|
|
|
209 |
|
|
|
210 |
<p>
|
|
|
211 |
Besides the essential HTML structure elements, Ghostscript HTML document's
|
|
|
212 |
<b><tt><head></tt></b> consists of three elements in this order:
|
|
|
213 |
|
|
|
214 |
<ol>
|
|
|
215 |
<li>A <b><tt><title></tt></b>, usually the same text as the
|
|
|
216 |
<a href="#Headline">headline</a>
|
|
|
217 |
|
|
|
218 |
<li>An RCS identification line giving the name of the file in an HTML
|
|
|
219 |
comment:
|
|
|
220 |
|
|
|
221 |
<blockquote>
|
|
|
222 |
<!-- The next line must not contain the literal string $,I,d,:! -->
|
|
|
223 |
<b><tt><!-- $Id</tt><tt>: </tt></b><b><em>{file name}</em></b><b><tt>.htm $ --></tt></b>
|
|
|
224 |
</blockquote>
|
|
|
225 |
|
|
|
226 |
<li>For documents converted from another form, an HTML comment line giving
|
|
|
227 |
the name of the original file before it was edited and converted to HTML:
|
|
|
228 |
|
|
|
229 |
<blockquote>
|
|
|
230 |
<b><tt><!-- Originally: </tt></b><b><em>{file name}</em></b><b><tt> --></tt></b>
|
|
|
231 |
</blockquote>
|
|
|
232 |
</ol>
|
|
|
233 |
|
|
|
234 |
<h3><a name="HTML_body"></a>HTML <b><tt><body></tt></b></h3>
|
|
|
235 |
|
|
|
236 |
<p>
|
|
|
237 |
A Ghostscript HTML document's <b><tt><body></tt></b> consists of five
|
|
|
238 |
elements in this order:
|
|
|
239 |
|
|
|
240 |
<ol>
|
|
|
241 |
<li><a name="Headline"></a>The <b><em>headline</em></b> is conspicuous text
|
|
|
242 |
at the top of the page, usually the same as the
|
|
|
243 |
<a href="#Structure_head"><b><tt><title></tt></b></a> text. It is
|
|
|
244 |
always in a table whose purpose is to provide a colored background using
|
|
|
245 |
<b><tt>bgcolor</tt></b>, going the full width of the page:
|
|
|
246 |
|
|
|
247 |
<blockquote>
|
|
|
248 |
<b><tt><p><table width="100%" border="0"><br>
|
|
|
249 |
<tr><th align="center" bgcolor="#CCCC00"><font size=6></tt></b><br>
|
|
|
250 |
<b><em>{Text}</em></b><br>
|
|
|
251 |
<b><tt></font><br>
|
|
|
252 |
</table></tt></b>
|
|
|
253 |
</blockquote>
|
|
|
254 |
|
|
|
255 |
<li><a name="Table_of_contents"></a>
|
|
|
256 |
The <b><em>table of contents</em></b> consists of nested unordered
|
|
|
257 |
lists <b><tt><ul></tt></b>, in most documents assembled strictly from
|
|
|
258 |
the <b><tt><Hn></tt></b> headers. The levels of nesting in the table
|
|
|
259 |
of contents correspond to the level numbers of the headers.
|
|
|
260 |
|
|
|
261 |
<li>The <b><em>hint</em></b> is a short section suggesting where to look
|
|
|
262 |
for other related information. With very few exceptions this always
|
|
|
263 |
includes a reference and link to
|
|
|
264 |
<a href="Readme.htm"><b><tt>Readme.htm</tt></b></a>, but may include other
|
|
|
265 |
suggestions and references.
|
|
|
266 |
|
|
|
267 |
<li>The substance of the document.
|
|
|
268 |
|
|
|
269 |
<li>The <b><em>trailer</em></b> contains, in a small font size,
|
|
|
270 |
|
|
|
271 |
<ol type=a>
|
|
|
272 |
<li>the <b><em>copyright notice</em></b> and other legal boilerplate text
|
|
|
273 |
<li>the <b><em>version number</em></b> of Ghostscript and the
|
|
|
274 |
<b><em>date</em></b> when the file was last modified.
|
|
|
275 |
</ol>
|
|
|
276 |
</ol>
|
|
|
277 |
|
|
|
278 |
<p>
|
|
|
279 |
This document for an example of that structure.
|
|
|
280 |
|
|
|
281 |
<hr>
|
|
|
282 |
|
|
|
283 |
<h2><a name="Inner_structure"></a>HTML inner structure</h2>
|
|
|
284 |
|
|
|
285 |
<h3><a name="Structuring_comments"></a>Structuring comments</h3>
|
|
|
286 |
|
|
|
287 |
<p>
|
|
|
288 |
Special comment lines within the HTML files mark internally the visible
|
|
|
289 |
sections of the document. They make it easy for both document developers
|
|
|
290 |
and programs to handle the HTML code. Each of these comments is exactly 80
|
|
|
291 |
characters wide, and each important section of a document is bracketed by a
|
|
|
292 |
unique beginning and ending pair. View the source code of this document
|
|
|
293 |
for an example of these structuring comments. The sections they mark are:
|
|
|
294 |
|
|
|
295 |
<ol>
|
|
|
296 |
<li>the <b><em>visible header</em></b>
|
|
|
297 |
<ol type=a>
|
|
|
298 |
<li>the <a href="#Headline"><b><em>headline</em></b></a>
|
|
|
299 |
<li>the <b><em>table of contents</em></b>
|
|
|
300 |
<li>the "see also" <b><em>hints</em></b>
|
|
|
301 |
</ol>
|
|
|
302 |
<li>the <b><em>body</em></b>
|
|
|
303 |
<li>the <b><em>trailer</em></b>
|
|
|
304 |
</ol>
|
|
|
305 |
|
|
|
306 |
<h3><a name="Headers"></a>Headers: <b><tt><Hn></tt></b></h3>
|
|
|
307 |
|
|
|
308 |
<p>
|
|
|
309 |
Give a header <b><tt><Hn></tt></b> this structure:
|
|
|
310 |
|
|
|
311 |
<blockquote><b><tt>
|
|
|
312 |
<h2><a name="Head_anchor"></a>Header text</h2>
|
|
|
313 |
</tt></b></blockquote>
|
|
|
314 |
|
|
|
315 |
<p>
|
|
|
316 |
That is, the opening header tag, an anchor, the header text, and the
|
|
|
317 |
closing tag.
|
|
|
318 |
|
|
|
319 |
<p>
|
|
|
320 |
Represent every header in the table of contents, linked
|
|
|
321 |
<b><tt><a href="#..."></tt></b>...<b><tt></a></tt></b> to
|
|
|
322 |
the header. Of course, the headers are also convenient linkage points for
|
|
|
323 |
references from other documents.
|
|
|
324 |
|
|
|
325 |
<h3><a name="Anchors"></a>Anchors: <b><tt><a name="..."></tt></b></h3>
|
|
|
326 |
|
|
|
327 |
<p>
|
|
|
328 |
Give an anchor a name consisting only of letters, digits, dots
|
|
|
329 |
("<b><tt>.</tt></b>"), hyphens ("<b><tt>-</tt></b>"), and underscores
|
|
|
330 |
("<b><tt>_</tt></b>"), but not white space or other punctuation marks.
|
|
|
331 |
This ensures that the name is readable and that an entire name always
|
|
|
332 |
appears on a single line of HTML source both where it's defined and
|
|
|
333 |
everywhere it's used, making it simple to find anchors by text search in
|
|
|
334 |
the HTML source code.
|
|
|
335 |
|
|
|
336 |
<p>
|
|
|
337 |
Choose anchor names to be readable and meaningful in the HTML source code.
|
|
|
338 |
For instance:
|
|
|
339 |
|
|
|
340 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
341 |
<tr valign=bottom>
|
|
|
342 |
<th align=left>Use this form
|
|
|
343 |
<td>
|
|
|
344 |
<th align=left>... <b><em>NOT</em></b> this form
|
|
|
345 |
<tr> <td colspan=3><hr>
|
|
|
346 |
<tr valign=top> <td><b><tt><a name="Image_formats"></a></tt></b>
|
|
|
347 |
<td>
|
|
|
348 |
<td><b><tt><a name="Imgfts"></a></tt></b>
|
|
|
349 |
</table></blockquote>
|
|
|
350 |
|
|
|
351 |
<p>
|
|
|
352 |
Anchors should be empty, that is
|
|
|
353 |
|
|
|
354 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
355 |
<tr valign=bottom>
|
|
|
356 |
<th align=left>Use this form
|
|
|
357 |
<td>
|
|
|
358 |
<th align=left>... <b><em>NOT</em></b> this form
|
|
|
359 |
<tr> <td colspan=3><hr>
|
|
|
360 |
<tr valign=top> <td><b><tt><a name="..."></a></tt></b>
|
|
|
361 |
<td>
|
|
|
362 |
<td><b><tt><a name="..."></tt></b><b><em>anything</em></b><b><tt></a></tt></b>
|
|
|
363 |
</table></blockquote>
|
|
|
364 |
|
|
|
365 |
<p>
|
|
|
366 |
<a name="Anchor_placement"></a>Place an anchor within a paragraph (indented
|
|
|
367 |
paragraph, list item, head, etc.) and at its beginning.
|
|
|
368 |
|
|
|
369 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
370 |
<tr valign=bottom>
|
|
|
371 |
<th align=left>Use this form
|
|
|
372 |
<td>
|
|
|
373 |
<th align=left>... <b><em>NOT</em></b> this form
|
|
|
374 |
<tr> <td colspan=3><hr>
|
|
|
375 |
<tr valign=top> <td><b><tt><p><a name="..."></a></tt></b>
|
|
|
376 |
<td>
|
|
|
377 |
<td><b><tt><p></tt></b><b><em> ...text... </em></b><b><tt><a name="..."></a></tt></b>
|
|
|
378 |
<tr valign=top> <td><b><tt><p><a name="..."></a></tt></b>
|
|
|
379 |
<td>
|
|
|
380 |
<td><b><tt><a name="..."></a><p></tt></b>
|
|
|
381 |
<tr valign=top> <td><b><tt><li><a name="..."></a></tt></b>
|
|
|
382 |
<td>
|
|
|
383 |
<td><b><tt><a name="..."></a><li></tt></b>
|
|
|
384 |
</table></blockquote>
|
|
|
385 |
|
|
|
386 |
<hr>
|
|
|
387 |
|
|
|
388 |
<h2><a name="Text"></a>The presentation of text</h2>
|
|
|
389 |
|
|
|
390 |
<h3><a name="Text_sections"></a>Sections of text</h3>
|
|
|
391 |
|
|
|
392 |
<h4><a name="Paragraphs"></a>Paragraphs: <b><tt><p></tt></b></h4>
|
|
|
393 |
|
|
|
394 |
<p>
|
|
|
395 |
Define unindented paragraphs with <b><tt><p></tt></b>, never with
|
|
|
396 |
explicit line breaks <b><tt><br></tt></b>, and make them
|
|
|
397 |
ragged-right, not right-filled or centered. Put the paragraph tag
|
|
|
398 |
<b><tt><p></tt></b> on a line alone, except when it is
|
|
|
399 |
<a href="#Anchor_placement">followed immediately by an anchor</a>.
|
|
|
400 |
Don't place the anchor before the paragraph tag.
|
|
|
401 |
|
|
|
402 |
<h4><a name="Blockquote"></a>Indented paragraphs: <b><tt><blockquote></tt></b></h4>
|
|
|
403 |
|
|
|
404 |
<p>
|
|
|
405 |
Define indented paragraphs with <b><tt><blockquote></tt></b>. Avoid
|
|
|
406 |
elaborate nested indentation -- that is, more than two levels. It is
|
|
|
407 |
generally a poor idea to try to make indentation carry too much weight of
|
|
|
408 |
meaning for text, so use indentation simply to separate visual elements for
|
|
|
409 |
easier reading.
|
|
|
410 |
|
|
|
411 |
<h4><a name="Line_breaks"></a>Explicit line breaks: <b><tt><br></tt></b></h4>
|
|
|
412 |
|
|
|
413 |
<p>
|
|
|
414 |
Use explicit line breaks <b><tt><br></tt></b> sparingly, and never as
|
|
|
415 |
a substitute for paragraph tags. Do use them in
|
|
|
416 |
|
|
|
417 |
<ul>
|
|
|
418 |
<li>multi-line addresses
|
|
|
419 |
<li>formatted coding examples
|
|
|
420 |
<li>table entries, sparingly
|
|
|
421 |
</ul>
|
|
|
422 |
|
|
|
423 |
<h4><a name="Preformatted_text"></a>Preformatted text: <b><tt><pre></tt></b></h4>
|
|
|
424 |
|
|
|
425 |
<p>
|
|
|
426 |
Use preformatted text <b><tt><pre></tt></b> exclusively for material
|
|
|
427 |
that must be presented with exact spacing in a monospaced font, such as
|
|
|
428 |
extended coding examples. Where extended preformatted text seems likely to
|
|
|
429 |
be wider than a typical browser window, reduce the font size:
|
|
|
430 |
|
|
|
431 |
<blockquote>
|
|
|
432 |
<b><tt><font size="-1"><pre></tt></b><br>
|
|
|
433 |
<b><em>... Wide preformatted text ...</em></b><br>
|
|
|
434 |
<b><tt></pre></font></tt></b>
|
|
|
435 |
</blockquote>
|
|
|
436 |
|
|
|
437 |
<h3><a name="Use_of_fonts"></a>The use of different font faces</h3>
|
|
|
438 |
|
|
|
439 |
<p>
|
|
|
440 |
Do not use named fonts. Use only standard markup to specify fonts, as
|
|
|
441 |
shown in this table.
|
|
|
442 |
|
|
|
443 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
444 |
<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Use of fonts</font><hr>
|
|
|
445 |
<tr valign=bottom>
|
|
|
446 |
<th align=left>Tag
|
|
|
447 |
<td>
|
|
|
448 |
<th align=left>Used for
|
|
|
449 |
<tr> <td colspan=3><hr>
|
|
|
450 |
<tr valign=top> <td><b><tt><address></tt></b>
|
|
|
451 |
<td>
|
|
|
452 |
<td>Addresses in running text
|
|
|
453 |
<tr valign=top> <td><b><tt><b></tt></b>
|
|
|
454 |
<td>
|
|
|
455 |
<td>Emphasis everywhere
|
|
|
456 |
<tr valign=top> <td><b><tt><em></tt></b>
|
|
|
457 |
<td>
|
|
|
458 |
<td>Emphasis, usually in running text; with <b><tt><b></tt></b>, strong emphasis
|
|
|
459 |
<tr valign=top> <td><b><tt><font size=</tt></b><b><em>N</em></b><b><tt>></tt></b>
|
|
|
460 |
<td>
|
|
|
461 |
<td>Table headings, extended <b><tt><pre></tt></b> examples
|
|
|
462 |
<tr valign=top> <td><b><tt><pre></tt></b>
|
|
|
463 |
<td>
|
|
|
464 |
<td>Preformatted text (to control spacing)
|
|
|
465 |
<tr valign=top> <td><b><tt><small></tt></b>
|
|
|
466 |
<td>
|
|
|
467 |
<td>Superscripts (smaller than <b><tt><font size="-1"></tt></b>)
|
|
|
468 |
<tr valign=top> <td><b><tt><sup></tt></b>
|
|
|
469 |
<td>
|
|
|
470 |
<td>Superscripts
|
|
|
471 |
<tr valign=top> <td><b><tt><tt></tt></b>
|
|
|
472 |
<td>
|
|
|
473 |
<td>With <b><tt><b></tt></b>, used for specific names of
|
|
|
474 |
code, programs, and data in running text, and in short examples
|
|
|
475 |
</table></blockquote>
|
|
|
476 |
|
|
|
477 |
<hr>
|
|
|
478 |
|
|
|
479 |
<h2><a name="Lists"></a>Lists: <b><tt><ul>, <ol>, <dl></tt></b></h2>
|
|
|
480 |
|
|
|
481 |
<p>
|
|
|
482 |
Don't over-use lists: instead simply use clear wording in running text
|
|
|
483 |
wherever possible. Use a list where the special formatting improves the
|
|
|
484 |
material's clarity and readability.
|
|
|
485 |
|
|
|
486 |
<p>
|
|
|
487 |
Most simple lists should be unordered (bulleted) lists
|
|
|
488 |
<b><tt><ul></tt></b>. Use an ordered (numbered or alphabetized) list
|
|
|
489 |
<b><tt><ol></tt></b> only where the exact ordering or an exact count
|
|
|
490 |
is important.
|
|
|
491 |
|
|
|
492 |
<p>
|
|
|
493 |
Where entries in a descriptive list <b><tt><dl></tt></b> contain
|
|
|
494 |
extended descriptions <b><tt><dd></tt></b> -- especially if the
|
|
|
495 |
descriptions contain paragraph breaks or tables -- improve the spacing
|
|
|
496 |
between entries by making each entry a separate list. That is, enclose
|
|
|
497 |
each entry in a separate list to give it more readable spacing, rather than
|
|
|
498 |
putting many <b><tt><dt>...<dd>...</tt></b> entries in a single
|
|
|
499 |
list:
|
|
|
500 |
|
|
|
501 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
502 |
<tr valign=bottom>
|
|
|
503 |
<th align=left>Use this form
|
|
|
504 |
<td>
|
|
|
505 |
<th align=left>... <b><em>NOT</em></b> this form
|
|
|
506 |
<tr> <td colspan=3><hr>
|
|
|
507 |
<tr> <td valign=top>
|
|
|
508 |
<b><tt><dl></tt></b><br>
|
|
|
509 |
<b><tt><dt></tt></b>Term<br>
|
|
|
510 |
<b><tt><dd></tt></b>Description<br>
|
|
|
511 |
<b><tt><p></tt></b>Another paragraph of description<br>
|
|
|
512 |
<b><tt></dl></tt></b><br>
|
|
|
513 |
<br>
|
|
|
514 |
<b><tt><dl></tt></b><br>
|
|
|
515 |
<b><tt><dt></tt></b>Another term<br>
|
|
|
516 |
<b><tt><dd></tt></b>Another description<br>
|
|
|
517 |
<b><tt></dl></tt></b><br>
|
|
|
518 |
...<br>
|
|
|
519 |
<td>
|
|
|
520 |
<td valign=top>
|
|
|
521 |
<b><tt><dl></tt></b><br>
|
|
|
522 |
<b><tt><dt></tt></b>Term<br>
|
|
|
523 |
<b><tt><dd></tt></b>Description<br>
|
|
|
524 |
<b><tt><p></tt></b>Another paragraph of description<br>
|
|
|
525 |
<b><tt><dt></tt></b>Another term<br>
|
|
|
526 |
<b><tt><dd></tt></b>Another description<br>
|
|
|
527 |
...<br>
|
|
|
528 |
<b><tt></dl></tt></b>
|
|
|
529 |
</table></blockquote>
|
|
|
530 |
|
|
|
531 |
<p>
|
|
|
532 |
This may be more work for the HTML writer, but the results for the reader
|
|
|
533 |
are often much better.
|
|
|
534 |
|
|
|
535 |
<hr>
|
|
|
536 |
|
|
|
537 |
<h2><a name="Tables"></a>Tables: <b><tt><table></tt></b></h2>
|
|
|
538 |
|
|
|
539 |
<h3><a name="Readability"></a>Readability for the user and the HTML writer</h3>
|
|
|
540 |
|
|
|
541 |
<p>
|
|
|
542 |
Format tables to be as readable as possible both with a browser and when
|
|
|
543 |
converted to plain text. Browsers and converters of all kinds handle
|
|
|
544 |
tables idiosyncratically, so there seems to be more art than science to
|
|
|
545 |
reaching this end, which accounts for all the detail in the guidelines for
|
|
|
546 |
tables: it is the reason for all the uses of background color
|
|
|
547 |
<b><tt>bgcolor</tt></b>, horizontal rules <b><tt><hr></tt></b>, and
|
|
|
548 |
explicit spacing.
|
|
|
549 |
|
|
|
550 |
<p>
|
|
|
551 |
Secondarily, arrange HTML source code for tables to be readable by the
|
|
|
552 |
writer and developer.
|
|
|
553 |
|
|
|
554 |
<h3><a name="Table_guidelines"></a>Specific guidelines for coding tables</h3>
|
|
|
555 |
|
|
|
556 |
<ul>
|
|
|
557 |
<li>Large tables have heads with the same background color as the page's
|
|
|
558 |
<a href="#Headline">headline</a>. (Color is used only in tables and only
|
|
|
559 |
this way, and it is the same color everywhere. In consideration of
|
|
|
560 |
differences of color vision, the color is chosen so that normal black text
|
|
|
561 |
contrasts with a brighter background, and the color itself against white.)
|
|
|
562 |
|
|
|
563 |
<li>Do not use borders for tables; they almost invariably only clutter the
|
|
|
564 |
appearance without adding to clarity, and they don't convert well to plain
|
|
|
565 |
text. For visual spacing prefer white space.
|
|
|
566 |
|
|
|
567 |
<li>Set cell padding and spacing to 0. Use explicit white space for
|
|
|
568 |
readability, not implicit white space.
|
|
|
569 |
|
|
|
570 |
<li>Begin the code for a new row <b><tt><tr></tt></b> on a new line.
|
|
|
571 |
Generally use <b><tt>valign=top</tt></b> to control the placement of text
|
|
|
572 |
in a row for readability with a browser or as plain text.
|
|
|
573 |
|
|
|
574 |
<li>Code the first column of a row beginning on the same line as the
|
|
|
575 |
beginning of the row, and then begin every other column on a separate line.
|
|
|
576 |
Always precede <b><tt><td></tt></b> by a tab character.
|
|
|
577 |
|
|
|
578 |
<li>Separate two columns of substantive material by a visually empty column
|
|
|
579 |
of nonbreaking spaces for readability. Specify the width of this empty
|
|
|
580 |
column in the first row, and in all other rows give that column a single
|
|
|
581 |
nonbreaking space.
|
|
|
582 |
|
|
|
583 |
<li>Use horizontal rules and visually empty rows for clarity, but
|
|
|
584 |
sparingly. Be consistent with the existing tables.
|
|
|
585 |
|
|
|
586 |
<li>Give every cell some contents: put a nonbreaking space in a visually
|
|
|
587 |
empty cell as a placeholder.
|
|
|
588 |
</ul>
|
|
|
589 |
|
|
|
590 |
<h3><a name="Typical_table"></a>HTML code for typical tables</h3>
|
|
|
591 |
|
|
|
592 |
<p>
|
|
|
593 |
The HTML source code for a typical large table should look like this:
|
|
|
594 |
|
|
|
595 |
<blockquote>
|
|
|
596 |
<pre><table cellpadding=0 cellspacing=0>
|
|
|
597 |
<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Large table</font><hr>
|
|
|
598 |
<tr> <th align=left>...
|
|
|
599 |
<td>&nbsp;&nbsp;&nbsp;
|
|
|
600 |
<th align=left>...
|
|
|
601 |
<td>&nbsp;&nbsp;&nbsp;
|
|
|
602 |
<th align=left>...
|
|
|
603 |
<tr> <td>...
|
|
|
604 |
<td>&nbsp;&nbsp;
|
|
|
605 |
<td>...
|
|
|
606 |
<td>&nbsp;
|
|
|
607 |
<td>...
|
|
|
608 |
...
|
|
|
609 |
</table>
|
|
|
610 |
</pre></blockquote>
|
|
|
611 |
|
|
|
612 |
<p>
|
|
|
613 |
The HTML source code for a typical small table should look like this:
|
|
|
614 |
|
|
|
615 |
<blockquote>
|
|
|
616 |
<pre><table cellpadding=0 cellspacing=0>
|
|
|
617 |
<tr> <td>...
|
|
|
618 |
<td>&nbsp;&nbsp;&nbsp;
|
|
|
619 |
<td>...
|
|
|
620 |
<tr> <td>...
|
|
|
621 |
<td>&nbsp;
|
|
|
622 |
<td>...
|
|
|
623 |
...
|
|
|
624 |
</table>
|
|
|
625 |
</pre></blockquote>
|
|
|
626 |
|
|
|
627 |
<hr>
|
|
|
628 |
|
|
|
629 |
<h2><a name="Unused_tags"></a>Tags not used</h2>
|
|
|
630 |
|
|
|
631 |
<p>
|
|
|
632 |
Don't use optional tags (ones not required by the HTML standard). These
|
|
|
633 |
include <b><tt></dd></tt></b>, <b><tt></dt></tt></b>,
|
|
|
634 |
<b><tt></li></tt></b>, <b><tt></p></tt></b>,
|
|
|
635 |
<b><tt></tr></tt></b>, <b><tt></th></tt></b>, and
|
|
|
636 |
<b><tt></td></tt></b>.
|
|
|
637 |
|
|
|
638 |
<hr>
|
|
|
639 |
|
|
|
640 |
<h2><a name="New_document"></a>Creating a new document</h2>
|
|
|
641 |
|
|
|
642 |
<h3><a name="File_name"></a>Name the new document in 8+3 format</h3>
|
|
|
643 |
|
|
|
644 |
<p>
|
|
|
645 |
If you create a new Ghostscript HTML document, choose for it a name in 8+3
|
|
|
646 |
format for cross-platform compabitility:
|
|
|
647 |
|
|
|
648 |
<blockquote>
|
|
|
649 |
<b><em>Name</em></b><b><tt>.htm</tt></b>
|
|
|
650 |
</blockquote>
|
|
|
651 |
|
|
|
652 |
<p>
|
|
|
653 |
where "<b><em>Name</em></b>" is no more than eight characters.
|
|
|
654 |
|
|
|
655 |
<p>
|
|
|
656 |
Begin the new file name with an upper-case letter like the existing names,
|
|
|
657 |
which are in mixed case beginning with upper-case letters. Use spelling,
|
|
|
658 |
not case, to distinguish between names: that is, don't create a new file
|
|
|
659 |
whose name differs from an existing one only by the difference between
|
|
|
660 |
upper and lower case, because some platforms can't store two such files.
|
|
|
661 |
|
|
|
662 |
<h3><a name="Plagiarize"></a>Use an existing document as a model</h3>
|
|
|
663 |
|
|
|
664 |
<p>
|
|
|
665 |
To create an entirely new Ghostscript document, plagiarize this one for the
|
|
|
666 |
<a href="#Structuring_comments">structuring comments</a> and other useful
|
|
|
667 |
parts. Then, using the <a href="#Structuring_comments">structuring
|
|
|
668 |
comments</a> as a guide to the sections of the document (in a text editor,
|
|
|
669 |
search for "<b><tt><!-- [</tt></b>"):
|
|
|
670 |
|
|
|
671 |
<ul>
|
|
|
672 |
<li>insert your own HTML title and <a href="#Headline">headline</a> (they
|
|
|
673 |
should ordinarily be the same text) in place of the old ones;
|
|
|
674 |
|
|
|
675 |
<li>insert your own RCS <b><tt>$Id</tt></b> in place of the old one in the
|
|
|
676 |
<a href="#Structure_head">HTML header</a>;
|
|
|
677 |
|
|
|
678 |
<li>delete the old entries in the <a href="#Table_of_contents">table of
|
|
|
679 |
contents</a>;
|
|
|
680 |
|
|
|
681 |
<li>keep the hint paragraph;
|
|
|
682 |
|
|
|
683 |
<li>delete the entire contents section between the structuring comments;
|
|
|
684 |
and
|
|
|
685 |
|
|
|
686 |
<li>in the trailer, update the version number and date.
|
|
|
687 |
</ul>
|
|
|
688 |
|
|
|
689 |
<p>
|
|
|
690 |
You now have a template document ready for new contents.
|
|
|
691 |
|
|
|
692 |
<h3><a name="Readme_material"></a>Write new references to go in <b><tt>Readme.htm</tt></b></h3>
|
|
|
693 |
|
|
|
694 |
<p>
|
|
|
695 |
Write material to go in <a href="Readme.htm"><b><tt>Readme.htm</tt></b></a>
|
|
|
696 |
that describes the new document, and links to it from two sections:
|
|
|
697 |
|
|
|
698 |
<ul>
|
|
|
699 |
<li>the <a href="Readme.htm#Theme_roadmap">thematic section</a> and
|
|
|
700 |
|
|
|
701 |
<li>the descriptions of documentation
|
|
|
702 |
<a href="Readme.htm#Ordered_roadmap">arranged by file name</a>.
|
|
|
703 |
</ul>
|
|
|
704 |
|
|
|
705 |
<h3><a name="New_doc_other"></a>Other considerations</h3>
|
|
|
706 |
|
|
|
707 |
<p>
|
|
|
708 |
Follow the other guidelines here, including which elements of the
|
|
|
709 |
document should go in which section according to the structuring comments,
|
|
|
710 |
and <a href="#Headers">anchoring every <b><tt><Hn></tt></b>
|
|
|
711 |
header</a>. As you create text and headers, you will want to rebuild the
|
|
|
712 |
<a href="#Table_of_contents">table of contents</a> from the headers
|
|
|
713 |
occasionally.
|
|
|
714 |
|
|
|
715 |
<p>
|
|
|
716 |
Pete Kaiser <<a href="mailto:kaiser@acm.org">kaiser@acm.org</a>>
|
|
|
717 |
wrote a package of GNU emacs functions specifically to handle Ghostscript
|
|
|
718 |
HTML documentation, including functions to build a table of contents from
|
|
|
719 |
headers in an HTML document, and to build and maintain tables and
|
|
|
720 |
other structures built along the guidelines in this document.
|
|
|
721 |
|
|
|
722 |
<hr>
|
|
|
723 |
|
|
|
724 |
<h2><a name="Miscellany"></a>Miscellany</h2>
|
|
|
725 |
|
|
|
726 |
<p>
|
|
|
727 |
Use <b><tt><></tt></b> to bracket links to visible email addresses
|
|
|
728 |
(<b><tt>mailto</tt></b>) in running text. This makes it easy for a user to
|
|
|
729 |
cut and paste the entire name and address into another document or mailer,
|
|
|
730 |
for instance
|
|
|
731 |
|
|
|
732 |
<blockquote>
|
|
|
733 |
Free Software Foundation <<a href="mailto:gnu@gnu.org">gnu@gnu.org</a>>
|
|
|
734 |
</blockquote>
|
|
|
735 |
|
|
|
736 |
<p>
|
|
|
737 |
For exponentiation use "<b><tt>^</tt></b>" (not "**" or "exp()") plus
|
|
|
738 |
writing the exponent as a superscript in <b><tt><small></tt></b>
|
|
|
739 |
size:
|
|
|
740 |
|
|
|
741 |
<blockquote>
|
|
|
742 |
Something<b><tt>^<sup></tt></b><b><tt><small></tt></b>exponent<b><tt></small></sup></tt></b>.
|
|
|
743 |
</blockquote>
|
|
|
744 |
|
|
|
745 |
<p>
|
|
|
746 |
to look like this:
|
|
|
747 |
|
|
|
748 |
<blockquote>
|
|
|
749 |
Something<b><tt>^</tt></b><sup><small>exponent</small></sup>
|
|
|
750 |
</blockquote>
|
|
|
751 |
|
|
|
752 |
<p>
|
|
|
753 |
This is intended for readability both in a browser and as plain text.
|
|
|
754 |
|
|
|
755 |
<!-- [2.0 end contents] ==================================================== -->
|
|
|
756 |
|
|
|
757 |
<!-- [3.0 begin visible trailer] =========================================== -->
|
|
|
758 |
<hr>
|
|
|
759 |
|
|
|
760 |
<p>
|
|
|
761 |
<small>Copyright © 1996, 2000 Aladdin Enterprises. All rights
|
|
|
762 |
reserved.</small>
|
|
|
763 |
|
|
|
764 |
<p>
|
|
|
765 |
This software is provided AS-IS with no warranty, either express or
|
|
|
766 |
implied.
|
|
|
767 |
|
|
|
768 |
This software is distributed under license and may not be copied,
|
|
|
769 |
modified or distributed except as expressly authorized under the terms
|
|
|
770 |
of the license contained in the file LICENSE in this distribution.
|
|
|
771 |
|
|
|
772 |
For more information about licensing, please refer to
|
|
|
773 |
http://www.ghostscript.com/licensing/. For information on
|
|
|
774 |
commercial licensing, go to http://www.artifex.com/licensing/ or
|
|
|
775 |
contact Artifex Software, Inc., 101 Lucas Valley Road #110,
|
|
|
776 |
San Rafael, CA 94903, U.S.A., +1(415)492-9861.
|
|
|
777 |
|
|
|
778 |
<p>
|
|
|
779 |
<small>Ghostscript version 8.53, 20 October 2005
|
|
|
780 |
|
|
|
781 |
<!-- [3.0 end visible trailer] ============================================= -->
|
|
|
782 |
|
|
|
783 |
</body>
|
|
|
784 |
</html>
|