git.oblomov.eu Git - wine/blob - documentation/documentation.sgml

   1   <chapter id="documentation">
   2     <title>Documenting Wine</title>
   3     <para>How to help out with the Wine documentation effort...</para>
   4
   5     <sect1 id="api-docs">
   6       <title>Writing Wine API Documentation</title>
   7
   8       <para>
   9         Written by &name-douglas-ridgway; <email>&email-douglas-ridgway;</email>
  10       </para>
  11       <para>
  12         (Extracted from <filename>wine/documentation/README.documentation</filename>)
  13       </para>
  14
  15       <para>
  16         To improve the documentation of the Wine API, just add
  17         comments to the existing source. For example,
  18       </para>
  19       <screen>
  20 /******************************************************************
  21  *         CopyMetaFileA   (GDI32.23)
  22  *
  23  *  Copies the metafile corresponding to hSrcMetaFile to either
  24  *  a disk file, if a filename is given, or to a new memory based
  25  *  metafile, if lpFileName is NULL.
  26  *
  27  * RETURNS
  28  *
  29  *  Handle to metafile copy on success, NULL on failure.
  30  *
  31  * BUGS
  32  *
  33  *  Copying to disk returns NULL even if successful.
  34  */
  35 HMETAFILE WINAPI CopyMetaFileA(
  36                    HMETAFILE hSrcMetaFile, /* handle of metafile to copy */
  37                    LPCSTR lpFilename /* filename if copying to a file */
  38 ) { ... }
  39       </screen>
  40       <para>
  41         becomes, after processing with <command>c2man</command> and
  42         <command>nroff -man</command>,
  43       </para>
  44       <screen>
  45 CopyMetaFileA(3w)                               CopyMetaFileA(3w)
  46
  47
  48 NAME
  49        CopyMetaFileA   (GDI32.23)
  50
  51 SYNOPSIS
  52        HMETAFILE CopyMetaFileA
  53        (
  54             HMETAFILE hSrcMetaFile,
  55             LPCSTR lpFilename
  56        );
  57
  58 PARAMETERS
  59        HMETAFILE hSrcMetaFile
  60               Handle of metafile to copy.
  61
  62        LPCSTR lpFilename
  63               Filename if copying to a file.
  64
  65 DESCRIPTION
  66        Copies  the  metafile  corresponding  to  hSrcMetaFile  to
  67        either a disk file, if a filename is given, or  to  a  new
  68        memory based metafile, if lpFileName is NULL.
  69
  70 RETURNS
  71        Handle to metafile copy on success, NULL on failure.
  72
  73 BUGS
  74        Copying to disk returns NULL even if successful.
  75
  76 SEE ALSO
  77        GetMetaFileA(3w),   GetMetaFileW(3w),   CopyMetaFileW(3w),
  78        PlayMetaFile(3w),  SetMetaFileBitsEx(3w),  GetMetaFileBit-
  79        sEx(3w)
  80       </screen>
  81     </sect1>
  82
  83     <sect1 id="wine-docbook">
  84       <title>The Wine DocBook System</title>
  85
  86       <para>
  87         Written by &name-john-sheets; <email>&email-john-sheets;</email>
  88       </para>
  89
  90       <sect2 id="writing-docbook">
  91         <title>Writing Documentation with DocBook</title>
  92
  93         <para>
  94           DocBook is a flavor of <acronym>SGML</acronym>
  95           (<firstterm>Standard Generalized Markup
  96           Language</firstterm>), a syntax for marking up the contents
  97           of documents.  HTML is another very common flavor of SGML;
  98           DocBook markup looks very similar to HTML markup, although
  99           the names of the markup tags differ.
 100         </para>
 101
 102         <sect3>
 103           <title>Terminology</title>
 104
 105           <para>
 106             SGML markup contains a number of syntactical elements that
 107             serve different purposes in the markup.  We'll run through
 108             the basics here to make sure we're on the same page when
 109             we refer to SGML semantics.
 110           </para>
 111           <para>
 112             The basic currency of SGML is the
 113             <firstterm>tag</firstterm>.  A simple tag consists of a
 114             pair of angle brackets and the name of the tag.  For
 115             example, the <sgmltag>para</sgmltag> tag would appear in
 116             an SGML document as <sgmltag
 117             class="starttag">para</sgmltag>.  This start tag indicates
 118             that the immediately following text should be classified
 119             according to the tag.  In regular SGML, each opening tag
 120             must have a matching end tag to show where the start tag's
 121             contents end.  End tags begin with
 122             <quote><literal>&lt;/</literal></quote> markup, e.g.,
 123             <sgmltag class="endtag">para</sgmltag>.
 124           </para>
 125           <para>
 126             The combination of a start tag, contents, and an end tag
 127             is called an <firstterm>element</firstterm>.  SGML
 128             elements can be nested inside of each other, or contain
 129             only text, or may be a combination of both text and other
 130             elements, although in most cases it is better to limit
 131             your elements to one or the other.
 132           </para>
 133           <para>
 134             The <acronym>XML</acronym> (<firstterm>eXtensible Markup
 135             Language</firstterm>) specification, a modern subset of
 136             the SGML specification, adds a so-called <firstterm>empty
 137             tag</firstterm>, for elements that contain no text
 138             content.  The entire element is a single tag, ending with
 139             <quote><literal>/&gt;</literal></quote>, e.g.,
 140             <sgmltag>&lt;xref/&gt;</sgmltag>.  However, use of this
 141             tag style restricts you to XML DocBook processing, and
 142             your document may no longer compile with SGML-only
 143             processing systems.
 144           </para>
 145           <!-- *** Note: We could normally use the "emptytag"
 146             attribute for XML empty tags, but that's only a recent
 147             addition, and we don't want to screw up documents
 148             generated against older stylesheets.
 149           *** -->
 150           <para>
 151             Often a processing system will need more information about
 152             an element than you can provide with just tags.  SGML
 153             allows you to add extra <quote>hints</quote> in the form
 154             of SGML <firstterm>attributes</firstterm> to pass along
 155             this information.  The most common use of attributes in
 156             DocBook is giving specific elements a name, or an ID, so
 157             you can refer to it from elsewhere.  This ID can be used
 158             for many things, including file-naming for HTML output,
 159             hyper-linking to specific parts of the document, and even
 160             pulling text from that element (see the <sgmltag
 161             class="starttag">xref</sgmltag> tag).
 162           </para>
 163           <para>
 164             An SGML attribute appears inside the start tag, between
 165             the &lt; and &gt; brackets.  For example, if you wanted to
 166             set the <sgmltag class="attribute">id</sgmltag> attribute
 167             of the <sgmltag class="starttag">book</sgmltag> element to
 168             <quote>mybook</quote>, you would create a start tag like
 169             this: <programlisting>&lt;book id="mybook"></programlisting>
 170           </para>
 171           <para>
 172             Notice that the contents of the attribute are enclosed in
 173             quote marks.  These quotes are optional in SGML, but
 174             mandatory in XML.  It's a good habit to use quotes, as it
 175             will make it much easier to migrate your documents to an
 176             XML processing system later on.
 177           </para>
 178           <para>
 179             You can also specify more than one attribute in a single
 180             tag: <programlisting>&lt;book id="mybook" status="draft"></programlisting>
 181           </para>
 182           <para>
 183             Another commonly used type of SGML markup is the
 184             <firstterm>entity</firstterm>.  An entity lets you
 185             associate a block of text with a name.  You declare the
 186             entity once, at the beginning of your document, and can
 187             invoke it as many times as you like throughout the
 188             document.  You can use entities as shorthand, or to make
 189             it easier to maintain certain phrases in a central
 190             location, or even to insert the contents of an entire file
 191             into your document.
 192           </para>
 193           <para>
 194             An entity in your document is always surrounded by the
 195             <quote>&amp;</quote> and <quote>;</quote> characters.  One
 196             entity you'll need sooner or later is the one for the
 197             <quote>&lt;</quote> character.  Since SGML expects all
 198             tags to begin with a <quote>&lt;</quote>, the
 199             <quote>&lt;</quote> is a reserved character.  To use it in
 200             your document (as I am doing here), you must insert it
 201             with the <literal>&amp;lt;</literal> entity.  Each time
 202             the SGML processor encounters <literal>&amp;lt;</literal>,
 203             it will place a literal <quote>&lt;</quote> in the output
 204             document.
 205           </para>
 206           <para>
 207             The final term you'll need to know when writing simple
 208             DocBook documents is the <acronym>DTD</acronym>
 209             (<firstterm>Document Type Declaration</firstterm>).  The
 210             DTD defines the flavor of SGML a given document is written
 211             in.  It lists all the legal tag names, like <sgmltag
 212             class="starttag">book</sgmltag>, <sgmltag
 213             class="starttag">para</sgmltag>, and so on, and declares
 214             how those tags are allowed to be used together.  For
 215             example, it doesn't make sense to put a <sgmltag
 216             class="starttag">book</sgmltag> element inside a <sgmltag
 217             class="starttag">para</sgmltag> paragraph element -- only
 218             the reverse.
 219           </para>
 220           <para>
 221             The DTD thus defines the legal structure of the document.
 222             It also declares which attributes can be used with which
 223             tags.  The SGML processing system can use the DTD to make
 224             sure the document is laid out properly before attempting
 225             to process it.  SGML-aware text editors like <link
 226             linkend="emacs-psgml">Emacs</link> can also use the DTD to
 227             guide you while you write, offering you choices about
 228             which tags you can add in different places in the
 229             document, and beeping at you when you try to add a tag
 230             where it doesn't belong.
 231           </para>
 232           <para>
 233             Generally, you will declare which DTD you want to use as
 234             the first line of your SGML document.  In the case of
 235             DocBook, you will use something like this:
 236             <programlisting>&lt!doctype book PUBLIC "-//OASIS//DTD
 237             DocBook V3.1//EN" []> &lt;book> ...
 238             &lt;/book></programlisting>
 239           </para>
 240           <para>
 241             Note that you must specify your toplevel element inside
 242             the doctype declaration.  If you were writing an article
 243             rather than a book, you might use this declaration instead:
 244             <programlisting>&lt!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
 245 &lt;article>
 246 ...
 247 &lt;/article></programlisting>
 248           </para>
 249         </sect3>
 250
 251         <sect3 id="sgml-document">
 252           <title>The Document</title>
 253           <para>
 254             Once you're comfortable with SGML, creating a DocBook
 255             document is quite simple and straightforward.  Even
 256             though DocBook contains over 300 different tags, you can
 257             usually get by with only a small subset of those tags.
 258             Most of them are for inline formatting, rather than for
 259             document structuring.  Furthermore, the common tags have
 260             short, intuitive names.
 261           </para>
 262           <para>
 263             Below is a (completely nonsensical) example to illustrate
 264             how a simple document might be laid out.  Notice that all
 265             <sgmltag class="starttag">chapter</sgmltag> and <sgmltag
 266             class="starttag">sect1</sgmltag> elements have <sgmltag
 267             class="attribute">id</sgmltag> attributes.  This is not
 268             mandatory, but is a good habit to get into, as DocBook is
 269             commonly converted into HTML, with a separate generated
 270             file for each <sgmltag class="starttag">book</sgmltag>,
 271             <sgmltag class="starttag">chapter</sgmltag>, and/or <sgmltag
 272             class="starttag">sect1</sgmltag> element.  If the given
 273             element has an <sgmltag class="attribute">id</sgmltag>
 274             attribute, the processor will typically name the file
 275             accordingly.  Thus, the below document might result in
 276             <filename>index.html</filename>,
 277             <filename>chapter-one.html</filename>,
 278             <filename>blobs.html</filename>, and so on.
 279           </para>
 280           <para>
 281             Also notice the text marked off with <quote>&lt;!--
 282             </quote> and <quote> --&gt;</quote> characters.  These
 283             denote SGML comments.  SGML processors will completely
 284             ignore anything between these markers, similar to
 285             <quote>/*</quote> and <quote>*/</quote> comments in C
 286             source code.
 287           </para>
 288
 289           <!-- Encase the following SGML excerpt inside a CDATA
 290                block so we don't have to bother converting all
 291                brackets to entities
 292           -->
 293           <programlisting>
 294 <![CDATA[
 295 <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
 296 <book id="index">
 297   <bookinfo>
 298     <title>A Poet's Guide to Nonsense</title>
 299   </bookinfo>
 300
 301   <chapter id="chapter-one">
 302     <title>Blobs and Gribbles</title>
 303
 304     <!-- This section contains only one major topic -->
 305     <sect1 id="blobs">
 306       <title>The Story Behind Blobs</title>
 307       <para>
 308         Blobs are often mistaken for ice cubes and rain
 309         puddles...
 310       </para>
 311     </sect1>
 312
 313     <!-- This section contains embedded sub-sections -->
 314     <sect1 id="gribbles">
 315       <title>Your Friend the Gribble</title>
 316       <para>
 317         A Gribble is a cute, unassuming little fellow...
 318       </para>
 319
 320       <sect2 id="gribble-temperament">
 321         <title>Gribble Temperament</title>
 322         <para>
 323           When left without food for several days...
 324         </para>
 325       </sect2>
 326
 327       <sect2 id="gribble-appearance">
 328         <title>Gribble Appearance</title>
 329         <para>
 330           Most Gribbles have a shock of white fur running from...
 331         </para>
 332       </sect2>
 333     </sect1>
 334   </chapter>
 335
 336   <chapter id="chapter-two">
 337     <title>Phantasmagoria</title>
 338
 339     <sect1 id="dretch-pools">
 340       <title>Dretch Pools</title>
 341
 342       <para>
 343         When most poets think of Dretch Pools, they tend to...
 344       </para>
 345     </sect>
 346   </chapter>
 347 </book>
 348 ]]>
 349 </programlisting>
 350         </sect3>
 351
 352         <sect3>
 353           <title>Common Elements</title>
 354           <para>
 355             Once you get used to the syntax of SGML, the next hurdle
 356             in writing DocBook documentation is to learn the many
 357             DocBook-specific tag names, and when to use them.  DocBook
 358             was created for technical documentation, and as such, the
 359             tag names and document structure are slanted towards the
 360             needs of such documentation.
 361           </para>
 362           <para>
 363             To cover its target audience, DocBook declares a wide
 364             variety of specialized tags, including tags for formatting
 365             source code (with somewhat of a C/C++ bias), computer
 366             prompts, GUI application features, keystrokes, and so on.
 367             DocBook also includes tags for universal formatting needs,
 368             like headers, footnotes, tables, and graphics.
 369           </para>
 370           <para>
 371             We won't cover all of these elements here (over 300
 372             DocBook tags exist!), but we will cover the basics.  To
 373             learn more about the other tags, check out the official
 374             DocBook guide, at <ulink
 375             url="http://docbook.org">http://docbook.org</ulink>.  To
 376             see how they are used in practice, download the SGML
 377             source for this manual (the Wine Developer Guide) and
 378             browse through it, comparing it to the generated HTML (or
 379             PostScript or PDF).
 380           </para>
 381           <para>
 382             There are often many correct ways to mark up a given piece
 383             of text, and you may have to make guesses about which tag
 384             to use.  Sometimes you'll have to make compromises.
 385             However, remember that it is possible to further <link
 386             linkend="docbook-tweaking">customize the output</link> of
 387             the SGML processors.  If you don't like the way a certain
 388             tag looks in HTML, that doesn't mean you should choose a
 389             different tag based on its output formatting.  The
 390             processing stylesheets can be altered to fix the
 391             formatting of that same tag everywhere in the document
 392             (not just in the place you're working on).  For example,
 393             if you're frustrated that the <sgmltag
 394             class="starttag">systemitem</sgmltag> tag doesn't produce
 395             any formatting by default, you should fix the stylesheets,
 396             not change the valid <sgmltag
 397             class="starttag">systemitem</sgmltag> tag to, for example,
 398             an <sgmltag class="starttag">emphasis</sgmltag> tag.
 399           </para>
 400           <para>
 401             Here are the common SGML elements:
 402           </para>
 403
 404           <variablelist>
 405             <title>Structural Elements</title>
 406             <varlistentry>
 407               <term><sgmltag class="starttag">book</sgmltag></term>
 408               <listitem>
 409                 <para>
 410                   The book is the most common toplevel element, and is
 411                   probably the one you should use for your document.
 412                 </para>
 413               </listitem>
 414             </varlistentry>
 415             <varlistentry>
 416               <term><sgmltag class="starttag">set</sgmltag></term>
 417               <listitem>
 418                 <para>
 419                   If you want to group more than one book into a
 420                   single unit, you can place them all inside a set.
 421                   This is useful when you want to bundle up
 422                   documentation in alternate ways.  We do this with
 423                   the Wine documentation, using a <sgmltag
 424                   class="starttag">set</sgmltag> to put everything
 425                   into a single directory (see
 426                   <filename>documentation/wine-doc.sgml</filename>),
 427                   and a <sgmltag class="starttag">book</sgmltag> to
 428                   put each Wine guide into a separate directory (see
 429                   <filename>documentation/wine-devel.sgml</filename>,
 430                   etc.).
 431                 </para>
 432               </listitem>
 433             </varlistentry>
 434             <varlistentry>
 435               <term><sgmltag class="starttag">chapter</sgmltag></term>
 436               <listitem>
 437                 <para>
 438                   A <sgmltag class="starttag">chapter</sgmltag>
 439                   element includes a single entire chapter of the
 440                   book.
 441                 </para>
 442               </listitem>
 443             </varlistentry>
 444             <varlistentry>
 445               <term><sgmltag class="starttag">part</sgmltag></term>
 446               <listitem>
 447                 <para>
 448                   If the chapters in your book fall into major
 449                   categories or groupings (as in the Wine Developer
 450                   Guide), you can place each collection of chapters
 451                   into a <sgmltag class="starttag">part</sgmltag>
 452                   element.
 453                 </para>
 454               </listitem>
 455             </varlistentry>
 456             <varlistentry>
 457               <term><sgmltag class="starttag">sect?</sgmltag></term>
 458               <listitem>
 459                 <para>
 460                   DocBook has many section elements to divide the
 461                   contents of a chapter into smaller chunks.  The
 462                   encouraged approach is to use the numbered section
 463                   tags, <sgmltag class="starttag">sect1</sgmltag>,
 464                   <sgmltag class="starttag">sect2</sgmltag>, <sgmltag
 465                   class="starttag">sect3</sgmltag>, <sgmltag
 466                   class="starttag">sect4</sgmltag>, and <sgmltag
 467                   class="starttag">sect5</sgmltag> (if necessary).
 468                   These tags must be nested in order: you can't place
 469                   a <sgmltag class="starttag">sect3</sgmltag> directly
 470                   inside a <sgmltag class="starttag">sect1</sgmltag>.
 471                   You have to nest the <sgmltag
 472                   class="starttag">sect3</sgmltag> inside a <sgmltag
 473                   class="starttag">sect2</sgmltag>, and so forth.
 474                   Documents with these explicit section groupings are
 475                   easier for SGML processors to deal with, and lead to
 476                   better organized documents.  DocBook also supplies a
 477                   <sgmltag class="starttag">section</sgmltag> element
 478                   which you can nest inside itself, but its use is
 479                   discouraged in favor of the numbered section tags.
 480                 </para>
 481               </listitem>
 482             </varlistentry>
 483             <varlistentry>
 484               <term><sgmltag class="starttag">title</sgmltag></term>
 485               <listitem>
 486                 <para>
 487                   The title of a book, chapter, part, section, etc.
 488                   In most of the major structural elements, like
 489                   <sgmltag class="starttag">chapter</sgmltag>,
 490                   <sgmltag class="starttag">part</sgmltag>, and the
 491                   various section tags, <sgmltag
 492                   class="starttag">title</sgmltag> is mandatory.  In
 493                   other elements like <sgmltag
 494                   class="starttag">book</sgmltag> and <sgmltag
 495                   class="starttag">note</sgmltag>, it's optional.
 496                 </para>
 497               </listitem>
 498             </varlistentry>
 499             <varlistentry>
 500               <term><sgmltag class="starttag">para</sgmltag></term>
 501               <listitem>
 502                 <para>
 503                   The basic unit of text is the paragraph, represented
 504                   by the <sgmltag class="starttag">para</sgmltag> tag.
 505                   This is probably the tag you'll use most often.  In
 506                   fact, in a simple document, you can probably get
 507                   away with using only <sgmltag
 508                   class="starttag">book</sgmltag>, <sgmltag
 509                   class="starttag">chapter</sgmltag>, <sgmltag
 510                   class="starttag">title</sgmltag>, and <sgmltag
 511                   class="starttag">para</sgmltag>.
 512                 </para>
 513               </listitem>
 514             </varlistentry>
 515             <varlistentry>
 516               <term><sgmltag class="starttag">article</sgmltag></term>
 517               <listitem>
 518                 <para>
 519                   For shorter, more targeted documents, like topic
 520                   pieces and whitepapers, you can use <sgmltag
 521                   class="starttag">article</sgmltag> as your toplevel
 522                   element.
 523                 </para>
 524               </listitem>
 525             </varlistentry>
 526           </variablelist>
 527
 528           <variablelist>
 529             <title>Inline Formatting Elements</title>
 530             <varlistentry>
 531               <term><sgmltag class="starttag">filename</sgmltag></term>
 532               <listitem>
 533                 <para>
 534                   The name of a file.  You can optionally set the
 535                   <sgmltag class="attribute">class</sgmltag> attribute
 536                   to <literal>Directory</literal>,
 537                   <literal>HeaderFile</literal>, and
 538                   <literal>SymLink</literal> to further classify the
 539                   filename.
 540                 </para>
 541               </listitem>
 542             </varlistentry>
 543             <varlistentry>
 544               <term><sgmltag class="starttag">userinput</sgmltag></term>
 545               <listitem>
 546                 <para>
 547                   Literal text entered by the user.
 548                 </para>
 549               </listitem>
 550             </varlistentry>
 551             <varlistentry>
 552               <term><sgmltag class="starttag">computeroutput</sgmltag></term>
 553               <listitem>
 554                 <para>
 555                   Literal text output by the computer.
 556                 </para>
 557               </listitem>
 558             </varlistentry>
 559             <varlistentry>
 560               <term><sgmltag class="starttag">literal</sgmltag></term>
 561               <listitem>
 562                 <para>
 563                   A catch-all element for literal computer data.  Its
 564                   use is somewhat vague; try to use a more specific
 565                   tag if possible, like <sgmltag
 566                   class="starttag">userinput</sgmltag> or <sgmltag
 567                   class="starttag">computeroutput</sgmltag>.
 568                 </para>
 569               </listitem>
 570             </varlistentry>
 571             <varlistentry>
 572               <term><sgmltag class="starttag">quote</sgmltag></term>
 573               <listitem>
 574                 <para>
 575                   An inline quotation.  This tag typically inserts
 576                   quotation marks for you, so you would write <sgmltag
 577                   class="starttag">quote</sgmltag>This is a
 578                   quote<sgmltag class="endtag">quote</sgmltag> rather
 579                   than "This is a quote".  This usage may be a little
 580                   bulkier, but it does allow for automated formatting
 581                   of all quoted material in the document.  Thus, if
 582                   you wanted all quotations to appear in italic, you
 583                   could make the change once in your stylesheet,
 584                   rather than doing a search and replace throughout
 585                   the document.  For larger chunks of quoted text, you
 586                   can use <sgmltag
 587                   class="starttag">blockquote</sgmltag>.
 588                 </para>
 589               </listitem>
 590             </varlistentry>
 591             <varlistentry>
 592               <term><sgmltag class="starttag">note</sgmltag></term>
 593               <listitem>
 594                 <para>
 595                   Insert a side note for the reader.  By default, the
 596                   SGML processor usually prefixes the content with
 597                   "Note:".  You can change this text by adding a
 598                   <sgmltag class="starttag">title</sgmltag> element.
 599                   Thus, to add a visible FIXME comment to the
 600                   documentation, you might write:
 601                 </para>
 602 <programlisting>
 603 <![CDATA[
 604 <note>
 605   <title>FIXME</title>
 606   <para>This section needs more info about...</para>
 607 </note>
 608 ]]></programlisting>
 609                 <para>
 610                   The results will look something like this:
 611                 </para>
 612                   <note>
 613                     <title>FIXME</title>
 614                     <para>This section needs more info about...</para>
 615                   </note>
 616               </listitem>
 617             </varlistentry>
 618             <varlistentry>
 619               <term><sgmltag class="starttag">sgmltag</sgmltag></term>
 620               <listitem>
 621                 <para>
 622                   Used for inserting SGML tags, etc., into a SGML
 623                   document without resorting to a lot of entity
 624                   quoting, e.g., &amp;lt;.  You can change the
 625                   appearance of the text with the <sgmltag
 626                   class="attribute">class</sgmltag> attribute.  Some
 627                   common values of this are
 628                   <literal>starttag</literal>,
 629                   <literal>endtag</literal>,
 630                   <literal>attribute</literal>,
 631                   <literal>attvalue</literal>, and even
 632                   <literal>sgmlcomment</literal>.  See this SGML file,
 633                   <filename>documentation/documentation.sgml</filename>,
 634                   for examples.
 635                 </para>
 636               </listitem>
 637             </varlistentry>
 638             <varlistentry>
 639               <term><sgmltag class="starttag">prompt</sgmltag></term>
 640               <listitem>
 641                 <para>
 642                   The text used for a computer prompt, for example a
 643                   shell prompt, or command-line application prompt.
 644                 </para>
 645               </listitem>
 646             </varlistentry>
 647             <varlistentry>
 648               <term><sgmltag class="starttag">replaceable</sgmltag></term>
 649               <listitem>
 650                 <para>
 651                   Meta-text that should be replaced by the user, not
 652                   typed in literally, e.g., in command descriptions
 653                   and <parameter>--help</parameter> outputs.
 654                 </para>
 655               </listitem>
 656             </varlistentry>
 657             <varlistentry>
 658               <term><sgmltag class="starttag">constant</sgmltag></term>
 659               <listitem>
 660                 <para>
 661                   A programming constant, e.g.,
 662                   <constant>MAX_PATH</constant>.
 663                 </para>
 664               </listitem>
 665             </varlistentry>
 666             <varlistentry>
 667               <term><sgmltag class="starttag">symbol</sgmltag></term>
 668               <listitem>
 669                 <para>
 670                   A symbolic value replaced, for example, by a
 671                   pre-processor.  This applies primarily to C macros,
 672                   but may have other uses.  Use the <sgmltag
 673                   class="starttag">constant</sgmltag> tag instead of
 674                   <sgmltag class="starttag">symbol</sgmltag> where
 675                   appropriate.
 676                 </para>
 677               </listitem>
 678             </varlistentry>
 679             <varlistentry>
 680               <term><sgmltag class="starttag">function</sgmltag></term>
 681               <listitem>
 682                 <para>
 683                   A programming function name.
 684                 </para>
 685               </listitem>
 686             </varlistentry>
 687             <varlistentry>
 688               <term><sgmltag class="starttag">parameter</sgmltag></term>
 689               <listitem>
 690                 <para>
 691                   Programming language parameters you pass with a
 692                   function.
 693                 </para>
 694               </listitem>
 695             </varlistentry>
 696             <varlistentry>
 697               <term><sgmltag class="starttag">option</sgmltag></term>
 698               <listitem>
 699                 <para>
 700                   Parameters you pass to a command-line executable.
 701                 </para>
 702               </listitem>
 703             </varlistentry>
 704             <varlistentry>
 705               <term><sgmltag class="starttag">varname</sgmltag></term>
 706               <listitem>
 707                 <para>
 708                   Variable name, typically in a programming language.
 709                 </para>
 710               </listitem>
 711             </varlistentry>
 712             <varlistentry>
 713               <term><sgmltag class="starttag">type</sgmltag></term>
 714               <listitem>
 715                 <para>
 716                   Programming language types, e.g., from a typedef
 717                   definition.  May have other uses, too.
 718                 </para>
 719               </listitem>
 720             </varlistentry>
 721             <varlistentry>
 722               <term><sgmltag class="starttag">structname</sgmltag></term>
 723               <listitem>
 724                 <para>
 725                   The name of a C-language <type>struct</type>
 726                   declaration, e.g., <structname>sockaddr</structname>.
 727                 </para>
 728               </listitem>
 729             </varlistentry>
 730             <varlistentry>
 731               <term><sgmltag class="starttag">structfield</sgmltag></term>
 732               <listitem>
 733                 <para>
 734                   A field inside a C <type>struct</type>.
 735                 </para>
 736               </listitem>
 737             </varlistentry>
 738             <varlistentry>
 739               <term><sgmltag class="starttag">command</sgmltag></term>
 740               <listitem>
 741                 <para>
 742                   An executable binary, e.g., <command>wine</command>
 743                   or <command>ls</command>.
 744                 </para>
 745               </listitem>
 746             </varlistentry>
 747             <varlistentry>
 748               <term><sgmltag class="starttag">envar</sgmltag></term>
 749               <listitem>
 750                 <para>
 751                   An environment variable, e.g, <envar>$PATH</envar>.
 752                 </para>
 753               </listitem>
 754             </varlistentry>
 755             <varlistentry>
 756               <term><sgmltag class="starttag">systemitem</sgmltag></term>
 757               <listitem>
 758                 <para>
 759                   A generic catch-all for system-related things, like
 760                   OS names, computer names, system resources, etc.
 761                 </para>
 762               </listitem>
 763             </varlistentry>
 764             <varlistentry>
 765               <term><sgmltag class="starttag">email</sgmltag></term>
 766               <listitem>
 767                 <para>
 768                   An email address.  The SGML processor will typically
 769                   add extra formatting characters, and even a
 770                   <literal>mailto:</literal> link for HTML pages.
 771                   Usage: <sgmltag
 772                   class="starttag">email</sgmltag>user@host.com<sgmltag
 773                   class="endtag">email</sgmltag>
 774                 </para>
 775               </listitem>
 776             </varlistentry>
 777             <varlistentry>
 778               <term><sgmltag class="starttag">firstterm</sgmltag></term>
 779               <listitem>
 780                 <para>
 781                   Special emphasis for introducing a new term.  Can
 782                   also be linked to a <sgmltag
 783                   class="starttag">glossary</sgmltag> entry, if
 784                   desired.
 785                 </para>
 786               </listitem>
 787             </varlistentry>
 788           </variablelist>
 789
 790           <variablelist>
 791             <title>Item Listing Elements</title>
 792             <varlistentry>
 793               <term><sgmltag class="starttag">itemizedlist</sgmltag></term>
 794               <listitem>
 795                 <para>
 796                   For bulleted lists, no numbering.  You can tweak the
 797                   layout with SGML attributes.
 798                 </para>
 799               </listitem>
 800             </varlistentry>
 801             <varlistentry>
 802               <term><sgmltag class="starttag">orderedlist</sgmltag></term>
 803               <listitem>
 804                 <para>
 805                   A numbered list; the SGML processor will insert the
 806                   numbers for you.  You can suggest numbering styles
 807                   with the <sgmltag
 808                   class="attribute">numeration</sgmltag> attribute.
 809                 </para>
 810               </listitem>
 811             </varlistentry>
 812             <varlistentry>
 813               <term><sgmltag class="starttag">simplelist</sgmltag></term>
 814               <listitem>
 815                 <para>
 816                   A very simple list of items, often inlined.  Control
 817                   the layout with the <sgmltag
 818                   class="attribute">type</sgmltag> attribute.
 819                 </para>
 820               </listitem>
 821             </varlistentry>
 822             <varlistentry>
 823               <term><sgmltag class="starttag">variablelist</sgmltag></term>
 824               <listitem>
 825                 <para>
 826                   A list of terms with definitions or descriptions,
 827                   like this very list!
 828                 </para>
 829               </listitem>
 830             </varlistentry>
 831           </variablelist>
 832
 833           <variablelist>
 834             <title>Block Text Quoting Elements</title>
 835             <varlistentry>
 836               <term><sgmltag class="starttag">programlisting</sgmltag></term>
 837               <listitem>
 838                 <para>
 839                   Quote a block of source code.  Typically highlighted
 840                   in the output and set off from normal text.
 841                 </para>
 842               </listitem>
 843             </varlistentry>
 844             <varlistentry>
 845               <term><sgmltag class="starttag">screen</sgmltag></term>
 846               <listitem>
 847                 <para>
 848                   Quote a block of visible computer output, like the
 849                   output of a command or chunks of debug logs.
 850                 </para>
 851               </listitem>
 852             </varlistentry>
 853           </variablelist>
 854
 855           <variablelist>
 856             <title>Hyperlink Elements</title>
 857             <varlistentry>
 858               <term><sgmltag class="starttag">link</sgmltag></term>
 859               <listitem>
 860                 <para>
 861                   Generic hypertext link, used for pointing to other
 862                   sections within the current document.  You supply
 863                   the visible text for the link, plus the name of the <sgmltag
 864                   class="attribute">id</sgmltag> attribute of the
 865                   element that you want to link to.  For example:
 866 <programlisting>&lt;link linkend="configuring-wine">the section on configuring wine&lt;/link>
 867 ...
 868 &lt;sect2 id="configuring-wine">
 869 ...</programlisting>
 870                 </para>
 871               </listitem>
 872             </varlistentry>
 873             <varlistentry>
 874               <term><sgmltag class="starttag">xref</sgmltag></term>
 875               <listitem>
 876                 <para>
 877                   In-document hyperlink that can generate its own
 878                   text.  Similar to the <sgmltag
 879                   class="starttag">link</sgmltag> tag, you use the
 880                   <sgmltag class="attribute">linkend</sgmltag>
 881                   attribute to specify which target element you want
 882                   to jump to:
 883                 </para>
 884                 <para>
 885 <programlisting>&lt;xref linkend="configuring-wine">
 886 ...
 887 &lt;sect2 id="configuring-wine">
 888 ...</programlisting>
 889                 </para>
 890                 <para>
 891                   By default, most SGML processors will autogenerate
 892                   some generic text for the <sgmltag
 893                   class="starttag">xref</sgmltag> link, like
 894                   <quote>Section 2.3.1</quote>.  You can use the
 895                   <sgmltag class="attribute">endterm</sgmltag>
 896                   attribute to grab the visible text content of the
 897                   hyperlink from another element:
 898                 </para>
 899                 <para>
 900 <programlisting>&lt;xref linkend="configuring-wine" endterm="config-title">
 901 ...
 902 &lt;sect2 id="configuring-wine">
 903   &lt;title id="config-title">Configuring Wine&lt;/title>
 904 ...</programlisting>
 905                 </para>
 906                 <para>
 907                   This would create a link to the
 908                   <symbol>configuring-wine</symbol> element,
 909                   displaying the text of the
 910                   <symbol>config-title</symbol> element for the
 911                   hyperlink.  Most often, you'll add an <sgmltag
 912                   class="attribute">id</sgmltag> attribute to the
 913                   <sgmltag class="starttag">title</sgmltag> of the
 914                   section you're linking to, as above, in which case
 915                   the SGML processor will use the target's title text
 916                   for the link text.
 917                 </para>
 918                 <para>
 919                   Alternatively, you can use an <sgmltag
 920                   class="attribute">xreflabel</sgmltag> attribute in
 921                   the target element tag to specify the link text:
 922                 </para>
 923 <programlisting>&lt;sect1 id="configuring-wine" xreflabel="Configuring Wine"></programlisting>
 924                 <note>
 925                   <para>
 926                     <sgmltag class="starttag">xref</sgmltag> is an
 927                     empty element.  You don't need a closing tag for
 928                     it (this is defined in the DTD).  In SGML
 929                     documents, you should use the form <sgmltag
 930                     class="starttag">xref</sgmltag>, while in XML
 931                     documents you should use
 932                     <sgmltag>&lt;xref/></sgmltag>.
 933                   </para>
 934                 </note>
 935               </listitem>
 936             </varlistentry>
 937             <varlistentry>
 938               <term><sgmltag class="starttag">anchor</sgmltag></term>
 939               <listitem>
 940                 <para>
 941                   An invisible tag, used for inserting <sgmltag
 942                   class="attribute">id</sgmltag> attributes into a
 943                   document to link to arbitrary places (i.e., when
 944                   it's not close enough to link to the top of an
 945                   element).
 946                 </para>
 947               </listitem>
 948             </varlistentry>
 949             <varlistentry>
 950               <term><sgmltag class="starttag">ulink</sgmltag></term>
 951               <listitem>
 952                 <para>
 953                   Hyperlink in URL form, e.g., <ulink
 954                   url="http://www.winehq.com">http://www.winehq.com</ulink>.
 955                 </para>
 956               </listitem>
 957             </varlistentry>
 958             <varlistentry>
 959               <term><sgmltag class="starttag">olink</sgmltag></term>
 960               <listitem>
 961                 <para>
 962                   Indirect hyperlink; can be used for linking to
 963                   external documents.  Not often used in practice.
 964                 </para>
 965               </listitem>
 966             </varlistentry>
 967           </variablelist>
 968         </sect3>
 969
 970         <sect3>
 971           <title>Multiple SGML files</title>
 972           <para>
 973             How to split an SGML document into multiple files...
 974           </para>
 975         </sect3>
 976       </sect2>
 977
 978       <sect2 id="sgml-environment">
 979         <title>The SGML Environment</title>
 980
 981         <para>
 982           You can write SGML/DocBook documents in any text editor you
 983           might find (although as we'll find in <xref
 984           linkend="emacs-psgml">, some editors are more friendly for
 985           this task than others).  However, if you want to convert
 986           those documents into a more friendly form for reading, such
 987           as HTML, PostScript, or PDF, you will need a working SGML
 988           environment.  This section attempts to lay out the various
 989           SGML rendering systems, and how they are set up on the
 990           popular Linux distributions.
 991         </para>
 992
 993         <sect3>
 994           <title>DSSSL Environment</title>
 995           <para>
 996             Explain tools and methodologies..
 997           </para>
 998         </sect3>
 999
1000         <sect3>
1001           <title>XSLT Environment</title>
1002           <para>
1003             Explain tools and methodologies...
1004           </para>
1005         </sect3>
1006
1007         <sect3>
1008           <title>SGML on Redhat</title>
1009           <para>
1010             Most Linux distributions have everything you need already
1011             bundled up in package form.  Unfortunately, each
1012             distribution seems to handle its SGML environment
1013             differently, installing it into different paths, and
1014             naming its packages according to its own whims.
1015           </para>
1016         </sect3>
1017
1018         <sect3>
1019           <title>SGML on Debian</title>
1020           <para>
1021             List package names and install locations...
1022           </para>
1023         </sect3>
1024
1025         <sect3>
1026           <title>SGML on Other Distributions</title>
1027           <para>
1028             List package names and install locations...
1029           </para>
1030         </sect3>
1031       </sect2>
1032
1033       <sect2 id="emacs-psgml">
1034         <title>PSGML Mode in Emacs</title>
1035         <para>
1036           Although you can write SGML documentation in any simple text
1037           editor, some editors provide extra support for entering SGML
1038           tags, and for verifying that the SGML you create is valid.
1039           SGML has been around for a long time, and many commercial
1040           editors exist for it; however, until recently open source
1041           SGML editors have been scarce.
1042         </para>
1043         <note>
1044           <title>FIXME</title>
1045           <para>
1046             List the available commercial and open source SGML
1047             editors.
1048           </para>
1049         </note>
1050         <para>
1051           The most commonly used open source SGML editor is Emacs,
1052           with the PSGML <firstterm>mode</firstterm>, or extension.
1053           Emacs does not supply a GUI or WYSIWYG (What You See Is What
1054           You Get) interface, but it does provide many helpful
1055           shortcuts for creating SGML, as well as automatic
1056           formatting, validity checking, and the ability to create
1057           your own macros to simplify complex, repetitive actions.
1058           We'll touch briefly on each of these points.
1059         </para>
1060         <para>
1061           The first thing you need is a working installation of Emacs
1062           (or XEmacs), with the PSGML package.  Most Linux
1063           distributions provide both as easy-to-install packages.
1064         </para>
1065         <para>
1066           Next, you'll need a working SGML environment.  See <xref
1067           linkend="sgml-environment"> for more info on setting that
1068           up.
1069         </para>
1070       </sect2>
1071
1072       <sect2 id="docbook-build">
1073         <title>The DocBook Build System</title>
1074
1075         <sect3 id="docbook-infrastructure">
1076           <title>Basic Infrastructure</title>
1077           <para>
1078             How the build/make system works (makefiles, db2html,
1079             db2html-winehq, jade, stylesheets).
1080           </para>
1081         </sect3>
1082
1083         <sect3 id="docbook-tweaking">
1084           <title>Tweaking the DSSSL stylesheets</title>
1085           <para>
1086             Things you can tweak, and how to do it (examples from
1087             default.dsl and winehq.dsl).
1088           </para>
1089         </sect3>
1090
1091         <sect3 id="docbook-generating">
1092           <title>Generating docs for Wine web sites</title>
1093           <para>
1094             Explain make_winehq, rsync, etc.
1095           </para>
1096         </sect3>
1097       </sect2>
1098     </sect1>
1099   </chapter>
1100
1101 <!-- Keep this comment at the end of the file
1102 Local variables:
1103 mode: sgml
1104 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
1105 End:
1106 -->