Check service database name in OpenSCManager().
[wine] / 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.org">http://www.winehq.org</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 -->