Fixed corruption when copying to the same surface (with the help of
[wine] / documentation / documentation.sgml
1   <chapter id="documentation">
2     <title>Documenting Wine</title>
3     <para>How to help out with the Wine documentation effort...</para>
4
5     <sect1 id="api-docs">
6       <title>Writing Wine API Documentation</title>
7
8       <para>
9         Written by &name-douglas-ridgway; <email>&email-douglas-ridgway;</email>
10       </para>
11       <para>
12         (Extracted from <filename>wine/documentation/README.documentation</filename>)
13       </para>
14
15       <para>
16         To improve the documentation of the Wine API, just add
17         comments to the existing source. For example,
18       </para>
19       <screen>
20 /******************************************************************
21  *         CopyMetaFileA   (GDI32.23)
22  *
23  *  Copies the metafile corresponding to hSrcMetaFile to either
24  *  a disk file, if a filename is given, or to a new memory based
25  *  metafile, if lpFileName is NULL.
26  *
27  * RETURNS
28  *
29  *  Handle to metafile copy on success, NULL on failure.
30  *
31  * BUGS
32  *
33  *  Copying to disk returns NULL even if successful.
34  */
35 HMETAFILE WINAPI CopyMetaFileA(
36                    HMETAFILE hSrcMetaFile, /* handle of metafile to copy */
37                    LPCSTR lpFilename /* filename if copying to a file */
38 ) { ... }
39       </screen>
40       <para>
41         becomes, after processing with <command>c2man</command> and
42         <command>nroff -man</command>,
43       </para>
44       <screen>
45 CopyMetaFileA(3w)                               CopyMetaFileA(3w)
46
47
48 NAME
49        CopyMetaFileA   (GDI32.23)
50
51 SYNOPSIS
52        HMETAFILE CopyMetaFileA
53        (
54             HMETAFILE hSrcMetaFile,
55             LPCSTR lpFilename
56        );
57
58 PARAMETERS
59        HMETAFILE hSrcMetaFile
60               Handle of metafile to copy.
61
62        LPCSTR lpFilename
63               Filename if copying to a file.
64
65 DESCRIPTION
66        Copies  the  metafile  corresponding  to  hSrcMetaFile  to
67        either a disk file, if a filename is given, or  to  a  new
68        memory based metafile, if lpFileName is NULL.
69
70 RETURNS
71        Handle to metafile copy on success, NULL on failure.
72
73 BUGS
74        Copying to disk returns NULL even if successful.
75
76 SEE ALSO
77        GetMetaFileA(3w),   GetMetaFileW(3w),   CopyMetaFileW(3w),
78        PlayMetaFile(3w),  SetMetaFileBitsEx(3w),  GetMetaFileBit-
79        sEx(3w)
80       </screen>
81     </sect1>
82
83     <sect1 id="wine-docbook">
84       <title>The Wine DocBook System</title>
85
86       <para>
87         Written by &name-john-sheets; <email>&email-john-sheets;</email>
88       </para>
89
90       <sect2 id="writing-docbook">
91         <title>Writing Documentation with DocBook</title>
92
93         <para>
94           DocBook is a flavor of <acronym>SGML</acronym>
95           (<firstterm>Standard Generalized Markup
96           Language</firstterm>), a syntax for marking up the contents
97           of documents.  HTML is another very common flavor of SGML;
98           DocBook markup looks very similar to HTML markup, although
99           the names of the markup tags differ.
100         </para>
101
102         <sect3>
103           <title>Terminology</title>
104
105           <para>
106             SGML markup contains a number of syntactical elements that
107             serve different purposes in the markup.  We'll run through
108             the basics here to make sure we're on the same page when
109             we refer to SGML semantics.
110           </para>
111           <para>
112             The basic currency of SGML is the
113             <firstterm>tag</firstterm>.  A simple tag consists of a
114             pair of angle brackets and the name of the tag.  For
115             example, the <sgmltag>para</sgmltag> tag would appear in
116             an SGML document as <sgmltag
117             class="starttag">para</sgmltag>.  This start tag indicates
118             that the immediately following text should be classified
119             according to the tag.  In regular SGML, each opening tag
120             must have a matching end tag to show where the start tag's
121             contents end.  End tags begin with
122             <quote><literal>&lt;/</literal></quote> markup, e.g.,
123             <sgmltag class="endtag">para</sgmltag>.  
124           </para>
125           <para>
126             The combination of a start tag, contents, and an end tag
127             is called an <firstterm>element</firstterm>.  SGML
128             elements can be nested inside of each other, or contain
129             only text, or may be a combination of both text and other
130             elements, although in most cases it is better to limit
131             your elements to one or the other.  
132           </para>
133           <para>
134             The <acronym>XML</acronym> (<firstterm>eXtensible Markup
135             Language</firstterm>) specification, a modern subset of
136             the SGML specification, adds a so-called <firstterm>empty
137             tag</firstterm>, for elements that contain no text
138             content.  The entire element is a single tag, ending with
139             <quote><literal>/&gt;</literal></quote>, e.g.,
140             <sgmltag>&lt;xref/&gt;</sgmltag>.  However, use of this
141             tag style restricts you to XML DocBook processing, and
142             your document may no longer compile with SGML-only
143             processing systems.
144           </para>
145           <!-- *** Note: We could normally use the "emptytag"
146             attribute for XML empty tags, but that's only a recent
147             addition, and we don't want to screw up documents
148             generated against older stylesheets.
149           *** -->
150           <para>
151             Often a processing system will need more information about
152             an element than you can provide with just tags.  SGML
153             allows you to add extra <quote>hints</quote> in the form
154             of SGML <firstterm>attributes</firstterm> to pass along
155             this information.  The most common use of attributes in
156             DocBook is giving specific elements a name, or an ID, so
157             you can refer to it from elsewhere.  This ID can be used
158             for many things, including file-naming for HTML output,
159             hyper-linking to specific parts of the document, and even
160             pulling text from that element (see the <sgmltag
161             class="starttag">xref</sgmltag> tag).
162           </para>
163           <para>
164             An SGML attribute appears inside the start tag, between
165             the &lt; and &gt; brackets.  For example, if you wanted to
166             set the <sgmltag class="attribute">id</sgmltag> attribute
167             of the <sgmltag class="starttag">book</sgmltag> element to
168             <quote>mybook</quote>, you would create a start tag like
169             this: <programlisting>&lt;book id="mybook"></programlisting>
170           </para>
171           <para>
172             Notice that the contents of the attribute are enclosed in
173             quote marks.  These quotes are optional in SGML, but
174             mandatory in XML.  It's a good habit to use quotes, as it
175             will make it much easier to migrate your documents to an
176             XML processing system later on.
177           </para>
178           <para>
179             You can also specify more than one attribute in a single
180             tag: <programlisting>&lt;book id="mybook" status="draft"></programlisting>
181           </para>
182           <para>
183             Another commonly used type of SGML markup is the
184             <firstterm>entity</firstterm>.  An entity lets you
185             associate a block of text with a name.  You declare the
186             entity once, at the beginning of your document, and can
187             invoke it as many times as you like throughout the
188             document.  You can use entities as shorthand, or to make
189             it easier to maintain certain phrases in a central
190             location, or even to insert the contents of an entire file
191             into your document.
192           </para>
193           <para>
194             An entity in your document is always surrounded by the
195             <quote>&amp;</quote> and <quote>;</quote> characters.  One
196             entity you'll need sooner or later is the one for the
197             <quote>&lt;</quote> character.  Since SGML expects all
198             tags to begin with a <quote>&lt;</quote>, the
199             <quote>&lt;</quote> is a reserved character.  To use it in
200             your document (as I am doing here), you must insert it
201             with the <literal>&amp;lt;</literal> entity.  Each time
202             the SGML processor encounters <literal>&amp;lt;</literal>,
203             it will place a literal <quote>&lt;</quote> in the output
204             document. Similarly you must use the <literal>&amp;gt;</literal> 
205             and <literal>&amp;amp;</literal> entities for the 
206             <quote>&gt;</quote> and <quote>&amp;</quote> characters.
207           </para>
208           <para>
209             The final term you'll need to know when writing simple
210             DocBook documents is the <acronym>DTD</acronym>
211             (<firstterm>Document Type Declaration</firstterm>).  The
212             DTD defines the flavor of SGML a given document is written
213             in.  It lists all the legal tag names, like <sgmltag
214             class="starttag">book</sgmltag>, <sgmltag
215             class="starttag">para</sgmltag>, and so on, and declares
216             how those tags are allowed to be used together.  For
217             example, it doesn't make sense to put a <sgmltag
218             class="starttag">book</sgmltag> element inside a <sgmltag
219             class="starttag">para</sgmltag> paragraph element -- only
220             the reverse.
221           </para>
222           <para>
223             The DTD thus defines the legal structure of the document.
224             It also declares which attributes can be used with which
225             tags.  The SGML processing system can use the DTD to make
226             sure the document is laid out properly before attempting
227             to process it.  SGML-aware text editors like <link
228             linkend="emacs-psgml">Emacs</link> can also use the DTD to
229             guide you while you write, offering you choices about
230             which tags you can add in different places in the
231             document, and beeping at you when you try to add a tag
232             where it doesn't belong.
233           </para>
234           <para>
235             Generally, you will declare which DTD you want to use as
236             the first line of your SGML document.  In the case of
237             DocBook, you will use something like this:
238             <programlisting>&lt!doctype book PUBLIC "-//OASIS//DTD
239             DocBook V3.1//EN" []> &lt;book> ...
240             &lt;/book></programlisting>
241           </para>
242           <para>
243             Note that you must specify your toplevel element inside
244             the doctype declaration.  If you were writing an article
245             rather than a book, you might use this declaration instead:
246             <programlisting>&lt!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
247 &lt;article>
248 ...
249 &lt;/article></programlisting>
250           </para>
251         </sect3>
252
253         <sect3 id="sgml-document">
254           <title>The Document</title>
255           <para>
256             Once you're comfortable with SGML, creating a DocBook
257             document is quite simple and straightforward.  Even
258             though DocBook contains over 300 different tags, you can
259             usually get by with only a small subset of those tags.
260             Most of them are for inline formatting, rather than for
261             document structuring.  Furthermore, the common tags have
262             short, intuitive names.
263           </para>
264           <para>
265             Below is a (completely nonsensical) example to illustrate
266             how a simple document might be laid out.  Notice that all
267             <sgmltag class="starttag">chapter</sgmltag> and <sgmltag
268             class="starttag">sect1</sgmltag> elements have <sgmltag
269             class="attribute">id</sgmltag> attributes.  This is not
270             mandatory, but is a good habit to get into, as DocBook is
271             commonly converted into HTML, with a separate generated
272             file for each <sgmltag class="starttag">book</sgmltag>,
273             <sgmltag class="starttag">chapter</sgmltag>, and/or <sgmltag
274             class="starttag">sect1</sgmltag> element.  If the given
275             element has an <sgmltag class="attribute">id</sgmltag>
276             attribute, the processor will typically name the file
277             accordingly.  Thus, the below document might result in
278             <filename>index.html</filename>,
279             <filename>chapter-one.html</filename>,
280             <filename>blobs.html</filename>, and so on.
281           </para>
282           <para>
283             Also notice the text marked off with <quote>&lt;!--
284             </quote> and <quote> --&gt;</quote> characters.  These
285             denote SGML comments.  SGML processors will completely
286             ignore anything between these markers, similar to
287             <quote>/*</quote> and <quote>*/</quote> comments in C
288             source code.
289           </para>
290
291           <!-- Encase the following SGML excerpt inside a CDATA
292                block so we don't have to bother converting all
293                brackets to entities
294           -->
295           <programlisting>
296 <![CDATA[
297 <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
298 <book id="index">
299   <bookinfo>
300     <title>A Poet's Guide to Nonsense</title>
301   </bookinfo>
302
303   <chapter id="chapter-one">
304     <title>Blobs and Gribbles</title>
305
306     <!-- This section contains only one major topic -->
307     <sect1 id="blobs">
308       <title>The Story Behind Blobs</title>
309       <para>
310         Blobs are often mistaken for ice cubes and rain
311         puddles...
312       </para>
313     </sect1>
314
315     <!-- This section contains embedded sub-sections -->
316     <sect1 id="gribbles">
317       <title>Your Friend the Gribble</title>
318       <para>
319         A Gribble is a cute, unassuming little fellow...
320       </para>
321
322       <sect2 id="gribble-temperament">
323         <title>Gribble Temperament</title>
324         <para>
325           When left without food for several days...
326         </para>
327       </sect2>
328
329       <sect2 id="gribble-appearance">
330         <title>Gribble Appearance</title>
331         <para>
332           Most Gribbles have a shock of white fur running from...
333         </para>
334       </sect2>
335     </sect1>
336   </chapter>
337
338   <chapter id="chapter-two">
339     <title>Phantasmagoria</title>
340
341     <sect1 id="dretch-pools">
342       <title>Dretch Pools</title>
343
344       <para>
345         When most poets think of Dretch Pools, they tend to...
346       </para>
347     </sect>
348   </chapter>
349 </book>
350 ]]>
351 </programlisting>
352         </sect3>
353
354         <sect3>
355           <title>Common Elements</title>
356           <para>
357             Once you get used to the syntax of SGML, the next hurdle
358             in writing DocBook documentation is to learn the many
359             DocBook-specific tag names, and when to use them.  DocBook
360             was created for technical documentation, and as such, the
361             tag names and document structure are slanted towards the
362             needs of such documentation.
363           </para>
364           <para>
365             To cover its target audience, DocBook declares a wide
366             variety of specialized tags, including tags for formatting
367             source code (with somewhat of a C/C++ bias), computer
368             prompts, GUI application features, keystrokes, and so on.
369             DocBook also includes tags for universal formatting needs,
370             like headers, footnotes, tables, and graphics.
371           </para>
372           <para>
373             We won't cover all of these elements here (over 300
374             DocBook tags exist!), but we will cover the basics.  To
375             learn more about the other tags, check out the official
376             DocBook guide, at <ulink
377             url="http://docbook.org">http://docbook.org</ulink>.  To
378             see how they are used in practice, download the SGML
379             source for this manual (the Wine Developer Guide) and
380             browse through it, comparing it to the generated HTML (or
381             PostScript or PDF).
382           </para>
383           <para>
384             There are often many correct ways to mark up a given piece
385             of text, and you may have to make guesses about which tag
386             to use.  Sometimes you'll have to make compromises.
387             However, remember that it is possible to further <link
388             linkend="docbook-tweaking">customize the output</link> of
389             the SGML processors.  If you don't like the way a certain
390             tag looks in HTML, that doesn't mean you should choose a
391             different tag based on its output formatting.  The
392             processing stylesheets can be altered to fix the
393             formatting of that same tag everywhere in the document
394             (not just in the place you're working on).  For example,
395             if you're frustrated that the <sgmltag
396             class="starttag">systemitem</sgmltag> tag doesn't produce
397             any formatting by default, you should fix the stylesheets,
398             not change the valid <sgmltag
399             class="starttag">systemitem</sgmltag> tag to, for example,
400             an <sgmltag class="starttag">emphasis</sgmltag> tag.
401           </para>
402           <para>
403             Here are the common SGML elements:
404           </para>
405
406           <variablelist>
407             <title>Structural Elements</title>
408             <varlistentry>
409               <term><sgmltag class="starttag">book</sgmltag></term>
410               <listitem>
411                 <para>
412                   The book is the most common toplevel element, and is
413                   probably the one you should use for your document.
414                 </para>
415               </listitem>
416             </varlistentry>
417             <varlistentry>
418               <term><sgmltag class="starttag">set</sgmltag></term>
419               <listitem>
420                 <para>
421                   If you want to group more than one book into a
422                   single unit, you can place them all inside a set.
423                   This is useful when you want to bundle up
424                   documentation in alternate ways.  We do this with
425                   the Wine documentation, using a <sgmltag
426                   class="starttag">set</sgmltag> to put everything
427                   into a single directory (see
428                   <filename>documentation/wine-doc.sgml</filename>),
429                   and a <sgmltag class="starttag">book</sgmltag> to
430                   put each Wine guide into a separate directory (see
431                   <filename>documentation/wine-devel.sgml</filename>,
432                   etc.).
433                 </para>
434               </listitem>
435             </varlistentry>
436             <varlistentry>
437               <term><sgmltag class="starttag">chapter</sgmltag></term>
438               <listitem>
439                 <para>
440                   A <sgmltag class="starttag">chapter</sgmltag>
441                   element includes a single entire chapter of the
442                   book.
443                 </para>
444               </listitem>
445             </varlistentry>
446             <varlistentry>
447               <term><sgmltag class="starttag">part</sgmltag></term>
448               <listitem>
449                 <para>
450                   If the chapters in your book fall into major
451                   categories or groupings (as in the Wine Developer
452                   Guide), you can place each collection of chapters
453                   into a <sgmltag class="starttag">part</sgmltag>
454                   element.
455                 </para>
456               </listitem>
457             </varlistentry>
458             <varlistentry>
459               <term><sgmltag class="starttag">sect?</sgmltag></term>
460               <listitem>
461                 <para>
462                   DocBook has many section elements to divide the
463                   contents of a chapter into smaller chunks.  The
464                   encouraged approach is to use the numbered section
465                   tags, <sgmltag class="starttag">sect1</sgmltag>,
466                   <sgmltag class="starttag">sect2</sgmltag>, <sgmltag
467                   class="starttag">sect3</sgmltag>, <sgmltag
468                   class="starttag">sect4</sgmltag>, and <sgmltag
469                   class="starttag">sect5</sgmltag> (if necessary).
470                   These tags must be nested in order: you can't place
471                   a <sgmltag class="starttag">sect3</sgmltag> directly
472                   inside a <sgmltag class="starttag">sect1</sgmltag>.
473                   You have to nest the <sgmltag
474                   class="starttag">sect3</sgmltag> inside a <sgmltag
475                   class="starttag">sect2</sgmltag>, and so forth.
476                   Documents with these explicit section groupings are
477                   easier for SGML processors to deal with, and lead to
478                   better organized documents.  DocBook also supplies a
479                   <sgmltag class="starttag">section</sgmltag> element
480                   which you can nest inside itself, but its use is
481                   discouraged in favor of the numbered section tags.
482                 </para>
483               </listitem>
484             </varlistentry>
485             <varlistentry>
486               <term><sgmltag class="starttag">title</sgmltag></term>
487               <listitem>
488                 <para>
489                   The title of a book, chapter, part, section, etc.
490                   In most of the major structural elements, like
491                   <sgmltag class="starttag">chapter</sgmltag>,
492                   <sgmltag class="starttag">part</sgmltag>, and the
493                   various section tags, <sgmltag
494                   class="starttag">title</sgmltag> is mandatory.  In
495                   other elements like <sgmltag
496                   class="starttag">book</sgmltag> and <sgmltag
497                   class="starttag">note</sgmltag>, it's optional.
498                 </para>
499               </listitem>
500             </varlistentry>
501             <varlistentry>
502               <term><sgmltag class="starttag">para</sgmltag></term>
503               <listitem>
504                 <para>
505                   The basic unit of text is the paragraph, represented
506                   by the <sgmltag class="starttag">para</sgmltag> tag.
507                   This is probably the tag you'll use most often.  In
508                   fact, in a simple document, you can probably get
509                   away with using only <sgmltag
510                   class="starttag">book</sgmltag>, <sgmltag
511                   class="starttag">chapter</sgmltag>, <sgmltag
512                   class="starttag">title</sgmltag>, and <sgmltag
513                   class="starttag">para</sgmltag>.
514                 </para>
515               </listitem>
516             </varlistentry>
517             <varlistentry>
518               <term><sgmltag class="starttag">article</sgmltag></term>
519               <listitem>
520                 <para>
521                   For shorter, more targeted documents, like topic
522                   pieces and whitepapers, you can use <sgmltag
523                   class="starttag">article</sgmltag> as your toplevel
524                   element.
525                 </para>
526               </listitem>
527             </varlistentry>
528           </variablelist>
529
530           <variablelist>
531             <title>Inline Formatting Elements</title>
532             <varlistentry>
533               <term><sgmltag class="starttag">filename</sgmltag></term>
534               <listitem>
535                 <para>
536                   The name of a file.  You can optionally set the
537                   <sgmltag class="attribute">class</sgmltag> attribute
538                   to <literal>Directory</literal>,
539                   <literal>HeaderFile</literal>, and
540                   <literal>SymLink</literal> to further classify the
541                   filename.
542                 </para>
543               </listitem>
544             </varlistentry>
545             <varlistentry>
546               <term><sgmltag class="starttag">userinput</sgmltag></term>
547               <listitem>
548                 <para>
549                   Literal text entered by the user.
550                 </para>
551               </listitem>
552             </varlistentry>
553             <varlistentry>
554               <term><sgmltag class="starttag">computeroutput</sgmltag></term>
555               <listitem>
556                 <para>
557                   Literal text output by the computer.
558                 </para>
559               </listitem>
560             </varlistentry>
561             <varlistentry>
562               <term><sgmltag class="starttag">literal</sgmltag></term>
563               <listitem>
564                 <para>
565                   A catch-all element for literal computer data.  Its
566                   use is somewhat vague; try to use a more specific
567                   tag if possible, like <sgmltag
568                   class="starttag">userinput</sgmltag> or <sgmltag
569                   class="starttag">computeroutput</sgmltag>.
570                 </para>
571               </listitem>
572             </varlistentry>
573             <varlistentry>
574               <term><sgmltag class="starttag">quote</sgmltag></term>
575               <listitem>
576                 <para>
577                   An inline quotation.  This tag typically inserts
578                   quotation marks for you, so you would write <sgmltag
579                   class="starttag">quote</sgmltag>This is a
580                   quote<sgmltag class="endtag">quote</sgmltag> rather
581                   than "This is a quote".  This usage may be a little
582                   bulkier, but it does allow for automated formatting
583                   of all quoted material in the document.  Thus, if
584                   you wanted all quotations to appear in italic, you
585                   could make the change once in your stylesheet,
586                   rather than doing a search and replace throughout
587                   the document.  For larger chunks of quoted text, you
588                   can use <sgmltag
589                   class="starttag">blockquote</sgmltag>.
590                 </para>
591               </listitem>
592             </varlistentry>
593             <varlistentry>
594               <term><sgmltag class="starttag">note</sgmltag></term>
595               <listitem>
596                 <para>
597                   Insert a side note for the reader.  By default, the
598                   SGML processor usually prefixes the content with
599                   "Note:".  You can change this text by adding a
600                   <sgmltag class="starttag">title</sgmltag> element.
601                   Thus, to add a visible FIXME comment to the
602                   documentation, you might write:
603                 </para>
604 <programlisting>
605 <![CDATA[
606 <note>
607   <title>FIXME</title>
608   <para>This section needs more info about...</para>
609 </note>
610 ]]></programlisting>
611                 <para>
612                   The results will look something like this:
613                 </para>
614                   <note>
615                     <title>FIXME</title>
616                     <para>This section needs more info about...</para>
617                   </note>
618               </listitem>
619             </varlistentry>
620             <varlistentry>
621               <term><sgmltag class="starttag">sgmltag</sgmltag></term>
622               <listitem>
623                 <para>
624                   Used for inserting SGML tags, etc., into a SGML
625                   document without resorting to a lot of entity
626                   quoting, e.g., &amp;lt;.  You can change the
627                   appearance of the text with the <sgmltag
628                   class="attribute">class</sgmltag> attribute.  Some
629                   common values of this are
630                   <literal>starttag</literal>,
631                   <literal>endtag</literal>,
632                   <literal>attribute</literal>,
633                   <literal>attvalue</literal>, and even
634                   <literal>sgmlcomment</literal>.  See this SGML file,
635                   <filename>documentation/documentation.sgml</filename>,
636                   for examples.
637                 </para>
638               </listitem>
639             </varlistentry>
640             <varlistentry>
641               <term><sgmltag class="starttag">prompt</sgmltag></term>
642               <listitem>
643                 <para>
644                   The text used for a computer prompt, for example a
645                   shell prompt, or command-line application prompt.
646                 </para>
647               </listitem>
648             </varlistentry>
649             <varlistentry>
650               <term><sgmltag class="starttag">replaceable</sgmltag></term>
651               <listitem>
652                 <para>
653                   Meta-text that should be replaced by the user, not
654                   typed in literally, e.g., in command descriptions
655                   and <parameter>--help</parameter> outputs.
656                 </para>
657               </listitem>
658             </varlistentry>
659             <varlistentry>
660               <term><sgmltag class="starttag">constant</sgmltag></term>
661               <listitem>
662                 <para>
663                   A programming constant, e.g.,
664                   <constant>MAX_PATH</constant>.
665                 </para>
666               </listitem>
667             </varlistentry>
668             <varlistentry>
669               <term><sgmltag class="starttag">symbol</sgmltag></term>
670               <listitem>
671                 <para>
672                   A symbolic value replaced, for example, by a
673                   pre-processor.  This applies primarily to C macros,
674                   but may have other uses.  Use the <sgmltag
675                   class="starttag">constant</sgmltag> tag instead of
676                   <sgmltag class="starttag">symbol</sgmltag> where
677                   appropriate.
678                 </para>
679               </listitem>
680             </varlistentry>
681             <varlistentry>
682               <term><sgmltag class="starttag">function</sgmltag></term>
683               <listitem>
684                 <para>
685                   A programming function name.
686                 </para>
687               </listitem>
688             </varlistentry>
689             <varlistentry>
690               <term><sgmltag class="starttag">parameter</sgmltag></term>
691               <listitem>
692                 <para>
693                   Programming language parameters you pass with a
694                   function.
695                 </para>
696               </listitem>
697             </varlistentry>
698             <varlistentry>
699               <term><sgmltag class="starttag">option</sgmltag></term>
700               <listitem>
701                 <para>
702                   Parameters you pass to a command-line executable.
703                 </para>
704               </listitem>
705             </varlistentry>
706             <varlistentry>
707               <term><sgmltag class="starttag">varname</sgmltag></term>
708               <listitem>
709                 <para>
710                   Variable name, typically in a programming language.
711                 </para>
712               </listitem>
713             </varlistentry>
714             <varlistentry>
715               <term><sgmltag class="starttag">type</sgmltag></term>
716               <listitem>
717                 <para>
718                   Programming language types, e.g., from a typedef
719                   definition.  May have other uses, too.
720                 </para>
721               </listitem>
722             </varlistentry>
723             <varlistentry>
724               <term><sgmltag class="starttag">structname</sgmltag></term>
725               <listitem>
726                 <para>
727                   The name of a C-language <type>struct</type>
728                   declaration, e.g., <structname>sockaddr</structname>.
729                 </para>
730               </listitem>
731             </varlistentry>
732             <varlistentry>
733               <term><sgmltag class="starttag">structfield</sgmltag></term>
734               <listitem>
735                 <para>
736                   A field inside a C <type>struct</type>.
737                 </para>
738               </listitem>
739             </varlistentry>
740             <varlistentry>
741               <term><sgmltag class="starttag">command</sgmltag></term>
742               <listitem>
743                 <para>
744                   An executable binary, e.g., <command>wine</command>
745                   or <command>ls</command>.
746                 </para>
747               </listitem>
748             </varlistentry>
749             <varlistentry>
750               <term><sgmltag class="starttag">envar</sgmltag></term>
751               <listitem>
752                 <para>
753                   An environment variable, e.g, <envar>$PATH</envar>.
754                 </para>
755               </listitem>
756             </varlistentry>
757             <varlistentry>
758               <term><sgmltag class="starttag">systemitem</sgmltag></term>
759               <listitem>
760                 <para>
761                   A generic catch-all for system-related things, like
762                   OS names, computer names, system resources, etc.
763                 </para>
764               </listitem>
765             </varlistentry>
766             <varlistentry>
767               <term><sgmltag class="starttag">email</sgmltag></term>
768               <listitem>
769                 <para>
770                   An email address.  The SGML processor will typically
771                   add extra formatting characters, and even a
772                   <literal>mailto:</literal> link for HTML pages.
773                   Usage: <sgmltag
774                   class="starttag">email</sgmltag>user@host.com<sgmltag
775                   class="endtag">email</sgmltag>
776                 </para>
777               </listitem>
778             </varlistentry>
779             <varlistentry>
780               <term><sgmltag class="starttag">firstterm</sgmltag></term>
781               <listitem>
782                 <para>
783                   Special emphasis for introducing a new term.  Can
784                   also be linked to a <sgmltag
785                   class="starttag">glossary</sgmltag> entry, if
786                   desired.
787                 </para>
788               </listitem>
789             </varlistentry>
790           </variablelist>
791
792           <variablelist>
793             <title>Item Listing Elements</title>
794             <varlistentry>
795               <term><sgmltag class="starttag">itemizedlist</sgmltag></term>
796               <listitem>
797                 <para>
798                   For bulleted lists, no numbering.  You can tweak the
799                   layout with SGML attributes.
800                 </para>
801               </listitem>
802             </varlistentry>
803             <varlistentry>
804               <term><sgmltag class="starttag">orderedlist</sgmltag></term>
805               <listitem>
806                 <para>
807                   A numbered list; the SGML processor will insert the
808                   numbers for you.  You can suggest numbering styles
809                   with the <sgmltag
810                   class="attribute">numeration</sgmltag> attribute.
811                 </para>
812               </listitem>
813             </varlistentry>
814             <varlistentry>
815               <term><sgmltag class="starttag">simplelist</sgmltag></term>
816               <listitem>
817                 <para>
818                   A very simple list of items, often inlined.  Control
819                   the layout with the <sgmltag
820                   class="attribute">type</sgmltag> attribute.
821                 </para>
822               </listitem>
823             </varlistentry>
824             <varlistentry>
825               <term><sgmltag class="starttag">variablelist</sgmltag></term>
826               <listitem>
827                 <para>
828                   A list of terms with definitions or descriptions,
829                   like this very list!
830                 </para>
831               </listitem>
832             </varlistentry>
833           </variablelist>
834
835           <variablelist>
836             <title>Block Text Quoting Elements</title>
837             <varlistentry>
838               <term><sgmltag class="starttag">programlisting</sgmltag></term>
839               <listitem>
840                 <para>
841                   Quote a block of source code.  Typically highlighted
842                   in the output and set off from normal text.
843                 </para>
844               </listitem>
845             </varlistentry>
846             <varlistentry>
847               <term><sgmltag class="starttag">screen</sgmltag></term>
848               <listitem>
849                 <para>
850                   Quote a block of visible computer output, like the
851                   output of a command or chunks of debug logs.
852                 </para>
853               </listitem>
854             </varlistentry>
855           </variablelist>
856
857           <variablelist>
858             <title>Hyperlink Elements</title>
859             <varlistentry>
860               <term><sgmltag class="starttag">link</sgmltag></term>
861               <listitem>
862                 <para>
863                   Generic hypertext link, used for pointing to other
864                   sections within the current document.  You supply
865                   the visible text for the link, plus the name of the <sgmltag
866                   class="attribute">id</sgmltag> attribute of the
867                   element that you want to link to.  For example:
868 <programlisting>&lt;link linkend="configuring-wine">the section on configuring wine&lt;/link>
869 ...
870 &lt;sect2 id="configuring-wine">
871 ...</programlisting>
872                 </para>
873               </listitem>
874             </varlistentry>
875             <varlistentry>
876               <term><sgmltag class="starttag">xref</sgmltag></term>
877               <listitem>
878                 <para>
879                   In-document hyperlink that can generate its own
880                   text.  Similar to the <sgmltag
881                   class="starttag">link</sgmltag> tag, you use the
882                   <sgmltag class="attribute">linkend</sgmltag>
883                   attribute to specify which target element you want
884                   to jump to:
885                 </para>
886                 <para>
887 <programlisting>&lt;xref linkend="configuring-wine">
888 ...
889 &lt;sect2 id="configuring-wine">
890 ...</programlisting>
891                 </para>
892                 <para>
893                   By default, most SGML processors will autogenerate
894                   some generic text for the <sgmltag
895                   class="starttag">xref</sgmltag> link, like
896                   <quote>Section 2.3.1</quote>.  You can use the
897                   <sgmltag class="attribute">endterm</sgmltag>
898                   attribute to grab the visible text content of the
899                   hyperlink from another element:
900                 </para>
901                 <para>
902 <programlisting>&lt;xref linkend="configuring-wine" endterm="config-title">
903 ...
904 &lt;sect2 id="configuring-wine">
905   &lt;title id="config-title">Configuring Wine&lt;/title>
906 ...</programlisting>
907                 </para>
908                 <para>
909                   This would create a link to the
910                   <symbol>configuring-wine</symbol> element,
911                   displaying the text of the
912                   <symbol>config-title</symbol> element for the
913                   hyperlink.  Most often, you'll add an <sgmltag
914                   class="attribute">id</sgmltag> attribute to the
915                   <sgmltag class="starttag">title</sgmltag> of the
916                   section you're linking to, as above, in which case
917                   the SGML processor will use the target's title text
918                   for the link text.
919                 </para>
920                 <para>
921                   Alternatively, you can use an <sgmltag
922                   class="attribute">xreflabel</sgmltag> attribute in
923                   the target element tag to specify the link text:
924                 </para>
925 <programlisting>&lt;sect1 id="configuring-wine" xreflabel="Configuring Wine"></programlisting>
926                 <note>
927                   <para>
928                     <sgmltag class="starttag">xref</sgmltag> is an
929                     empty element.  You don't need a closing tag for
930                     it (this is defined in the DTD).  In SGML
931                     documents, you should use the form <sgmltag
932                     class="starttag">xref</sgmltag>, while in XML
933                     documents you should use
934                     <sgmltag>&lt;xref/></sgmltag>.
935                   </para>
936                 </note>
937               </listitem>
938             </varlistentry>
939             <varlistentry>
940               <term><sgmltag class="starttag">anchor</sgmltag></term>
941               <listitem>
942                 <para>
943                   An invisible tag, used for inserting <sgmltag
944                   class="attribute">id</sgmltag> attributes into a
945                   document to link to arbitrary places (i.e., when
946                   it's not close enough to link to the top of an
947                   element).
948                 </para>
949               </listitem>
950             </varlistentry>
951             <varlistentry>
952               <term><sgmltag class="starttag">ulink</sgmltag></term>
953               <listitem>
954                 <para>
955                   Hyperlink in URL form, e.g., <ulink
956                   url="http://www.winehq.com">http://www.winehq.com</ulink>.
957                 </para>
958               </listitem>
959             </varlistentry>
960             <varlistentry>
961               <term><sgmltag class="starttag">olink</sgmltag></term>
962               <listitem>
963                 <para>
964                   Indirect hyperlink; can be used for linking to
965                   external documents.  Not often used in practice.
966                 </para>
967               </listitem>
968             </varlistentry>
969           </variablelist>
970         </sect3>
971
972         <sect3>
973           <title>Multiple SGML files</title>
974           <para>
975             How to split an SGML document into multiple files...
976           </para>
977         </sect3>
978       </sect2>
979
980       <sect2 id="sgml-environment">
981         <title>The SGML Environment</title>
982
983         <para>
984           You can write SGML/DocBook documents in any text editor you
985           might find (although as we'll find in <xref
986           linkend="emacs-psgml">, some editors are more friendly for
987           this task than others).  However, if you want to convert
988           those documents into a more friendly form for reading, such
989           as HTML, PostScript, or PDF, you will need a working SGML
990           environment.  This section attempts to lay out the various
991           SGML rendering systems, and how they are set up on the
992           popular Linux distributions.
993         </para>
994
995         <sect3>
996           <title>DSSSL Environment</title>
997           <para>
998             Explain tools and methodologies..
999           </para>
1000         </sect3>
1001
1002         <sect3>
1003           <title>XSLT Environment</title>
1004           <para>
1005             Explain tools and methodologies...
1006           </para>
1007         </sect3>
1008
1009         <sect3>
1010           <title>SGML on Redhat</title>
1011           <para>
1012             Most Linux distributions have everything you need already
1013             bundled up in package form.  Unfortunately, each
1014             distribution seems to handle its SGML environment
1015             differently, installing it into different paths, and
1016             naming its packages according to its own whims.
1017           </para>
1018           <para>
1019             The following packages seems to be sufficient for RedHat 7.1.  You
1020             will want to be careful about the order in which you install the
1021             rpms.
1022             <itemizedlist>
1023               <listitem><para>sgml-common-*.rpm</para></listitem>
1024               <listitem><para>openjade-*.rpm</para></listitem>
1025               <listitem><para>perl-SGMLSpm-*.rpm</para></listitem>
1026               <listitem><para>docbook-dtd*.rpm</para></listitem>
1027               <listitem><para>docbook-style-dsssl-*.rpm</para></listitem>
1028               <listitem><para>tetex-*.rpm</para></listitem>
1029               <listitem><para>jadetex-*.rpm</para></listitem>
1030               <listitem><para>docbook-utils-*.rpm</para></listitem>
1031             </itemizedlist>
1032             You can also use ghostscript to view the ps format output and 
1033             Adobe Acrobat 4 to view the pdf file.
1034           </para>
1035         </sect3>
1036
1037         <sect3>
1038           <title>SGML on Debian</title>
1039           <para>
1040             List package names and install locations...
1041           </para>
1042         </sect3>
1043
1044         <sect3>
1045           <title>SGML on Other Distributions</title>
1046           <para>
1047             List package names and install locations...
1048           </para>
1049         </sect3>
1050       </sect2>
1051
1052       <sect2 id="emacs-psgml">
1053         <title>PSGML Mode in Emacs</title>
1054         <para>
1055           Although you can write SGML documentation in any simple text
1056           editor, some editors provide extra support for entering SGML
1057           tags, and for verifying that the SGML you create is valid.
1058           SGML has been around for a long time, and many commercial
1059           editors exist for it; however, until recently open source
1060           SGML editors have been scarce.
1061         </para>
1062         <note>
1063           <title>FIXME</title>
1064           <para>
1065             List the available commercial and open source SGML
1066             editors.
1067           </para>
1068         </note>
1069         <para>
1070           The most commonly used open source SGML editor is Emacs,
1071           with the PSGML <firstterm>mode</firstterm>, or extension.
1072           Emacs does not supply a GUI or WYSIWYG (What You See Is What
1073           You Get) interface, but it does provide many helpful
1074           shortcuts for creating SGML, as well as automatic
1075           formatting, validity checking, and the ability to create
1076           your own macros to simplify complex, repetitive actions.
1077           We'll touch briefly on each of these points.
1078         </para>
1079         <para>
1080           The first thing you need is a working installation of Emacs
1081           (or XEmacs), with the PSGML package.  Most Linux
1082           distributions provide both as easy-to-install packages.
1083         </para>
1084         <para>
1085           Next, you'll need a working SGML environment.  See <xref
1086           linkend="sgml-environment"> for more info on setting that
1087           up.
1088         </para>
1089       </sect2>
1090
1091       <sect2 id="docbook-build">
1092         <title>The DocBook Build System</title>
1093
1094         <sect3 id="docbook-infrastructure">
1095           <title>Basic Infrastructure</title>
1096           <para>
1097             How the build/make system works (makefiles, db2html,
1098             db2html-winehq, jade, stylesheets).
1099           </para>
1100         </sect3>
1101
1102         <sect3 id="docbook-tweaking">
1103           <title>Tweaking the DSSSL stylesheets</title>
1104           <para>
1105             Things you can tweak, and how to do it (examples from
1106             default.dsl and winehq.dsl).
1107           </para>
1108         </sect3>
1109
1110         <sect3 id="docbook-generating">
1111           <title>Generating docs for Wine web sites</title>
1112           <para>
1113             Explain make_winehq, rsync, etc.
1114           </para>
1115         </sect3>
1116       </sect2>
1117     </sect1>
1118   </chapter>
1119
1120 <!-- Keep this comment at the end of the file
1121 Local variables:
1122 mode: sgml
1123 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
1124 End:
1125 -->