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