HTML coding and style guidelines for Ghostscript documentation

Table of contents

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

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

  1. 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;
  2. the substantive contents;
  3. 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

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

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:

  1. A <title>, usually the same text as the headline
  2. An RCS identification line giving the name of the file in an HTML comment:
    <!-- $Id: {file name}.htm $ -->
  3. 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:
    <!-- Originally: {file name} -->

HTML <body>

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

  1. 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>
  2. 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.
  3. 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.
  4. The substance of the document.
  5. 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:

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

Headers: <Hn>

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.

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>

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>

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

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

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>

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

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>&nbsp;&nbsp;&nbsp;
        <th align=left>...
        <td>&nbsp;&nbsp;&nbsp;
        <th align=left>...
<tr>    <td>...
        <td>&nbsp;&nbsp;
        <td>...
        <td>&nbsp;
        <td>...
...
</table>

The HTML source code for a typical small table should look like this:

<table cellpadding=0 cellspacing=0>
<tr>    <td>...
        <td>&nbsp;&nbsp;&nbsp;
        <td>...
<tr>    <td>...
        <td>&nbsp;
        <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 "<!-- ["):

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:

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.


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