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