123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <head>
- <title>HTML coding and style guidelines for Ghostscript documentation</title>
- <!-- $Id: Htmstyle.htm,v 1.18.2.2 2002/02/01 05:31:25 raph Exp $ -->
- <link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
- </head>
- <body>
- <!-- [1.0 begin visible header] ============================================ -->
- <!-- [1.1 begin headline] ================================================== -->
- <h1>HTML coding and style guidelines for Ghostscript documentation</h1>
- <!-- [1.1 end headline] ==================================================== -->
- <!-- [1.2 begin table of contents] ========================================= -->
- <h2>Table of contents</h2>
- <blockquote><ul>
- <li><a href="#Introduction">Introduction</a>
- <li><a href="#Appearance">Appearance and contents</a>
- <ul>
- <li><a href="#Page_structure">Page structure</a>
- <li><a href="#Links_outside">Links to outside the Ghostscript documentation</a>
- <li><a href="#Images">Images and graphics</a>
- <li><a href="#index.html"><b><tt>index.html</tt></b></a>
- </ul>
- <li><a href="#Large_structure">HTML large structure</a>
- <ul>
- <li><a href="#HTML_head">HTML <b><tt><head></tt></b></a>
- <li><a href="#HTML_body">HTML <b><tt><body></tt></b></a>
- </ul>
- <li><a href="#Inner_structure">HTML inner structure</a>
- <ul>
- <li><a href="#Structuring_comments">Structuring comments</a>
- <li><a href="#Headers">Headers: <b><tt><Hn></tt></b></a>
- <li><a href="#Anchors">Anchors: <b><tt><a name="..."></tt></b></a>
- </ul>
- <li><a href="#Text">The presentation of text</a>
- <ul>
- <li><a href="#Text_sections">Sections of text</a>
- <ul>
- <li><a href="#Paragraphs">Paragraphs: <b><tt><p></tt></b></a>
- <li><a href="#Blockquote">Indented paragraphs: <b><tt><blockquote></tt></b></a>
- <li><a href="#Line_breaks">Explicit line breaks: <b><tt><br></tt></b></a>
- <li><a href="#Preformatted_text">Preformatted text: <b><tt><pre></tt></b></a>
- </ul>
- <li><a href="#Use_of_fonts">The use of different font faces</a>
- </ul>
- <li><a href="#Lists">Lists: <b><tt><ul>, <ol>, <dl></tt></b></a>
- <li><a href="#Tables">Tables: <b><tt><table></tt></b></a>
- <ul>
- <li><a href="#Readability">Readability for the user and the HTML writer</a>
- <li><a href="#Table_guidelines">Specific guidelines for coding tables</a>
- <li><a href="#Typical_table">HTML code for typical tables</a>
- </ul>
- <li><a href="#Unused_tags">Tags not used</a>
- <li><a href="#New_document">Creating a new document</a>
- <ul>
- <li><a href="#File_name">Name the new document in 8+3 format</a>
- <li><a href="#Plagiarize">Use an existing document as a model</a>
- <li><a href="#Readme_material">Write new references to go in <b><tt>Readme.htm</tt></b></a>
- <li><a href="#New_doc_other">Other considerations</a>
- </ul>
- <li><a href="#Miscellany">Miscellany</a>
- </ul></blockquote>
- <!-- [1.2 end table of contents] =========================================== -->
- <!-- [1.3 begin hint] ====================================================== -->
- <p>For other information, see the <a href="Readme.htm">Ghostscript
- overview</a>.
- <!-- [1.3 end hint] ======================================================== -->
- <hr>
- <!-- [1.0 end visible header] ============================================== -->
- <!-- [2.0 begin contents] ================================================== -->
- <h2><a name="Introduction"></a>Introduction</h2>
- <p>
- 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.
- <p>
- The remainder of this document expresses the guidelines used to create the
- HTML form of the Ghostscript documentation. The guidelines are intended to
- encourage
- <ul>
- <li>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;
- <li>correct HTML that conforms to prevailing standards;
- <li>consistent HTML coding among all Ghostscript's documents; and
- <li>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.
- </ul>
- <p>
- Here are those guidelines.
- <hr>
- <h2><a name="Appearance"></a>Appearance and contents</h2>
- <p>
- 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.
- <h3><a name="Page_structure"></a>Page structure</h3>
- <p>
- A Ghostscript document in HTML form should consist of
- <ol>
- <li>a visual header containing
- <ol type=a>
- <li>a conspicuous highlighted headline;
- <li>a table of contents;
- <li>"hints": references to other useful documents, always including
- <a href="Readme.htm">Readme.htm</a>;
- </ol>
- <li>the substantive contents;
- <li>a visual trailer consisting entirely of
- <ol type=a>
- <li>standard copyright and licensing text;
- <li>the Ghostscript version number; and
- <li>the date when the document was last modified.
- </ol>
- </ol>
- <p>
- This document is an example of this standard visible structure. Also see
- below about "<a href="#Structuring_comments">Structuring comments</a>" in
- HTML source code.
- <p>
- Where it makes sense to modify the standard structure to make the document
- more usable, do that. See
- <a href="Readme.htm"><b><tt>Readme.htm</tt></b></a> for an example: the
- introductory material at the beginning of the visible header, before the
- table of contents.
- <h3><a name="Links_outside"></a>Links to outside the Ghostscript documentation</h3>
- <p>
- Links to sites and documents outside the ghostscript distribution
- must carry the <code>class="offsite"</code> attribute and value. This signals special
- formatting to the stylesheet to assist users reading offline.
- <p>
- Avoid gratuitous commercial links; for instance, link the title of a book
- to its publisher, not to one particular on-line bookseller. See
- <a href="Language.htm#Capabilities"><b><tt>Language.htm</tt></b></a> for an
- example, the reference to the <em>PostScript Language Reference
- Manual</em>.
- <p>
- Similarly, where you have a choice, refer to free software rather than
- commercial products. See
- <a href="Make.htm#Third-party_libraries">Make.htm</a> for an example, the
- reference to <a href="Make.htm#Third-party_libraries">InfoZip
- <b><tt>unzip</tt></b></a> (where many commercial products provide similar
- functions).
- <h3><a name="Images"></a>Images and graphics</h3>
- <p>
- 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.
- <h3><a name="index.html"></a><b><tt>index.html</tt></b></h3>
- <p>
- <b><tt>index.html</tt></b> is not a part of the visible Ghostscript
- documentation itself, but when it is placed with all the
- <b><tt>*.htm</tt></b> files in a directory and a browser refers to the
- directory name alone, most servers are configured to deliver a file named
- <b><tt>index.html</tt></b> by default. This one does nothing except
- immediately to open the introductory Ghostscript document
- <a href="index.html"><b><tt>Readme.htm</tt></b></a>. This is intended to
- make life easier for both webmasters and users.
- <hr>
- <h2><a name="Large_structure"></a>HTML large structure</h2>
- <h3><a name="HTML_head"></a>HTML <b><tt><head></tt></b></h3>
- <p>
- Besides the essential HTML structure elements, Ghostscript HTML document's
- <b><tt><head></tt></b> consists of three elements in this order:
- <ol>
- <li>A <b><tt><title></tt></b>, usually the same text as the
- <a href="#Headline">headline</a>
- <li>An RCS identification line giving the name of the file in an HTML
- comment:
- <blockquote>
- <!-- The next line must not contain the literal string $,I,d,:! -->
- <b><tt><!-- $Id</tt><tt>: </tt></b><b><em>{file name}</em></b><b><tt>.htm $ --></tt></b>
- </blockquote>
- <li>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:
- <blockquote>
- <b><tt><!-- Originally: </tt></b><b><em>{file name}</em></b><b><tt> --></tt></b>
- </blockquote>
- </ol>
- <h3><a name="HTML_body"></a>HTML <b><tt><body></tt></b></h3>
- <p>
- A Ghostscript HTML document's <b><tt><body></tt></b> consists of five
- elements in this order:
- <ol>
- <li><a name="Headline"></a>The <b><em>headline</em></b> is conspicuous text
- at the top of the page, usually the same as the
- <a href="#Structure_head"><b><tt><title></tt></b></a> text. It is
- always in a table whose purpose is to provide a colored background using
- <b><tt>bgcolor</tt></b>, going the full width of the page:
- <blockquote>
- <b><tt><p><table width="100%" border="0"><br>
- <tr><th align="center" bgcolor="#CCCC00"><font size=6></tt></b><br>
- <b><em>{Text}</em></b><br>
- <b><tt></font><br>
- </table></tt></b>
- </blockquote>
- <li><a name="Table_of_contents"></a>
- The <b><em>table of contents</em></b> consists of nested unordered
- lists <b><tt><ul></tt></b>, in most documents assembled strictly from
- the <b><tt><Hn></tt></b> headers. The levels of nesting in the table
- of contents correspond to the level numbers of the headers.
- <li>The <b><em>hint</em></b> is a short section suggesting where to look
- for other related information. With very few exceptions this always
- includes a reference and link to
- <a href="Readme.htm"><b><tt>Readme.htm</tt></b></a>, but may include other
- suggestions and references.
- <li>The substance of the document.
- <li>The <b><em>trailer</em></b> contains, in a small font size,
- <ol type=a>
- <li>the <b><em>copyright notice</em></b> and other legal boilerplate text
- <li>the <b><em>version number</em></b> of Ghostscript and the
- <b><em>date</em></b> when the file was last modified.
- </ol>
- </ol>
- <p>
- This document for an example of that structure.
- <hr>
- <h2><a name="Inner_structure"></a>HTML inner structure</h2>
- <h3><a name="Structuring_comments"></a>Structuring comments</h3>
- <p>
- 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:
- <ol>
- <li>the <b><em>visible header</em></b>
- <ol type=a>
- <li>the <a href="#Headline"><b><em>headline</em></b></a>
- <li>the <b><em>table of contents</em></b>
- <li>the "see also" <b><em>hints</em></b>
- </ol>
- <li>the <b><em>body</em></b>
- <li>the <b><em>trailer</em></b>
- </ol>
- <h3><a name="Headers"></a>Headers: <b><tt><Hn></tt></b></h3>
- <p>
- Give a header <b><tt><Hn></tt></b> this structure:
- <blockquote><b><tt>
- <h2><a name="Head_anchor"></a>Header text</h2>
- </tt></b></blockquote>
- <p>
- That is, the opening header tag, an anchor, the header text, and the
- closing tag.
- <p>
- Represent every header in the table of contents, linked
- <b><tt><a href="#..."></tt></b>...<b><tt></a></tt></b> to
- the header. Of course, the headers are also convenient linkage points for
- references from other documents.
- <h3><a name="Anchors"></a>Anchors: <b><tt><a name="..."></tt></b></h3>
- <p>
- Give an anchor a name consisting only of letters, digits, dots
- ("<b><tt>.</tt></b>"), hyphens ("<b><tt>-</tt></b>"), and underscores
- ("<b><tt>_</tt></b>"), 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.
- <p>
- Choose anchor names to be readable and meaningful in the HTML source code.
- For instance:
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr valign=bottom>
- <th align=left>Use this form
- <td>
- <th align=left>... <b><em>NOT</em></b> this form
- <tr> <td colspan=3><hr>
- <tr valign=top> <td><b><tt><a name="Image_formats"></a></tt></b>
- <td>
- <td><b><tt><a name="Imgfts"></a></tt></b>
- </table></blockquote>
- <p>
- Anchors should be empty, that is
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr valign=bottom>
- <th align=left>Use this form
- <td>
- <th align=left>... <b><em>NOT</em></b> this form
- <tr> <td colspan=3><hr>
- <tr valign=top> <td><b><tt><a name="..."></a></tt></b>
- <td>
- <td><b><tt><a name="..."></tt></b><b><em>anything</em></b><b><tt></a></tt></b>
- </table></blockquote>
- <p>
- <a name="Anchor_placement"></a>Place an anchor within a paragraph (indented
- paragraph, list item, head, etc.) and at its beginning.
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr valign=bottom>
- <th align=left>Use this form
- <td>
- <th align=left>... <b><em>NOT</em></b> this form
- <tr> <td colspan=3><hr>
- <tr valign=top> <td><b><tt><p><a name="..."></a></tt></b>
- <td>
- <td><b><tt><p></tt></b><b><em> ...text... </em></b><b><tt><a name="..."></a></tt></b>
- <tr valign=top> <td><b><tt><p><a name="..."></a></tt></b>
- <td>
- <td><b><tt><a name="..."></a><p></tt></b>
- <tr valign=top> <td><b><tt><li><a name="..."></a></tt></b>
- <td>
- <td><b><tt><a name="..."></a><li></tt></b>
- </table></blockquote>
- <hr>
- <h2><a name="Text"></a>The presentation of text</h2>
- <h3><a name="Text_sections"></a>Sections of text</h3>
- <h4><a name="Paragraphs"></a>Paragraphs: <b><tt><p></tt></b></h4>
- <p>
- Define unindented paragraphs with <b><tt><p></tt></b>, never with
- explicit line breaks <b><tt><br></tt></b>, and make them
- ragged-right, not right-filled or centered. Put the paragraph tag
- <b><tt><p></tt></b> on a line alone, except when it is
- <a href="#Anchor_placement">followed immediately by an anchor</a>.
- Don't place the anchor before the paragraph tag.
- <h4><a name="Blockquote"></a>Indented paragraphs: <b><tt><blockquote></tt></b></h4>
- <p>
- Define indented paragraphs with <b><tt><blockquote></tt></b>. 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.
- <h4><a name="Line_breaks"></a>Explicit line breaks: <b><tt><br></tt></b></h4>
- <p>
- Use explicit line breaks <b><tt><br></tt></b> sparingly, and never as
- a substitute for paragraph tags. Do use them in
- <ul>
- <li>multi-line addresses
- <li>formatted coding examples
- <li>table entries, sparingly
- </ul>
- <h4><a name="Preformatted_text"></a>Preformatted text: <b><tt><pre></tt></b></h4>
- <p>
- Use preformatted text <b><tt><pre></tt></b> 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:
- <blockquote>
- <b><tt><font size="-1"><pre></tt></b><br>
- <b><em>... Wide preformatted text ...</em></b><br>
- <b><tt></pre></font></tt></b>
- </blockquote>
- <h3><a name="Use_of_fonts"></a>The use of different font faces</h3>
- <p>
- Do not use named fonts. Use only standard markup to specify fonts, as
- shown in this table.
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Use of fonts</font><hr>
- <tr valign=bottom>
- <th align=left>Tag
- <td>
- <th align=left>Used for
- <tr> <td colspan=3><hr>
- <tr valign=top> <td><b><tt><address></tt></b>
- <td>
- <td>Addresses in running text
- <tr valign=top> <td><b><tt><b></tt></b>
- <td>
- <td>Emphasis everywhere
- <tr valign=top> <td><b><tt><em></tt></b>
- <td>
- <td>Emphasis, usually in running text; with <b><tt><b></tt></b>, strong emphasis
- <tr valign=top> <td><b><tt><font size=</tt></b><b><em>N</em></b><b><tt>></tt></b>
- <td>
- <td>Table headings, extended <b><tt><pre></tt></b> examples
- <tr valign=top> <td><b><tt><pre></tt></b>
- <td>
- <td>Preformatted text (to control spacing)
- <tr valign=top> <td><b><tt><small></tt></b>
- <td>
- <td>Superscripts (smaller than <b><tt><font size="-1"></tt></b>)
- <tr valign=top> <td><b><tt><sup></tt></b>
- <td>
- <td>Superscripts
- <tr valign=top> <td><b><tt><tt></tt></b>
- <td>
- <td>With <b><tt><b></tt></b>, used for specific names of
- code, programs, and data in running text, and in short examples
- </table></blockquote>
- <hr>
- <h2><a name="Lists"></a>Lists: <b><tt><ul>, <ol>, <dl></tt></b></h2>
- <p>
- 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.
- <p>
- Most simple lists should be unordered (bulleted) lists
- <b><tt><ul></tt></b>. Use an ordered (numbered or alphabetized) list
- <b><tt><ol></tt></b> only where the exact ordering or an exact count
- is important.
- <p>
- Where entries in a descriptive list <b><tt><dl></tt></b> contain
- extended descriptions <b><tt><dd></tt></b> -- 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 <b><tt><dt>...<dd>...</tt></b> entries in a single
- list:
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr valign=bottom>
- <th align=left>Use this form
- <td>
- <th align=left>... <b><em>NOT</em></b> this form
- <tr> <td colspan=3><hr>
- <tr> <td valign=top>
- <b><tt><dl></tt></b><br>
- <b><tt><dt></tt></b>Term<br>
- <b><tt><dd></tt></b>Description<br>
- <b><tt><p></tt></b>Another paragraph of description<br>
- <b><tt></dl></tt></b><br>
- <br>
- <b><tt><dl></tt></b><br>
- <b><tt><dt></tt></b>Another term<br>
- <b><tt><dd></tt></b>Another description<br>
- <b><tt></dl></tt></b><br>
- ...<br>
- <td>
- <td valign=top>
- <b><tt><dl></tt></b><br>
- <b><tt><dt></tt></b>Term<br>
- <b><tt><dd></tt></b>Description<br>
- <b><tt><p></tt></b>Another paragraph of description<br>
- <b><tt><dt></tt></b>Another term<br>
- <b><tt><dd></tt></b>Another description<br>
- ...<br>
- <b><tt></dl></tt></b>
- </table></blockquote>
- <p>
- This may be more work for the HTML writer, but the results for the reader
- are often much better.
- <hr>
- <h2><a name="Tables"></a>Tables: <b><tt><table></tt></b></h2>
- <h3><a name="Readability"></a>Readability for the user and the HTML writer</h3>
- <p>
- 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
- <b><tt>bgcolor</tt></b>, horizontal rules <b><tt><hr></tt></b>, and
- explicit spacing.
- <p>
- Secondarily, arrange HTML source code for tables to be readable by the
- writer and developer.
- <h3><a name="Table_guidelines"></a>Specific guidelines for coding tables</h3>
- <ul>
- <li>Large tables have heads with the same background color as the page's
- <a href="#Headline">headline</a>. (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.)
- <li>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.
- <li>Set cell padding and spacing to 0. Use explicit white space for
- readability, not implicit white space.
- <li>Begin the code for a new row <b><tt><tr></tt></b> on a new line.
- Generally use <b><tt>valign=top</tt></b> to control the placement of text
- in a row for readability with a browser or as plain text.
- <li>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 <b><tt><td></tt></b> by a tab character.
- <li>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.
- <li>Use horizontal rules and visually empty rows for clarity, but
- sparingly. Be consistent with the existing tables.
- <li>Give every cell some contents: put a nonbreaking space in a visually
- empty cell as a placeholder.
- </ul>
- <h3><a name="Typical_table"></a>HTML code for typical tables</h3>
- <p>
- The HTML source code for a typical large table should look like this:
- <blockquote>
- <pre><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>
- </pre></blockquote>
- <p>
- The HTML source code for a typical small table should look like this:
- <blockquote>
- <pre><table cellpadding=0 cellspacing=0>
- <tr> <td>...
- <td>&nbsp;&nbsp;&nbsp;
- <td>...
- <tr> <td>...
- <td>&nbsp;
- <td>...
- ...
- </table>
- </pre></blockquote>
- <hr>
- <h2><a name="Unused_tags"></a>Tags not used</h2>
- <p>
- Don't use optional tags (ones not required by the HTML standard). These
- include <b><tt></dd></tt></b>, <b><tt></dt></tt></b>,
- <b><tt></li></tt></b>, <b><tt></p></tt></b>,
- <b><tt></tr></tt></b>, <b><tt></th></tt></b>, and
- <b><tt></td></tt></b>.
- <hr>
- <h2><a name="New_document"></a>Creating a new document</h2>
- <h3><a name="File_name"></a>Name the new document in 8+3 format</h3>
- <p>
- If you create a new Ghostscript HTML document, choose for it a name in 8+3
- format for cross-platform compabitility:
- <blockquote>
- <b><em>Name</em></b><b><tt>.htm</tt></b>
- </blockquote>
- <p>
- where "<b><em>Name</em></b>" is no more than eight characters.
- <p>
- 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.
- <h3><a name="Plagiarize"></a>Use an existing document as a model</h3>
- <p>
- To create an entirely new Ghostscript document, plagiarize this one for the
- <a href="#Structuring_comments">structuring comments</a> and other useful
- parts. Then, using the <a href="#Structuring_comments">structuring
- comments</a> as a guide to the sections of the document (in a text editor,
- search for "<b><tt><!-- [</tt></b>"):
- <ul>
- <li>insert your own HTML title and <a href="#Headline">headline</a> (they
- should ordinarily be the same text) in place of the old ones;
- <li>insert your own RCS <b><tt>$Id</tt></b> in place of the old one in the
- <a href="#Structure_head">HTML header</a>;
- <li>delete the old entries in the <a href="#Table_of_contents">table of
- contents</a>;
- <li>keep the hint paragraph;
- <li>delete the entire contents section between the structuring comments;
- and
- <li>in the trailer, update the version number and date.
- </ul>
- <p>
- You now have a template document ready for new contents.
- <h3><a name="Readme_material"></a>Write new references to go in <b><tt>Readme.htm</tt></b></h3>
- <p>
- Write material to go in <a href="Readme.htm"><b><tt>Readme.htm</tt></b></a>
- that describes the new document, and links to it from two sections:
- <ul>
- <li>the <a href="Readme.htm#Theme_roadmap">thematic section</a> and
- <li>the descriptions of documentation
- <a href="Readme.htm#Ordered_roadmap">arranged by file name</a>.
- </ul>
- <h3><a name="New_doc_other"></a>Other considerations</h3>
- <p>
- Follow the other guidelines here, including which elements of the
- document should go in which section according to the structuring comments,
- and <a href="#Headers">anchoring every <b><tt><Hn></tt></b>
- header</a>. As you create text and headers, you will want to rebuild the
- <a href="#Table_of_contents">table of contents</a> from the headers
- occasionally.
- <p>
- Pete Kaiser <<a href="mailto:kaiser@acm.org">kaiser@acm.org</a>>
- 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.
- <hr>
- <h2><a name="Miscellany"></a>Miscellany</h2>
- <p>
- Use <b><tt><></tt></b> to bracket links to visible email addresses
- (<b><tt>mailto</tt></b>) 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
- <blockquote>
- Free Software Foundation <<a href="mailto:gnu@gnu.org">gnu@gnu.org</a>>
- </blockquote>
- <p>
- For exponentiation use "<b><tt>^</tt></b>" (not "**" or "exp()") plus
- writing the exponent as a superscript in <b><tt><small></tt></b>
- size:
- <blockquote>
- Something<b><tt>^<sup></tt></b><b><tt><small></tt></b>exponent<b><tt></small></sup></tt></b>.
- </blockquote>
- <p>
- to look like this:
- <blockquote>
- Something<b><tt>^</tt></b><sup><small>exponent</small></sup>
- </blockquote>
- <p>
- This is intended for readability both in a browser and as plain text.
- <!-- [2.0 end contents] ==================================================== -->
- <!-- [3.0 begin visible trailer] =========================================== -->
- <hr>
- <p>
- <small>Copyright © 1996, 2000 Aladdin Enterprises. All rights
- reserved.</small>
- <p>
- <small>This file is part of AFPL Ghostscript. See the
- <a href="Public.htm">Aladdin Free Public License</a> (the "License") for
- full details of the terms of using, copying, modifying, and redistributing
- AFPL Ghostscript.</small>
- <p>
- <small>Ghostscript version 7.04, 31 January 2002
- <!-- [3.0 end visible trailer] ============================================= -->
- </body>
- </html>
|