1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 2"http://www.w3.org/TR/html4/loose.dtd"> 3<html> 4<head> 5<title>HTML coding and style guidelines for Ghostscript documentation</title> 6<!-- $Id: Htmstyle.htm,v 1.44 2005/10/20 19:46:23 ray Exp $ --> 7<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 8</head> 9 10<body> 11<!-- [1.0 begin visible header] ============================================ --> 12 13<!-- [1.1 begin headline] ================================================== --> 14 15<h1>HTML coding and style guidelines for Ghostscript documentation</h1> 16 17<!-- [1.1 end headline] ==================================================== --> 18 19<!-- [1.2 begin table of contents] ========================================= --> 20 21<h2>Table of contents</h2> 22 23<blockquote><ul> 24<li><a href="#Introduction">Introduction</a> 25<li><a href="#Appearance">Appearance and contents</a> 26<ul> 27<li><a href="#Page_structure">Page structure</a> 28<li><a href="#Links_outside">Links to outside the Ghostscript documentation</a> 29<li><a href="#Images">Images and graphics</a> 30<li><a href="#index.html"><b><tt>index.html</tt></b></a> 31</ul> 32<li><a href="#Large_structure">HTML large structure</a> 33<ul> 34<li><a href="#HTML_head">HTML <b><tt><head></tt></b></a> 35<li><a href="#HTML_body">HTML <b><tt><body></tt></b></a> 36</ul> 37<li><a href="#Inner_structure">HTML inner structure</a> 38<ul> 39<li><a href="#Structuring_comments">Structuring comments</a> 40<li><a href="#Headers">Headers: <b><tt><Hn></tt></b></a> 41<li><a href="#Anchors">Anchors: <b><tt><a name="..."></tt></b></a> 42</ul> 43<li><a href="#Text">The presentation of text</a> 44<ul> 45<li><a href="#Text_sections">Sections of text</a> 46<ul> 47<li><a href="#Paragraphs">Paragraphs: <b><tt><p></tt></b></a> 48<li><a href="#Blockquote">Indented paragraphs: <b><tt><blockquote></tt></b></a> 49<li><a href="#Line_breaks">Explicit line breaks: <b><tt><br></tt></b></a> 50<li><a href="#Preformatted_text">Preformatted text: <b><tt><pre></tt></b></a> 51</ul> 52<li><a href="#Use_of_fonts">The use of different font faces</a> 53</ul> 54<li><a href="#Lists">Lists: <b><tt><ul>, <ol>, <dl></tt></b></a> 55<li><a href="#Tables">Tables: <b><tt><table></tt></b></a> 56<ul> 57<li><a href="#Readability">Readability for the user and the HTML writer</a> 58<li><a href="#Table_guidelines">Specific guidelines for coding tables</a> 59<li><a href="#Typical_table">HTML code for typical tables</a> 60</ul> 61<li><a href="#Unused_tags">Tags not used</a> 62<li><a href="#New_document">Creating a new document</a> 63<ul> 64<li><a href="#File_name">Name the new document in 8+3 format</a> 65<li><a href="#Plagiarize">Use an existing document as a model</a> 66<li><a href="#Readme_material">Write new references to go in <b><tt>Readme.htm</tt></b></a> 67<li><a href="#New_doc_other">Other considerations</a> 68</ul> 69<li><a href="#Miscellany">Miscellany</a> 70</ul></blockquote> 71 72<!-- [1.2 end table of contents] =========================================== --> 73 74<!-- [1.3 begin hint] ====================================================== --> 75 76<p>For other information, see the <a href="Readme.htm">Ghostscript 77overview</a>. 78 79<!-- [1.3 end hint] ======================================================== --> 80 81<hr> 82 83<!-- [1.0 end visible header] ============================================== --> 84 85<!-- [2.0 begin contents] ================================================== --> 86 87<h2><a name="Introduction"></a>Introduction</h2> 88 89<p> 90The most important intention in casting Ghostscript's documentation into 91Hypertext Markup Language (HTML) from simple text form is to improve its 92usefulness greatly to those who use, install, and build Ghostscript: 93everything else is details. The wide spread of World Wide Web browsers now 94makes it possible to distribute documents which are not only readable as 95text, but also richly cross-linked as hypertext. Using hypertext through a 96browser can reduce the effort required to find and use the information 97people often need in order to use Ghostscript. 98 99<p> 100The remainder of this document expresses the guidelines used to create the 101HTML form of the Ghostscript documentation. The guidelines are intended to 102encourage 103 104<ul> 105<li>documents that are easy to read and understand in all of the most-used 106forms: on screen with a browser, printed by a browser, or as plain text; 107 108<li>correct HTML that conforms to prevailing standards; 109 110<li>consistent HTML coding among all Ghostscript's documents; and 111 112<li>HTML documents that are as simple as possible in light of their 113contents; free of difficult, little-used, or proprietary constructs; and 114easy to understand and modify. 115</ul> 116 117<p> 118Here are those guidelines. 119 120<hr> 121 122<h2><a name="Appearance"></a>Appearance and contents</h2> 123 124<p> 125What the user sees browsing the documentation, and what a document 126developer or editor sees working with it, are different. This section is 127about what the user sees. 128 129<h3><a name="Page_structure"></a>Page structure</h3> 130 131<p> 132A Ghostscript document in HTML form should consist of 133 134<ol> 135<li>a visual header containing 136<ol type=a> 137<li>a conspicuous highlighted headline; 138<li>a table of contents; 139<li>"hints": references to other useful documents, always including 140<a href="Readme.htm">Readme.htm</a>; 141</ol> 142<li>the substantive contents; 143<li>a visual trailer consisting entirely of 144<ol type=a> 145<li>standard copyright and licensing text; 146<li>the Ghostscript version number; and 147<li>the date when the document was last modified. 148</ol> 149</ol> 150 151<p> 152This document is an example of this standard visible structure. Also see 153below about "<a href="#Structuring_comments">Structuring comments</a>" in 154HTML source code. 155 156<p> 157Where it makes sense to modify the standard structure to make the document 158more usable, do that. See 159<a href="Readme.htm"><b><tt>Readme.htm</tt></b></a> for an example: the 160introductory material at the beginning of the visible header, before the 161table of contents. 162 163<h3><a name="Links_outside"></a>Links to outside the Ghostscript documentation</h3> 164 165<p> 166Links to sites and documents outside the ghostscript distribution 167must carry the <code>class="offsite"</code> attribute and value. This signals special 168formatting to the stylesheet to assist users reading offline. 169 170<p> 171Avoid gratuitous commercial links; for instance, link the title of a book 172to its publisher, not to one particular on-line bookseller. See 173<a href="Language.htm#Capabilities"><b><tt>Language.htm</tt></b></a> for an 174example, the reference to the <em>PostScript Language Reference 175Manual</em>. 176 177<p> 178Similarly, where you have a choice, refer to free software rather than 179commercial products. See 180<a href="Make.htm#Third-party_libraries">Make.htm</a> for an example, the 181reference to <a href="Make.htm#Third-party_libraries">InfoZip 182<b><tt>unzip</tt></b></a> (where many commercial products provide similar 183functions). 184 185<h3><a name="Images"></a>Images and graphics</h3> 186 187<p> 188Use no graphics or images. The documents are text-only, so nothing is lost 189when a document is converted into ASCII text. This is an explicit initial 190design goal of the HTML documentation. 191 192<h3><a name="index.html"></a><b><tt>index.html</tt></b></h3> 193 194<p> 195<b><tt>index.html</tt></b> is not a part of the visible Ghostscript 196documentation itself, but when it is placed with all the 197<b><tt>*.htm</tt></b> files in a directory and a browser refers to the 198directory name alone, most servers are configured to deliver a file named 199<b><tt>index.html</tt></b> by default. This one does nothing except 200immediately to open the introductory Ghostscript document 201<a href="index.html"><b><tt>Readme.htm</tt></b></a>. This is intended to 202make life easier for both webmasters and users. 203 204<hr> 205 206<h2><a name="Large_structure"></a>HTML large structure</h2> 207 208<h3><a name="HTML_head"></a>HTML <b><tt><head></tt></b></h3> 209 210<p> 211Besides the essential HTML structure elements, Ghostscript HTML document's 212<b><tt><head></tt></b> consists of three elements in this order: 213 214<ol> 215<li>A <b><tt><title></tt></b>, usually the same text as the 216<a href="#Headline">headline</a> 217 218<li>An RCS identification line giving the name of the file in an HTML 219comment: 220 221<blockquote> 222<!-- The next line must not contain the literal string $,I,d,:! --> 223<b><tt><!-- $Id</tt><tt>: </tt></b><b><em>{file name}</em></b><b><tt>.htm $ --></tt></b> 224</blockquote> 225 226<li>For documents converted from another form, an HTML comment line giving 227the name of the original file before it was edited and converted to HTML: 228 229<blockquote> 230<b><tt><!-- Originally: </tt></b><b><em>{file name}</em></b><b><tt> --></tt></b> 231</blockquote> 232</ol> 233 234<h3><a name="HTML_body"></a>HTML <b><tt><body></tt></b></h3> 235 236<p> 237A Ghostscript HTML document's <b><tt><body></tt></b> consists of five 238elements in this order: 239 240<ol> 241<li><a name="Headline"></a>The <b><em>headline</em></b> is conspicuous text 242at the top of the page, usually the same as the 243<a href="#Structure_head"><b><tt><title></tt></b></a> text. It is 244always in a table whose purpose is to provide a colored background using 245<b><tt>bgcolor</tt></b>, going the full width of the page: 246 247<blockquote> 248<b><tt><p><table width="100%" border="0"><br> 249<tr><th align="center" bgcolor="#CCCC00"><font size=6></tt></b><br> 250<b><em>{Text}</em></b><br> 251<b><tt></font><br> 252</table></tt></b> 253</blockquote> 254 255<li><a name="Table_of_contents"></a> 256The <b><em>table of contents</em></b> consists of nested unordered 257lists <b><tt><ul></tt></b>, in most documents assembled strictly from 258the <b><tt><Hn></tt></b> headers. The levels of nesting in the table 259of contents correspond to the level numbers of the headers. 260 261<li>The <b><em>hint</em></b> is a short section suggesting where to look 262for other related information. With very few exceptions this always 263includes a reference and link to 264<a href="Readme.htm"><b><tt>Readme.htm</tt></b></a>, but may include other 265suggestions and references. 266 267<li>The substance of the document. 268 269<li>The <b><em>trailer</em></b> contains, in a small font size, 270 271<ol type=a> 272<li>the <b><em>copyright notice</em></b> and other legal boilerplate text 273<li>the <b><em>version number</em></b> of Ghostscript and the 274<b><em>date</em></b> when the file was last modified. 275</ol> 276</ol> 277 278<p> 279This document for an example of that structure. 280 281<hr> 282 283<h2><a name="Inner_structure"></a>HTML inner structure</h2> 284 285<h3><a name="Structuring_comments"></a>Structuring comments</h3> 286 287<p> 288Special comment lines within the HTML files mark internally the visible 289sections of the document. They make it easy for both document developers 290and programs to handle the HTML code. Each of these comments is exactly 80 291characters wide, and each important section of a document is bracketed by a 292unique beginning and ending pair. View the source code of this document 293for an example of these structuring comments. The sections they mark are: 294 295<ol> 296<li>the <b><em>visible header</em></b> 297<ol type=a> 298<li>the <a href="#Headline"><b><em>headline</em></b></a> 299<li>the <b><em>table of contents</em></b> 300<li>the "see also" <b><em>hints</em></b> 301</ol> 302<li>the <b><em>body</em></b> 303<li>the <b><em>trailer</em></b> 304</ol> 305 306<h3><a name="Headers"></a>Headers: <b><tt><Hn></tt></b></h3> 307 308<p> 309Give a header <b><tt><Hn></tt></b> this structure: 310 311<blockquote><b><tt> 312<h2><a name="Head_anchor"></a>Header text</h2> 313</tt></b></blockquote> 314 315<p> 316That is, the opening header tag, an anchor, the header text, and the 317closing tag. 318 319<p> 320Represent every header in the table of contents, linked 321<b><tt><a href="#..."></tt></b>...<b><tt></a></tt></b> to 322the header. Of course, the headers are also convenient linkage points for 323references from other documents. 324 325<h3><a name="Anchors"></a>Anchors: <b><tt><a name="..."></tt></b></h3> 326 327<p> 328Give an anchor a name consisting only of letters, digits, dots 329("<b><tt>.</tt></b>"), hyphens ("<b><tt>-</tt></b>"), and underscores 330("<b><tt>_</tt></b>"), but not white space or other punctuation marks. 331This ensures that the name is readable and that an entire name always 332appears on a single line of HTML source both where it's defined and 333everywhere it's used, making it simple to find anchors by text search in 334the HTML source code. 335 336<p> 337Choose anchor names to be readable and meaningful in the HTML source code. 338For instance: 339 340<blockquote><table cellpadding=0 cellspacing=0> 341<tr valign=bottom> 342 <th align=left>Use this form 343 <td> 344 <th align=left>... <b><em>NOT</em></b> this form 345<tr> <td colspan=3><hr> 346<tr valign=top> <td><b><tt><a name="Image_formats"></a></tt></b> 347 <td> 348 <td><b><tt><a name="Imgfts"></a></tt></b> 349</table></blockquote> 350 351<p> 352Anchors should be empty, that is 353 354<blockquote><table cellpadding=0 cellspacing=0> 355<tr valign=bottom> 356 <th align=left>Use this form 357 <td> 358 <th align=left>... <b><em>NOT</em></b> this form 359<tr> <td colspan=3><hr> 360<tr valign=top> <td><b><tt><a name="..."></a></tt></b> 361 <td> 362 <td><b><tt><a name="..."></tt></b><b><em>anything</em></b><b><tt></a></tt></b> 363</table></blockquote> 364 365<p> 366<a name="Anchor_placement"></a>Place an anchor within a paragraph (indented 367paragraph, list item, head, etc.) and at its beginning. 368 369<blockquote><table cellpadding=0 cellspacing=0> 370<tr valign=bottom> 371 <th align=left>Use this form 372 <td> 373 <th align=left>... <b><em>NOT</em></b> this form 374<tr> <td colspan=3><hr> 375<tr valign=top> <td><b><tt><p><a name="..."></a></tt></b> 376 <td> 377 <td><b><tt><p></tt></b><b><em> ...text... </em></b><b><tt><a name="..."></a></tt></b> 378<tr valign=top> <td><b><tt><p><a name="..."></a></tt></b> 379 <td> 380 <td><b><tt><a name="..."></a><p></tt></b> 381<tr valign=top> <td><b><tt><li><a name="..."></a></tt></b> 382 <td> 383 <td><b><tt><a name="..."></a><li></tt></b> 384</table></blockquote> 385 386<hr> 387 388<h2><a name="Text"></a>The presentation of text</h2> 389 390<h3><a name="Text_sections"></a>Sections of text</h3> 391 392<h4><a name="Paragraphs"></a>Paragraphs: <b><tt><p></tt></b></h4> 393 394<p> 395Define unindented paragraphs with <b><tt><p></tt></b>, never with 396explicit line breaks <b><tt><br></tt></b>, and make them 397ragged-right, not right-filled or centered. Put the paragraph tag 398<b><tt><p></tt></b> on a line alone, except when it is 399<a href="#Anchor_placement">followed immediately by an anchor</a>. 400Don't place the anchor before the paragraph tag. 401 402<h4><a name="Blockquote"></a>Indented paragraphs: <b><tt><blockquote></tt></b></h4> 403 404<p> 405Define indented paragraphs with <b><tt><blockquote></tt></b>. Avoid 406elaborate nested indentation -- that is, more than two levels. It is 407generally a poor idea to try to make indentation carry too much weight of 408meaning for text, so use indentation simply to separate visual elements for 409easier reading. 410 411<h4><a name="Line_breaks"></a>Explicit line breaks: <b><tt><br></tt></b></h4> 412 413<p> 414Use explicit line breaks <b><tt><br></tt></b> sparingly, and never as 415a substitute for paragraph tags. Do use them in 416 417<ul> 418<li>multi-line addresses 419<li>formatted coding examples 420<li>table entries, sparingly 421</ul> 422 423<h4><a name="Preformatted_text"></a>Preformatted text: <b><tt><pre></tt></b></h4> 424 425<p> 426Use preformatted text <b><tt><pre></tt></b> exclusively for material 427that must be presented with exact spacing in a monospaced font, such as 428extended coding examples. Where extended preformatted text seems likely to 429be wider than a typical browser window, reduce the font size: 430 431<blockquote> 432<b><tt><font size="-1"><pre></tt></b><br> 433<b><em>... Wide preformatted text ...</em></b><br> 434<b><tt></pre></font></tt></b> 435</blockquote> 436 437<h3><a name="Use_of_fonts"></a>The use of different font faces</h3> 438 439<p> 440Do not use named fonts. Use only standard markup to specify fonts, as 441shown in this table. 442 443<blockquote><table cellpadding=0 cellspacing=0> 444<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Use of fonts</font><hr> 445<tr valign=bottom> 446 <th align=left>Tag 447 <td> 448 <th align=left>Used for 449<tr> <td colspan=3><hr> 450<tr valign=top> <td><b><tt><address></tt></b> 451 <td> 452 <td>Addresses in running text 453<tr valign=top> <td><b><tt><b></tt></b> 454 <td> 455 <td>Emphasis everywhere 456<tr valign=top> <td><b><tt><em></tt></b> 457 <td> 458 <td>Emphasis, usually in running text; with <b><tt><b></tt></b>, strong emphasis 459<tr valign=top> <td><b><tt><font size=</tt></b><b><em>N</em></b><b><tt>></tt></b> 460 <td> 461 <td>Table headings, extended <b><tt><pre></tt></b> examples 462<tr valign=top> <td><b><tt><pre></tt></b> 463 <td> 464 <td>Preformatted text (to control spacing) 465<tr valign=top> <td><b><tt><small></tt></b> 466 <td> 467 <td>Superscripts (smaller than <b><tt><font size="-1"></tt></b>) 468<tr valign=top> <td><b><tt><sup></tt></b> 469 <td> 470 <td>Superscripts 471<tr valign=top> <td><b><tt><tt></tt></b> 472 <td> 473 <td>With <b><tt><b></tt></b>, used for specific names of 474 code, programs, and data in running text, and in short examples 475</table></blockquote> 476 477<hr> 478 479<h2><a name="Lists"></a>Lists: <b><tt><ul>, <ol>, <dl></tt></b></h2> 480 481<p> 482Don't over-use lists: instead simply use clear wording in running text 483wherever possible. Use a list where the special formatting improves the 484material's clarity and readability. 485 486<p> 487Most simple lists should be unordered (bulleted) lists 488<b><tt><ul></tt></b>. Use an ordered (numbered or alphabetized) list 489<b><tt><ol></tt></b> only where the exact ordering or an exact count 490is important. 491 492<p> 493Where entries in a descriptive list <b><tt><dl></tt></b> contain 494extended descriptions <b><tt><dd></tt></b> -- especially if the 495descriptions contain paragraph breaks or tables -- improve the spacing 496between entries by making each entry a separate list. That is, enclose 497each entry in a separate list to give it more readable spacing, rather than 498putting many <b><tt><dt>...<dd>...</tt></b> entries in a single 499list: 500 501<blockquote><table cellpadding=0 cellspacing=0> 502<tr valign=bottom> 503 <th align=left>Use this form 504 <td> 505 <th align=left>... <b><em>NOT</em></b> this form 506<tr> <td colspan=3><hr> 507<tr> <td valign=top> 508 <b><tt><dl></tt></b><br> 509 <b><tt><dt></tt></b>Term<br> 510 <b><tt><dd></tt></b>Description<br> 511 <b><tt><p></tt></b>Another paragraph of description<br> 512 <b><tt></dl></tt></b><br> 513 <br> 514 <b><tt><dl></tt></b><br> 515 <b><tt><dt></tt></b>Another term<br> 516 <b><tt><dd></tt></b>Another description<br> 517 <b><tt></dl></tt></b><br> 518 ...<br> 519 <td> 520 <td valign=top> 521 <b><tt><dl></tt></b><br> 522 <b><tt><dt></tt></b>Term<br> 523 <b><tt><dd></tt></b>Description<br> 524 <b><tt><p></tt></b>Another paragraph of description<br> 525 <b><tt><dt></tt></b>Another term<br> 526 <b><tt><dd></tt></b>Another description<br> 527 ...<br> 528 <b><tt></dl></tt></b> 529</table></blockquote> 530 531<p> 532This may be more work for the HTML writer, but the results for the reader 533are often much better. 534 535<hr> 536 537<h2><a name="Tables"></a>Tables: <b><tt><table></tt></b></h2> 538 539<h3><a name="Readability"></a>Readability for the user and the HTML writer</h3> 540 541<p> 542Format tables to be as readable as possible both with a browser and when 543converted to plain text. Browsers and converters of all kinds handle 544tables idiosyncratically, so there seems to be more art than science to 545reaching this end, which accounts for all the detail in the guidelines for 546tables: it is the reason for all the uses of background color 547<b><tt>bgcolor</tt></b>, horizontal rules <b><tt><hr></tt></b>, and 548explicit spacing. 549 550<p> 551Secondarily, arrange HTML source code for tables to be readable by the 552writer and developer. 553 554<h3><a name="Table_guidelines"></a>Specific guidelines for coding tables</h3> 555 556<ul> 557<li>Large tables have heads with the same background color as the page's 558<a href="#Headline">headline</a>. (Color is used only in tables and only 559this way, and it is the same color everywhere. In consideration of 560differences of color vision, the color is chosen so that normal black text 561contrasts with a brighter background, and the color itself against white.) 562 563<li>Do not use borders for tables; they almost invariably only clutter the 564appearance without adding to clarity, and they don't convert well to plain 565text. For visual spacing prefer white space. 566 567<li>Set cell padding and spacing to 0. Use explicit white space for 568readability, not implicit white space. 569 570<li>Begin the code for a new row <b><tt><tr></tt></b> on a new line. 571Generally use <b><tt>valign=top</tt></b> to control the placement of text 572in a row for readability with a browser or as plain text. 573 574<li>Code the first column of a row beginning on the same line as the 575beginning of the row, and then begin every other column on a separate line. 576Always precede <b><tt><td></tt></b> by a tab character. 577 578<li>Separate two columns of substantive material by a visually empty column 579of nonbreaking spaces for readability. Specify the width of this empty 580column in the first row, and in all other rows give that column a single 581nonbreaking space. 582 583<li>Use horizontal rules and visually empty rows for clarity, but 584sparingly. Be consistent with the existing tables. 585 586<li>Give every cell some contents: put a nonbreaking space in a visually 587empty cell as a placeholder. 588</ul> 589 590<h3><a name="Typical_table"></a>HTML code for typical tables</h3> 591 592<p> 593The HTML source code for a typical large table should look like this: 594 595<blockquote> 596<pre><table cellpadding=0 cellspacing=0> 597<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Large table</font><hr> 598<tr> <th align=left>... 599 <td>&nbsp;&nbsp;&nbsp; 600 <th align=left>... 601 <td>&nbsp;&nbsp;&nbsp; 602 <th align=left>... 603<tr> <td>... 604 <td>&nbsp;&nbsp; 605 <td>... 606 <td>&nbsp; 607 <td>... 608... 609</table> 610</pre></blockquote> 611 612<p> 613The HTML source code for a typical small table should look like this: 614 615<blockquote> 616<pre><table cellpadding=0 cellspacing=0> 617<tr> <td>... 618 <td>&nbsp;&nbsp;&nbsp; 619 <td>... 620<tr> <td>... 621 <td>&nbsp; 622 <td>... 623... 624</table> 625</pre></blockquote> 626 627<hr> 628 629<h2><a name="Unused_tags"></a>Tags not used</h2> 630 631<p> 632Don't use optional tags (ones not required by the HTML standard). These 633include <b><tt></dd></tt></b>, <b><tt></dt></tt></b>, 634<b><tt></li></tt></b>, <b><tt></p></tt></b>, 635<b><tt></tr></tt></b>, <b><tt></th></tt></b>, and 636<b><tt></td></tt></b>. 637 638<hr> 639 640<h2><a name="New_document"></a>Creating a new document</h2> 641 642<h3><a name="File_name"></a>Name the new document in 8+3 format</h3> 643 644<p> 645If you create a new Ghostscript HTML document, choose for it a name in 8+3 646format for cross-platform compabitility: 647 648<blockquote> 649<b><em>Name</em></b><b><tt>.htm</tt></b> 650</blockquote> 651 652<p> 653where "<b><em>Name</em></b>" is no more than eight characters. 654 655<p> 656Begin the new file name with an upper-case letter like the existing names, 657which are in mixed case beginning with upper-case letters. Use spelling, 658not case, to distinguish between names: that is, don't create a new file 659whose name differs from an existing one only by the difference between 660upper and lower case, because some platforms can't store two such files. 661 662<h3><a name="Plagiarize"></a>Use an existing document as a model</h3> 663 664<p> 665To create an entirely new Ghostscript document, plagiarize this one for the 666<a href="#Structuring_comments">structuring comments</a> and other useful 667parts. Then, using the <a href="#Structuring_comments">structuring 668comments</a> as a guide to the sections of the document (in a text editor, 669search for "<b><tt><!-- [</tt></b>"): 670 671<ul> 672<li>insert your own HTML title and <a href="#Headline">headline</a> (they 673should ordinarily be the same text) in place of the old ones; 674 675<li>insert your own RCS <b><tt>$Id</tt></b> in place of the old one in the 676<a href="#Structure_head">HTML header</a>; 677 678<li>delete the old entries in the <a href="#Table_of_contents">table of 679contents</a>; 680 681<li>keep the hint paragraph; 682 683<li>delete the entire contents section between the structuring comments; 684and 685 686<li>in the trailer, update the version number and date. 687</ul> 688 689<p> 690You now have a template document ready for new contents. 691 692<h3><a name="Readme_material"></a>Write new references to go in <b><tt>Readme.htm</tt></b></h3> 693 694<p> 695Write material to go in <a href="Readme.htm"><b><tt>Readme.htm</tt></b></a> 696that describes the new document, and links to it from two sections: 697 698<ul> 699<li>the <a href="Readme.htm#Theme_roadmap">thematic section</a> and 700 701<li>the descriptions of documentation 702<a href="Readme.htm#Ordered_roadmap">arranged by file name</a>. 703</ul> 704 705<h3><a name="New_doc_other"></a>Other considerations</h3> 706 707<p> 708Follow the other guidelines here, including which elements of the 709document should go in which section according to the structuring comments, 710and <a href="#Headers">anchoring every <b><tt><Hn></tt></b> 711header</a>. As you create text and headers, you will want to rebuild the 712<a href="#Table_of_contents">table of contents</a> from the headers 713occasionally. 714 715<p> 716Pete Kaiser <<a href="mailto:kaiser@acm.org">kaiser@acm.org</a>> 717wrote a package of GNU emacs functions specifically to handle Ghostscript 718HTML documentation, including functions to build a table of contents from 719headers in an HTML document, and to build and maintain tables and 720other structures built along the guidelines in this document. 721 722<hr> 723 724<h2><a name="Miscellany"></a>Miscellany</h2> 725 726<p> 727Use <b><tt><></tt></b> to bracket links to visible email addresses 728(<b><tt>mailto</tt></b>) in running text. This makes it easy for a user to 729cut and paste the entire name and address into another document or mailer, 730for instance 731 732<blockquote> 733Free Software Foundation <<a href="mailto:gnu@gnu.org">gnu@gnu.org</a>> 734</blockquote> 735 736<p> 737For exponentiation use "<b><tt>^</tt></b>" (not "**" or "exp()") plus 738writing the exponent as a superscript in <b><tt><small></tt></b> 739size: 740 741<blockquote> 742Something<b><tt>^<sup></tt></b><b><tt><small></tt></b>exponent<b><tt></small></sup></tt></b>. 743</blockquote> 744 745<p> 746to look like this: 747 748<blockquote> 749Something<b><tt>^</tt></b><sup><small>exponent</small></sup> 750</blockquote> 751 752<p> 753This is intended for readability both in a browser and as plain text. 754 755<!-- [2.0 end contents] ==================================================== --> 756 757<!-- [3.0 begin visible trailer] =========================================== --> 758<hr> 759 760<p> 761<small>Copyright © 1996, 2000 Aladdin Enterprises. All rights 762reserved.</small> 763 764<p> 765This software is provided AS-IS with no warranty, either express or 766implied. 767 768This software is distributed under license and may not be copied, 769modified or distributed except as expressly authorized under the terms 770of the license contained in the file LICENSE in this distribution. 771 772For more information about licensing, please refer to 773http://www.ghostscript.com/licensing/. For information on 774commercial licensing, go to http://www.artifex.com/licensing/ or 775contact Artifex Software, Inc., 101 Lucas Valley Road #110, 776San Rafael, CA 94903, U.S.A., +1(415)492-9861. 777 778<p> 779<small>Ghostscript version 8.53, 20 October 2005 780 781<!-- [3.0 end visible trailer] ============================================= --> 782 783</body> 784</html> 785