documentation/documentation.sgml

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