HTML coding and style guidelines for Ghostscript documentation

Introduction
Appearance and contents

Page structure
Links to outside the Ghostscript documentation
Images and graphics
index.html

HTML large structure

HTML <head>
HTML <body>

HTML inner structure

Structuring comments
Headers: <Hn>
Anchors: <a name="...">

The presentation of text

Sections of text

Paragraphs: <p>
Indented paragraphs: <blockquote>
Explicit line breaks: <br>
Preformatted text: <pre>

The use of different font faces

Lists: <ul>, <ol>, <dl>
Tables: <table>

Readability for the user and the HTML writer
Specific guidelines for coding tables
HTML code for typical tables

Tags not used
Creating a new document

Name the new document in 8+3 format
Use an existing document as a model
Write new references to go in Readme.htm
Other considerations

Miscellany

For other information, see the Ghostscript overview.

Introduction

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

documents that are easy to read and understand in all of the most-used forms: on screen with a browser, printed by a browser, or as plain text;
correct HTML that conforms to prevailing standards;
consistent HTML coding among all Ghostscript's documents; and
HTML documents that are as simple as possible in light of their contents; free of difficult, little-used, or proprietary constructs; and easy to understand and modify.

Here are those guidelines.

Appearance and contents

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.

Page structure

A Ghostscript document in HTML form should consist of

a visual header containing
1. a conspicuous highlighted headline;
2. a table of contents;
3. "hints": references to other useful documents, always including Readme.htm;
the substantive contents;
a visual trailer consisting entirely of
1. standard copyright and licensing text;
2. the Ghostscript version number; and
3. the date when the document was last modified.

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 outside the Ghostscript documentation

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).

Images and graphics

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`

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.

HTML large structure

HTML `<head>`

Besides the essential HTML structure elements, Ghostscript HTML document's <head> consists of three elements in this order:

A <title>, usually the same text as the headline
An RCS identification line giving the name of the file in an HTML comment:

For documents converted from another form, an HTML comment line giving the name of the original file before it was edited and converted to HTML:

HTML `<body>`

A Ghostscript HTML document's <body> consists of five elements in this order:

The headline is conspicuous text at the top of the page, usually the same as the <title> text. It is always in a table whose purpose is to provide a colored background using bgcolor, going the full width of the page:
<p><table width="100%" border="0"> <tr><th align="center" bgcolor="#CCCC00"><font size=6>
{Text}
</font> </table>
The table of contents consists of nested unordered lists <ul>, in most documents assembled strictly from the <Hn> headers. The levels of nesting in the table of contents correspond to the level numbers of the headers.
The hint is a short section suggesting where to look for other related information. With very few exceptions this always includes a reference and link to Readme.htm, but may include other suggestions and references.
The substance of the document.
The trailer contains, in a small font size,
1. the copyright notice and other legal boilerplate text
2. the version number of Ghostscript and the date when the file was last modified.

This document for an example of that structure.

HTML inner structure

Structuring comments

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:

the visible header
1. the headline
2. the table of contents
3. the "see also" hints
the body
the trailer

Headers: `<Hn>`

Give a header <Hn> this structure:

<h1><a name="Head_anchor"></a>Header text</h1>

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.

Anchors: `<a name="...">`

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>

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>

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>

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>`

The presentation of text

Sections of text

Paragraphs: `<p>`

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.

Indented paragraphs: `<blockquote>`

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.

Explicit line breaks: `<br>`

Use explicit line breaks <br> sparingly, and never as a substitute for paragraph tags. Do use them in

multi-line addresses
formatted coding examples
table entries, sparingly

Preformatted text: `<pre>`

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>

The use of different font faces

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

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

Lists: `<ul>, <ol>, <dl>`

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>

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.

Tables: `<table>`

Readability for the user and the HTML writer

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.

Specific guidelines for coding tables

Large tables have heads with the same background color as the page's headline. (Color is used only in tables and only this way, and it is the same color everywhere. In consideration of differences of color vision, the color is chosen so that normal black text contrasts with a brighter background, and the color itself against white.)
Do not use borders for tables; they almost invariably only clutter the appearance without adding to clarity, and they don't convert well to plain text. For visual spacing prefer white space.
Set cell padding and spacing to 0. Use explicit white space for readability, not implicit white space.
Begin the code for a new row <tr> on a new line. Generally use valign=top to control the placement of text in a row for readability with a browser or as plain text.
Code the first column of a row beginning on the same line as the beginning of the row, and then begin every other column on a separate line. Always precede <td> by a tab character.
Separate two columns of substantive material by a visually empty column of nonbreaking spaces for readability. Specify the width of this empty column in the first row, and in all other rows give that column a single nonbreaking space.
Use horizontal rules and visually empty rows for clarity, but sparingly. Be consistent with the existing tables.
Give every cell some contents: put a nonbreaking space in a visually empty cell as a placeholder.

HTML code for typical tables

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>

Tags not used

Don't use optional tags (ones not required by the HTML standard). These include </dd>, </dt>, </li>, </p>, </tr>, </th>, and </td>.

Creating a new document

Name the new document in 8+3 format

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.

Use an existing document as a model

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 "<!-- ["):

insert your own HTML title and headline (they should ordinarily be the same text) in place of the old ones;
insert your own RCS $Id in place of the old one in the HTML header;
delete the old entries in the table of contents;
keep the hint paragraph;
delete the entire contents section between the structuring comments; and
in the trailer, update the version number and date.

You now have a template document ready for new contents.

Write new references to go in `Readme.htm`

Write material to go in Readme.htm that describes the new document, and links to it from two sections:

the thematic section and
the descriptions of documentation arranged by file name.

Other considerations

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.

Miscellany

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.

This file is part of Aladdin Ghostscript. See the Aladdin Free Public License (the "License") for full details of the terms of using, copying, modifying, and redistributing Aladdin Ghostscript.

Ghostscript version 6.0, 3 February 2000

Table of contents