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