1 <chapter id=
"documentation">
2 <title>Documenting Wine
</title>
5 Written by &name-jon-griffiths;
<email>&email-jon-griffiths;
</email>
9 This chapter describes how you can help improve Wines documentation.
13 Like most large scale volunteer projects, Wine is strongest in areas that are rewarding
14 for its volunteers to work in. The majority of contributors send code patches either
15 fixing bugs, adding new functionalty or otherwise improving the software components of
16 the distribution. A lesser number contribute in other ways, such as reporting bugs and
17 regressions, creating tests, providing organisational assistance, or helping to document
22 Documentation is important for many reasons, and is often the key to the end user having
23 a successful experience in installing, setting up and using software. Because Wine is a
24 complicated, evolving entity, providing quality up to date documentation is vital to
25 encourage more people to persevere with using and contributing to the project.
26 The following sections describe in detail how to go about adding to or updating Wines
27 existing documentation.
30 <sect1 id=
"doc-overview">
31 <title>An Overview Of Wine Documentation
</title>
34 The Wine source code tree comes with a large amount of documentation in the
35 <filename>documentation/
</filename> subdirectory. This used to be a collection
36 of text files culled from various places such as the Wine Weekly News and the wine-devel
37 mailing list, but was reorganised some time ago into a number of books, each of which is
38 marked up using SGML. You are reading one of these books (the
39 <emphasis>Wine Developer's Guide
</emphasis>) right now.
43 Since being reorganised, the books have been updated and extended regularly. In their
44 current state they provide a good framework which over time can be expanded and kept
45 up to date. This means that most of the time when further documentation is added, it is
46 a simple matter of updating the content of an already existing file. The books
47 available at the time of writing are:
52 The
<emphasis>Wine User Guide
</emphasis>. This book contains information for end users
53 on installing, configuring and running Wine.
57 The
<emphasis>Wine Developer's Guide
</emphasis>. This book contains information and
58 guidelines for developers and contributors to the Wine project.
62 The
<emphasis>Winelib User's Guide
</emphasis>. This book contains information for
63 developers using Winelib to port Win32 applications to Unix.
67 The
<emphasis>Wine Packagers Guide
</emphasis>. This book contains information for
68 anyone who will be distributing Wine to end users in a prepackaged format.
72 The
<emphasis>Wine FAQ
</emphasis>. This book contains frequently asked questions
73 about Wine with their answers.
79 Another source of documentation is the
<emphasis>Wine API Guide
</emphasis>. This is
80 generated information taken from special comments placed in the Wine source code.
81 When you update or add new API calls to Wine you should consider documenting them so
82 that developers can determine what the API does and how it should be used.
86 The next sections describe how to create Wine API documentation and how to work with
87 SGML so you can add to the existing books.
92 <title>Writing Wine API Documentation
</title>
95 Written by &name-jon-griffiths;
<email>&email-jon-griffiths;
</email>
98 <sect2 id=
"api-docs-intro">
99 <title>Introduction to API Documentation
</title>
101 Wine includes a large amount of documentation on the API functions
102 it implements. There are serveral reasons to want to document the Win32
107 To allow Wine developers to know what each function should do, should
108 they need to update or fix it.
112 To allow Winelib users to understand the functions that are available
113 to their applications.
117 To provide an alternative source of free documentation on the Win32 API.
121 To provide more accurate documentation where the existing documentation
122 is accendentally or deliberately vague or misleading.
129 To this end, a semi formalised way of producing documentation from the Wine
130 source code has evolved. Since the primary users of API documentation are Wine
131 developers themselves, documentation is usually inserted into the source code
132 in the form of comments and notes. Good things to include in the documentation
133 of a function include:
137 The purpose of the function.
141 The parameters of the function and their purpose.
145 The return value of the function, in success as well as failure cases.
149 Additional notes such as interaction with other parts of the system, differences
150 between Wines implementation and Win32s, errors in MSDN documentation,
151 undocumented cases and bugs that Wine corrects or is compatible with.
158 Good documentation helps developers be aware of the effects of making changes. It
159 also allows good tests to be written which cover all of the documented cases.
163 Note that you do not need to be a programmer to update the documentation in Wine.
164 If you would like to contribute to the project, patches that improve the API
165 documentation are welcome. The following describes how to format any documentation
166 that you write so that the Wine documentation generator can extract it and make it
167 available to other developers and users.
171 In general, if you did not write the function in question, you should be wary of
172 adding comments to other peoples code. It is quite possible you may misunderstand
173 or misrepresent what the original author intended! Adding API documentation on
174 the other hand can be done by anybody, since in most cases there is plenty of
175 information about what a function is supposed to do (if it isn't obvious)
176 available in books and articles on the internet.
180 A final warning concerns copyright and must be noted. If you read MSDN or any
181 publication in order to find out what an API call does, you must be aware that
182 the text you are reading is copyrighted and in most cases cannot legally be
183 reproduced without the authors permission. If you copy verbatim any information
184 from such sources and submit it for inclusion into Wine, you open yourself up
185 to potential legal liability. You must ensure that anything you submit is
186 your own work, although it can be based on your understanding gleaned from
187 reading other peoples work.
191 <sect2 id=
"api-docs-basics">
192 <title>Basic API Documentation
</title>
195 The general form of an API comment in Wine is a block comment immediately before a
196 function is implemented in the source code. General comments within a function body or
197 at the top of an implementation file are ignored by the API documentation generator.
198 Such comments are for the benefit of developers only, for example to explain what the
199 source code is doing or to describe something that may not be obvious to the person
200 reading the source code.
204 The following text uses the function
<emphasis>PathRelativePathToA()
</emphasis> from
205 <filename>SHLWAPI.DLL
</filename> as an example. You can find this function in the Wine
206 source code tree in the file
<filename>dlls/shlwapi/path.c
</filename>.
210 The first line of the comment gives the name of the function, the DLL that the
211 function is exported from, and its export ordinal number. This is the simplest
212 (and most common type of) comment:
216 /*************************************************************************
217 * PathRelativePathToA [SHLWAPI.@]
222 The functions name and the DLL name are obvious. The ordinal number takes one of
223 two forms: Either
<command>@
</command> as in the above, or a number if the export
224 is exported by ordinal. You can see which to use by looking at the DLL's
225 <filename>.spec
</filename> file. If the line on which the function is listed begins
226 with a number, use it, otherwise use the
<command>@
</command> symbol, which indicates
227 that this function is imported only by name.
231 Note also that round or square brackets can be used, and whitespace between the name
232 and the DLL/ordinal is free form. Thus the following is equally valid:
236 /*************************************************************************
237 * PathRelativePathToA (SHLWAPI.@)
242 This basic comment will not get processed into documentation, since it
243 contains no information. In order to produce documentation for the function,
244 We must add some of the information listed above.
248 First we add a description of the function. This can be as long as you like, but
249 typically contains only a brief description of what the function is meant to do
250 in general terms. It is free form text:
254 /*************************************************************************
255 * PathRelativePathToA [SHLWAPI.@]
257 * Create a relative path from one path to another.
262 To be truly useful however we must document the parameters to the function.
263 There are two methods for doing this: In the comment, or in the function
268 Parameters documented in the comment should be formatted as follows:
272 /*************************************************************************
273 * PathRelativePathToA [SHLWAPI.@]
275 * Create a relative path from one path to another.
278 * lpszPath [O] Destination for relative path
279 * lpszFrom [I] Source path
280 * dwAttrFrom [I] File attribute of source path
281 * lpszTo [I] Destination path
282 * dwAttrTo [I] File attributes of destination path
288 The parameters section starts with
<command>PARAMS
</command> on its own line.
289 Each parameter is listed in the order they appear in the functions prototype,
290 first with the parameters name, followed by its input/output status, followed
291 by a free form text description of the comment.
295 The input/output status tells the programmer whether the value will be modified
296 by the function (an output parameter), or only read (an input parameter). The
297 status must be enclosed in square brackets to be recognised, otherwise, or if it
298 is absent, anything following the parameter name is treated as the parameter
299 description. This field is case insensitive and can be any of the following:
300 <command>[I]
</command>,
<command>[In]
</command>,
<command>[O]
</command>,
301 <command>[Out]
</command>,
<command>[I/O]
</command>,
<command>[In/Out]
</command>.
305 Parameters documented in the prototype should be formatted as follows:
309 /*************************************************************************
310 * PathRelativePathToA [SHLWAPI.@]
312 * Create a relative path from one path to another.
315 BOOL WINAPI PathRelativePathToA(
316 LPSTR lpszPath, /* [O] Destination for relative path */
317 LPCSTR lpszFrom, /* [I] Source path */
318 DWORD dwAttrFrom, /* [I] File attribute of source path */
319 LPCSTR lpszTo, /* [I] Destination path */
320 DWORD dwAttrTo) /* [I] File attributes of destination path */
324 The choice of which style to use is up to you, although for readability it
325 is suggested you stick with the same style within a single source file.
329 Following the description and parameters come a number of optional sections, all
330 in the same format. A section is defined as the section name, which is an all upper
331 case section name on its own line, followed by free form text. You can create any
332 sections you like, however for consistency it is recommended you use the following
337 <command>NOTES
</command>. Anything that needs to be noted about the function
338 such as special cases and the effects of input arguments.
342 <command>BUGS
</command>. Any bugs in the function that exist 'by design', i.e.
343 those that will not be fixed or exist for compatibility with Windows.
347 <command>TODO
</command>. Any unhandled cases or missing functionality in the Wine
348 implementation of the function.
352 <command>FIXME
</command>. Things that should be updated or addressed in the implementation
353 of the function at some future date (perhaps dependent on other parts of Wine). Note
354 that if this information is only relevant to Wine developers then it should probably
355 be placed in the relavent code section instead.
361 Following or before the optional sections comes the
<command>RETURNS
</command> section
362 which describes the return value of the function. This is free form text but should include
363 what is returned on success as well as possible error return codes. Note that this
364 section must be present for documentation to be generated for your comment.
368 Our final documentation looks like the following:
372 /*************************************************************************
373 * PathRelativePathToA [SHLWAPI.@]
375 * Create a relative path from one path to another.
378 * lpszPath [O] Destination for relative path
379 * lpszFrom [I] Source path
380 * dwAttrFrom [I] File attribute of source path
381 * lpszTo [I] Destination path
382 * dwAttrTo [I] File attributes of destination path
385 * TRUE If a relative path can be formed. lpszPath contains the new path
386 * FALSE If the paths are not relative or any parameters are invalid
389 * lpszTo should be at least MAX_PATH in length.
390 * Calling this function with relative paths for lpszFrom or lpszTo may
391 * give erroneous results.
393 * The Win32 version of this function contains a bug where the lpszTo string
394 * may be referenced
1 byte beyond the end of the string. As a result random
395 * garbage may be written to the output path, depending on what lies beyond
396 * the last byte of the string. This bug occurs because of the behaviour of
397 * PathCommonPrefix() (see notes for that function), and no workaround seems
398 * possible with Win32.
399 * This bug has been fixed here, so for example the relative path from
"\\"
400 * to
"\\" is correctly determined as
"." in this implementation.
405 <sect2 id=
"api-docs-advanced">
406 <title>Advanced API Documentation
</title>
409 There is no markup language for formatting API comments, since they should
410 be easily readable by any developer working on the source file. A number of
411 constructs are treated specially however, and are noted here. You can use these
412 constructs to enhance the usefulness of the generated documentation by making it
413 easier to read and referencing related documents.
417 Any valid c identifier that ends with
<command>()
</command> is taken to
418 be an API function and is formatted accordingly. When generating documentation,
419 this text will become a link to that API call, if the output type supports
420 hyperlinks or their equivalent.
424 Similarly, any interface name starting with a capital I and followed by the
425 words
"reference" or
"object" become a link to that objects documentation.
429 Where an Ascii and Unicode version of a function are available, it is
430 recommended that you document only the Ascii version and have the Unicode
431 version refer to the Ascii one, as follows:
434 /*************************************************************************
435 * PathRelativePathToW [SHLWAPI.@]
437 * See PathRelativePathToA.
441 Alternately you may use the following form:
444 /*************************************************************************
445 * PathRelativePathToW [SHLWAPI.@]
447 * Unicode version of PathRelativePathToA.
452 You may also use this construct in any other section, such as
<command>NOTES
</command>.
456 Any numbers and text in quotes (
<command>""</command>) are highlighted.
460 Words in all uppercase are assumed to be API constants and are highlighted. If
461 you want to emphasise something in the documentation, put it in a section by itself
462 rather than making it upper case.
466 Blank lines in a section cause a new paragraph to be started. Blank lines
467 at the start and end of sections are ignored.
471 Any comment line starting with (
<command>"*|"</command>) is treated as raw text and
472 is not pre-processed before being output. This should be used for code listings,
473 tables and any text that should remain unformatted.
477 Any line starting with a single word followed by a colon (
<command>:
</command>)
478 is assumed to be case listing and is emphasised and put in its own paragrah. This
479 is most often used for return values, as in the example section below.
483 * Success: TRUE. Something happens that is documented here.
484 * Failure: FALSE. The reasons why this call can fail are listed here.
488 Any line starting with a (
<command>-
</command>) is put into a paragraph by itself.
489 this allows lists to avoid being run together.
493 If you are in doubt as to how your comment will look, try generating the API
494 documentation and checking the output.
498 <sect2 id=
"api-docs-extra">
499 <title>Extra API Documentation
</title>
502 Simply documenting the API calls available provides a great deal of information to
503 developers working with the Win32 API. However additional documentation is needed
504 before the API Guide can be considered truly useful or comprehensive. For example,
505 COM objects that are available for developers use should be documented, along with
506 the interface(s) that those objects export. Also, it would be helpful to document
507 each dll, to provide some structure to the documentation.
511 To facilitate providing extra documentation, you can create comments that provide
512 extra documentation on functions, or on keywords such as the name of a COM interface
513 or a type definition.
517 These items are generated using the same formatting rules as described earlier. The
518 only difference is the first line of the comment, which indicates to the generator
519 that the documentation is supplimental and does not describe an export from the dll
524 Lets assume you have implemented a COM interface that you want to document; we'll
525 use the name
<command>IExample
</command> as an example here. Your comment would
526 look like the following (assuming you are exporting this object from
527 <filename>EXAMPLE.DLL
</filename>):
529 /*************************************************************************
532 * The IExample object provides lots of interesting functionality.
539 Format this documentation exactly as you would a standard export. The only
540 difference is the use of curly brackets to mark this documentation as supplimental.
541 The generator will output this documentation using the name given before the
542 DLL name, and will link to it from the main DLL page. In addition, if you have
543 referred to the comment name in other documentation using
"IExample interface",
544 "IExample object", or
"IExample()", those references will point to this documentation.
548 If you document you COM interfaces this way then all following extra comments that
549 follow in the same source file that begin with the same document title will be added
550 as references to this comment before it is output. For an example of this see
551 <filename>dlls/oleaut32/safearray.c
</filename>. This uses an extra comment to document
552 The SafeArray functions and link them together under one heading.
556 As a special case, if you use the DLL name as the comment name, the comment will
557 be treated as documentation on the DLL itself. When the documentation for the DLL
558 is processed, the contents of the comment will be placed before the generated
559 statistics, exports and other information that makes up a DLL's documentation page.
563 <sect2 id=
"api-docs-generating">
564 <title>Generating API Documentation
</title>
567 Having edited or added new API documentation to a source code file, you
568 should generate the documentation to ensure that the result is what you
569 expected. Wine includes a tool (slightly misleadingly) called
570 <command>c2man.pl
</command> in the
<filename>tools/
</filename> directory
571 which is used to generate the documentation from the source code.
575 You can run
<command>c2man.pl
</command> manually for testing purposes; it is
576 a fairly simple perl script which parses
<filename>.c
</filename> files
577 to create output in several formats. If you wish to try this you may want
578 to run it with no arguments, which will cause it to print usage information.
582 An easier way is to use Wines build system. To create man pages for a given
583 dll, just type
<command>make man
</command> from within the dlls directory
584 or type
<command>make manpages
</command> in the root directory of the Wine
585 source tree. You can then check that a man page was generated for your function,
586 it should be present in the
<filename>documentation/man3w
</filename> directory
587 with the same name as the function.
591 Once you have generated the man pages from the source code, running
592 <command>make install
</command> will install them for you. By default they are
593 installed in section
3w of the manual, so they don't conflict with any existing
594 man page names. So, to read the man page you should use
595 <command>man -S
3w {name}
</command>. Alternately you can edit
596 <filename>/etc/man.config
</filename> and add
3w to the list of search paths
597 given in the variable
<emphasis>MANSECT
</emphasis>.
601 You can also generate HTML output for the API documentation, in this case the
602 make command is
<command>make doc-html
</command> in the dll directory,
603 or
<command>make htmlpages
</command> from the root. The output will be
604 placed by default under
<filename>documentation/html
</filename>. Similarly
605 you can create SGML source code to produce the
<emphasis>Wine Api Guide
</emphasis>
606 with the command
<command>make sgmlpages
</command>.
611 <sect1 id=
"wine-docbook">
612 <title>The Wine DocBook System
</title>
615 Written by &name-john-sheets;
<email>&email-john-sheets;
</email>
618 Modified by &name-tony-lambregts;
<email>&email-tony-lambregts;
</email> Nov.
2002
621 <sect2 id=
"writing-docbook">
622 <title>Writing Documentation with DocBook
</title>
625 DocBook is a flavour of
<acronym>SGML
</acronym>
626 (
<firstterm>Standard Generalized Markup
627 Language
</firstterm>), a syntax for marking up the contents
628 of documents. HTML is another very common flavour of SGML;
629 DocBook markup looks very similar to HTML markup, although
630 the names of the markup tags differ.
633 <title>Getting Started
</title>
635 <title>Why SGML?
</title>
637 The simple answer to that is that SGML allows you
638 to create multiple formats of a given document from a single
639 source. Currently it is used to create HTML, PDF and PS
640 (PostScript) versions of the Wine books.
645 <title>What do I need?
</title>
647 You need the SGML tools. There are various places where you
648 can get them. The most generic way of getting them is from their
649 source as discussed below.
654 <title>Quick instructions
</title>
656 These are the basic steps to create the Wine books from the SGML source.
663 Go to
<ulink url=
"http://www.sgmltools.org">http://www.sgmltools.org
</ulink>
667 Download all of the sgmltools packages
671 Install them all and build them (
<command>./configure; make; make install
</command>)
675 Switch to your toplevel Wine directory
679 Run
<command>./configure
</command> (or
<command>make distclean && ./configure
</command>)
683 Switch to the
<filename>documentation/
</filename> directory
687 run
<command>./make_winehq
</command>
691 View
<filename>wine-doc/index.html
</filename> in your favorite browser
699 <title>Getting SGML for various distributions
</title>
701 Most Linux distributions have everything you need already
702 bundled up in package form. Unfortunately, each
703 distribution seems to handle its SGML environment
704 differently, installing it into different paths, and
705 naming its packages according to its own whims.
709 <title>SGML on Red Hat
</title>
711 The following packages seem to be sufficient for Red Hat
7.1. You
712 will want to be careful about the order in which you install the
715 <listitem><para>sgml-common-*.rpm
</para></listitem>
716 <listitem><para>openjade-*.rpm
</para></listitem>
717 <listitem><para>perl-SGMLSpm-*.rpm
</para></listitem>
718 <listitem><para>docbook-dtd*.rpm
</para></listitem>
719 <listitem><para>docbook-style-dsssl-*.rpm
</para></listitem>
720 <listitem><para>tetex-*.rpm
</para></listitem>
721 <listitem><para>jadetex-*.rpm
</para></listitem>
722 <listitem><para>docbook-utils-*.rpm
</para></listitem>
724 You can also use ghostscript to view the ps format output and
725 Adobe Acrobat
4 to view the pdf file.
730 <title>SGML on Debian
</title>
732 This is not a definitive listing yet, but it seems
733 you might need the following packages:
735 <listitem><para>docbook
</para></listitem>
736 <listitem><para>docbook-dsssl
</para></listitem>
737 <listitem><para>docbook-utils
</para></listitem>
738 <listitem><para>docbook-xml
</para></listitem>
739 <listitem><para>docbook-xsl
</para></listitem>
740 <listitem><para>sgml-base
</para></listitem>
741 <listitem><para>sgml-data
</para></listitem>
742 <listitem><para>tetex-base
</para></listitem>
743 <listitem><para>tetex-bin
</para></listitem>
744 <listitem><para>jade
</para></listitem>
745 <listitem><para>jadetex
</para></listitem>
751 <title>SGML on Other Distributions
</title>
753 <title>Fix me
</title>
755 List package names and install locations...
761 <title>Terminology
</title>
764 SGML markup contains a number of syntactical elements that
765 serve different purposes in the markup. We'll run through
766 the basics here to make sure we're on the same page when
767 we refer to SGML semantics.
770 The basic currency of SGML is the
771 <firstterm>tag
</firstterm>. A simple tag consists of a
772 pair of angle brackets and the name of the tag. For
773 example, the
<sgmltag>para
</sgmltag> tag would appear in
774 an SGML document as
<sgmltag
775 class=
"starttag">para
</sgmltag>. This start tag indicates
776 that the immediately following text should be classified
777 according to the tag. In regular SGML, each opening tag
778 must have a matching end tag to show where the start tag's
779 contents end. End tags begin with
780 <quote><literal></
</literal></quote> markup, e.g.,
781 <sgmltag class=
"endtag">para
</sgmltag>.
784 The combination of a start tag, contents, and an end tag
785 is called an
<firstterm>element
</firstterm>. SGML
786 elements can be nested inside of each other, or contain
787 only text, or may be a combination of both text and other
788 elements, although in most cases it is better to limit
789 your elements to one or the other.
792 The
<acronym>XML
</acronym> (
<firstterm>eXtensible Markup
793 Language
</firstterm>) specification, a modern subset of
794 the SGML specification, adds a so-called
<firstterm>empty
795 tag
</firstterm>, for elements that contain no text
796 content. The entire element is a single tag, ending with
797 <quote><literal>/
></literal></quote>, e.g.,
798 <sgmltag><xref/
></sgmltag>. However, use of this
799 tag style restricts you to XML DocBook processing, and
800 your document may no longer compile with SGML-only
803 <!-- *** Note: We could normally use the "emptytag"
804 attribute for XML empty tags, but that's only a recent
805 addition, and we don't want to screw up documents
806 generated against older stylesheets.
809 Often a processing system will need more information about
810 an element than you can provide with just tags. SGML
811 allows you to add extra
<quote>hints
</quote> in the form
812 of SGML
<firstterm>attributes
</firstterm> to pass along
813 this information. The most common use of attributes in
814 DocBook is giving specific elements a name, or an ID, so
815 you can refer to it from elsewhere. This ID can be used
816 for many things, including file-naming for HTML output,
817 hyper-linking to specific parts of the document, and even
818 pulling text from that element (see the
<sgmltag
819 class=
"starttag">xref
</sgmltag> tag).
822 An SGML attribute appears inside the start tag, between
823 the
< and
> brackets. For example, if you wanted to
824 set the
<sgmltag class=
"attribute">id
</sgmltag> attribute
825 of the
<sgmltag class=
"starttag">book
</sgmltag> element to
826 <quote>mybook
</quote>, you would create a start tag like
827 this:
<programlisting><book
id=
"mybook"></programlisting>
830 Notice that the contents of the attribute are enclosed in
831 quote marks. These quotes are optional in SGML, but
832 mandatory in XML. It's a good habit to use quotes, as it
833 will make it much easier to migrate your documents to an
834 XML processing system later on.
837 You can also specify more than one attribute in a single
838 tag:
<programlisting><book
id=
"mybook" status=
"draft"></programlisting>
841 Another commonly used type of SGML markup is the
842 <firstterm>entity
</firstterm>. An entity lets you
843 associate a block of text with a name. You declare the
844 entity once, at the beginning of your document, and can
845 invoke it as many times as you like throughout the
846 document. You can use entities as shorthand, or to make
847 it easier to maintain certain phrases in a central
848 location, or even to insert the contents of an entire file
852 An entity in your document is always surrounded by the
853 <quote>&</quote> and
<quote>;
</quote> characters. One
854 entity you'll need sooner or later is the one for the
855 <quote><</quote> character. Since SGML expects all
856 tags to begin with a
<quote><</quote>, the
857 <quote><</quote> is a reserved character. To use it in
858 your document (as I am doing here), you must insert it
859 with the
<literal>&lt;
</literal> entity. Each time
860 the SGML processor encounters
<literal>&lt;
</literal>,
861 it will place a literal
<quote><</quote> in the output
862 document. Similarly you must use the
<literal>&gt;
</literal>
863 and
<literal>&amp;
</literal> entities for the
864 <quote>></quote> and
<quote>&</quote> characters.
867 The final term you'll need to know when writing simple
868 DocBook documents is the
<acronym>DTD
</acronym>
869 (
<firstterm>Document Type Declaration
</firstterm>). The
870 DTD defines the flavour of SGML a given document is written
871 in. It lists all the legal tag names, like
<sgmltag
872 class=
"starttag">book
</sgmltag>,
<sgmltag
873 class=
"starttag">para
</sgmltag>, and so on, and declares
874 how those tags are allowed to be used together. For
875 example, it doesn't make sense to put a
<sgmltag
876 class=
"starttag">book
</sgmltag> element inside a
<sgmltag
877 class=
"starttag">para
</sgmltag> paragraph element -- only
881 The DTD thus defines the legal structure of the document.
882 It also declares which attributes can be used with which
883 tags. The SGML processing system can use the DTD to make
884 sure the document is laid out properly before attempting
885 to process it. SGML-aware text editors like
<link
886 linkend=
"emacs-psgml">Emacs
</link> can also use the DTD to
887 guide you while you write, offering you choices about
888 which tags you can add in different places in the
889 document, and beeping at you when you try to add a tag
890 where it doesn't belong.
893 Generally, you will declare which DTD you want to use as
894 the first line of your SGML document. In the case of
895 DocBook, you will use something like this:
896 <programlisting><!doctype book PUBLIC
"-//OASIS//DTD
897 DocBook V3.1//EN" []
> <book
> ...
898 </book
></programlisting>
901 Note that you must specify your toplevel element inside
902 the doctype declaration. If you were writing an article
903 rather than a book, you might use this declaration instead:
904 <programlisting><!doctype article PUBLIC
"-//OASIS//DTD DocBook V3.1//EN" []
>
907 </article
></programlisting>
911 <sect3 id=
"sgml-document">
912 <title>The Document
</title>
914 Once you're comfortable with SGML, creating a DocBook
915 document is quite simple and straightforward. Even
916 though DocBook contains over
300 different tags, you can
917 usually get by with only a small subset of those tags.
918 Most of them are for inline formatting, rather than for
919 document structuring. Furthermore, the common tags have
920 short, intuitive names.
923 Below is a (completely nonsensical) example to illustrate
924 how a simple document might be laid out. Notice that all
925 <sgmltag class=
"starttag">chapter
</sgmltag> and
<sgmltag
926 class=
"starttag">sect1
</sgmltag> elements have
<sgmltag
927 class=
"attribute">id
</sgmltag> attributes. This is not
928 mandatory, but is a good habit to get into, as DocBook is
929 commonly converted into HTML, with a separate generated
930 file for each
<sgmltag class=
"starttag">book
</sgmltag>,
931 <sgmltag class=
"starttag">chapter
</sgmltag>, and/or
<sgmltag
932 class=
"starttag">sect1
</sgmltag> element. If the given
933 element has an
<sgmltag class=
"attribute">id
</sgmltag>
934 attribute, the processor will typically name the file
935 accordingly. Thus, the below document might result in
936 <filename>index.html
</filename>,
937 <filename>chapter-one.html
</filename>,
938 <filename>blobs.html
</filename>, and so on.
941 Also notice the text marked off with
<quote><!--
942 </quote> and
<quote> --
></quote> characters. These
943 denote SGML comments. SGML processors will completely
944 ignore anything between these markers, similar to
945 <quote>/*
</quote> and
<quote>*/
</quote> comments in C
949 <!-- Encase the following SGML excerpt inside a CDATA
950 block so we don't have to bother converting all
955 <!doctype book PUBLIC
"-//OASIS//DTD DocBook V3.1//EN" []
>
958 <title>A Poet's Guide to Nonsense
</title>
961 <chapter id=
"chapter-one">
962 <title>Blobs and Gribbles
</title>
964 <!-- This section contains only one major topic -->
966 <title>The Story Behind Blobs
</title>
968 Blobs are often mistaken for ice cubes and rain
973 <!-- This section contains embedded sub-sections -->
974 <sect1 id=
"gribbles">
975 <title>Your Friend the Gribble
</title>
977 A Gribble is a cute, unassuming little fellow...
980 <sect2 id=
"gribble-temperament">
981 <title>Gribble Temperament
</title>
983 When left without food for several days...
987 <sect2 id=
"gribble-appearance">
988 <title>Gribble Appearance
</title>
990 Most Gribbles have a shock of white fur running from...
996 <chapter id=
"chapter-two">
997 <title>Phantasmagoria
</title>
999 <sect1 id=
"dretch-pools">
1000 <title>Dretch Pools
</title>
1003 When most poets think of Dretch Pools, they tend to...
1013 <title>Common Elements
</title>
1015 Once you get used to the syntax of SGML, the next hurdle
1016 in writing DocBook documentation is to learn the many
1017 DocBook-specific tag names, and when to use them. DocBook
1018 was created for technical documentation, and as such, the
1019 tag names and document structure are slanted towards the
1020 needs of such documentation.
1023 To cover its target audience, DocBook declares a wide
1024 variety of specialized tags, including tags for formatting
1025 source code (with somewhat of a C/C++ bias), computer
1026 prompts, GUI application features, keystrokes, and so on.
1027 DocBook also includes tags for universal formatting needs,
1028 like headers, footnotes, tables, and graphics.
1031 We won't cover all of these elements here (over
300
1032 DocBook tags exist!), but we will cover the basics. To
1033 learn more about the other tags, check out the official
1034 DocBook guide, at
<ulink
1035 url=
"http://docbook.org">http://docbook.org
</ulink>. To
1036 see how they are used in practice, download the SGML
1037 source for this manual (the Wine Developer Guide) and
1038 browse through it, comparing it to the generated HTML (or
1042 There are often many correct ways to mark up a given piece
1043 of text, and you may have to make guesses about which tag
1044 to use. Sometimes you'll have to make compromises.
1045 However, remember that it is possible to further
<link
1046 linkend=
"docbook-tweaking">customize the output
</link> of
1047 the SGML processors. If you don't like the way a certain
1048 tag looks in HTML, that doesn't mean you should choose a
1049 different tag based on its output formatting. The
1050 processing stylesheets can be altered to fix the
1051 formatting of that same tag everywhere in the document
1052 (not just in the place you're working on). For example,
1053 if you're frustrated that the
<sgmltag
1054 class=
"starttag">systemitem
</sgmltag> tag doesn't produce
1055 any formatting by default, you should fix the stylesheets,
1056 not change the valid
<sgmltag
1057 class=
"starttag">systemitem
</sgmltag> tag to, for example,
1058 an
<sgmltag class=
"starttag">emphasis
</sgmltag> tag.
1061 Here are the common SGML elements:
1065 <title>Structural Elements
</title>
1067 <term><sgmltag class=
"starttag">book
</sgmltag></term>
1070 The book is the most common toplevel element, and is
1071 probably the one you should use for your document.
1076 <term><sgmltag class=
"starttag">set
</sgmltag></term>
1079 If you want to group more than one book into a
1080 single unit, you can place them all inside a set.
1081 This is useful when you want to bundle up
1082 documentation in alternate ways. We do this with
1083 the Wine documentation, using
1084 <sgmltag class=
"starttag">book
</sgmltag> to
1085 put each Wine guide into a separate directory (see
1086 <filename>documentation/wine-devel.sgml
</filename>,
1092 <term><sgmltag class=
"starttag">chapter
</sgmltag></term>
1095 A
<sgmltag class=
"starttag">chapter
</sgmltag>
1096 element includes a single entire chapter of the
1102 <term><sgmltag class=
"starttag">part
</sgmltag></term>
1105 If the chapters in your book fall into major
1106 categories or groupings (as in the Wine Developer
1107 Guide), you can place each collection of chapters
1108 into a
<sgmltag class=
"starttag">part
</sgmltag>
1114 <term><sgmltag class=
"starttag">sect?
</sgmltag></term>
1117 DocBook has many section elements to divide the
1118 contents of a chapter into smaller chunks. The
1119 encouraged approach is to use the numbered section
1120 tags,
<sgmltag class=
"starttag">sect1
</sgmltag>,
1121 <sgmltag class=
"starttag">sect2
</sgmltag>,
<sgmltag
1122 class=
"starttag">sect3
</sgmltag>,
<sgmltag
1123 class=
"starttag">sect4
</sgmltag>, and
<sgmltag
1124 class=
"starttag">sect5
</sgmltag> (if necessary).
1125 These tags must be nested in order: you can't place
1126 a
<sgmltag class=
"starttag">sect3
</sgmltag> directly
1127 inside a
<sgmltag class=
"starttag">sect1
</sgmltag>.
1128 You have to nest the
<sgmltag
1129 class=
"starttag">sect3
</sgmltag> inside a
<sgmltag
1130 class=
"starttag">sect2
</sgmltag>, and so forth.
1131 Documents with these explicit section groupings are
1132 easier for SGML processors to deal with, and lead to
1133 better organized documents. DocBook also supplies a
1134 <sgmltag class=
"starttag">section
</sgmltag> element
1135 which you can nest inside itself, but its use is
1136 discouraged in favor of the numbered section tags.
1141 <term><sgmltag class=
"starttag">title
</sgmltag></term>
1144 The title of a book, chapter, part, section, etc.
1145 In most of the major structural elements, like
1146 <sgmltag class=
"starttag">chapter
</sgmltag>,
1147 <sgmltag class=
"starttag">part
</sgmltag>, and the
1148 various section tags,
<sgmltag
1149 class=
"starttag">title
</sgmltag> is mandatory. In
1150 other elements like
<sgmltag
1151 class=
"starttag">book
</sgmltag> and
<sgmltag
1152 class=
"starttag">note
</sgmltag>, it's optional.
1157 <term><sgmltag class=
"starttag">para
</sgmltag></term>
1160 The basic unit of text is the paragraph, represented
1161 by the
<sgmltag class=
"starttag">para
</sgmltag> tag.
1162 This is probably the tag you'll use most often. In
1163 fact, in a simple document, you can probably get
1164 away with using only
<sgmltag
1165 class=
"starttag">book
</sgmltag>,
<sgmltag
1166 class=
"starttag">chapter
</sgmltag>,
<sgmltag
1167 class=
"starttag">title
</sgmltag>, and
<sgmltag
1168 class=
"starttag">para
</sgmltag>.
1173 <term><sgmltag class=
"starttag">article
</sgmltag></term>
1176 For shorter, more targeted documents, like topic
1177 pieces and whitepapers, you can use
<sgmltag
1178 class=
"starttag">article
</sgmltag> as your toplevel
1186 <title>Inline Formatting Elements
</title>
1188 <term><sgmltag class=
"starttag">filename
</sgmltag></term>
1191 The name of a file. You can optionally set the
1192 <sgmltag class=
"attribute">class
</sgmltag> attribute
1193 to
<literal>Directory
</literal>,
1194 <literal>HeaderFile
</literal>, and
1195 <literal>SymLink
</literal> to further classify the
1201 <term><sgmltag class=
"starttag">userinput
</sgmltag></term>
1204 Literal text entered by the user.
1209 <term><sgmltag class=
"starttag">computeroutput
</sgmltag></term>
1212 Literal text output by the computer.
1217 <term><sgmltag class=
"starttag">literal
</sgmltag></term>
1220 A catch-all element for literal computer data. Its
1221 use is somewhat vague; try to use a more specific
1222 tag if possible, like
<sgmltag
1223 class=
"starttag">userinput
</sgmltag> or
<sgmltag
1224 class=
"starttag">computeroutput
</sgmltag>.
1229 <term><sgmltag class=
"starttag">quote
</sgmltag></term>
1232 An inline quotation. This tag typically inserts
1233 quotation marks for you, so you would write
<sgmltag
1234 class=
"starttag">quote
</sgmltag>This is a
1235 quote
<sgmltag class=
"endtag">quote
</sgmltag> rather
1236 than
"This is a quote". This usage may be a little
1237 bulkier, but it does allow for automated formatting
1238 of all quoted material in the document. Thus, if
1239 you wanted all quotations to appear in italic, you
1240 could make the change once in your stylesheet,
1241 rather than doing a search and replace throughout
1242 the document. For larger chunks of quoted text, you
1244 class=
"starttag">blockquote
</sgmltag>.
1249 <term><sgmltag class=
"starttag">note
</sgmltag></term>
1252 Insert a side note for the reader. By default, the
1253 SGML processor usually prefixes the content with
1254 "Note:". You can change this text by adding a
1255 <sgmltag class=
"starttag">title
</sgmltag> element.
1256 Thus, to add a visible FIXME comment to the
1257 documentation, you might write:
1262 <title>FIXME
</title>
1263 <para>This section needs more info about...
</para>
1265 ]]
></programlisting>
1267 The results will look something like this:
1270 <title>FIXME
</title>
1271 <para>This section needs more info about...
</para>
1276 <term><sgmltag class=
"starttag">sgmltag
</sgmltag></term>
1279 Used for inserting SGML tags, etc., into a SGML
1280 document without resorting to a lot of entity
1281 quoting, e.g.,
&lt;. You can change the
1282 appearance of the text with the
<sgmltag
1283 class=
"attribute">class
</sgmltag> attribute. Some
1284 common values of this are
1285 <literal>starttag
</literal>,
1286 <literal>endtag
</literal>,
1287 <literal>attribute
</literal>,
1288 <literal>attvalue
</literal>, and even
1289 <literal>sgmlcomment
</literal>. See this SGML file,
1290 <filename>documentation/documentation.sgml
</filename>,
1296 <term><sgmltag class=
"starttag">prompt
</sgmltag></term>
1299 The text used for a computer prompt, for example a
1300 shell prompt, or command-line application prompt.
1305 <term><sgmltag class=
"starttag">replaceable
</sgmltag></term>
1308 Meta-text that should be replaced by the user, not
1309 typed in literally, e.g., in command descriptions
1310 and
<parameter>--help
</parameter> outputs.
1315 <term><sgmltag class=
"starttag">constant
</sgmltag></term>
1318 A programming constant, e.g.,
1319 <constant>MAX_PATH
</constant>.
1324 <term><sgmltag class=
"starttag">symbol
</sgmltag></term>
1327 A symbolic value replaced, for example, by a
1328 pre-processor. This applies primarily to C macros,
1329 but may have other uses. Use the
<sgmltag
1330 class=
"starttag">constant
</sgmltag> tag instead of
1331 <sgmltag class=
"starttag">symbol
</sgmltag> where
1337 <term><sgmltag class=
"starttag">function
</sgmltag></term>
1340 A programming function name.
1345 <term><sgmltag class=
"starttag">parameter
</sgmltag></term>
1348 Programming language parameters you pass with a
1354 <term><sgmltag class=
"starttag">option
</sgmltag></term>
1357 Parameters you pass to a command-line executable.
1362 <term><sgmltag class=
"starttag">varname
</sgmltag></term>
1365 Variable name, typically in a programming language.
1370 <term><sgmltag class=
"starttag">type
</sgmltag></term>
1373 Programming language types, e.g., from a typedef
1374 definition. May have other uses, too.
1379 <term><sgmltag class=
"starttag">structname
</sgmltag></term>
1382 The name of a C-language
<type>struct
</type>
1383 declaration, e.g.,
<structname>sockaddr
</structname>.
1388 <term><sgmltag class=
"starttag">structfield
</sgmltag></term>
1391 A field inside a C
<type>struct
</type>.
1396 <term><sgmltag class=
"starttag">command
</sgmltag></term>
1399 An executable binary, e.g.,
<command>wine
</command>
1400 or
<command>ls
</command>.
1405 <term><sgmltag class=
"starttag">envar
</sgmltag></term>
1408 An environment variable, e.g,
<envar>$PATH
</envar>.
1413 <term><sgmltag class=
"starttag">systemitem
</sgmltag></term>
1416 A generic catch-all for system-related things, like
1417 OS names, computer names, system resources, etc.
1422 <term><sgmltag class=
"starttag">email
</sgmltag></term>
1425 An email address. The SGML processor will typically
1426 add extra formatting characters, and even a
1427 <literal>mailto:
</literal> link for HTML pages.
1429 class=
"starttag">email
</sgmltag>user@host.com
<sgmltag
1430 class=
"endtag">email
</sgmltag>
1435 <term><sgmltag class=
"starttag">firstterm
</sgmltag></term>
1438 Special emphasis for introducing a new term. Can
1439 also be linked to a
<sgmltag
1440 class=
"starttag">glossary
</sgmltag> entry, if
1448 <title>Item Listing Elements
</title>
1450 <term><sgmltag class=
"starttag">itemizedlist
</sgmltag></term>
1453 For bulleted lists, no numbering. You can tweak the
1454 layout with SGML attributes.
1459 <term><sgmltag class=
"starttag">orderedlist
</sgmltag></term>
1462 A numbered list; the SGML processor will insert the
1463 numbers for you. You can suggest numbering styles
1465 class=
"attribute">numeration
</sgmltag> attribute.
1470 <term><sgmltag class=
"starttag">simplelist
</sgmltag></term>
1473 A very simple list of items, often inlined. Control
1474 the layout with the
<sgmltag
1475 class=
"attribute">type
</sgmltag> attribute.
1480 <term><sgmltag class=
"starttag">variablelist
</sgmltag></term>
1483 A list of terms with definitions or descriptions,
1484 like this very list!
1491 <title>Block Text Quoting Elements
</title>
1493 <term><sgmltag class=
"starttag">programlisting
</sgmltag></term>
1496 Quote a block of source code. Typically highlighted
1497 in the output and set off from normal text.
1502 <term><sgmltag class=
"starttag">screen
</sgmltag></term>
1505 Quote a block of visible computer output, like the
1506 output of a command or chunks of debug logs.
1513 <title>Hyperlink Elements
</title>
1515 <term><sgmltag class=
"starttag">link
</sgmltag></term>
1518 Generic hypertext link, used for pointing to other
1519 sections within the current document. You supply
1520 the visible text for the link, plus the name of the
<sgmltag
1521 class=
"attribute">id
</sgmltag> attribute of the
1522 element that you want to link to. For example:
1523 <programlisting><link
linkend=
"configuring-wine">the section on configuring wine
</link
>
1525 <sect2
id=
"configuring-wine">
1526 ...
</programlisting>
1531 <term><sgmltag class=
"starttag">xref
</sgmltag></term>
1534 In-document hyperlink that can generate its own
1535 text. Similar to the
<sgmltag
1536 class=
"starttag">link
</sgmltag> tag, you use the
1537 <sgmltag class=
"attribute">linkend
</sgmltag>
1538 attribute to specify which target element you want
1542 <programlisting><xref
linkend=
"configuring-wine">
1544 <sect2
id=
"configuring-wine">
1545 ...
</programlisting>
1548 By default, most SGML processors will autogenerate
1549 some generic text for the
<sgmltag
1550 class=
"starttag">xref
</sgmltag> link, like
1551 <quote>Section
2.3.1</quote>. You can use the
1552 <sgmltag class=
"attribute">endterm
</sgmltag>
1553 attribute to grab the visible text content of the
1554 hyperlink from another element:
1557 <programlisting><xref
linkend=
"configuring-wine" endterm=
"config-title">
1559 <sect2
id=
"configuring-wine">
1560 <title
id=
"config-title">Configuring Wine
</title
>
1561 ...
</programlisting>
1564 This would create a link to the
1565 <symbol>configuring-wine
</symbol> element,
1566 displaying the text of the
1567 <symbol>config-title
</symbol> element for the
1568 hyperlink. Most often, you'll add an
<sgmltag
1569 class=
"attribute">id
</sgmltag> attribute to the
1570 <sgmltag class=
"starttag">title
</sgmltag> of the
1571 section you're linking to, as above, in which case
1572 the SGML processor will use the target's title text
1576 Alternatively, you can use an
<sgmltag
1577 class=
"attribute">xreflabel
</sgmltag> attribute in
1578 the target element tag to specify the link text:
1580 <programlisting><sect1
id=
"configuring-wine" xreflabel=
"Configuring Wine"></programlisting>
1583 <sgmltag class=
"starttag">xref
</sgmltag> is an
1584 empty element. You don't need a closing tag for
1585 it (this is defined in the DTD). In SGML
1586 documents, you should use the form
<sgmltag
1587 class=
"starttag">xref
</sgmltag>, while in XML
1588 documents you should use
1589 <sgmltag><xref
/></sgmltag>.
1595 <term><sgmltag class=
"starttag">anchor
</sgmltag></term>
1598 An invisible tag, used for inserting
<sgmltag
1599 class=
"attribute">id
</sgmltag> attributes into a
1600 document to link to arbitrary places (i.e., when
1601 it's not close enough to link to the top of an
1607 <term><sgmltag class=
"starttag">ulink
</sgmltag></term>
1610 Hyperlink in URL form, e.g.,
<ulink
1611 url=
"http://www.winehq.com">http://www.winehq.com
</ulink>.
1616 <term><sgmltag class=
"starttag">olink
</sgmltag></term>
1619 Indirect hyperlink; can be used for linking to
1620 external documents. Not often used in practice.
1628 <title>Multiple SGML files
</title>
1630 How to split an SGML document into multiple files...
1635 <sect2 id=
"sgml-environment">
1636 <title>The SGML Environment
</title>
1639 You can write SGML/DocBook documents in any text editor you
1640 might find (although as we'll find in
<xref
1641 linkend=
"emacs-psgml">, some editors are more friendly for
1642 this task than others). However, if you want to convert
1643 those documents into a more friendly form for reading, such
1644 as HTML, PostScript, or PDF, you will need a working SGML
1645 environment. This section attempts to lay out the various
1646 SGML rendering systems, and how they are set up on the
1647 popular Linux distributions.
1651 <title>DSSSL Environment
</title>
1653 Explain tools and methodologies..
1658 <title>XSLT Environment
</title>
1660 Explain tools and methodologies...
1666 <sect2 id=
"emacs-psgml">
1667 <title>PSGML Mode in Emacs
</title>
1669 Although you can write SGML documentation in any simple text
1670 editor, some editors provide extra support for entering SGML
1671 tags, and for verifying that the SGML you create is valid.
1672 SGML has been around for a long time, and many commercial
1673 editors exist for it; however, until recently open source
1674 SGML editors have been scarce.
1677 <title>FIXME
</title>
1679 List the available commercial and open source SGML
1684 The most commonly used open source SGML editor is Emacs,
1685 with the PSGML
<firstterm>mode
</firstterm>, or extension.
1686 Emacs does not supply a GUI or WYSIWYG (What You See Is What
1687 You Get) interface, but it does provide many helpful
1688 shortcuts for creating SGML, as well as automatic
1689 formatting, validity checking, and the ability to create
1690 your own macros to simplify complex, repetitive actions.
1691 We'll touch briefly on each of these points.
1694 The first thing you need is a working installation of Emacs
1695 (or XEmacs), with the PSGML package. Most Linux
1696 distributions provide both as easy-to-install packages.
1699 Next, you'll need a working SGML environment. See
<xref
1700 linkend=
"sgml-environment"> for more info on setting that
1705 <sect2 id=
"docbook-build">
1706 <title>The DocBook Build System
</title>
1708 <sect3 id=
"docbook-infrastructure">
1709 <title>Basic Infrastructure
</title>
1711 FIXME: How the build/make system works (makefiles, db2html,
1716 <sect3 id=
"docbook-tweaking">
1717 <title>Tweaking the DSSSL stylesheets
</title>
1719 FIXME: Things you can tweak, and how to do it (examples from
1720 default.dsl and print.dsl).
1724 <sect3 id=
"docbook-generating">
1725 <title>Generating docs for Wine web sites
</title>
1727 FIXME: Explain make, rsync, etc.
1734 <!-- Keep this comment at the end of the file
1737 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")