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 functionality 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 organizational 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 reorganized 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 reorganized, 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 several 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 accidentally or deliberately vague or misleading.
 123           </para></listitem>
 124
 125           </itemizedlist>
 126       </para>
 127
 128       <para>
 129         To this end, a semi formalized 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 recognized, 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 relevant 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 emphasize 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 emphasized and put in its own paragraph. 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 supplemental 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 supplemental.
 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>
 716                 <para>
 717                   sgml-common-*.rpm
 718                 </para>
 719               </listitem>
 720               <listitem>
 721                 <para>
 722                   openjade-*.rpm
 723                 </para>
 724               </listitem>
 725               <listitem>
 726                 <para>
 727                   perl-SGMLSpm-*.rpm
 728                 </para>
 729               </listitem>
 730               <listitem>
 731                 <para>
 732                   docbook-dtd*.rpm
 733                 </para>
 734               </listitem>
 735               <listitem>
 736                 <para>
 737                   docbook-style-dsssl-*.rpm
 738                 </para>
 739               </listitem>
 740               <listitem>
 741                 <para>
 742                   tetex-*.rpm
 743                 </para>
 744               </listitem>
 745               <listitem>
 746                 <para>
 747                   jadetex-*.rpm
 748                 </para>
 749               </listitem>
 750               <listitem>
 751                 <para>
 752                   docbook-utils-*.rpm
 753                 </para>
 754               </listitem>
 755             </itemizedlist>
 756             You can also use ghostscript to view the ps format output and
 757             Adobe Acrobat 4 to view the pdf file.
 758           </para>
 759         </sect4>
 760
 761         <sect4>
 762           <title>SGML on Debian</title>
 763           <para>
 764            This is not a definitive listing yet, but it seems
 765            you might need the following packages:
 766             <itemizedlist>
 767               <listitem>
 768                 <para>
 769                   docbook
 770                 </para>
 771               </listitem>
 772               <listitem>
 773                 <para>
 774                   docbook-dsssl
 775                 </para>
 776               </listitem>
 777               <listitem>
 778                 <para>
 779                   docbook-utils
 780                 </para>
 781               </listitem>
 782               <listitem>
 783                 <para>
 784                   docbook-xml
 785                 </para>
 786               </listitem>
 787               <listitem>
 788                 <para>
 789                   docbook-xsl
 790                 </para>
 791               </listitem>
 792               <listitem>
 793                 <para>
 794                   sgml-base
 795                 </para>
 796               </listitem>
 797               <listitem>
 798                 <para>
 799                   sgml-data
 800                 </para>
 801               </listitem>
 802               <listitem>
 803                 <para>
 804                   tetex-base
 805                 </para>
 806               </listitem>
 807               <listitem>
 808                 <para>
 809                   tetex-bin
 810                 </para>
 811               </listitem>
 812               <listitem>
 813                 <para>
 814                   jade
 815                 </para>
 816               </listitem>
 817               <listitem>
 818                 <para>
 819                   jadetex
 820                 </para>
 821               </listitem>
 822             </itemizedlist>
 823           </para>
 824         </sect4>
 825
 826         <sect4>
 827           <title>SGML on Other Distributions</title>
 828           <note>
 829           <title>Fix me</title>
 830           <para>
 831             List package names and install locations...
 832           </para>
 833           </note>
 834         </sect4>
 835         </sect3>
 836         <sect3>
 837           <title>Terminology</title>
 838
 839           <para>
 840             SGML markup contains a number of syntactical elements that
 841             serve different purposes in the markup.  We'll run through
 842             the basics here to make sure we're on the same page when
 843             we refer to SGML semantics.
 844           </para>
 845           <para>
 846             The basic currency of SGML is the
 847             <firstterm>tag</firstterm>.  A simple tag consists of a
 848             pair of angle brackets and the name of the tag.  For
 849             example, the <sgmltag>para</sgmltag> tag would appear in
 850             an SGML document as <sgmltag
 851             class="starttag">para</sgmltag>.  This start tag indicates
 852             that the immediately following text should be classified
 853             according to the tag.  In regular SGML, each opening tag
 854             must have a matching end tag to show where the start tag's
 855             contents end.  End tags begin with
 856             <quote><literal>&lt;/</literal></quote> markup, e.g.,
 857             <sgmltag class="endtag">para</sgmltag>.
 858           </para>
 859           <para>
 860             The combination of a start tag, contents, and an end tag
 861             is called an <firstterm>element</firstterm>.  SGML
 862             elements can be nested inside of each other, or contain
 863             only text, or may be a combination of both text and other
 864             elements, although in most cases it is better to limit
 865             your elements to one or the other.
 866           </para>
 867           <para>
 868             The <acronym>XML</acronym> (<firstterm>eXtensible Markup
 869             Language</firstterm>) specification, a modern subset of
 870             the SGML specification, adds a so-called <firstterm>empty
 871             tag</firstterm>, for elements that contain no text
 872             content.  The entire element is a single tag, ending with
 873             <quote><literal>/&gt;</literal></quote>, e.g.,
 874             <sgmltag>&lt;xref/&gt;</sgmltag>.  However, use of this
 875             tag style restricts you to XML DocBook processing, and
 876             your document may no longer compile with SGML-only
 877             processing systems.
 878           </para>
 879           <!-- *** Note: We could normally use the "emptytag"
 880             attribute for XML empty tags, but that's only a recent
 881             addition, and we don't want to screw up documents
 882             generated against older stylesheets.
 883           *** -->
 884           <para>
 885             Often a processing system will need more information about
 886             an element than you can provide with just tags.  SGML
 887             allows you to add extra <quote>hints</quote> in the form
 888             of SGML <firstterm>attributes</firstterm> to pass along
 889             this information.  The most common use of attributes in
 890             DocBook is giving specific elements a name, or an ID, so
 891             you can refer to it from elsewhere.  This ID can be used
 892             for many things, including file-naming for HTML output,
 893             hyper-linking to specific parts of the document, and even
 894             pulling text from that element (see the <sgmltag
 895             class="starttag">xref</sgmltag> tag).
 896           </para>
 897           <para>
 898             An SGML attribute appears inside the start tag, between
 899             the &lt; and &gt; brackets.  For example, if you wanted to
 900             set the <sgmltag class="attribute">id</sgmltag> attribute
 901             of the <sgmltag class="starttag">book</sgmltag> element to
 902             <quote>mybook</quote>, you would create a start tag like
 903             this: <programlisting>&lt;book id="mybook"></programlisting>
 904           </para>
 905           <para>
 906             Notice that the contents of the attribute are enclosed in
 907             quote marks.  These quotes are optional in SGML, but
 908             mandatory in XML.  It's a good habit to use quotes, as it
 909             will make it much easier to migrate your documents to an
 910             XML processing system later on.
 911           </para>
 912           <para>
 913             You can also specify more than one attribute in a single
 914             tag: <programlisting>&lt;book id="mybook" status="draft"></programlisting>
 915           </para>
 916           <para>
 917             Another commonly used type of SGML markup is the
 918             <firstterm>entity</firstterm>.  An entity lets you
 919             associate a block of text with a name.  You declare the
 920             entity once, at the beginning of your document, and can
 921             invoke it as many times as you like throughout the
 922             document.  You can use entities as shorthand, or to make
 923             it easier to maintain certain phrases in a central
 924             location, or even to insert the contents of an entire file
 925             into your document.
 926           </para>
 927           <para>
 928             An entity in your document is always surrounded by the
 929             <quote>&amp;</quote> and <quote>;</quote> characters.  One
 930             entity you'll need sooner or later is the one for the
 931             <quote>&lt;</quote> character.  Since SGML expects all
 932             tags to begin with a <quote>&lt;</quote>, the
 933             <quote>&lt;</quote> is a reserved character.  To use it in
 934             your document (as I am doing here), you must insert it
 935             with the <literal>&amp;lt;</literal> entity.  Each time
 936             the SGML processor encounters <literal>&amp;lt;</literal>,
 937             it will place a literal <quote>&lt;</quote> in the output
 938             document. Similarly you must use the <literal>&amp;gt;</literal>
 939             and <literal>&amp;amp;</literal> entities for the
 940             <quote>&gt;</quote> and <quote>&amp;</quote> characters.
 941           </para>
 942           <para>
 943             The final term you'll need to know when writing simple
 944             DocBook documents is the <acronym>DTD</acronym>
 945             (<firstterm>Document Type Declaration</firstterm>).  The
 946             DTD defines the flavour of SGML a given document is written
 947             in.  It lists all the legal tag names, like <sgmltag
 948             class="starttag">book</sgmltag>, <sgmltag
 949             class="starttag">para</sgmltag>, and so on, and declares
 950             how those tags are allowed to be used together.  For
 951             example, it doesn't make sense to put a <sgmltag
 952             class="starttag">book</sgmltag> element inside a <sgmltag
 953             class="starttag">para</sgmltag> paragraph element -- only
 954             the reverse.
 955           </para>
 956           <para>
 957             The DTD thus defines the legal structure of the document.
 958             It also declares which attributes can be used with which
 959             tags.  The SGML processing system can use the DTD to make
 960             sure the document is laid out properly before attempting
 961             to process it.  SGML-aware text editors like <link
 962             linkend="emacs-psgml">Emacs</link> can also use the DTD to
 963             guide you while you write, offering you choices about
 964             which tags you can add in different places in the
 965             document, and beeping at you when you try to add a tag
 966             where it doesn't belong.
 967           </para>
 968           <para>
 969             Generally, you will declare which DTD you want to use as
 970             the first line of your SGML document.  In the case of
 971             DocBook, you will use something like this:
 972             <programlisting>&lt!doctype book PUBLIC "-//OASIS//DTD
 973             DocBook V3.1//EN" []> &lt;book> ...
 974             &lt;/book></programlisting>
 975           </para>
 976           <para>
 977             Note that you must specify your toplevel element inside
 978             the doctype declaration.  If you were writing an article
 979             rather than a book, you might use this declaration instead:
 980             <programlisting>&lt!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
 981 &lt;article>
 982 ...
 983 &lt;/article></programlisting>
 984           </para>
 985         </sect3>
 986
 987         <sect3 id="sgml-document">
 988           <title>The Document</title>
 989           <para>
 990             Once you're comfortable with SGML, creating a DocBook
 991             document is quite simple and straightforward.  Even
 992             though DocBook contains over 300 different tags, you can
 993             usually get by with only a small subset of those tags.
 994             Most of them are for inline formatting, rather than for
 995             document structuring.  Furthermore, the common tags have
 996             short, intuitive names.
 997           </para>
 998           <para>
 999             Below is a (completely nonsensical) example to illustrate
