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