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 proprietary products. See Make.htm for an example, the reference to InfoZip unzip (where many proprietary 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.
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:
Besides the essential HTML structure elements, Ghostscript HTML document's <head> consists of following elements in this order:
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<!-- $Id: {file name}.htm $ -->
<!-- Originally: {file name} -->
A Ghostscript HTML document's <body> consists of elements in this order:
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:
<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.
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>
Define unindented paragraphs with <p>, not explicit line breaks <br>. Do not fully-justify or centre paragraphs.
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>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.
...Wide preformatted text...
</pre></font>
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 Element Used for address Addresses in running text em Emphasis strong Strong emphasis th Table headings pre Preformatted text (to control spacing) sup Superscripts tt 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 (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
* 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.
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.
The HTML source code for a typical large table should look like this:
<table>
<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Large table</font><hr>
<tr align=left><th>...
<th>...
<th>...
<tr> <td>...
<td>...
<td>...
...
</table>
The HTML source code for a typical small table should look like this:
<table>
<tr> <td>...
<td>...
<tr> <td>...
<td>...
...
</table>
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.
If you create a new Ghostscript HTML document, choose a name with 3 letters extension, separated by a dot, for cross-platform compabitility:
Name.htm
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:
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 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 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 [gnu@gnu.org]
For exponentiation use "^" (not "**" or "exp()") plus writing the exponent as a superscript size, and use non-inline stylesheet to make superscript smaller:
Something^<sup>exponent</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. For more information about licensing, please refer to http://www.ghostscript.com/licensing/. For information on commercial licensing, go to http://www.artifex.com/licensing/ 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