1000             how a simple document might be laid out.  Notice that all
1001             <sgmltag class="starttag">chapter</sgmltag> and <sgmltag
1002             class="starttag">sect1</sgmltag> elements have <sgmltag
1003             class="attribute">id</sgmltag> attributes.  This is not
1004             mandatory, but is a good habit to get into, as DocBook is
1005             commonly converted into HTML, with a separate generated
1006             file for each <sgmltag class="starttag">book</sgmltag>,
1007             <sgmltag class="starttag">chapter</sgmltag>, and/or <sgmltag
1008             class="starttag">sect1</sgmltag> element.  If the given
1009             element has an <sgmltag class="attribute">id</sgmltag>
1010             attribute, the processor will typically name the file
1011             accordingly.  Thus, the below document might result in
1012             <filename>index.html</filename>,
1013             <filename>chapter-one.html</filename>,
1014             <filename>blobs.html</filename>, and so on.
1015           </para>
1016           <para>
1017             Also notice the text marked off with <quote>&lt;!--
1018             </quote> and <quote> --&gt;</quote> characters.  These
1019             denote SGML comments.  SGML processors will completely
1020             ignore anything between these markers, similar to
1021             <quote>/*</quote> and <quote>*/</quote> comments in C
1022             source code.
1023           </para>
1024
1025           <!-- Encase the following SGML excerpt inside a CDATA
1026                block so we don't have to bother converting all
1027                brackets to entities
1028           -->
1029           <programlisting>
1030 <![CDATA[
1031 <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
1032 <book id="index">
1033   <bookinfo>
1034     <title>A Poet's Guide to Nonsense</title>
1035   </bookinfo>
1036
1037   <chapter id="chapter-one">
1038     <title>Blobs and Gribbles</title>
1039
1040     <!-- This section contains only one major topic -->
1041     <sect1 id="blobs">
1042       <title>The Story Behind Blobs</title>
1043       <para>
1044         Blobs are often mistaken for ice cubes and rain
1045         puddles...
1046       </para>
1047     </sect1>
1048
1049     <!-- This section contains embedded sub-sections -->
1050     <sect1 id="gribbles">
1051       <title>Your Friend the Gribble</title>
1052       <para>
1053         A Gribble is a cute, unassuming little fellow...
1054       </para>
1055
1056       <sect2 id="gribble-temperament">
1057         <title>Gribble Temperament</title>
1058         <para>
1059           When left without food for several days...
1060         </para>
1061       </sect2>
1062
1063       <sect2 id="gribble-appearance">
1064         <title>Gribble Appearance</title>
1065         <para>
1066           Most Gribbles have a shock of white fur running from...
1067         </para>
1068       </sect2>
1069     </sect1>
1070   </chapter>
1071
1072   <chapter id="chapter-two">
1073     <title>Phantasmagoria</title>
1074
1075     <sect1 id="dretch-pools">
1076       <title>Dretch Pools</title>
1077
1078       <para>
1079         When most poets think of Dretch Pools, they tend to...
1080       </para>
1081     </sect>
1082   </chapter>
1083 </book>
1084 ]]>
1085 </programlisting>
1086         </sect3>
1087
1088         <sect3>
1089           <title>Common Elements</title>
1090           <para>
1091             Once you get used to the syntax of SGML, the next hurdle
1092             in writing DocBook documentation is to learn the many
1093             DocBook-specific tag names, and when to use them.  DocBook
1094             was created for technical documentation, and as such, the
1095             tag names and document structure are slanted towards the
1096             needs of such documentation.
1097           </para>
1098           <para>
1099             To cover its target audience, DocBook declares a wide
1100             variety of specialized tags, including tags for formatting
1101             source code (with somewhat of a C/C++ bias), computer
1102             prompts, GUI application features, keystrokes, and so on.
1103             DocBook also includes tags for universal formatting needs,
1104             like headers, footnotes, tables, and graphics.
1105           </para>
1106           <para>
1107             We won't cover all of these elements here (over 300
1108             DocBook tags exist!), but we will cover the basics.  To
1109             learn more about the other tags, check out the official
1110             DocBook guide, at <ulink
1111             url="http://docbook.org">http://docbook.org</ulink>.  To
1112             see how they are used in practice, download the SGML
1113             source for this manual (the Wine Developer Guide) and
1114             browse through it, comparing it to the generated HTML (or
1115             PostScript or PDF).
1116           </para>
1117           <para>
1118             There are often many correct ways to mark up a given piece
1119             of text, and you may have to make guesses about which tag
1120             to use.  Sometimes you'll have to make compromises.
1121             However, remember that it is possible to further <link
1122             linkend="docbook-tweaking">customize the output</link> of
1123             the SGML processors.  If you don't like the way a certain
1124             tag looks in HTML, that doesn't mean you should choose a
1125             different tag based on its output formatting.  The
1126             processing stylesheets can be altered to fix the
1127             formatting of that same tag everywhere in the document
1128             (not just in the place you're working on).  For example,
1129             if you're frustrated that the <sgmltag
1130             class="starttag">systemitem</sgmltag> tag doesn't produce
1131             any formatting by default, you should fix the stylesheets,
1132             not change the valid <sgmltag
1133             class="starttag">systemitem</sgmltag> tag to, for example,
1134             an <sgmltag class="starttag">emphasis</sgmltag> tag.
1135           </para>
1136           <para>
1137             Here are the common SGML elements:
1138           </para>
1139
1140           <variablelist>
1141             <title>Structural Elements</title>
1142             <varlistentry>
1143               <term><sgmltag class="starttag">book</sgmltag></term>
1144               <listitem>
1145                 <para>
1146                   The book is the most common toplevel element, and is
1147                   probably the one you should use for your document.
1148                 </para>
1149               </listitem>
1150             </varlistentry>
1151             <varlistentry>
1152               <term><sgmltag class="starttag">set</sgmltag></term>
1153               <listitem>
1154                 <para>
1155                   If you want to group more than one book into a
1156                   single unit, you can place them all inside a set.
1157                   This is useful when you want to bundle up
1158                   documentation in alternate ways.  We do this with
1159                   the Wine documentation, using
1160                   <sgmltag class="starttag">book</sgmltag> to
1161                   put each Wine guide into a separate directory (see
1162                   <filename>documentation/wine-devel.sgml</filename>,
1163                   etc.).
1164                 </para>
1165               </listitem>
1166             </varlistentry>
1167             <varlistentry>
1168               <term><sgmltag class="starttag">chapter</sgmltag></term>
1169               <listitem>
1170                 <para>
1171                   A <sgmltag class="starttag">chapter</sgmltag>
1172                   element includes a single entire chapter of the
1173                   book.
1174                 </para>
1175               </listitem>
1176             </varlistentry>
1177             <varlistentry>
1178               <term><sgmltag class="starttag">part</sgmltag></term>
1179               <listitem>
1180                 <para>
1181                   If the chapters in your book fall into major
1182                   categories or groupings (as in the Wine Developer
1183                   Guide), you can place each collection of chapters
1184                   into a <sgmltag class="starttag">part</sgmltag>
1185                   element.
1186                 </para>
1187               </listitem>
1188             </varlistentry>
1189             <varlistentry>
1190               <term><sgmltag class="starttag">sect?</sgmltag></term>
1191               <listitem>
1192                 <para>
1193                   DocBook has many section elements to divide the
1194                   contents of a chapter into smaller chunks.  The
1195                   encouraged approach is to use the numbered section
1196                   tags, <sgmltag class="starttag">sect1</sgmltag>,
1197                   <sgmltag class="starttag">sect2</sgmltag>, <sgmltag
1198                   class="starttag">sect3</sgmltag>, <sgmltag
1199                   class="starttag">sect4</sgmltag>, and <sgmltag
1200                   class="starttag">sect5</sgmltag> (if necessary).
1201                   These tags must be nested in order: you can't place
1202                   a <sgmltag class="starttag">sect3</sgmltag> directly
1203                   inside a <sgmltag class="starttag">sect1</sgmltag>.
1204                   You have to nest the <sgmltag
1205                   class="starttag">sect3</sgmltag> inside a <sgmltag
1206                   class="starttag">sect2</sgmltag>, and so forth.
1207                   Documents with these explicit section groupings are
1208                   easier for SGML processors to deal with, and lead to
1209                   better organized documents.  DocBook also supplies a
1210                   <sgmltag class="starttag">section</sgmltag> element
1211                   which you can nest inside itself, but its use is
1212                   discouraged in favor of the numbered section tags.
1213                 </para>
1214               </listitem>
1215             </varlistentry>
1216             <varlistentry>
1217               <term><sgmltag class="starttag">title</sgmltag></term>
1218               <listitem>
1219                 <para>
1220                   The title of a book, chapter, part, section, etc.
1221                   In most of the major structural elements, like
1222                   <sgmltag class="starttag">chapter</sgmltag>,
1223                   <sgmltag class="starttag">part</sgmltag>, and the
1224                   various section tags, <sgmltag
1225                   class="starttag">title</sgmltag> is mandatory.  In
1226                   other elements like <sgmltag
1227                   class="starttag">book</sgmltag> and <sgmltag
1228                   class="starttag">note</sgmltag>, it's optional.
1229                 </para>
1230               </listitem>
1231             </varlistentry>
1232             <varlistentry>
1233               <term><sgmltag class="starttag">para</sgmltag></term>
1234               <listitem>
1235                 <para>
1236                   The basic unit of text is the paragraph, represented
1237                   by the <sgmltag class="starttag">para</sgmltag> tag.
1238                   This is probably the tag you'll use most often.  In
1239                   fact, in a simple document, you can probably get
1240                   away with using only <sgmltag
1241                   class="starttag">book</sgmltag>, <sgmltag
1242                   class="starttag">chapter</sgmltag>, <sgmltag
1243                   class="starttag">title</sgmltag>, and <sgmltag
1244                   class="starttag">para</sgmltag>.
1245                 </para>
1246               </listitem>
1247             </varlistentry>
1248             <varlistentry>
1249               <term><sgmltag class="starttag">article</sgmltag></term>
1250               <listitem>
1251                 <para>
1252                   For shorter, more targeted documents, like topic
1253                   pieces and whitepapers, you can use <sgmltag
1254                   class="starttag">article</sgmltag> as your toplevel
1255                   element.
1256                 </para>
1257               </listitem>
1258             </varlistentry>
1259           </variablelist>
1260
1261           <variablelist>
1262             <title>Inline Formatting Elements</title>
1263             <varlistentry>
1264               <term><sgmltag class="starttag">filename</sgmltag></term>
1265               <listitem>
1266                 <para>
1267                   The name of a file.  You can optionally set the
1268                   <sgmltag class="attribute">class</sgmltag> attribute
1269                   to <literal>Directory</literal>,
1270                   <literal>HeaderFile</literal>, and
1271                   <literal>SymLink</literal> to further classify the
1272                   filename.
1273                 </para>
1274               </listitem>
1275             </varlistentry>
1276             <varlistentry>
1277               <term><sgmltag class="starttag">userinput</sgmltag></term>
1278               <listitem>
1279                 <para>
1280                   Literal text entered by the user.
1281                 </para>
1282               </listitem>
1283             </varlistentry>
1284             <varlistentry>
1285               <term><sgmltag class="starttag">computeroutput</sgmltag></term>
1286               <listitem>
1287                 <para>
1288                   Literal text output by the computer.
1289                 </para>
1290               </listitem>
1291             </varlistentry>
1292             <varlistentry>
1293               <term><sgmltag class="starttag">literal</sgmltag></term>
1294               <listitem>
1295                 <para>
1296                   A catch-all element for literal computer data.  Its
1297                   use is somewhat vague; try to use a more specific
1298                   tag if possible, like <sgmltag
1299                   class="starttag">userinput</sgmltag> or <sgmltag
1300                   class="starttag">computeroutput</sgmltag>.
1301                 </para>
1302               </listitem>
1303             </varlistentry>
1304             <varlistentry>
1305               <term><sgmltag class="starttag">quote</sgmltag></term>
1306               <listitem>
1307                 <para>
1308                   An inline quotation.  This tag typically inserts
1309                   quotation marks for you, so you would write <sgmltag
1310                   class="starttag">quote</sgmltag>This is a
1311                   quote<sgmltag class="endtag">quote</sgmltag> rather
1312                   than "This is a quote".  This usage may be a little
1313                   bulkier, but it does allow for automated formatting
1314                   of all quoted material in the document.  Thus, if
1315                   you wanted all quotations to appear in italic, you
1316                   could make the change once in your stylesheet,
1317                   rather than doing a search and replace throughout
1318                   the document.  For larger chunks of quoted text, you
1319                   can use <sgmltag
1320                   class="starttag">blockquote</sgmltag>.
1321                 </para>
1322               </listitem>
1323             </varlistentry>
1324             <varlistentry>
1325               <term><sgmltag class="starttag">note</sgmltag></term>
1326               <listitem>
1327                 <para>
1328                   Insert a side note for the reader.  By default, the
1329                   SGML processor usually prefixes the content with
1330                   "Note:".  You can change this text by adding a
1331                   <sgmltag class="starttag">title</sgmltag> element.
1332                   Thus, to add a visible FIXME comment to the
1333                   documentation, you might write:
1334                 </para>
1335 <programlisting>
1336 <![CDATA[
1337 <note>
1338   <title>FIXME</title>
1339   <para>This section needs more info about...</para>
1340 </note>
1341 ]]></programlisting>
1342                 <para>
1343                   The results will look something like this:
1344                 </para>
1345                   <note>
1346                     <title>FIXME</title>
1347                     <para>This section needs more info about...</para>
1348                   </note>
1349               </listitem>
1350             </varlistentry>
1351             <varlistentry>
1352               <term><sgmltag class="starttag">sgmltag</sgmltag></term>
1353               <listitem>
1354                 <para>
1355                   Used for inserting SGML tags, etc., into a SGML
1356                   document without resorting to a lot of entity
1357                   quoting, e.g., &amp;lt;.  You can change the
1358                   appearance of the text with the <sgmltag
1359                   class="attribute">class</sgmltag> attribute.  Some
1360                   common values of this are
1361                   <literal>starttag</literal>,
1362                   <literal>endtag</literal>,
1363                   <literal>attribute</literal>,
1364                   <literal>attvalue</literal>, and even
1365                   <literal>sgmlcomment</literal>.  See this SGML file,
1366                   <filename>documentation/documentation.sgml</filename>,
1367                   for examples.
1368                 </para>
1369               </listitem>
1370             </varlistentry>
1371             <varlistentry>
1372               <term><sgmltag class="starttag">prompt</sgmltag></term>
1373               <listitem>
1374                 <para>
1375                   The text used for a computer prompt, for example a
1376                   shell prompt, or command-line application prompt.
1377                 </para>
1378               </listitem>
1379             </varlistentry>
1380             <varlistentry>
1381               <term><sgmltag class="starttag">replaceable</sgmltag></term>
1382               <listitem>
1383                 <para>
1384                   Meta-text that should be replaced by the user, not
1385                   typed in literally, e.g., in command descriptions
1386                   and <parameter>--help</parameter> outputs.
1387                 </para>
1388               </listitem>
1389             </varlistentry>
1390             <varlistentry>
1391               <term><sgmltag class="starttag">constant</sgmltag></term>
1392               <listitem>
1393                 <para>
1394                   A programming constant, e.g.,
1395                   <constant>MAX_PATH</constant>.
1396                 </para>
1397               </listitem>
1398             </varlistentry>
1399             <varlistentry>
1400               <term><sgmltag class="starttag">symbol</sgmltag></term>
1401               <listitem>
1402                 <para>
1403                   A symbolic value replaced, for example, by a
1404                   pre-processor.  This applies primarily to C macros,
1405                   but may have other uses.  Use the <sgmltag
1406                   class="starttag">constant</sgmltag> tag instead of
1407                   <sgmltag class="starttag">symbol</sgmltag> where
1408                   appropriate.
1409                 </para>
1410               </listitem>
1411             </varlistentry>
1412             <varlistentry>
1413               <term><sgmltag class="starttag">function</sgmltag></term>
1414               <listitem>
1415                 <para>
1416                   A programming function name.
1417                 </para>
1418               </listitem>
1419             </varlistentry>
1420             <varlistentry>
1421               <term><sgmltag class="starttag">parameter</sgmltag></term>
1422               <listitem>
1423                 <para>
1424                   Programming language parameters you pass with a
1425                   function.
1426                 </para>
1427               </listitem>
1428             </varlistentry>
1429             <varlistentry>
1430               <term><sgmltag class="starttag">option</sgmltag></term>
1431               <listitem>
1432                 <para>
1433                   Parameters you pass to a command-line executable.
1434                 </para>
1435               </listitem>
1436             </varlistentry>
1437             <varlistentry>
1438               <term><sgmltag class="starttag">varname</sgmltag></term>
1439               <listitem>
1440                 <para>
1441                   Variable name, typically in a programming language.
1442                 </para>
1443               </listitem>
1444             </varlistentry>
1445             <varlistentry>
1446               <term><sgmltag class="starttag">type</sgmltag></term>
1447               <listitem>
1448                 <para>
1449                   Programming language types, e.g., from a typedef
1450                   definition.  May have other uses, too.
1451                 </para>
1452               </listitem>
1453             </varlistentry>
1454             <varlistentry>
1455               <term><sgmltag class="starttag">structname</sgmltag></term>
1456               <listitem>
1457                 <para>
1458                   The name of a C-language <type>struct</type>
1459                   declaration, e.g., <structname>sockaddr</structname>.
1460                 </para>
1461               </listitem>
1462             </varlistentry>
1463             <varlistentry>
1464               <term><sgmltag class="starttag">structfield</sgmltag></term>
1465               <listitem>
1466                 <para>
1467                   A field inside a C <type>struct</type>.
1468                 </para>
1469               </listitem>
1470             </varlistentry>
1471             <varlistentry>
1472               <term><sgmltag class="starttag">command</sgmltag></term>
1473               <listitem>
1474                 <para>
1475                   An executable binary, e.g., <command>wine</command>
1476                   or <command>ls</command>.
1477                 </para>
1478               </listitem>
1479             </varlistentry>
1480             <varlistentry>
1481               <term><sgmltag class="starttag">envar</sgmltag></term>
1482               <listitem>
1483                 <para>
1484                   An environment variable, e.g, <envar>$PATH</envar>.
1485                 </para>
1486               </listitem>
1487             </varlistentry>
1488             <varlistentry>
1489               <term><sgmltag class="starttag">systemitem</sgmltag></term>
1490               <listitem>
1491                 <para>
1492                   A generic catch-all for system-related things, like
1493                   OS names, computer names, system resources, etc.
1494                 </para>
1495               </listitem>
1496             </varlistentry>
1497             <varlistentry>
1498               <term><sgmltag class="starttag">email</sgmltag></term>
1499               <listitem>
1500                 <para>
1501                   An email address.  The SGML processor will typically
1502                   add extra formatting characters, and even a
1503                   <literal>mailto:</literal> link for HTML pages.
1504                   Usage: <sgmltag
1505                   class="starttag">email</sgmltag>user@host.com<sgmltag
1506                   class="endtag">email</sgmltag>
1507                 </para>
1508               </listitem>
1509             </varlistentry>
1510             <varlistentry>
1511               <term><sgmltag class="starttag">firstterm</sgmltag></term>
1512               <listitem>
1513                 <para>
1514                   Special emphasis for introducing a new term.  Can
1515                   also be linked to a <sgmltag
1516                   class="starttag">glossary</sgmltag> entry, if
1517                   desired.
1518                 </para>
1519               </listitem>
1520             </varlistentry>
1521           </variablelist>
1522
1523           <variablelist>
1524             <title>Item Listing Elements</title>
1525             <varlistentry>
1526               <term><sgmltag class="starttag">itemizedlist</sgmltag></term>
1527               <listitem>
1528                 <para>
1529                   For bulleted lists, no numbering.  You can tweak the
1530                   layout with SGML attributes.
1531                 </para>
1532               </listitem>
1533             </varlistentry>
1534             <varlistentry>
1535               <term><sgmltag class="starttag">orderedlist</sgmltag></term>
1536               <listitem>
1537                 <para>
1538                   A numbered list; the SGML processor will insert the
1539                   numbers for you.  You can suggest numbering styles
1540                   with the <sgmltag
1541                   class="attribute">numeration</sgmltag> attribute.
1542                 </para>
1543               </listitem>
1544             </varlistentry>
1545             <varlistentry>
1546               <term><sgmltag class="starttag">simplelist</sgmltag></term>
1547               <listitem>
1548                 <para>
1549                   A very simple list of items, often inlined.  Control
1550                   the layout with the <sgmltag
1551                   class="attribute">type</sgmltag> attribute.
1552                 </para>
1553               </listitem>
1554             </varlistentry>
1555             <varlistentry>
1556               <term><sgmltag class="starttag">variablelist</sgmltag></term>
1557               <listitem>
1558                 <para>
1559                   A list of terms with definitions or descriptions,
1560                   like this very list!
1561                 </para>
1562               </listitem>
1563             </varlistentry>
1564           </variablelist>
1565
1566           <variablelist>
1567             <title>Block Text Quoting Elements</title>
1568             <varlistentry>
1569               <term><sgmltag class="starttag">programlisting</sgmltag></term>
1570               <listitem>
1571                 <para>
1572                   Quote a block of source code.  Typically highlighted
1573                   in the output and set off from normal text.
1574                 </para>
1575               </listitem>
1576             </varlistentry>
1577             <varlistentry>
1578               <term><sgmltag class="starttag">screen</sgmltag></term>
1579               <listitem>
1580                 <para>
1581                   Quote a block of visible computer output, like the
1582                   output of a command or chunks of debug logs.
1583                 </para>
1584               </listitem>
1585             </varlistentry>
1586           </variablelist>
1587
1588           <variablelist>
1589             <title>Hyperlink Elements</title>
1590             <varlistentry>
1591               <term><sgmltag class="starttag">link</sgmltag></term>
1592               <listitem>
1593                 <para>
1594                   Generic hypertext link, used for pointing to other
1595                   sections within the current document.  You supply
1596                   the visible text for the link, plus the name of the <sgmltag
1597                   class="attribute">id</sgmltag> attribute of the
1598                   element that you want to link to.  For example:
1599 <programlisting>&lt;link linkend="configuring-wine">the section on configuring wine&lt;/link>
1600 ...
1601 &lt;sect2 id="configuring-wine">
1602 ...</programlisting>
1603                 </para>
1604               </listitem>
1605             </varlistentry>
1606             <varlistentry>
1607               <term><sgmltag class="starttag">xref</sgmltag></term>
1608               <listitem>
1609                 <para>
1610                   In-document hyperlink that can generate its own
1611                   text.  Similar to the <sgmltag
1612                   class="starttag">link</sgmltag> tag, you use the
1613                   <sgmltag class="attribute">linkend</sgmltag>
1614                   attribute to specify which target element you want
1615                   to jump to:
1616                 </para>
1617                 <para>
1618 <programlisting>&lt;xref linkend="configuring-wine">
1619 ...
1620 &lt;sect2 id="configuring-wine">
1621 ...</programlisting>
1622                 </para>
1623                 <para>
1624                   By default, most SGML processors will auto generate
1625                   some generic text for the <sgmltag
1626                   class="starttag">xref</sgmltag> link, like
1627                   <quote>Section 2.3.1</quote>.  You can use the
1628                   <sgmltag class="attribute">endterm</sgmltag>
1629                   attribute to grab the visible text content of the
1630                   hyperlink from another element:
1631                 </para>
1632                 <para>
1633 <programlisting>&lt;xref linkend="configuring-wine" endterm="config-title">
1634 ...
1635 &lt;sect2 id="configuring-wine">
1636   &lt;title id="config-title">Configuring Wine&lt;/title>
1637 ...</programlisting>
1638                 </para>
1639                 <para>
1640                   This would create a link to the
1641                   <symbol>configuring-wine</symbol> element,
1642                   displaying the text of the
1643                   <symbol>config-title</symbol> element for the
1644                   hyperlink.  Most often, you'll add an <sgmltag
1645                   class="attribute">id</sgmltag> attribute to the
1646                   <sgmltag class="starttag">title</sgmltag> of the
1647                   section you're linking to, as above, in which case
1648                   the SGML processor will use the target's title text
1649                   for the link text.
1650                 </para>
1651                 <para>
1652                   Alternatively, you can use an <sgmltag
1653                   class="attribute">xreflabel</sgmltag> attribute in
1654                   the target element tag to specify the link text:
1655                 </para>
1656 <programlisting>&lt;sect1 id="configuring-wine" xreflabel="Configuring Wine"></programlisting>
1657                 <note>
1658                   <para>
1659                     <sgmltag class="starttag">xref</sgmltag> is an
1660                     empty element.  You don't need a closing tag for
1661                     it (this is defined in the DTD).  In SGML
1662                     documents, you should use the form <sgmltag
1663                     class="starttag">xref</sgmltag>, while in XML
1664                     documents you should use
1665                     <sgmltag>&lt;xref/></sgmltag>.
1666                   </para>
1667                 </note>
1668               </listitem>
1669             </varlistentry>
1670             <varlistentry>
1671               <term><sgmltag class="starttag">anchor</sgmltag></term>
1672               <listitem>
1673                 <para>
1674                   An invisible tag, used for inserting <sgmltag
1675                   class="attribute">id</sgmltag> attributes into a
1676                   document to link to arbitrary places (i.e., when
1677                   it's not close enough to link to the top of an
1678                   element).
1679                 </para>
1680               </listitem>
1681             </varlistentry>
1682             <varlistentry>
1683               <term><sgmltag class="starttag">ulink</sgmltag></term>
1684               <listitem>
1685                 <para>
1686                   Hyperlink in URL form, e.g., <ulink
1687                   url="http://www.winehq.com">http://www.winehq.com</ulink>.
1688                 </para>
1689               </listitem>
1690             </varlistentry>
1691             <varlistentry>
1692               <term><sgmltag class="starttag">olink</sgmltag></term>
1693               <listitem>
1694                 <para>
1695                   Indirect hyperlink; can be used for linking to
1696                   external documents.  Not often used in practice.
1697                 </para>
1698               </listitem>
1699             </varlistentry>
1700           </variablelist>
1701         </sect3>
1702
1703         <sect3>
1704           <title>Multiple SGML files</title>
1705           <para>
1706             How to split an SGML document into multiple files...
1707           </para>
1708         </sect3>
1709       </sect2>
1710
1711       <sect2 id="sgml-environment">
1712         <title>The SGML Environment</title>
1713
1714         <para>
1715           You can write SGML/DocBook documents in any text editor you
1716           might find (although as we'll find in <xref
1717           linkend="emacs-psgml">, some editors are more friendly for
1718           this task than others).  However, if you want to convert
1719           those documents into a more friendly form for reading, such
1720           as HTML, PostScript, or PDF, you will need a working SGML
1721           environment.  This section attempts to lay out the various
1722           SGML rendering systems, and how they are set up on the
1723           popular Linux distributions.
1724         </para>
1725
1726         <sect3>
1727           <title>DSSSL Environment</title>
1728           <para>
1729             Explain tools and methodologies..
1730           </para>
1731         </sect3>
1732
1733         <sect3>
1734           <title>XSLT Environment</title>
1735           <para>
1736             Explain tools and methodologies...
1737           </para>
1738         </sect3>
1739
1740       </sect2>
1741
1742       <sect2 id="emacs-psgml">
1743         <title>PSGML Mode in Emacs</title>
1744         <para>
1745           Although you can write SGML documentation in any simple text
1746           editor, some editors provide extra support for entering SGML
1747           tags, and for verifying that the SGML you create is valid.
1748           SGML has been around for a long time, and many commercial
1749           editors exist for it; however, until recently open source
1750           SGML editors have been scarce.
1751         </para>
1752         <note>
1753           <title>FIXME</title>
1754           <para>
1755             List the available commercial and open source SGML
1756             editors.
1757           </para>
1758         </note>
1759         <para>
1760           The most commonly used open source SGML editor is Emacs,
1761           with the PSGML <firstterm>mode</firstterm>, or extension.
1762           Emacs does not supply a GUI or WYSIWYG (What You See Is What
1763           You Get) interface, but it does provide many helpful
1764           shortcuts for creating SGML, as well as automatic
1765           formatting, validity checking, and the ability to create
1766           your own macros to simplify complex, repetitive actions.
1767           We'll touch briefly on each of these points.
1768         </para>
1769         <para>
1770           The first thing you need is a working installation of Emacs
1771           (or XEmacs), with the PSGML package.  Most Linux
1772           distributions provide both as easy-to-install packages.
1773         </para>
1774         <para>
1775           Next, you'll need a working SGML environment.  See <xref
1776           linkend="sgml-environment"> for more info on setting that
1777           up.
1778         </para>
1779       </sect2>
1780
1781       <sect2 id="docbook-build">
1782         <title>The DocBook Build System</title>
1783
1784         <sect3 id="docbook-infrastructure">
1785           <title>Basic Infrastructure</title>
1786           <para>
1787             FIXME: How the build/make system works (makefiles, db2html,
1788             jade, stylesheets).
1789           </para>
1790         </sect3>
1791
1792         <sect3 id="docbook-tweaking">
1793           <title>Tweaking the DSSSL stylesheets</title>
1794           <para>
1795             FIXME: Things you can tweak, and how to do it (examples from
1796             default.dsl and print.dsl).
1797           </para>
1798         </sect3>
1799
1800         <sect3 id="docbook-generating">
1801           <title>Generating docs for Wine web sites</title>
1802           <para>
1803             FIXME: Explain make, rsync, etc.
1804           </para>
1805         </sect3>
1806       </sect2>
1807     </sect1>
1808   </chapter>
1809
1810 <!-- Keep this comment at the end of the file
1811 Local variables:
1812 mode: sgml
1813 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
1814 End:
1815 -->