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