documentation/documentation.sgml

   1   <chapter id="documentation">
   2     <title>Documenting Wine</title>
   3
   4     <para>
   5       This chapter describes how you can help improve Wines documentation.
   6     </para>
   7
   8     <para>
   9       Like most large scale volunteer projects, Wine is strongest in areas that are rewarding
  10       for its volunteers to work in. The majority of contributors send code patches either
  11       fixing bugs, adding new functionality or otherwise improving the software components of
  12       the distribution. A lesser number contribute in other ways, such as reporting bugs and
  13       regressions, creating tests, providing organizational assistance, or helping to document
  14       Wine.
  15     </para>
  16
  17     <para>
  18       Documentation is important for many reasons, and is often the key to the end user having
  19       a successful experience in installing, setting up and using software. Because Wine is a
  20       complicated, evolving entity, providing quality up to date documentation is vital to
  21       encourage more people to persevere with using and contributing to the project.
  22       The following sections describe in detail how to go about adding to or updating Wines
  23       existing documentation.
  24     </para>
  25
  26     <sect1 id="doc-overview">
  27       <title>An Overview Of Wine Documentation</title>
  28
  29       <para>
  30         The Wine source code tree comes with a large amount of documentation in the
  31         <filename>documentation/</filename> subdirectory. This used to be a collection
  32         of text files culled from various places such as the Wine Weekly News and the wine-devel
  33         mailing list, but was reorganized some time ago into a number of books, each of which is
  34         marked up using SGML. You are reading one of these books (the
  35         <emphasis>Wine Developer's Guide</emphasis>) right now.
  36       </para>
  37
  38       <para>
  39         Since being reorganized, the books have been updated and extended regularly. In their
  40         current state they provide a good framework which over time can be expanded and kept
  41         up to date. This means that most of the time when further documentation is added, it is
  42         a simple matter of updating the content of an already existing file. The books
  43         available at the time of writing are:
  44
  45           <itemizedlist>
  46
  47           <listItem><para>
  48           The <emphasis>Wine User Guide</emphasis>. This book contains information for end users
  49           on installing, configuring and running Wine.
  50           </para></listitem>
  51
  52           <listItem><para>
  53           The <emphasis>Wine Developer's Guide</emphasis>. This book contains information and
  54           guidelines for developers and contributors to the Wine project.
  55           </para></listitem>
  56
  57           <listItem><para>
  58           The <emphasis>Winelib User's Guide</emphasis>. This book contains information for
  59           developers using Winelib to port Win32 applications to Unix.
  60           </para></listitem>
  61
  62           <listItem><para>
  63           The <emphasis>Wine Packagers Guide</emphasis>. This book contains information for
  64           anyone who will be distributing Wine to end users in a prepackaged format.
  65           </para></listitem>
  66
  67           <listItem><para>
  68           The <emphasis>Wine FAQ</emphasis>. This book contains frequently asked questions
  69           about Wine with their answers.
  70           </para></listitem>
  71           </itemizedlist>
  72       </para>
  73
  74       <para>
  75         Another source of documentation is the <emphasis>Wine API Guide</emphasis>. This is
  76         generated information taken from special comments placed in the Wine source code.
  77         When you update or add new API calls to Wine you should consider documenting them so
  78         that developers can determine what the API does and how it should be used.
  79       </para>
  80
  81       <para>
  82         The next sections describe how to create Wine API documentation and how to work with
  83         SGML so you can add to the existing books.
  84       </para>
  85     </sect1>
  86
  87     <sect1 id="api-docs">
  88       <title>Writing Wine API Documentation</title>
  89
  90       <sect2 id="api-docs-intro">
  91       <title>Introduction to API Documentation</title>
  92       <para>
  93         Wine includes a large amount of documentation on the API functions
  94         it implements. There are several reasons to want to document the Win32
  95         API:
  96           <itemizedlist>
  97
  98           <listItem><para>
  99           To allow Wine developers to know what each function should do, should
 100           they need to update or fix it.
 101           </para></listitem>
 102
 103           <listItem><para>
 104           To allow Winelib users to understand the functions that are available
 105           to their applications.
 106           </para></listitem>
 107
 108           <listItem><para>
 109           To provide an alternative source of free documentation on the Win32 API.
 110           </para></listitem>
 111
 112           <listItem><para>
 113           To provide more accurate documentation where the existing documentation
 114           is accidentally or deliberately vague or misleading.
 115           </para></listitem>
 116
 117           </itemizedlist>
 118       </para>
 119
 120       <para>
 121         To this end, a semi formalized way of producing documentation from the Wine
 122         source code has evolved. Since the primary users of API documentation are Wine
 123         developers themselves, documentation is usually inserted into the source code
 124         in the form of comments and notes. Good things to include in the documentation
 125         of a function include:
 126           <itemizedlist>
 127
 128           <listItem><para>
 129           The purpose of the function.
 130           </para></listitem>
 131
 132           <listItem><para>
 133           The parameters of the function and their purpose.
 134           </para></listitem>
 135
 136           <listItem><para>
 137           The return value of the function, in success as well as failure cases.
 138           </para></listitem>
 139
 140           <listItem><para>
 141           Additional notes such as interaction with other parts of the system, differences
 142           between Wines implementation and Win32s, errors in MSDN documentation,
 143           undocumented cases and bugs that Wine corrects or is compatible with.
 144           </para></listitem>
 145
 146           </itemizedlist>
 147       </para>
 148
 149       <para>
 150         Good documentation helps developers be aware of the effects of making changes. It
 151         also allows good tests to be written which cover all of the documented cases.
 152       </para>
 153
 154       <para>
 155         Note that you do not need to be a programmer to update the documentation in Wine.
 156         If you would like to contribute to the project, patches that improve the API
 157         documentation are welcome. The following describes how to format any documentation
 158         that you write so that the Wine documentation generator can extract it and make it
 159         available to other developers and users.
 160       </para>
 161
 162       <para>
 163         In general, if you did not write the function in question, you should be wary of
 164         adding comments to other peoples code. It is quite possible you may misunderstand
 165         or misrepresent what the original author intended! Adding API documentation on
 166         the other hand can be done by anybody, since in most cases there is plenty of
 167         information about what a function is supposed to do (if it isn't obvious)
 168         available in books and articles on the internet.
 169       </para>
 170
 171       <para>
 172         A final warning concerns copyright and must be noted. If you read MSDN or any
 173         publication in order to find out what an API call does, you must be aware that
 174         the text you are reading is copyrighted and in most cases cannot legally be
 175         reproduced without the authors permission. If you copy verbatim any information
 176         from such sources and submit it for inclusion into Wine, you open yourself up
 177         to potential legal liability. You must ensure that anything you submit is
 178         your own work, although it can be based on your understanding gleaned from
 179         reading other peoples work.
 180       </para>
 181       </sect2>
 182
 183       <sect2 id="api-docs-basics">
 184       <title>Basic API Documentation</title>
 185
 186       <para>
 187         The general form of an API comment in Wine is a block comment immediately before a
 188         function is implemented in the source code. General comments within a function body or
 189         at the top of an implementation file are ignored by the API documentation generator.
 190         Such comments are for the benefit of developers only, for example to explain what the
 191         source code is doing or to describe something that may not be obvious to the person
 192         reading the source code.
 193       </para>
 194
 195       <para>
 196         The following text uses the function <emphasis>PathRelativePathToA()</emphasis> from
 197         <filename>SHLWAPI.DLL</filename> as an example. You can find this function in the Wine
 198         source code tree in the file <filename>dlls/shlwapi/path.c</filename>.
 199       </para>
 200
 201       <para>
 202         The first line of the comment gives the name of the function, the DLL that the
 203         function is exported from, and its export ordinal number. This is the simplest
 204         (and most common type of) comment:
 205       </para>
 206
 207       <screen>
 208 /*************************************************************************
 209  * PathRelativePathToA   [SHLWAPI.@]
 210  */
 211       </screen>
 212
 213       <para>
 214         The functions name and the DLL name are obvious. The ordinal number takes one of
 215         two forms: Either <command>@</command> as in the above, or a number if the export
 216         is exported by ordinal. You can see which to use by looking at the DLL's
 217         <filename>.spec</filename> file. If the line on which the function is listed begins
 218         with a number, use it, otherwise use the <command>@</command> symbol, which indicates
 219         that this function is imported only by name.
 220       </para>
 221
 222       <para>
 223         Note also that round or square brackets can be used, and whitespace between the name
 224         and the DLL/ordinal is free form. Thus the following is equally valid:
 225       </para>
 226
 227       <screen>
 228 /*************************************************************************
 229  *              PathRelativePathToA     (SHLWAPI.@)
 230  */
 231       </screen>
 232
 233       <para>
 234         This basic comment will not get processed into documentation, since it
 235         contains no information. In order to produce documentation for the function,
 236         We must add some of the information listed above.
 237       </para>
 238
 239       <para>
 240         First we add a description of the function. This can be as long as you like, but
 241         typically contains only a brief description of what the function is meant to do
 242         in general terms. It is free form text:
 243       </para>
 244
 245       <screen>
 246 /*************************************************************************
 247  * PathRelativePathToA   [SHLWAPI.@]
 248  *
 249  * Create a relative path from one path to another.
 250  */
 251       </screen>
 252
 253       <para>
 254         To be truly useful however we must document the parameters to the function.
 255         There are two methods for doing this: In the comment, or in the function
 256         prototype.
 257       </para>
 258
 259       <para>
 260         Parameters documented in the comment should be formatted as follows:
 261       </para>
 262
 263       <screen>
 264 /*************************************************************************
 265  * PathRelativePathToA   [SHLWAPI.@]
 266  *
 267  * Create a relative path from one path to another.
 268  *
 269  * PARAMS
 270  *  lpszPath   [O] Destination for relative path
 271  *  lpszFrom   [I] Source path
 272  *  dwAttrFrom [I] File attribute of source path
 273  *  lpszTo     [I] Destination path
 274  *  dwAttrTo   [I] File attributes of destination path
 275  *
 276  */
 277       </screen>
 278
 279       <para>
 280         The parameters section starts with <command>PARAMS</command> on its own line.
 281         Each parameter is listed in the order they appear in the functions prototype,
 282         first with the parameters name, followed by its input/output status, followed
 283         by a free form text description of the comment.
 284       </para>
 285
 286       <para>
 287         The input/output status tells the programmer whether the value will be modified
 288         by the function (an output parameter), or only read (an input parameter). The
 289         status must be enclosed in square brackets to be recognized, otherwise, or if it
 290         is absent, anything following the parameter name is treated as the parameter
 291         description. This field is case insensitive and can be any of the following:
 292         <command>[I]</command>, <command>[In]</command>, <command>[O]</command>,
 293         <command>[Out]</command>, <command>[I/O]</command>, <command>[In/Out]</command>.
 294       </para>
 295
 296       <para>
 297         Parameters documented in the prototype should be formatted as follows:
 298       </para>
 299
 300       <screen>
 301 /*************************************************************************
 302  * PathRelativePathToA   [SHLWAPI.@]
 303  *
 304  * Create a relative path from one path to another.
 305  *
 306  */
 307 BOOL WINAPI PathRelativePathToA(
 308  LPSTR  lpszPath,   /* [O] Destination for relative path */
 309  LPCSTR lpszFrom,   /* [I] Source path */
 310  DWORD  dwAttrFrom, /* [I] File attribute of source path */
 311  LPCSTR lpszTo,     /* [I] Destination path */
 312  DWORD  dwAttrTo)   /* [I] File attributes of destination path */
 313       </screen>
 314
 315       <para>
 316         The choice of which style to use is up to you, although for readability it
 317         is suggested you stick with the same style within a single source file.
 318       </para>
 319
 320       <para>
 321         Following the description and parameters come a number of optional sections, all
 322         in the same format. A section is defined as the section name, which is an all upper
 323         case section name on its own line, followed by free form text. You can create any
 324         sections you like, however for consistency it is recommended you use the following
 325         section names:
 326           <orderedlist>
 327
 328           <listItem><para>
 329           <command>NOTES</command>. Anything that needs to be noted about the function
 330           such as special cases and the effects of input arguments.
 331           </para></listitem>
 332
 333           <listItem><para>
 334           <command>BUGS</command>. Any bugs in the function that exist 'by design', i.e.
 335           those that will not be fixed or exist for compatibility with Windows.
 336           </para></listitem>
 337
 338           <listItem><para>
 339           <command>TODO</command>. Any unhandled cases or missing functionality in the Wine
 340           implementation of the function.
 341           </para></listitem>
 342
 343           <listItem><para>
 344           <command>FIXME</command>. Things that should be updated or addressed in the implementation
 345           of the function at some future date (perhaps dependent on other parts of Wine). Note
 346           that if this information is only relevant to Wine developers then it should probably
 347           be placed in the relevant code section instead.
 348           </para></listitem>
 349           </orderedlist>
 350       </para>
 351
 352       <para>
 353         Following or before the optional sections comes the <command>RETURNS</command> section
 354         which describes the return value of the function. This is free form text but should include
 355         what is returned on success as well as possible error return codes. Note that this
 356         section must be present for documentation to be generated for your comment.
 357       </para>
 358
 359       <para>
 360         Our final documentation looks like the following:
 361       </para>
 362
 363       <screen>
 364 /*************************************************************************
 365  * PathRelativePathToA   [SHLWAPI.@]
 366  *
 367  * Create a relative path from one path to another.
 368  *
 369  * PARAMS
 370  *  lpszPath   [O] Destination for relative path
 371  *  lpszFrom   [I] Source path
 372  *  dwAttrFrom [I] File attribute of source path
 373  *  lpszTo     [I] Destination path
 374  *  dwAttrTo   [I] File attributes of destination path
 375  *
 376  * RETURNS
 377  *  TRUE  If a relative path can be formed. lpszPath contains the new path
 378  *  FALSE If the paths are not relative or any parameters are invalid
 379  *
 380  * NOTES
 381  *  lpszTo should be at least MAX_PATH in length.
 382  *  Calling this function with relative paths for lpszFrom or lpszTo may
 383  *  give erroneous results.
 384  *
 385  *  The Win32 version of this function contains a bug where the lpszTo string
 386  *  may be referenced 1 byte beyond the end of the string. As a result random
 387  *  garbage may be written to the output path, depending on what lies beyond
 388  *  the last byte of the string. This bug occurs because of the behaviour of
 389  *  PathCommonPrefix() (see notes for that function), and no workaround seems
 390  *  possible with Win32.
 391  *  This bug has been fixed here, so for example the relative path from "\\"
 392  *  to "\\" is correctly determined as "." in this implementation.
 393  */
 394       </screen>
 395       </sect2>
 396
 397       <sect2 id="api-docs-advanced">
 398       <title>Advanced API Documentation</title>
 399
 400       <para>
 401         There is no markup language for formatting API comments, since they should
 402         be easily readable by any developer working on the source file. A number of
 403         constructs are treated specially however, and are noted here. You can use these
 404         constructs to enhance the usefulness of the generated documentation by making it
 405         easier to read and referencing related documents.
 406       </para>
 407
 408       <para>
 409         Any valid c identifier that ends with <command>()</command> is taken to
 410         be an API function and is formatted accordingly. When generating documentation,
 411         this text will become a link to that API call, if the output type supports
 412         hyperlinks or their equivalent.
 413       </para>
 414
 415       <para>
 416         Similarly, any interface name starting with a capital I and followed by the
 417         words "reference" or "object" become a link to that objects documentation.
 418       </para>
 419
 420       <para>
 421         Where an Ascii and Unicode version of a function are available, it is
 422         recommended that you document only the Ascii version and have the Unicode
 423         version refer to the Ascii one, as follows:
 424       </para>
 425       <screen>
 426 /*************************************************************************
 427  * PathRelativePathToW   [SHLWAPI.@]
 428  *
 429  * See PathRelativePathToA.
 430  */
 431       </screen>
 432       <para>
 433         Alternately you may use the following form:
 434       </para>
 435       <screen>
 436 /*************************************************************************
 437  * PathRelativePathToW   [SHLWAPI.@]
 438  *
 439  * Unicode version of PathRelativePathToA.
 440  */
 441       </screen>
 442
 443       <para>
 444         You may also use this construct in any other section, such as <command>NOTES</command>.
 445       </para>
 446
 447       <para>
 448         Any numbers and text in quotes (<command>""</command>) are highlighted.
 449       </para>
 450
 451       <para>
 452         Words in all uppercase are assumed to be API constants and are highlighted. If
 453         you want to emphasize something in the documentation, put it in a section by itself
 454         rather than making it upper case.
 455       </para>
 456
 457       <para>
 458         Blank lines in a section cause a new paragraph to be started. Blank lines
 459         at the start and end of sections are ignored.
 460       </para>
 461
 462       <para>
 463         Any comment line starting with (<command>"*|"</command>) is treated as raw text and
 464         is not pre-processed before being output. This should be used for code listings,
 465         tables and any text that should remain unformatted.
 466       </para>
 467
 468       <para>
 469         Any line starting with a single word followed by a colon (<command>:</command>)
 470         is assumed to be case listing and is emphasized and put in its own paragraph. This
 471         is most often used for return values, as in the example section below.
 472       </para>
 473       <screen>
 474  * RETURNS
 475  *  Success: TRUE. Something happens that is documented here.
 476  *  Failure: FALSE. The reasons why this call can fail are listed here.
 477       </screen>
 478
 479       <para>
 480         Any line starting with a (<command>-</command>) is put into a paragraph by itself.
 481         this allows lists to avoid being run together.
 482       </para>
 483
 484       <para>
 485         If you are in doubt as to how your comment will look, try generating the API
 486         documentation and checking the output.
 487       </para>
 488       </sect2>
 489
 490       <sect2 id="api-docs-extra">
 491       <title>Extra API Documentation</title>
 492
 493       <para>
 494         Simply documenting the API calls available provides a great deal of information to
 495         developers working with the Win32 API. However additional documentation is needed
 496         before the API Guide can be considered truly useful or comprehensive. For example,
 497         COM objects that are available for developers use should be documented, along with
 498         the interface(s) that those objects export. Also, it would be helpful to document
 499         each dll, to provide some structure to the documentation.
 500       </para>
 501
 502       <para>
 503         To facilitate providing extra documentation, you can create comments that provide
 504         extra documentation on functions, or on keywords such as the name of a COM interface
 505         or a type definition.
 506       </para>
 507
 508       <para>
 509         These items are generated using the same formatting rules as described earlier. The
 510         only difference is the first line of the comment, which indicates to the generator
 511         that the documentation is supplemental and does not describe an export from the dll
 512         being processed.
 513       </para>
 514
 515       <para>
 516         Lets assume you have implemented a COM interface that you want to document; we'll
 517         use the name <command>IExample</command> as an example here. Your comment would
 518         look like the following (assuming you are exporting this object from
 519         <filename>EXAMPLE.DLL</filename>):
 520       <screen>
 521 /*************************************************************************
 522  * IExample   {EXAMPLE}
 523  *
 524  * The IExample object provides lots of interesting functionality.
 525  * ...
 526  */
 527       </screen>
 528       </para>
 529
 530       <para>
 531         Format this documentation exactly as you would a standard export. The only
 532         difference is the use of curly brackets to mark this documentation as supplemental.
 533         The generator will output this documentation using the name given before the
 534         DLL name, and will link to it from the main DLL page. In addition, if you have
 535         referred to the comment name in other documentation using "IExample interface",
 536         "IExample object", or "IExample()", those references will point to this documentation.
 537       </para>
 538
 539       <para>
 540         If you document you COM interfaces this way then all following extra comments that
 541         follow in the same source file that begin with the same document title will be added
 542         as references to this comment before it is output. For an example of this see
 543         <filename>dlls/oleaut32/safearray.c</filename>. This uses an extra comment to document
 544         The SafeArray functions and link them together under one heading.
 545       </para>
 546
 547        <para>
 548         As a special case, if you use the DLL name as the comment name, the comment will
 549         be treated as documentation on the DLL itself. When the documentation for the DLL
 550         is processed, the contents of the comment will be placed before the generated
 551         statistics, exports and other information that makes up a DLL's documentation page.
 552       </para>
 553       </sect2>
 554
 555       <sect2 id="api-docs-generating">
 556       <title>Generating API Documentation</title>
 557
 558       <para>
 559         Having edited or added new API documentation to a source code file, you
 560         should generate the documentation to ensure that the result is what you
 561         expected. Wine includes a tool (slightly misleadingly) called
 562         <command>c2man.pl</command> in the <filename>tools/</filename> directory
 563         which is used to generate the documentation from the source code.
 564       </para>
 565
 566       <para>
 567         You can run <command>c2man.pl</command> manually for testing purposes; it is
 568         a fairly simple perl script which parses <filename>.c</filename> files
 569         to create output in several formats. If you wish to try this you may want
 570         to run it with no arguments, which will cause it to print usage information.
 571       </para>
 572
 573       <para>
 574         An easier way is to use Wines build system. To create man pages for a given
 575         dll, just type <command>make man</command> from within the dlls directory
 576         or type <command>make manpages</command> in the root directory of the Wine
 577         source tree. You can then check that a man page was generated for your function,
 578         it should be present in the <filename>documentation/man3w</filename> directory
 579         with the same name as the function.
 580       </para>
 581
 582       <para>
 583         Once you have generated the man pages from the source code, running
 584         <command>make install</command> will install them for you. By default they are
 585         installed in section 3w of the manual, so they don't conflict with any existing
 586         man page names. So, to read the man page you should use
 587         <command>man -S 3w {name}</command>. Alternately you can edit
 588         <filename>/etc/man.config</filename> and add 3w to the list of search paths
 589         given in the variable <emphasis>MANSECT</emphasis>.
 590       </para>
 591
 592       <para>
 593         You can also generate HTML output for the API documentation, in this case the
 594         make command is <command>make doc-html</command> in the dll directory,
 595         or <command>make htmlpages</command> from the root. The output will be
 596         placed by default under <filename>documentation/html</filename>. Similarly
 597         you can create SGML source code to produce the <emphasis>Wine Api Guide</emphasis>
 598         with the command <command>make sgmlpages</command>.
 599       </para>
 600       </sect2>
 601     </sect1>
 602
 603     <sect1 id="wine-docbook">
 604       <title>The Wine DocBook System</title>
 605
 606       <sect2 id="writing-docbook">
 607         <title>Writing Documentation with DocBook</title>
 608
 609         <para>
 610           DocBook is a flavour of <acronym>SGML</acronym>
 611           (<firstterm>Standard Generalized Markup
 612           Language</firstterm>), a syntax for marking up the contents
 613           of documents.  HTML is another very common flavour of SGML;
 614           DocBook markup looks very similar to HTML markup, although
 615           the names of the markup tags differ.
 616         </para>
 617         <sect3>
 618           <title>Getting Started</title>
 619             <note>
 620             <title>Why SGML?</title>
 621               <para>
 622                The simple answer to that is that SGML allows you
 623                to create multiple formats of a given document from a single
 624                source. Currently it is used to create HTML, PDF and PS
 625                (PostScript) versions of the Wine books.
 626               </para>
 627             </note>
 628
 629             <note>
 630             <title>What do I need?</title>
 631               <para>
 632                You need the SGML tools. There are various places where you
 633                can get them. The most generic way of getting them is from their
 634                source as discussed below.
 635               </para>
 636             </note>
 637
 638             <note>
 639             <title>Quick instructions</title>
 640               <para>
 641                These are the basic steps to create the Wine books from the SGML source.
 642               </para>
 643             </note>
 644
 645           <orderedlist>
 646
 647           <listItem><para>
 648           Go to <ulink url="http://www.sgmltools.org">http://www.sgmltools.org</ulink>
 649           </para></listitem>
 650
 651           <listItem><para>
 652           Download all of the sgmltools packages
 653           </para></listitem>
 654
 655           <listItem><para>
 656           Install them all and build them (<command>./configure; make; make install</command>)
 657           </para></listitem>
 658
 659           <listItem><para>
 660           Switch to your toplevel Wine directory
 661           </para></listitem>
 662
 663           <listItem><para>
 664           Run <command>./configure</command> (or <command>make distclean && ./configure</command>)
 665           </para></listitem>
 666
 667           <listItem><para>
 668           Switch to the <filename>documentation/</filename> directory
 669           </para></listitem>
 670
 671           <listItem><para>
 672           run <command>make html</command>
 673           </para></listitem>
 674
 675           <listItem><para>
 676           View <filename>wine-user.html</filename>, <filename>wine-devel.html</filename>, etc in your favorite browser
 677           </para></listitem>
 678
 679           </orderedlist>
 680
 681         </sect3>
 682
 683         <sect3>
 684           <title>Getting SGML for various distributions</title>
 685           <para>
 686             Most Linux distributions have everything you need already
 687             bundled up in package form.  Unfortunately, each
 688             distribution seems to handle its SGML environment
 689             differently, installing it into different paths, and
 690             naming its packages according to its own whims.
 691           </para>
 692
 693           <sect4>
 694           <title>SGML on Red Hat</title>
 695           <para>
 696             The following packages seem to be sufficient for Red Hat 7.1.  You
 697             will want to be careful about the order in which you install the
 698             RPMs.
 699             <itemizedlist>
 700               <listitem>
 701                 <para>
 702                   sgml-common-*.rpm
 703                 </para>
 704               </listitem>
 705               <listitem>
 706                 <para>
 707                   openjade-*.rpm
 708                 </para>
 709               </listitem>
 710               <listitem>
 711                 <para>
 712                   perl-SGMLSpm-*.rpm
 713                 </para>
 714               </listitem>
 715               <listitem>
 716                 <para>
 717                   docbook-dtd*.rpm
 718                 </para>
 719               </listitem>
 720               <listitem>
 721                 <para>
 722                   docbook-style-dsssl-*.rpm
 723                 </para>
 724               </listitem>
 725               <listitem>
 726                 <para>
 727                   tetex-*.rpm
 728                 </para>
 729               </listitem>
 730               <listitem>
 731                 <para>
 732                   jadetex-*.rpm
 733                 </para>
 734               </listitem>
 735               <listitem>
 736                 <para>
 737                   docbook-utils-*.rpm
 738                 </para>
 739               </listitem>
 740             </itemizedlist>
 741             You can also use ghostscript to view the ps format output and
 742             Adobe Acrobat 4 to view the pdf file.
 743           </para>
 744         </sect4>
 745
 746         <sect4>
 747           <title>SGML on Debian</title>
 748           <para>
 749            This is not a definitive listing yet, but it seems
 750            you might need the following packages:
 751             <itemizedlist>
 752               <listitem>
 753                 <para>
 754                   docbook
 755                 </para>
 756               </listitem>
 757               <listitem>
 758                 <para>
 759                   docbook-dsssl
 760                 </para>
 761               </listitem>
 762               <listitem>
 763                 <para>
 764                   docbook-utils
 765                 </para>
 766               </listitem>
 767               <listitem>
 768                 <para>
 769                   docbook-xml
 770                 </para>
 771               </listitem>
 772               <listitem>
 773                 <para>
 774                   docbook-xsl
 775                 </para>
 776               </listitem>
 777               <listitem>
 778                 <para>
 779                   sgml-base
 780                 </para>
 781               </listitem>
 782               <listitem>
 783                 <para>
 784                   sgml-data
 785                 </para>
 786               </listitem>
 787               <listitem>
 788                 <para>
 789                   tetex-base
 790                 </para>
 791               </listitem>
 792               <listitem>
 793                 <para>
 794                   tetex-bin
 795                 </para>
 796               </listitem>
 797               <listitem>
 798                 <para>
 799                   jade
 800                 </para>
 801               </listitem>
 802               <listitem>
 803                 <para>
 804                   jadetex
 805                 </para>
 806               </listitem>
 807             </itemizedlist>
 808           </para>
 809         </sect4>
 810
 811         </sect3>
 812         <sect3>
 813           <title>Terminology</title>
 814
 815           <para>
 816             SGML markup contains a number of syntactical elements that
 817             serve different purposes in the markup.  We'll run through
 818             the basics here to make sure we're on the same page when
 819             we refer to SGML semantics.
 820           </para>
 821           <para>
 822             The basic currency of SGML is the
 823             <firstterm>tag</firstterm>.  A simple tag consists of a
 824             pair of angle brackets and the name of the tag.  For
 825             example, the <sgmltag>para</sgmltag> tag would appear in
 826             an SGML document as <sgmltag
 827             class="starttag">para</sgmltag>.  This start tag indicates
 828             that the immediately following text should be classified
 829             according to the tag.  In regular SGML, each opening tag
 830             must have a matching end tag to show where the start tag's
 831             contents end.  End tags begin with
 832             <quote><literal>&lt;/</literal></quote> markup, e.g.,
 833             <sgmltag class="endtag">para</sgmltag>.
 834           </para>
 835           <para>
 836             The combination of a start tag, contents, and an end tag
 837             is called an <firstterm>element</firstterm>.  SGML
 838             elements can be nested inside of each other, or contain
 839             only text, or may be a combination of both text and other
 840             elements, although in most cases it is better to limit
 841             your elements to one or the other.
 842           </para>
 843           <para>
 844             The <acronym>XML</acronym> (<firstterm>eXtensible Markup
 845             Language</firstterm>) specification, a modern subset of
 846             the SGML specification, adds a so-called <firstterm>empty
 847             tag</firstterm>, for elements that contain no text
 848             content.  The entire element is a single tag, ending with
 849             <quote><literal>/&gt;</literal></quote>, e.g.,
 850             <sgmltag>&lt;xref/&gt;</sgmltag>.  However, use of this
 851             tag style restricts you to XML DocBook processing, and
 852             your document may no longer compile with SGML-only
 853             processing systems.
 854           </para>
 855           <!-- *** Note: We could normally use the "emptytag"
 856             attribute for XML empty tags, but that's only a recent
 857             addition, and we don't want to screw up documents
 858             generated against older stylesheets.
 859           *** -->
 860           <para>
 861             Often a processing system will need more information about
 862             an element than you can provide with just tags.  SGML
 863             allows you to add extra <quote>hints</quote> in the form
 864             of SGML <firstterm>attributes</firstterm> to pass along
 865             this information.  The most common use of attributes in
 866             DocBook is giving specific elements a name, or an ID, so
 867             you can refer to it from elsewhere.  This ID can be used
 868             for many things, including file-naming for HTML output,
 869             hyper-linking to specific parts of the document, and even
 870             pulling text from that element (see the <sgmltag
 871             class="starttag">xref</sgmltag> tag).
 872           </para>
 873           <para>
 874             An SGML attribute appears inside the start tag, between
 875             the &lt; and &gt; brackets.  For example, if you wanted to
 876             set the <sgmltag class="attribute">id</sgmltag> attribute
 877             of the <sgmltag class="starttag">book</sgmltag> element to
 878             <quote>mybook</quote>, you would create a start tag like
 879             this: <programlisting>&lt;book id="mybook"></programlisting>
 880           </para>
 881           <para>
 882             Notice that the contents of the attribute are enclosed in
 883             quote marks.  These quotes are optional in SGML, but
 884             mandatory in XML.  It's a good habit to use quotes, as it
 885             will make it much easier to migrate your documents to an
 886             XML processing system later on.
 887           </para>
 888           <para>
 889             You can also specify more than one attribute in a single
 890             tag: <programlisting>&lt;book id="mybook" status="draft"></programlisting>
 891           </para>
 892           <para>
 893             Another commonly used type of SGML markup is the
 894             <firstterm>entity</firstterm>.  An entity lets you
 895             associate a block of text with a name.  You declare the
 896             entity once, at the beginning of your document, and can
 897             invoke it as many times as you like throughout the
 898             document.  You can use entities as shorthand, or to make
 899             it easier to maintain certain phrases in a central
 900             location, or even to insert the contents of an entire file
 901             into your document.
 902           </para>
 903           <para>
 904             An entity in your document is always surrounded by the
 905             <quote>&amp;</quote> and <quote>;</quote> characters.  One
 906             entity you'll need sooner or later is the one for the
 907             <quote>&lt;</quote> character.  Since SGML expects all
 908             tags to begin with a <quote>&lt;</quote>, the
 909             <quote>&lt;</quote> is a reserved character.  To use it in
 910             your document (as I am doing here), you must insert it
 911             with the <literal>&amp;lt;</literal> entity.  Each time
 912             the SGML processor encounters <literal>&amp;lt;</literal>,
 913             it will place a literal <quote>&lt;</quote> in the output
 914             document. Similarly you must use the <literal>&amp;gt;</literal>
 915             and <literal>&amp;amp;</literal> entities for the
 916             <quote>&gt;</quote> and <quote>&amp;</quote> characters.
 917           </para>
 918           <para>
 919             The final term you'll need to know when writing simple
 920             DocBook documents is the <acronym>DTD</acronym>
 921             (<firstterm>Document Type Declaration</firstterm>).  The
 922             DTD defines the flavour of SGML a given document is written
 923             in.  It lists all the legal tag names, like <sgmltag
 924             class="starttag">book</sgmltag>, <sgmltag
 925             class="starttag">para</sgmltag>, and so on, and declares
 926             how those tags are allowed to be used together.  For
 927             example, it doesn't make sense to put a <sgmltag
 928             class="starttag">book</sgmltag> element inside a <sgmltag
 929             class="starttag">para</sgmltag> paragraph element -- only
 930             the reverse.
 931           </para>
 932           <para>
 933             The DTD thus defines the legal structure of the document.
 934             It also declares which attributes can be used with which
 935             tags.  The SGML processing system can use the DTD to make
 936             sure the document is laid out properly before attempting
 937             to process it.  SGML-aware text editors like <link
 938             linkend="emacs-psgml">Emacs</link> can also use the DTD to
 939             guide you while you write, offering you choices about
 940             which tags you can add in different places in the
 941             document, and beeping at you when you try to add a tag
 942             where it doesn't belong.
 943           </para>
 944           <para>
 945             Generally, you will declare which DTD you want to use as
 946             the first line of your SGML document.  In the case of
 947             DocBook, you will use something like this:
 948             <programlisting>&lt!doctype book PUBLIC "-//OASIS//DTD
 949             DocBook V3.1//EN" []> &lt;book> ...
 950             &lt;/book></programlisting>
 951           </para>
 952           <para>
 953             Note that you must specify your toplevel element inside
 954             the doctype declaration.  If you were writing an article
 955             rather than a book, you might use this declaration instead:
 956             <programlisting>&lt!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
 957 &lt;article>
 958 ...
 959 &lt;/article></programlisting>
 960           </para>
 961         </sect3>
 962
 963         <sect3 id="sgml-document">
 964           <title>The Document</title>
 965           <para>
 966             Once you're comfortable with SGML, creating a DocBook
 967             document is quite simple and straightforward.  Even
 968             though DocBook contains over 300 different tags, you can
 969             usually get by with only a small subset of those tags.
 970             Most of them are for inline formatting, rather than for
 971             document structuring.  Furthermore, the common tags have
 972             short, intuitive names.
 973           </para>
 974           <para>
 975             Below is a (completely nonsensical) example to illustrate
 976             how a simple document might be laid out.  Notice that all
 977             <sgmltag class="starttag">chapter</sgmltag> and <sgmltag
 978             class="starttag">sect1</sgmltag> elements have <sgmltag
 979             class="attribute">id</sgmltag> attributes.  This is not
 980             mandatory, but is a good habit to get into, as DocBook is
 981             commonly converted into HTML, with a separate generated
 982             file for each <sgmltag class="starttag">book</sgmltag>,
 983             <sgmltag class="starttag">chapter</sgmltag>, and/or <sgmltag
 984             class="starttag">sect1</sgmltag> element.  If the given
 985             element has an <sgmltag class="attribute">id</sgmltag>
 986             attribute, the processor will typically name the file
 987             accordingly.  Thus, the below document might result in
 988             <filename>index.html</filename>,
 989             <filename>chapter-one.html</filename>,
 990             <filename>blobs.html</filename>, and so on.
 991           </para>
 992           <para>
 993             Also notice the text marked off with <quote>&lt;!--
 994             </quote> and <quote> --&gt;</quote> characters.  These
 995             denote SGML comments.  SGML processors will completely
 996             ignore anything between these markers, similar to
 997             <quote>/*</quote> and <quote>*/</quote> comments in C
 998             source code.
 999           </para>
1000
1001           <!-- Encase the following SGML excerpt inside a CDATA
1002                block so we don't have to bother converting all
1003                brackets to entities
1004           -->
1005           <programlisting>
1006 <![CDATA[
1007 <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
1008 <book id="index">
1009   <bookinfo>
1010     <title>A Poet's Guide to Nonsense</title>
1011   </bookinfo>
1012
1013   <chapter id="chapter-one">
1014     <title>Blobs and Gribbles</title>
1015
1016     <!-- This section contains only one major topic -->
1017     <sect1 id="blobs">
1018       <title>The Story Behind Blobs</title>
1019       <para>
1020         Blobs are often mistaken for ice cubes and rain
1021         puddles...
1022       </para>
1023     </sect1>
1024
1025     <!-- This section contains embedded sub-sections -->
1026     <sect1 id="gribbles">
1027       <title>Your Friend the Gribble</title>
1028       <para>
1029         A Gribble is a cute, unassuming little fellow...
1030       </para>
1031
1032       <sect2 id="gribble-temperament">
1033         <title>Gribble Temperament</title>
1034         <para>
1035           When left without food for several days...
1036         </para>
1037       </sect2>
1038
1039       <sect2 id="gribble-appearance">
1040         <title>Gribble Appearance</title>
1041         <para>
1042           Most Gribbles have a shock of white fur running from...
1043         </para>
1044       </sect2>
1045     </sect1>
1046   </chapter>
1047
1048   <chapter id="chapter-two">
1049     <title>Phantasmagoria</title>
1050
1051     <sect1 id="dretch-pools">
1052       <title>Dretch Pools</title>
1053
1054       <para>
1055         When most poets think of Dretch Pools, they tend to...
1056       </para>
1057     </sect>
1058   </chapter>
1059 </book>
1060 ]]>
1061 </programlisting>
1062         </sect3>
1063
1064         <sect3>
1065           <title>Common Elements</title>
1066           <para>
1067             Once you get used to the syntax of SGML, the next hurdle
1068             in writing DocBook documentation is to learn the many
1069             DocBook-specific tag names, and when to use them.  DocBook
1070             was created for technical documentation, and as such, the
1071             tag names and document structure are slanted towards the
1072             needs of such documentation.
1073           </para>
1074           <para>
1075             To cover its target audience, DocBook declares a wide
1076             variety of specialized tags, including tags for formatting
1077             source code (with somewhat of a C/C++ bias), computer
1078             prompts, GUI application features, keystrokes, and so on.
1079             DocBook also includes tags for universal formatting needs,
1080             like headers, footnotes, tables, and graphics.
1081           </para>
1082           <para>
1083             We won't cover all of these elements here (over 300
1084             DocBook tags exist!), but we will cover the basics.  To
1085             learn more about the other tags, check out the official
1086             DocBook guide, at <ulink
1087             url="http://docbook.org">http://docbook.org</ulink>.  To
1088             see how they are used in practice, download the SGML
1089             source for this manual (the Wine Developer Guide) and
1090             browse through it, comparing it to the generated HTML (or
1091             PostScript or PDF).
1092           </para>
1093           <para>
1094             There are often many correct ways to mark up a given piece
1095             of text, and you may have to make guesses about which tag
1096             to use.  Sometimes you'll have to make compromises.
1097             However, remember that it is possible to further customize
1098             the output of  the SGML processors.  If you don't like the
1099             way a certain tag looks in HTML, that doesn't mean you
1100             should choose a different tag based on its output formatting.
1101             The processing stylesheets can be altered to fix the
1102             formatting of that same tag everywhere in the document
1103             (not just in the place you're working on).  For example,
1104             if you're frustrated that the <sgmltag
1105             class="starttag">systemitem</sgmltag> tag doesn't produce
1106             any formatting by default, you should fix the stylesheets,
1107             not change the valid <sgmltag
1108             class="starttag">systemitem</sgmltag> tag to, for example,
1109             an <sgmltag class="starttag">emphasis</sgmltag> tag.
1110           </para>
1111           <para>
1112             Here are the common SGML elements:
1113           </para>
1114
1115           <variablelist>
1116             <title>Structural Elements</title>
1117             <varlistentry>
1118               <term><sgmltag class="starttag">book</sgmltag></term>
1119               <listitem>
1120                 <para>
1121                   The book is the most common toplevel element, and is
1122                   probably the one you should use for your document.
1123                 </para>
1124               </listitem>
1125             </varlistentry>
1126             <varlistentry>
1127               <term><sgmltag class="starttag">set</sgmltag></term>
1128               <listitem>
1129                 <para>
1130                   If you want to group more than one book into a
1131                   single unit, you can place them all inside a set.
1132                   This is useful when you want to bundle up
1133                   documentation in alternate ways.  We do this with
1134                   the Wine documentation, using
1135                   <sgmltag class="starttag">book</sgmltag> to
1136                   put each Wine guide into a separate directory (see
1137                   <filename>documentation/wine-devel.sgml</filename>,
1138                   etc.).
1139                 </para>
1140               </listitem>
1141             </varlistentry>
1142             <varlistentry>
1143               <term><sgmltag class="starttag">chapter</sgmltag></term>
1144               <listitem>
1145                 <para>
1146                   A <sgmltag class="starttag">chapter</sgmltag>
1147                   element includes a single entire chapter of the
1148                   book.
1149                 </para>
1150               </listitem>
1151             </varlistentry>
1152             <varlistentry>
1153               <term><sgmltag class="starttag">part</sgmltag></term>
1154               <listitem>
1155                 <para>
1156                   If the chapters in your book fall into major
1157                   categories or groupings (as in the Wine Developer
1158                   Guide), you can place each collection of chapters
1159                   into a <sgmltag class="starttag">part</sgmltag>
1160                   element.
1161                 </para>
1162               </listitem>
1163             </varlistentry>
1164             <varlistentry>
1165               <term><sgmltag class="starttag">sect?</sgmltag></term>
1166               <listitem>
1167                 <para>
1168                   DocBook has many section elements to divide the
1169                   contents of a chapter into smaller chunks.  The
1170                   encouraged approach is to use the numbered section
1171                   tags, <sgmltag class="starttag">sect1</sgmltag>,
1172                   <sgmltag class="starttag">sect2</sgmltag>, <sgmltag
1173                   class="starttag">sect3</sgmltag>, <sgmltag
1174                   class="starttag">sect4</sgmltag>, and <sgmltag
1175                   class="starttag">sect5</sgmltag> (if necessary).
1176                   These tags must be nested in order: you can't place
1177                   a <sgmltag class="starttag">sect3</sgmltag> directly
1178                   inside a <sgmltag class="starttag">sect1</sgmltag>.
1179                   You have to nest the <sgmltag
1180                   class="starttag">sect3</sgmltag> inside a <sgmltag
1181                   class="starttag">sect2</sgmltag>, and so forth.
1182                   Documents with these explicit section groupings are
1183                   easier for SGML processors to deal with, and lead to
1184                   better organized documents.  DocBook also supplies a
1185                   <sgmltag class="starttag">section</sgmltag> element
1186                   which you can nest inside itself, but its use is
1187                   discouraged in favor of the numbered section tags.
1188                 </para>
1189               </listitem>
1190             </varlistentry>
1191             <varlistentry>
1192               <term><sgmltag class="starttag">title</sgmltag></term>
1193               <listitem>
1194                 <para>
1195                   The title of a book, chapter, part, section, etc.
1196                   In most of the major structural elements, like
1197                   <sgmltag class="starttag">chapter</sgmltag>,
1198                   <sgmltag class="starttag">part</sgmltag>, and the
1199                   various section tags, <sgmltag
1200                   class="starttag">title</sgmltag> is mandatory.  In
1201                   other elements like <sgmltag
1202                   class="starttag">book</sgmltag> and <sgmltag
1203                   class="starttag">note</sgmltag>, it's optional.
1204                 </para>
1205               </listitem>
1206             </varlistentry>
1207             <varlistentry>
1208               <term><sgmltag class="starttag">para</sgmltag></term>
1209               <listitem>
1210                 <para>
1211                   The basic unit of text is the paragraph, represented
1212                   by the <sgmltag class="starttag">para</sgmltag> tag.
1213                   This is probably the tag you'll use most often.  In
1214                   fact, in a simple document, you can probably get
1215                   away with using only <sgmltag
1216                   class="starttag">book</sgmltag>, <sgmltag
1217                   class="starttag">chapter</sgmltag>, <sgmltag
1218                   class="starttag">title</sgmltag>, and <sgmltag
1219                   class="starttag">para</sgmltag>.
1220                 </para>
1221               </listitem>
1222             </varlistentry>
1223             <varlistentry>
1224               <term><sgmltag class="starttag">article</sgmltag></term>
1225               <listitem>
1226                 <para>
1227                   For shorter, more targeted documents, like topic
1228                   pieces and whitepapers, you can use <sgmltag
1229                   class="starttag">article</sgmltag> as your toplevel
1230                   element.
1231                 </para>
1232               </listitem>
1233             </varlistentry>
1234           </variablelist>
1235
1236           <variablelist>
1237             <title>Inline Formatting Elements</title>
1238             <varlistentry>
1239               <term><sgmltag class="starttag">filename</sgmltag></term>
1240               <listitem>
1241                 <para>
1242                   The name of a file.  You can optionally set the
1243                   <sgmltag class="attribute">class</sgmltag> attribute
1244                   to <literal>Directory</literal>,
1245                   <literal>HeaderFile</literal>, and
1246                   <literal>SymLink</literal> to further classify the
1247                   filename.
1248                 </para>
1249               </listitem>
1250             </varlistentry>
1251             <varlistentry>
1252               <term><sgmltag class="starttag">userinput</sgmltag></term>
1253               <listitem>
1254                 <para>
1255                   Literal text entered by the user.
1256                 </para>
1257               </listitem>
1258             </varlistentry>
1259             <varlistentry>
1260               <term><sgmltag class="starttag">computeroutput</sgmltag></term>
1261               <listitem>
1262                 <para>
1263                   Literal text output by the computer.
1264                 </para>
1265               </listitem>
1266             </varlistentry>
1267             <varlistentry>
1268               <term><sgmltag class="starttag">literal</sgmltag></term>
1269               <listitem>
1270                 <para>
1271                   A catch-all element for literal computer data.  Its
1272                   use is somewhat vague; try to use a more specific
1273                   tag if possible, like <sgmltag
1274                   class="starttag">userinput</sgmltag> or <sgmltag
1275                   class="starttag">computeroutput</sgmltag>.
1276                 </para>
1277               </listitem>
1278             </varlistentry>
1279             <varlistentry>
1280               <term><sgmltag class="starttag">quote</sgmltag></term>
1281               <listitem>
1282                 <para>
1283                   An inline quotation.  This tag typically inserts
1284                   quotation marks for you, so you would write <sgmltag
1285                   class="starttag">quote</sgmltag>This is a
1286                   quote<sgmltag class="endtag">quote</sgmltag> rather
1287                   than "This is a quote".  This usage may be a little
1288                   bulkier, but it does allow for automated formatting
1289                   of all quoted material in the document.  Thus, if
1290                   you wanted all quotations to appear in italic, you
1291                   could make the change once in your stylesheet,
1292                   rather than doing a search and replace throughout
1293                   the document.  For larger chunks of quoted text, you
1294                   can use <sgmltag
1295                   class="starttag">blockquote</sgmltag>.
1296                 </para>
1297               </listitem>
1298             </varlistentry>
1299             <varlistentry>
1300               <term><sgmltag class="starttag">note</sgmltag></term>
1301               <listitem>
1302                 <para>
1303                   Insert a side note for the reader.  By default, the
1304                   SGML processor usually prefixes the content with
1305                   "Note:".  You can change this text by adding a
1306                   <sgmltag class="starttag">title</sgmltag> element.
1307                   Thus, to add a visible FIXME comment to the
1308                   documentation, you might write:
1309                 </para>
1310 <programlisting>
1311 <![CDATA[
1312 <note>
1313   <title>EXAMPLE</title>
1314   <para>This is an example note...</para>
1315 </note>
1316 ]]></programlisting>
1317                 <para>
1318                   The results will look something like this:
1319                 </para>
1320                   <note>
1321                     <title>EXAMPLE</title>
1322                     <para>This is an example note...</para>
1323                   </note>
1324               </listitem>
1325             </varlistentry>
1326             <varlistentry>
1327               <term><sgmltag class="starttag">sgmltag</sgmltag></term>
1328               <listitem>
1329                 <para>
1330                   Used for inserting SGML tags, etc., into a SGML
1331                   document without resorting to a lot of entity
1332                   quoting, e.g., &amp;lt;.  You can change the
1333                   appearance of the text with the <sgmltag
1334                   class="attribute">class</sgmltag> attribute.  Some
1335                   common values of this are
1336                   <literal>starttag</literal>,
1337                   <literal>endtag</literal>,
1338                   <literal>attribute</literal>,
1339                   <literal>attvalue</literal>, and even
1340                   <literal>sgmlcomment</literal>.  See this SGML file,
1341                   <filename>documentation/documentation.sgml</filename>,
1342                   for examples.
1343                 </para>
1344               </listitem>
1345             </varlistentry>
1346             <varlistentry>
1347               <term><sgmltag class="starttag">prompt</sgmltag></term>
1348               <listitem>
1349                 <para>
1350                   The text used for a computer prompt, for example a
1351                   shell prompt, or command-line application prompt.
1352                 </para>
1353               </listitem>
1354             </varlistentry>
1355             <varlistentry>
1356               <term><sgmltag class="starttag">replaceable</sgmltag></term>
1357               <listitem>
1358                 <para>
1359                   Meta-text that should be replaced by the user, not
1360                   typed in literally, e.g., in command descriptions
1361                   and <parameter>--help</parameter> outputs.
1362                 </para>
1363               </listitem>
1364             </varlistentry>
1365             <varlistentry>
1366               <term><sgmltag class="starttag">constant</sgmltag></term>
1367               <listitem>
1368                 <para>
1369                   A programming constant, e.g.,
1370                   <constant>MAX_PATH</constant>.
1371                 </para>
1372               </listitem>
1373             </varlistentry>
1374             <varlistentry>
1375               <term><sgmltag class="starttag">symbol</sgmltag></term>
1376               <listitem>
1377                 <para>
1378                   A symbolic value replaced, for example, by a
1379                   pre-processor.  This applies primarily to C macros,
1380                   but may have other uses.  Use the <sgmltag
1381                   class="starttag">constant</sgmltag> tag instead of
1382                   <sgmltag class="starttag">symbol</sgmltag> where
1383                   appropriate.
1384                 </para>
1385               </listitem>
1386             </varlistentry>
1387             <varlistentry>
1388               <term><sgmltag class="starttag">function</sgmltag></term>
1389               <listitem>
1390                 <para>
1391                   A programming function name.
1392                 </para>
1393               </listitem>
1394             </varlistentry>
1395             <varlistentry>
1396               <term><sgmltag class="starttag">parameter</sgmltag></term>
1397               <listitem>
1398                 <para>
1399                   Programming language parameters you pass with a
1400                   function.
1401                 </para>
1402               </listitem>
1403             </varlistentry>
1404             <varlistentry>
1405               <term><sgmltag class="starttag">option</sgmltag></term>
1406               <listitem>
1407                 <para>
1408                   Parameters you pass to a command-line executable.
1409                 </para>
1410               </listitem>
1411             </varlistentry>
1412             <varlistentry>
1413               <term><sgmltag class="starttag">varname</sgmltag></term>
1414               <listitem>
1415                 <para>
1416                   Variable name, typically in a programming language.
1417                 </para>
1418               </listitem>
1419             </varlistentry>
1420             <varlistentry>
1421               <term><sgmltag class="starttag">type</sgmltag></term>
1422               <listitem>
1423                 <para>
1424                   Programming language types, e.g., from a typedef
1425                   definition.  May have other uses, too.
1426                 </para>
1427               </listitem>
1428             </varlistentry>
1429             <varlistentry>
1430               <term><sgmltag class="starttag">structname</sgmltag></term>
1431               <listitem>
1432                 <para>
1433                   The name of a C-language <type>struct</type>
1434                   declaration, e.g., <structname>sockaddr</structname>.
1435                 </para>
1436               </listitem>
1437             </varlistentry>
1438             <varlistentry>
1439               <term><sgmltag class="starttag">structfield</sgmltag></term>
1440               <listitem>
1441                 <para>
1442                   A field inside a C <type>struct</type>.
1443                 </para>
1444               </listitem>
1445             </varlistentry>
1446             <varlistentry>
1447               <term><sgmltag class="starttag">command</sgmltag></term>
1448               <listitem>
1449                 <para>
1450                   An executable binary, e.g., <command>wine</command>
1451                   or <command>ls</command>.
1452                 </para>
1453               </listitem>
1454             </varlistentry>
1455             <varlistentry>
1456               <term><sgmltag class="starttag">envar</sgmltag></term>
1457               <listitem>
1458                 <para>
1459                   An environment variable, e.g, <envar>$PATH</envar>.
1460                 </para>
1461               </listitem>
1462             </varlistentry>
1463             <varlistentry>
1464               <term><sgmltag class="starttag">systemitem</sgmltag></term>
1465               <listitem>
1466                 <para>
1467                   A generic catch-all for system-related things, like
1468                   OS names, computer names, system resources, etc.
1469                 </para>
1470               </listitem>
1471             </varlistentry>
1472             <varlistentry>
1473               <term><sgmltag class="starttag">email</sgmltag></term>
1474               <listitem>
1475                 <para>
1476                   An email address.  The SGML processor will typically
1477                   add extra formatting characters, and even a
1478                   <literal>mailto:</literal> link for HTML pages.
1479                   Usage: <sgmltag
1480                   class="starttag">email</sgmltag>user@host.com<sgmltag
1481                   class="endtag">email</sgmltag>
1482                 </para>
1483               </listitem>
1484             </varlistentry>
1485             <varlistentry>
1486               <term><sgmltag class="starttag">firstterm</sgmltag></term>
1487               <listitem>
1488                 <para>
1489                   Special emphasis for introducing a new term.  Can
1490                   also be linked to a <sgmltag
1491                   class="starttag">glossary</sgmltag> entry, if
1492                   desired.
1493                 </para>
1494               </listitem>
1495             </varlistentry>
1496           </variablelist>
1497
1498           <variablelist>
1499             <title>Item Listing Elements</title>
1500             <varlistentry>
1501               <term><sgmltag class="starttag">itemizedlist</sgmltag></term>
1502               <listitem>
1503                 <para>
1504                   For bulleted lists, no numbering.  You can tweak the
1505                   layout with SGML attributes.
1506                 </para>
1507               </listitem>
1508             </varlistentry>
1509             <varlistentry>
1510               <term><sgmltag class="starttag">orderedlist</sgmltag></term>
1511               <listitem>
1512                 <para>
1513                   A numbered list; the SGML processor will insert the
1514                   numbers for you.  You can suggest numbering styles
1515                   with the <sgmltag
1516                   class="attribute">numeration</sgmltag> attribute.
1517                 </para>
1518               </listitem>
1519             </varlistentry>
1520             <varlistentry>
1521               <term><sgmltag class="starttag">simplelist</sgmltag></term>
1522               <listitem>
1523                 <para>
1524                   A very simple list of items, often inlined.  Control
1525                   the layout with the <sgmltag
1526                   class="attribute">type</sgmltag> attribute.
1527                 </para>
1528               </listitem>
1529             </varlistentry>
1530             <varlistentry>
1531               <term><sgmltag class="starttag">variablelist</sgmltag></term>
1532               <listitem>
1533                 <para>
1534                   A list of terms with definitions or descriptions,
1535                   like this very list!
1536                 </para>
1537               </listitem>
1538             </varlistentry>
1539           </variablelist>
1540
1541           <variablelist>
1542             <title>Block Text Quoting Elements</title>
1543             <varlistentry>
1544               <term><sgmltag class="starttag">programlisting</sgmltag></term>
1545               <listitem>
1546                 <para>
1547                   Quote a block of source code.  Typically highlighted
1548                   in the output and set off from normal text.
1549                 </para>
1550               </listitem>
1551             </varlistentry>
1552             <varlistentry>
1553               <term><sgmltag class="starttag">screen</sgmltag></term>
1554               <listitem>
1555                 <para>
1556                   Quote a block of visible computer output, like the
1557                   output of a command or chunks of debug logs.
1558                 </para>
1559               </listitem>
1560             </varlistentry>
1561           </variablelist>
1562
1563           <variablelist>
1564             <title>Hyperlink Elements</title>
1565             <varlistentry>
1566               <term><sgmltag class="starttag">link</sgmltag></term>
1567               <listitem>
1568                 <para>
1569                   Generic hypertext link, used for pointing to other
1570                   sections within the current document.  You supply
1571                   the visible text for the link, plus the name of the <sgmltag
1572                   class="attribute">id</sgmltag> attribute of the
1573                   element that you want to link to.  For example:
1574 <programlisting>&lt;link linkend="configuring-wine">the section on configuring wine&lt;/link>
1575 ...
1576 &lt;sect2 id="configuring-wine">
1577 ...</programlisting>
1578                 </para>
1579               </listitem>
1580             </varlistentry>
1581             <varlistentry>
1582               <term><sgmltag class="starttag">xref</sgmltag></term>
1583               <listitem>
1584                 <para>
1585                   In-document hyperlink that can generate its own
1586                   text.  Similar to the <sgmltag
1587                   class="starttag">link</sgmltag> tag, you use the
1588                   <sgmltag class="attribute">linkend</sgmltag>
1589                   attribute to specify which target element you want
1590                   to jump to:
1591                 </para>
1592                 <para>
1593 <programlisting>&lt;xref linkend="configuring-wine">
1594 ...
1595 &lt;sect2 id="configuring-wine">
1596 ...</programlisting>
1597                 </para>
1598                 <para>
1599                   By default, most SGML processors will auto generate
1600                   some generic text for the <sgmltag
1601                   class="starttag">xref</sgmltag> link, like
1602                   <quote>Section 2.3.1</quote>.  You can use the
1603                   <sgmltag class="attribute">endterm</sgmltag>
1604                   attribute to grab the visible text content of the
1605                   hyperlink from another element:
1606                 </para>
1607                 <para>
1608 <programlisting>&lt;xref linkend="configuring-wine" endterm="config-title">
1609 ...
1610 &lt;sect2 id="configuring-wine">
1611   &lt;title id="config-title">Configuring Wine&lt;/title>
1612 ...</programlisting>
1613                 </para>
1614                 <para>
1615                   This would create a link to the
1616                   <symbol>configuring-wine</symbol> element,
1617                   displaying the text of the
1618                   <symbol>config-title</symbol> element for the
1619                   hyperlink.  Most often, you'll add an <sgmltag
1620                   class="attribute">id</sgmltag> attribute to the
1621                   <sgmltag class="starttag">title</sgmltag> of the
1622                   section you're linking to, as above, in which case
1623                   the SGML processor will use the target's title text
1624                   for the link text.
1625                 </para>
1626                 <para>
1627                   Alternatively, you can use an <sgmltag
1628                   class="attribute">xreflabel</sgmltag> attribute in
1629                   the target element tag to specify the link text:
1630                 </para>
1631 <programlisting>&lt;sect1 id="configuring-wine" xreflabel="Configuring Wine"></programlisting>
1632                 <note>
1633                   <para>
1634                     <sgmltag class="starttag">xref</sgmltag> is an
1635                     empty element.  You don't need a closing tag for
1636                     it (this is defined in the DTD).  In SGML
1637                     documents, you should use the form <sgmltag
1638                     class="starttag">xref</sgmltag>, while in XML
1639                     documents you should use
1640                     <sgmltag>&lt;xref/></sgmltag>.
1641                   </para>
1642                 </note>
1643               </listitem>
1644             </varlistentry>
1645             <varlistentry>
1646               <term><sgmltag class="starttag">anchor</sgmltag></term>
1647               <listitem>
1648                 <para>
1649                   An invisible tag, used for inserting <sgmltag
1650                   class="attribute">id</sgmltag> attributes into a
1651                   document to link to arbitrary places (i.e., when
1652                   it's not close enough to link to the top of an
1653                   element).
1654                 </para>
1655               </listitem>
1656             </varlistentry>
1657             <varlistentry>
1658               <term><sgmltag class="starttag">ulink</sgmltag></term>
1659               <listitem>
1660                 <para>
1661                   Hyperlink in URL form, e.g., <ulink
1662                   url="http://www.winehq.com">http://www.winehq.com</ulink>.
1663                 </para>
1664               </listitem>
1665             </varlistentry>
1666             <varlistentry>
1667               <term><sgmltag class="starttag">olink</sgmltag></term>
1668               <listitem>
1669                 <para>
1670                   Indirect hyperlink; can be used for linking to
1671                   external documents.  Not often used in practice.
1672                 </para>
1673               </listitem>
1674             </varlistentry>
1675           </variablelist>
1676         </sect3>
1677
1678         <!--sect3>
1679           <title>Multiple SGML files</title>
1680           <para>
1681             How to split an SGML document into multiple files...
1682           </para>
1683         </sect3-->
1684       </sect2>
1685
1686       <sect2 id="sgml-environment">
1687         <title>The SGML Environment</title>
1688
1689         <para>
1690           You can write SGML/DocBook documents in any text editor you
1691           might find (although as we'll find in <xref
1692           linkend="emacs-psgml">, some editors are more friendly for
1693           this task than others).  However, if you want to convert
1694           those documents into a more friendly form for reading, such
1695           as HTML, PostScript, or PDF, you will need a working SGML
1696           environment.  This section attempts to lay out the various
1697           SGML rendering systems, and how they are set up on the
1698           popular Linux distributions.
1699         </para>
1700
1701         <!--sect3>
1702           <title>DSSSL Environment</title>
1703           <para>
1704             Explain tools and methodologies..
1705           </para>
1706         </sect3-->
1707
1708         <!--sect3>
1709           <title>XSLT Environment</title>
1710           <para>
1711             Explain tools and methodologies...
1712           </para>
1713         </sect3-->
1714
1715       </sect2>
1716
1717       <sect2 id="emacs-psgml">
1718         <title>PSGML Mode in Emacs</title>
1719         <para>
1720           Although you can write SGML documentation in any simple text
1721           editor, some editors provide extra support for entering SGML
1722           tags, and for verifying that the SGML you create is valid.
1723           SGML has been around for a long time, and many commercial
1724           editors exist for it; however, until recently open source
1725           SGML editors have been scarce.
1726         </para>
1727         <!--note>
1728           <title>FIXME</title>
1729           <para>
1730             List the available commercial and open source SGML
1731             editors.
1732           </para>
1733         </note-->
1734         <para>
1735           The most commonly used open source SGML editor is Emacs,
1736           with the PSGML <firstterm>mode</firstterm>, or extension.
1737           Emacs does not supply a GUI or WYSIWYG (What You See Is What
1738           You Get) interface, but it does provide many helpful
1739           shortcuts for creating SGML, as well as automatic
1740           formatting, validity checking, and the ability to create
1741           your own macros to simplify complex, repetitive actions.
1742           We'll touch briefly on each of these points.
1743         </para>
1744         <para>
1745           The first thing you need is a working installation of Emacs
1746           (or XEmacs), with the PSGML package.  Most Linux
1747           distributions provide both as easy-to-install packages.
1748         </para>
1749         <para>
1750           Next, you'll need a working SGML environment.  See <xref
1751           linkend="sgml-environment"> for more info on setting that
1752           up.
1753         </para>
1754       </sect2>
1755
1756       <!--sect2 id="docbook-build">
1757         <title>The DocBook Build System</title>
1758
1759         <sect3 id="docbook-infrastructure">
1760           <title>Basic Infrastructure</title>
1761           <para>
1762             FIXME: How the build/make system works (makefiles, db2html,
1763             jade, stylesheets).
1764           </para>
1765         </sect3>
1766
1767         <sect3 id="docbook-tweaking">
1768           <title>Tweaking the DSSSL stylesheets</title>
1769           <para>
1770             FIXME: Things you can tweak, and how to do it (examples from
1771             default.dsl and print.dsl).
1772           </para>
1773         </sect3>
1774
1775         <sect3 id="docbook-generating">
1776           <title>Generating docs for Wine web sites</title>
1777           <para>
1778             FIXME: Explain make, rsync, etc.
1779           </para>
1780         </sect3>
1781       </sect2-->
1782     </sect1>
1783   </chapter>
1784
1785 <!-- Keep this comment at the end of the file
1786 Local variables:
1787 mode: sgml
1788 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
1789 End:
1790 -->