HTML coding and style guidelines for Ghostscript documentation

Table of contents

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.

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 proprietary products. See Make.htm for an example, the reference to InfoZip unzip (where many proprietary 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 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


SGML element !DOCTYPE is used to tell brower the kind of document is being viewed, as well as the Document Type Definition (DTD) being used for HTML/XHTML documents. For consistency and compatibility sake, Ghostscript manual is a HTML, not XHTML document. Ghostscript follows the latest HTML standard, and only uses standard DTD. At of time of writing this document, only following !DOCTYPE elements are considered as valid for a Ghostscript manual:

HTML <head>

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

  1. A <title>, usually the same text as the headline
  2. A <meta>, required to inform browser on document's own encoding. This is especially important for making localized manuals:
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  3. An RCS identification line giving the name of the file in an HTML comment:
    <!-- $Id: {file name}.htm $ -->
  4. 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 elements in this order:

  1. The headline is conspicuous text at the top of the page, usually the same as the <title> text. It has colored background and the width of the page, formatted by stylesheet.
  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:

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

That is, an anchor, the opening header tag, 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:

Use this form ... NOT this form
<a name="..."></a> <a name="...">anything</a>
<a name="..."></a> <a name="..." />

To avoid accidental altering of document structure when inserting texts, place an anchor before the start tag of a paragraph (indented paragraph, list item, head, etc.),

Use this form ... NOT this form
<a name="..."></a><p> <p>...text...<a name="..."></a>
<a name="..."></a><p> <p><a name="..."></a>
<a name="..."></a><li> <li><a name="..."></a>

The presentation of text

Sections of text

Paragraphs: <p>

Define unindented paragraphs with <p>, not explicit line breaks <br>. Do not fully-justify or centre paragraphs.

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...
However, even with reduced font size, there are chances that preformatted text to be wider than typical browser window. The affected code lines should be broken up whenever possible. Even by following above guides, do not expect readers to see every preformatted line to fit into a 'typical' browser window.

The use of different font faces

Avoid using FONT element when using a different font. Inline stylesheet should be restricted to isolated usages. For example, if certain font is explicitly used for more than once per document, or being used consistently for certain type of contents such as example code, inline stylesheet should be replaced by non-inline versions.

When a font is used, only specifies generic font family, unless documentation requires showing an example rendering of certain font, or if the manual is not displayed properly on browsers that come with the operating systems supported by Ghostscript. When a specific font is used, generic font family name (if any applicable family exists) must be included in stylesheet properties, to allow substitute fonts be shown to users who don't have the specific fonts.

Previous versions of HTML coding and style guidelines incorrectly refer certain HTML element as fonts. These elements are not fonts, and are not substitutes for using stylesheets to format certain types of texts.

Use of elements
ElementUsed for
addressAddresses in running text
strongStrong emphasis
thTable headings
prePreformatted text (to control spacing)
ttSpecific 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 (serialized) list <ol> only where the exact ordering or an exact count is important.

Where entries in a definition list <dl> contain extended descriptions <dd> -- especially if the descriptions contain paragraph breaks or tables -- use stylesheet to insert margin between terms, to make it more readale. Do not create empty list, because such act alters document structure, which makes the list difficult to maintain, especially when using nested lists.

Use this form* ... NOT this form
<p>Another paragraph of description
<dt>Another term
<dd>Another description
<p>Another paragraph of description

<dt>Another term
<dd>Another description

* To format the content, use non-zero value on margin-bottom property on element DT.

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. Nevertheless, the guideline expects the document to be run on standard compliant browsers, so it is not a good idea to use table to substitute CSS formatting, even if some popular browsers do not fully support CSS properties. Fortunately, Ghostscript documents tends to stick with CSS1 formatting, so even if a popular browser does not fully support all the latest CSS properties, the fallback presentation should be at least readable.

Secondarily, arrange HTML source code for tables to be readable by the writer and developer.

Thirdly, avoid using 1-column tables.

Specific guidelines for coding tables

HTML code for typical tables

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

<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Large table</font><hr>
<tr align=left><th>...
<tr>    <td>...

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

<tr>    <td>...
<tr>    <td>...

Tags not used

If a document's own format and DTD combination supports optional end tags for a given element, do not use the end tag. For specific tags that supports end tags, consult HTML specification and the DTD settings used by Ghostscript manual. For HTML 4.01 with default DTD, affected elements include DD, DT, LI, P, TR, TH, TD.

Creating a new document

Naming new document

If you create a new Ghostscript HTML document, choose a name with 3 letters extension, separated by a dot, for cross-platform compabitility:


where "Name" should have no more than 8 characters, unless extra characters are necessary to clearly summerize the purpose of the individual document.

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.

There are file systems and environments that can handle characters not defined by ASCII. File name must not be written using those characters because:

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, use 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 <> 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 square bracket to quote links to visible email addresses (mailto) in inline 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 []

For exponentiation use "^" (not "**" or "exp()") plus writing the exponent as a superscript size, and use non-inline stylesheet to make superscript smaller:


to look like this:


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. For more information about licensing, please refer to For information on commercial licensing, go to or contact Artifex Software, Inc., 101 Lucas Valley Road #110, San Rafael, CA 94903, U.S.A., +1(415)492-9861.

Ghostscript version 8.53, 20 October 2005