documentation/documentation.sgml

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