|
|
For other information, see the Ghostscript overview.
The most important intention in casting Ghostscript's documentation into Hypertext Markup Language (HTML) from simple text form is to improve its usefulness greatly to those who use, install, and build Ghostscript: everything else is details. The wide spread of World Wide Web browsers now makes it possible to distribute documents which are not only readable as text, but also richly cross-linked as hypertext. Using hypertext through a browser can reduce the effort required to find and use the information people often need in order to use Ghostscript.
The remainder of this document expresses the guidelines used to create the HTML form of the Ghostscript documentation. The guidelines are intended to encourage
Here are those guidelines.
What the user sees browsing the documentation, and what a document developer or editor sees working with it, are different. This section is about what the user sees.
A Ghostscript document in HTML form should consist of
This document is an example of this standard visible structure. Also see below about "Structuring comments" in HTML source code.
Where it makes sense to modify the standard structure to make the document more usable, do that. See Readme.htm for an example: the introductory material at the beginning of the visible header, before the table of contents.
Links to sites and documents outside the ghostscript distribution
must carry the class="offsite" attribute and value. This signals special
formatting to the stylesheet to assist users reading offline.
Avoid gratuitous commercial links; for instance, link the title of a book to its publisher, not to one particular on-line bookseller. See Language.htm for an example, the reference to the PostScript Language Reference Manual.
Similarly, where you have a choice, refer to free software rather than commercial products. See Make.htm for an example, the reference to InfoZip unzip (where many commercial products provide similar functions).
Use no graphics or images. The documents are text-only, so nothing is lost when a document is converted into ASCII text. This is an explicit initial design goal of the HTML documentation.
index.html is not a part of the visible Ghostscript documentation itself, but when it is placed with all the *.htm files in a directory and a browser refers to the directory name alone, most servers are configured to deliver a file named index.html by default. This one does nothing except immediately to open the introductory Ghostscript document Readme.htm. This is intended to make life easier for both webmasters and users.
Besides the essential HTML structure elements, Ghostscript HTML document's <head> consists of three elements in this order:
<!-- $Id: {file name}.htm $ -->
<!-- Originally: {file name} -->
A Ghostscript HTML document's <body> consists of five elements in this order:
<p><table width="100%" border="0">
<tr><th align="center" bgcolor="#CCCC00"><font size=6>
{Text}
</font>
</table>
This document for an example of that structure.
Special comment lines within the HTML files mark internally the visible sections of the document. They make it easy for both document developers and programs to handle the HTML code. Each of these comments is exactly 80 characters wide, and each important section of a document is bracketed by a unique beginning and ending pair. View the source code of this document for an example of these structuring comments. The sections they mark are:
Give a header <Hn> this structure:
<h2><a name="Head_anchor"></a>Header text</h2>
That is, the opening header tag, an anchor, the header text, and the closing tag.
Represent every header in the table of contents, linked <a href="#...">...</a> to the header. Of course, the headers are also convenient linkage points for references from other documents.
Give an anchor a name consisting only of letters, digits, dots ("."), hyphens ("-"), and underscores ("_"), but not white space or other punctuation marks. This ensures that the name is readable and that an entire name always appears on a single line of HTML source both where it's defined and everywhere it's used, making it simple to find anchors by text search in the HTML source code.
Choose anchor names to be readable and meaningful in the HTML source code. For instance:
Use this form ... NOT this form
<a name="Image_formats"></a> <a name="Imgfts"></a>
Anchors should be empty, that is
Use this form ... NOT this form
<a name="..."></a> <a name="...">anything</a>
Place an anchor within a paragraph (indented paragraph, list item, head, etc.) and at its beginning.
Use this form ... NOT this form
<p><a name="..."></a> <p> ...text... <a name="..."></a> <p><a name="..."></a> <a name="..."></a><p> <li><a name="..."></a> <a name="..."></a><li>
Define unindented paragraphs with <p>, never with explicit line breaks <br>, and make them ragged-right, not right-filled or centered. Put the paragraph tag <p> on a line alone, except when it is followed immediately by an anchor. Don't place the anchor before the paragraph tag.
Define indented paragraphs with <blockquote>. Avoid elaborate nested indentation -- that is, more than two levels. It is generally a poor idea to try to make indentation carry too much weight of meaning for text, so use indentation simply to separate visual elements for easier reading.
Use explicit line breaks <br> sparingly, and never as a substitute for paragraph tags. Do use them in
Use preformatted text <pre> exclusively for material that must be presented with exact spacing in a monospaced font, such as extended coding examples. Where extended preformatted text seems likely to be wider than a typical browser window, reduce the font size:
<font size="-1"><pre>
... Wide preformatted text ...
</pre></font>
Do not use named fonts. Use only standard markup to specify fonts, as shown in this table.
Use of fonts
Tag Used for
<address> Addresses in running text <b> Emphasis everywhere <em> Emphasis, usually in running text; with <b>, strong emphasis <font size=N> Table headings, extended <pre> examples <pre> Preformatted text (to control spacing) <small> Superscripts (smaller than <font size="-1">) <sup> Superscripts <tt> With <b>, used for specific names of code, programs, and data in running text, and in short examples
Don't over-use lists: instead simply use clear wording in running text wherever possible. Use a list where the special formatting improves the material's clarity and readability.
Most simple lists should be unordered (bulleted) lists <ul>. Use an ordered (numbered or alphabetized) list <ol> only where the exact ordering or an exact count is important.
Where entries in a descriptive list <dl> contain extended descriptions <dd> -- especially if the descriptions contain paragraph breaks or tables -- improve the spacing between entries by making each entry a separate list. That is, enclose each entry in a separate list to give it more readable spacing, rather than putting many <dt>...<dd>... entries in a single list:
Use this form ... NOT this form
<dl>
<dt>Term
<dd>Description
<p>Another paragraph of description
</dl>
<dl>
<dt>Another term
<dd>Another description
</dl>
...
<dl>
<dt>Term
<dd>Description
<p>Another paragraph of description
<dt>Another term
<dd>Another description
...
</dl>
This may be more work for the HTML writer, but the results for the reader are often much better.
Format tables to be as readable as possible both with a browser and when converted to plain text. Browsers and converters of all kinds handle tables idiosyncratically, so there seems to be more art than science to reaching this end, which accounts for all the detail in the guidelines for tables: it is the reason for all the uses of background color bgcolor, horizontal rules <hr>, and explicit spacing.
Secondarily, arrange HTML source code for tables to be readable by the writer and developer.
The HTML source code for a typical large table should look like this:
<table cellpadding=0 cellspacing=0>
<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Large table</font><hr>
<tr> <th align=left>...
<td>
<th align=left>...
<td>
<th align=left>...
<tr> <td>...
<td>
<td>...
<td>
<td>...
...
</table>
The HTML source code for a typical small table should look like this:
<table cellpadding=0 cellspacing=0>
<tr> <td>...
<td>
<td>...
<tr> <td>...
<td>
<td>...
...
</table>
Don't use optional tags (ones not required by the HTML standard). These include </dd>, </dt>, </li>, </p>, </tr>, </th>, and </td>.
If you create a new Ghostscript HTML document, choose for it a name in 8+3 format for cross-platform compabitility:
Name.htm
where "Name" is no more than eight characters.
Begin the new file name with an upper-case letter like the existing names, which are in mixed case beginning with upper-case letters. Use spelling, not case, to distinguish between names: that is, don't create a new file whose name differs from an existing one only by the difference between upper and lower case, because some platforms can't store two such files.
To create an entirely new Ghostscript document, plagiarize this one for the structuring comments and other useful parts. Then, using the structuring comments as a guide to the sections of the document (in a text editor, search for "<!-- ["):
You now have a template document ready for new contents.
Write material to go in Readme.htm that describes the new document, and links to it from two sections:
Follow the other guidelines here, including which elements of the document should go in which section according to the structuring comments, and anchoring every <Hn> header. As you create text and headers, you will want to rebuild the table of contents from the headers occasionally.
Pete Kaiser <kaiser@acm.org> wrote a package of GNU emacs functions specifically to handle Ghostscript HTML documentation, including functions to build a table of contents from headers in an HTML document, and to build and maintain tables and other structures built along the guidelines in this document.
Use <> to bracket links to visible email addresses (mailto) in running text. This makes it easy for a user to cut and paste the entire name and address into another document or mailer, for instance
Free Software Foundation <gnu@gnu.org>
For exponentiation use "^" (not "**" or "exp()") plus writing the exponent as a superscript in <small> size:
Something^<sup><small>exponent</small></sup>.
to look like this:
Something^exponent
This is intended for readability both in a browser and as plain text.
Copyright © 1996, 2000 Aladdin Enterprises. All rights reserved.
This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of the license contained in the file LICENSE in this distribution.
Ghostscript version 7.07, 17 May 2003