diff options
Diffstat (limited to 'Master/xemtex/doc/ghostscript/Htmstyle.htm')
| -rw-r--r-- | Master/xemtex/doc/ghostscript/Htmstyle.htm | 778 |
1 files changed, 778 insertions, 0 deletions
diff --git a/Master/xemtex/doc/ghostscript/Htmstyle.htm b/Master/xemtex/doc/ghostscript/Htmstyle.htm new file mode 100644 index 00000000000..05b4e82ef06 --- /dev/null +++ b/Master/xemtex/doc/ghostscript/Htmstyle.htm @@ -0,0 +1,778 @@ +<!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.11.2.5 2003/05/17 14:39:00 giles 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> +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. + +<p> +<small>Ghostscript version 7.07, 17 May 2003 + +<!-- [3.0 end visible trailer] ============================================= --> + +</body> +</html> |