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