1732 lines
71 KiB
Plaintext
1732 lines
71 KiB
Plaintext
<chapter id="documentation">
|
|
<title>Documenting Wine</title>
|
|
|
|
<para>
|
|
Written by &name-jon-griffiths; <email>&email-jon-griffiths;</email>
|
|
</para>
|
|
|
|
<para>
|
|
This chapter describes how you can help improve Wines documentation.
|
|
</para>
|
|
|
|
<para>
|
|
Like most large scale volunteer projects, Wine is strongest in areas that are rewarding
|
|
for its volunteers to work in. The majority of contributors send code patches either
|
|
fixing bugs, adding new functionalty or otherwise improving the software components of
|
|
the distribution. A lesser number contribute in other ways, such as reporting bugs and
|
|
regressions, creating tests, providing organisational assistance, or helping to document
|
|
Wine.
|
|
</para>
|
|
|
|
<para>
|
|
Documentation is important for many reasons, and is often the key to the end user having
|
|
a successful experience in installing, setting up and using software. Because Wine is a
|
|
complicated, evolving entity, providing quality up to date documentation is vital to
|
|
encourage more people to persevere with using and contributing to the project.
|
|
The following sections describe in detail how to go about adding to or updating Wines
|
|
existing documentation.
|
|
</para>
|
|
|
|
<sect1 id="doc-overview">
|
|
<title>An Overview Of Wine Documentation</title>
|
|
|
|
<para>
|
|
The Wine source code tree comes with a large amount of documentation in the
|
|
<filename>documentation/</filename> subdirectory. This used to be a collection
|
|
of text files culled from various places such as the Wine Weekly News and the wine-devel
|
|
mailing list, but was reorganised some time ago into a number of books, each of which is
|
|
marked up using SGML. You are reading one of these books (the
|
|
<emphasis>Wine Developer's Guide</emphasis>) right now.
|
|
</para>
|
|
|
|
<para>
|
|
Since being reorganised, the books have been updated and extended regularly. In their
|
|
current state they provide a good framework which over time can be expanded and kept
|
|
up to date. This means that most of the time when further documentation is added, it is
|
|
a simple matter of updating the content of an already existing file. The books
|
|
available at the time of writing are:
|
|
|
|
<itemizedlist>
|
|
|
|
<listItem><para>
|
|
The <emphasis>Wine User Guide</emphasis>. This book contains information for end users
|
|
on installing, configuring and running Wine.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
The <emphasis>Wine Developer's Guide</emphasis>. This book contains information and
|
|
guidelines for developers and contributors to the Wine project.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
The <emphasis>Winelib User's Guide</emphasis>. This book contains information for
|
|
developers using Winelib to port Win32 applications to Unix.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
The <emphasis>Wine Packagers Guide</emphasis>. This book contains information for
|
|
anyone who will be distributing Wine to end users in a prepackaged format.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
The <emphasis>Wine FAQ</emphasis>. This book contains frequently asked questions
|
|
about Wine with their answers.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Another source of documentation is the <emphasis>Wine API Guide</emphasis>. This is
|
|
generated information taken from special comments placed in the Wine source code.
|
|
When you update or add new API calls to Wine you should consider documenting them so
|
|
that developers can determine what the API does and how it should be used.
|
|
</para>
|
|
|
|
<para>
|
|
The next sections describe how to create Wine API documentation and how to work with
|
|
SGML so you can add to the existing books.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="api-docs">
|
|
<title>Writing Wine API Documentation</title>
|
|
|
|
<para>
|
|
Written by &name-jon-griffiths; <email>&email-jon-griffiths;</email>
|
|
</para>
|
|
|
|
<sect2 id="api-docs-intro">
|
|
<title>Introduction to API Documentation</title>
|
|
<para>
|
|
Wine includes a large amount of documentation on the API functions
|
|
it implements. There are serveral reasons to want to document the Win32
|
|
API:
|
|
<itemizedlist>
|
|
|
|
<listItem><para>
|
|
To allow Wine developers to know what each function should do, should
|
|
they need to update or fix it.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
To allow Winelib users to understand the functions that are available
|
|
to their applications.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
To provide an alternative source of free documentation on the Win32 API.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
To provide more accurate documentation where the existing documentation
|
|
is accendentally or deliberately vague or misleading.
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
To this end, a semi formalised way of producing documentation from the Wine
|
|
source code has evolved. Since the primary users of API documentation are Wine
|
|
developers themselves, documentation is usually inserted into the source code
|
|
in the form of comments and notes. Good things to include in the documentation
|
|
of a function include:
|
|
<itemizedlist>
|
|
|
|
<listItem><para>
|
|
The purpose of the function.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
The parameters of the function and their purpose.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
The return value of the function, in success as well as failure cases.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
Additional notes such as interaction with other parts of the system, differences
|
|
between Wines implementation and Win32s, errors in MSDN documentation,
|
|
undocumented cases and bugs that Wine corrects or is compatable with.
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Good documentation helps developers be aware of the effects of making changes. It
|
|
also allows good tests to be written which cover all of the documented cases.
|
|
</para>
|
|
|
|
<para>
|
|
Note that you do not need to be a programmer to update the documentation in Wine.
|
|
If you would like to contribute to the project, patches that improve the API
|
|
documentation are welcome. The following describes how to format any documentation
|
|
that you write so that the Wine documentation generator can extract it and make it
|
|
available to other developers and users.
|
|
</para>
|
|
|
|
<para>
|
|
In general, if you did not write the function in question, you should be wary of
|
|
adding comments to other peoples code. It is quite possible you may misunderstand
|
|
or misrepresent what the original author intended! Adding API documentation on
|
|
the other hand can be done by anybody, since in most cases there is plenty of
|
|
information about what a function is supposed to do (if it isn't obvious)
|
|
available in books and articles on the internet.
|
|
</para>
|
|
|
|
<para>
|
|
A final warning concerns copyright and must be noted. If you read MSDN or any
|
|
publication in order to find out what an API call does, you must be aware that
|
|
the text you are reading is copyrighted and in most cases cannot legally be
|
|
reproduced without the authors permission. If you copy verbatim any information
|
|
from such sources and submit it for inclusion into Wine, you open yourself up
|
|
to potential legal liability. You must ensure that anything you submit is
|
|
your own work, although it can be based on your understanding gleaned from
|
|
reading other peoples work.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-docs-basics">
|
|
<title>Basic API Documentation</title>
|
|
|
|
<para>
|
|
The general form of an API comment in Wine is a block comment immediately before a
|
|
function is implemented in the source code. General comments within a function body or
|
|
at the top of an implementation file are ignored by the API documentation generator.
|
|
Such comments are for the benefit of developers only, for example to explain what the
|
|
source code is doing or to describe something that may not be obvious to the person
|
|
reading the source code.
|
|
</para>
|
|
|
|
<para>
|
|
The following text uses the function <emphasis>PathRelativePathToA()</emphasis> from
|
|
<filename>SHLWAPI.DLL</filename> as an example. You can find this function in the Wine
|
|
source code tree in the file <filename>dlls/shlwapi/path.c</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
The first line of the comment gives the name of the function, the DLL that the
|
|
function is exported from, and its export ordinal number. This is the simplest
|
|
(and most common type of) comment:
|
|
</para>
|
|
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToA [SHLWAPI.@]
|
|
*/
|
|
</screen>
|
|
|
|
<para>
|
|
The functions name and the DLL name are obvious. The ordinal number takes one of
|
|
two forms: Either <command>@</command> as in the above, or a number if the export
|
|
is exported by ordinal. You can see which to use by looking at the DLL's
|
|
<filename>.spec</filename> file. If the line on which the function is listed begins
|
|
with a number, use it, otherwise use the <command>@</command> symbol, which indicates
|
|
that this function is imported only by name.
|
|
</para>
|
|
|
|
<para>
|
|
Note also that round or square brackets can be used, and whitespace between the name
|
|
and the DLL/ordinal is free form. Thus the following is equally valid:
|
|
</para>
|
|
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToA (SHLWAPI.@)
|
|
*/
|
|
</screen>
|
|
|
|
<para>
|
|
This basic comment will not get processed into documentation, since it
|
|
contains no information. In order to produce documentation for the function,
|
|
We must add some of the information listed above.
|
|
</para>
|
|
|
|
<para>
|
|
First we add a description of the function. This can be as long as you like, but
|
|
typically contains only a brief description of what the function is meant to do
|
|
in general terms. It is free form text:
|
|
</para>
|
|
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToA [SHLWAPI.@]
|
|
*
|
|
* Create a relative path from one path to another.
|
|
*/
|
|
</screen>
|
|
|
|
<para>
|
|
To be truly useful however we must document the parameters to the function.
|
|
There are two methods for doing this: In the comment, or in the function
|
|
prototype.
|
|
</para>
|
|
|
|
<para>
|
|
Parameters documented in the comment should be formatted as follows:
|
|
</para>
|
|
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToA [SHLWAPI.@]
|
|
*
|
|
* Create a relative path from one path to another.
|
|
*
|
|
* PARAMS
|
|
* lpszPath [O] Destination for relative path
|
|
* lpszFrom [I] Source path
|
|
* dwAttrFrom [I] File attribute of source path
|
|
* lpszTo [I] Destination path
|
|
* dwAttrTo [I] File attributes of destination path
|
|
*
|
|
*/
|
|
</screen>
|
|
|
|
<para>
|
|
The parameters section starts with <command>PARAMS</command> on its own line.
|
|
Each parameter is listed in the order they appear in the functions prototype,
|
|
first with the parameters name, followed by its input/output status, followed
|
|
by a free form text description of the comment.
|
|
</para>
|
|
|
|
<para>
|
|
The input/output status tells the programmer whether the value will be modified
|
|
by the function (an output parameter), or only read (an input parameter). The
|
|
status must be enclosed in square brackets to be recognised, otherwise, or if it
|
|
is absent, anything following the parameter name is treated as the parameter
|
|
description. This field is case insensitive and can be any of the following:
|
|
<command>[I]</command>, <command>[In]</command>, <command>[O]</command>,
|
|
<command>[Out]</command>, <command>[I/O]</command>, <command>[In/Out]</command>.
|
|
</para>
|
|
|
|
<para>
|
|
Parameters documented in the prototype should be formatted as follows:
|
|
</para>
|
|
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToA [SHLWAPI.@]
|
|
*
|
|
* Create a relative path from one path to another.
|
|
*
|
|
*/
|
|
BOOL WINAPI PathRelativePathToA(
|
|
LPSTR lpszPath, /* [O] Destination for relative path */
|
|
LPCSTR lpszFrom, /* [I] Source path */
|
|
DWORD dwAttrFrom, /* [I] File attribute of source path */
|
|
LPCSTR lpszTo, /* [I] Destination path */
|
|
DWORD dwAttrTo) /* [I] File attributes of destination path */
|
|
</screen>
|
|
|
|
<para>
|
|
The choice of which style to use is up to you, although for readability it
|
|
is suggested you stick with the same style within a single source file.
|
|
</para>
|
|
|
|
<para>
|
|
Following the description and parameters come a number of optional sections, all
|
|
in the same format. A section is defined as the section name, which is an all upper
|
|
case section name on its own line, followed by free form text. You can create any
|
|
sections you like, however for consistency it is recommended you use the following
|
|
section names:
|
|
<orderedlist>
|
|
|
|
<listItem><para>
|
|
<command>NOTES</command>. Anything that needs to be noted about the function
|
|
such as special cases and the effects of input arguments.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
<command>BUGS</command>. Any bugs in the function that exist 'by design', i.e.
|
|
those that will not be fixed or exist for compatability with Windows.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
<command>TODO</command>. Any unhandled cases or missing functionality in the Wine
|
|
implementation of the function.
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
<command>FIXME</command>. Things that should be updated or addressed in the implementation
|
|
of the function at some future date (perhaps dependent on other parts of Wine). Note
|
|
that if this information is only relevant to Wine developers then it should probably
|
|
be placed in the relavent code section instead.
|
|
</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Following or before the optional sections comes the <command>RETURNS</command> section
|
|
which describes the return value of the function. This is free form text but should include
|
|
what is returned on success as well as possible error return codes. Note that this
|
|
section must be present for documentation to be generated for your comment.
|
|
</para>
|
|
|
|
<para>
|
|
Our final documentation looks like the following:
|
|
</para>
|
|
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToA [SHLWAPI.@]
|
|
*
|
|
* Create a relative path from one path to another.
|
|
*
|
|
* PARAMS
|
|
* lpszPath [O] Destination for relative path
|
|
* lpszFrom [I] Source path
|
|
* dwAttrFrom [I] File attribute of source path
|
|
* lpszTo [I] Destination path
|
|
* dwAttrTo [I] File attributes of destination path
|
|
*
|
|
* RETURNS
|
|
* TRUE If a relative path can be formed. lpszPath contains the new path
|
|
* FALSE If the paths are not relative or any parameters are invalid
|
|
*
|
|
* NOTES
|
|
* lpszTo should be at least MAX_PATH in length.
|
|
* Calling this function with relative paths for lpszFrom or lpszTo may
|
|
* give erroneous results.
|
|
*
|
|
* The Win32 version of this function contains a bug where the lpszTo string
|
|
* may be referenced 1 byte beyond the end of the string. As a result random
|
|
* garbage may be written to the output path, depending on what lies beyond
|
|
* the last byte of the string. This bug occurs because of the behaviour of
|
|
* PathCommonPrefix() (see notes for that function), and no workaround seems
|
|
* possible with Win32.
|
|
* This bug has been fixed here, so for example the relative path from "\\"
|
|
* to "\\" is correctly determined as "." in this implementation.
|
|
*/
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2 id="api-docs-advanced">
|
|
<title>Advanced API Documentation</title>
|
|
|
|
<para>
|
|
There is no markup language for formatting API comments, since they should
|
|
be easily readable by any developer working on the source file. A number of
|
|
constructs are treated specially however, and are noted here. You can use these
|
|
constructs to enhance the usefulness of the generated documentation by making it
|
|
easier to read and referencing related documents.
|
|
</para>
|
|
|
|
<para>
|
|
Any valid c identifier that ends with <command>()</command> is taken to
|
|
be an API function and is formatted accordingly. When generating documentation,
|
|
this text will become a link to that API call, if the output type supports
|
|
hyperlinks or their equivalent.
|
|
</para>
|
|
|
|
<para>
|
|
Similarly, any interface name starting with a capital I and followed by the
|
|
words "reference" or "object" become a link to that objects documentation.
|
|
</para>
|
|
|
|
<para>
|
|
Where an Ascii and Unicode version of a function are available, it is
|
|
recommended that you document only the Ascii version and have the Unicode
|
|
version refer to the Ascii one, as follows:
|
|
</para>
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToW [SHLWAPI.@]
|
|
*
|
|
* See PathRelativePathToA.
|
|
*/
|
|
</screen>
|
|
<para>
|
|
Alternately you may use the following form:
|
|
</para>
|
|
<screen>
|
|
/*************************************************************************
|
|
* PathRelativePathToW [SHLWAPI.@]
|
|
*
|
|
* Unicode version of PathRelativePathToA.
|
|
*/
|
|
</screen>
|
|
|
|
<para>
|
|
You may also use this construct in any other section, such as <command>NOTES</command>.
|
|
</para>
|
|
|
|
<para>
|
|
Any numbers and text in quotes (<command>""</command>) are highlighted.
|
|
</para>
|
|
|
|
<para>
|
|
Words in all uppercase are assumed to be API constants and are highlighted. If
|
|
you want to emphasise something in the documentation, put it in a section by itself
|
|
rather than making it upper case.
|
|
</para>
|
|
|
|
<para>
|
|
Blank lines in a section cause a new paragraph to be started. Blank lines
|
|
at the start and end of sections are ignored.
|
|
</para>
|
|
|
|
<para>
|
|
Any comment line starting with (<command>"*|"</command>) is treated as raw text and
|
|
is not pre-processed before being output. This should be used for code listings,
|
|
tables and any text that should remain unformatted.
|
|
</para>
|
|
|
|
<para>
|
|
Any line starting with a single word followed by a colon (<command>:</command>)
|
|
is assumed to be case listing and is emphasised and put in its own paragrah. This
|
|
is most often used for return values, as in the example section below.
|
|
</para>
|
|
<screen>
|
|
* RETURNS
|
|
* Success: TRUE. Something happens that is documented here.
|
|
* Failure: FALSE. The reasons why this call can fail are listed here.
|
|
</screen>
|
|
|
|
<para>
|
|
Any line starting with a (<command>-</command>) is put into a paragraph by itself.
|
|
this allows lists to avoid being run together.
|
|
</para>
|
|
|
|
<para>
|
|
If you are in doubt as to how your comment will look, try generating the API
|
|
documentation and checking the output.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-docs-extra">
|
|
<title>Extra API Documentation</title>
|
|
|
|
<para>
|
|
Simply documenting the API calls available provides a great deal of information to
|
|
developers working with the Win32 API. However additional documentation is needed
|
|
before the API Guide can be considered truly useful or comprehensive. For example,
|
|
COM objects that are available for developers use should be documented, along with
|
|
the interface(s) that those objects export. Also, it would be helpful to document
|
|
each dll, to provide some structure to the documentation.
|
|
</para>
|
|
|
|
<para>
|
|
To facilitate providing extra documentation, you can create comments that provide
|
|
extra documentation on functions, or on keywords such as the name of a COM interface
|
|
or a type definition.
|
|
</para>
|
|
|
|
<para>
|
|
These items are generated using the same formatting rules as described earlier. The
|
|
only difference is the first line of the comment, which indicates to the generator
|
|
that the documentation is supplimental and does not describe an export from the dll
|
|
being processed.
|
|
</para>
|
|
|
|
<para>
|
|
Lets assume you have implemented a COM interface that you want to document; we'll
|
|
use the name <command>IExample</command> as an example here. Your comment would
|
|
look like the following (assuming you are exporting this object from
|
|
<filename>EXAMPLE.DLL</filename>):
|
|
<screen>
|
|
/*************************************************************************
|
|
* IExample {EXAMPLE}
|
|
*
|
|
* The IExample object provides lots of interesting functionality.
|
|
* ...
|
|
*/
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Format this documentation exactly as you would a standard export. The only
|
|
difference is the use of curly brackets to mark this documentation as supplimental.
|
|
The generator will output this documentation using the name given before the
|
|
DLL name, and will link to it from the main DLL page. In addition, if you have
|
|
referred to the comment name in other documentation using "IExample interface",
|
|
"IExample object", or "IExample()", those references will point to this documentation.
|
|
</para>
|
|
|
|
<para>
|
|
If you document you COM interfaces this way then all following extra comments that
|
|
follow in the same source file that begin with the same document title will be added
|
|
as references to this comment before it is output. For an example of this see
|
|
<filename>dlls/oleaut32/safearray.c</filename>. This uses an extra comment to document
|
|
The SafeArray functions and link them together under one heading.
|
|
</para>
|
|
|
|
<para>
|
|
As a special case, if you use the DLL name as the comment name, the comment will
|
|
be treated as documentation on the DLL itself. When the documentation for the DLL
|
|
is processed, the contents of the comment will be placed before the generated
|
|
statistics, exports and other information that makes up a DLL's documentation page.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-docs-generating">
|
|
<title>Generating API Documentation</title>
|
|
|
|
<para>
|
|
Having edited or added new API documentation to a source code file, you
|
|
should generate the documentation to ensure that the result is what you
|
|
expected. Wine includes a tool (slightly misleadingly) called
|
|
<command>c2man.pl</command> in the <filename>tools/</filename> directory
|
|
which is used to generate the documentation from the source code.
|
|
</para>
|
|
|
|
<para>
|
|
You can run <command>c2man.pl</command> manually for testing purposes; it is
|
|
a fairly simple perl script which parses <filename>.c</filename> files
|
|
to create output in several formats. If you wish to try this you may want
|
|
to run it with no arguments, which will cause it to print usage information.
|
|
</para>
|
|
|
|
<para>
|
|
An easier way is to use Wines build system. To create man pages for a given
|
|
dll, just type <command>make man</command> from within the dlls directory
|
|
or type <command>make manpages</command> in the root directory of the Wine
|
|
source tree. You can then check that a man page was generated for your function,
|
|
it should be present in the <filename>documentation/man3w</filename> directory
|
|
with the same name as the function.
|
|
</para>
|
|
|
|
<para>
|
|
Once you have generated the man pages from the source code, running
|
|
<command>make install</command> will install them for you. By default they are
|
|
installed in section 3w of the manual, so they don't conflict with any existing
|
|
man page names. So, to read the man page you should use
|
|
<command>man -S 3w {name}</command>. Alternately you can edit
|
|
<filename>/etc/man.config</filename> and add 3w to the list of search paths
|
|
given in the variable <emphasis>MANSECT</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
You can also generate HTML output for the API documentation, in this case the
|
|
make command is <command>make doc-html</command> in the dll directory,
|
|
or <command>make htmlpages</command> from the root. The output will be
|
|
placed by default under <filename>documentation/html</filename>. Similarly
|
|
you can create SGML source code to produce the <emphasis>Wine Api Guide</emphasis>
|
|
with the command <command>make sgmlpages</command>.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="wine-docbook">
|
|
<title>The Wine DocBook System</title>
|
|
|
|
<para>
|
|
Written by &name-john-sheets; <email>&email-john-sheets;</email>
|
|
</para>
|
|
<para>
|
|
Modified by &name-tony-lambregts; <email>&email-tony-lambregts;</email> Nov. 2002
|
|
</para>
|
|
|
|
<sect2 id="writing-docbook">
|
|
<title>Writing Documentation with DocBook</title>
|
|
|
|
<para>
|
|
DocBook is a flavor of <acronym>SGML</acronym>
|
|
(<firstterm>Standard Generalized Markup
|
|
Language</firstterm>), a syntax for marking up the contents
|
|
of documents. HTML is another very common flavor of SGML;
|
|
DocBook markup looks very similar to HTML markup, although
|
|
the names of the markup tags differ.
|
|
</para>
|
|
<sect3>
|
|
<title>Getting Started</title>
|
|
<note>
|
|
<title>Why SGML?</title>
|
|
<para>
|
|
The simple answer to that is that SGML allows you
|
|
to create multiple formats of a given document from a single
|
|
source. Currently it is used to create html, pdf and PS (PostScript)
|
|
versions of the Wine books.
|
|
</para>
|
|
</note>
|
|
|
|
<note>
|
|
<title>What do I need?</title>
|
|
<para>
|
|
You need the sgml tools. There are various places where you
|
|
can get them. The most generic way of geting them is from their
|
|
source as discussed below.
|
|
</para>
|
|
</note>
|
|
|
|
<note>
|
|
<title>Quick instructions</title>
|
|
<para>
|
|
These are the basic steps to create the Wine books from the sgml source.
|
|
</para>
|
|
</note>
|
|
|
|
<orderedlist>
|
|
|
|
<listItem><para>
|
|
Go to <ulink url="http://www.sgmltools.org">http://www.sgmltools.org</ulink>
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
Download all of the sgmltools packages
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
Install them all and build them (<command>./configure; make; make install</command>)
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
Switch to your toplevel Wine directory
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
Run <command>./configure</command> (or <command>make distclean && ./configure</command>)
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
Switch to the <filename>documentation/</filename> directory
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
run <command>./make_winehq</command>
|
|
</para></listitem>
|
|
|
|
<listItem><para>
|
|
View <filename>wine-doc/index.html</filename> in your favorite browser
|
|
</para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Getting SGML for various distributions</title>
|
|
<para>
|
|
Most Linux distributions have everything you need already
|
|
bundled up in package form. Unfortunately, each
|
|
distribution seems to handle its SGML environment
|
|
differently, installing it into different paths, and
|
|
naming its packages according to its own whims.
|
|
</para>
|
|
|
|
<sect4>
|
|
<title>SGML on Redhat</title>
|
|
<para>
|
|
The following packages seems to be sufficient for RedHat 7.1. You
|
|
will want to be careful about the order in which you install the
|
|
rpms.
|
|
<itemizedlist>
|
|
<listitem><para>sgml-common-*.rpm</para></listitem>
|
|
<listitem><para>openjade-*.rpm</para></listitem>
|
|
<listitem><para>perl-SGMLSpm-*.rpm</para></listitem>
|
|
<listitem><para>docbook-dtd*.rpm</para></listitem>
|
|
<listitem><para>docbook-style-dsssl-*.rpm</para></listitem>
|
|
<listitem><para>tetex-*.rpm</para></listitem>
|
|
<listitem><para>jadetex-*.rpm</para></listitem>
|
|
<listitem><para>docbook-utils-*.rpm</para></listitem>
|
|
</itemizedlist>
|
|
You can also use ghostscript to view the ps format output and
|
|
Adobe Acrobat 4 to view the pdf file.
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>SGML on Debian</title>
|
|
<note>
|
|
<title>Fix me</title>
|
|
<para>
|
|
List package names and install locations...
|
|
</para>
|
|
</note>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>SGML on Other Distributions</title>
|
|
<note>
|
|
<title>Fix me</title>
|
|
<para>
|
|
List package names and install locations...
|
|
</para>
|
|
</note>
|
|
</sect4>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Terminology</title>
|
|
|
|
<para>
|
|
SGML markup contains a number of syntactical elements that
|
|
serve different purposes in the markup. We'll run through
|
|
the basics here to make sure we're on the same page when
|
|
we refer to SGML semantics.
|
|
</para>
|
|
<para>
|
|
The basic currency of SGML is the
|
|
<firstterm>tag</firstterm>. A simple tag consists of a
|
|
pair of angle brackets and the name of the tag. For
|
|
example, the <sgmltag>para</sgmltag> tag would appear in
|
|
an SGML document as <sgmltag
|
|
class="starttag">para</sgmltag>. This start tag indicates
|
|
that the immediately following text should be classified
|
|
according to the tag. In regular SGML, each opening tag
|
|
must have a matching end tag to show where the start tag's
|
|
contents end. End tags begin with
|
|
<quote><literal></</literal></quote> markup, e.g.,
|
|
<sgmltag class="endtag">para</sgmltag>.
|
|
</para>
|
|
<para>
|
|
The combination of a start tag, contents, and an end tag
|
|
is called an <firstterm>element</firstterm>. SGML
|
|
elements can be nested inside of each other, or contain
|
|
only text, or may be a combination of both text and other
|
|
elements, although in most cases it is better to limit
|
|
your elements to one or the other.
|
|
</para>
|
|
<para>
|
|
The <acronym>XML</acronym> (<firstterm>eXtensible Markup
|
|
Language</firstterm>) specification, a modern subset of
|
|
the SGML specification, adds a so-called <firstterm>empty
|
|
tag</firstterm>, for elements that contain no text
|
|
content. The entire element is a single tag, ending with
|
|
<quote><literal>/></literal></quote>, e.g.,
|
|
<sgmltag><xref/></sgmltag>. However, use of this
|
|
tag style restricts you to XML DocBook processing, and
|
|
your document may no longer compile with SGML-only
|
|
processing systems.
|
|
</para>
|
|
<!-- *** Note: We could normally use the "emptytag"
|
|
attribute for XML empty tags, but that's only a recent
|
|
addition, and we don't want to screw up documents
|
|
generated against older stylesheets.
|
|
*** -->
|
|
<para>
|
|
Often a processing system will need more information about
|
|
an element than you can provide with just tags. SGML
|
|
allows you to add extra <quote>hints</quote> in the form
|
|
of SGML <firstterm>attributes</firstterm> to pass along
|
|
this information. The most common use of attributes in
|
|
DocBook is giving specific elements a name, or an ID, so
|
|
you can refer to it from elsewhere. This ID can be used
|
|
for many things, including file-naming for HTML output,
|
|
hyper-linking to specific parts of the document, and even
|
|
pulling text from that element (see the <sgmltag
|
|
class="starttag">xref</sgmltag> tag).
|
|
</para>
|
|
<para>
|
|
An SGML attribute appears inside the start tag, between
|
|
the < and > brackets. For example, if you wanted to
|
|
set the <sgmltag class="attribute">id</sgmltag> attribute
|
|
of the <sgmltag class="starttag">book</sgmltag> element to
|
|
<quote>mybook</quote>, you would create a start tag like
|
|
this: <programlisting><book id="mybook"></programlisting>
|
|
</para>
|
|
<para>
|
|
Notice that the contents of the attribute are enclosed in
|
|
quote marks. These quotes are optional in SGML, but
|
|
mandatory in XML. It's a good habit to use quotes, as it
|
|
will make it much easier to migrate your documents to an
|
|
XML processing system later on.
|
|
</para>
|
|
<para>
|
|
You can also specify more than one attribute in a single
|
|
tag: <programlisting><book id="mybook" status="draft"></programlisting>
|
|
</para>
|
|
<para>
|
|
Another commonly used type of SGML markup is the
|
|
<firstterm>entity</firstterm>. An entity lets you
|
|
associate a block of text with a name. You declare the
|
|
entity once, at the beginning of your document, and can
|
|
invoke it as many times as you like throughout the
|
|
document. You can use entities as shorthand, or to make
|
|
it easier to maintain certain phrases in a central
|
|
location, or even to insert the contents of an entire file
|
|
into your document.
|
|
</para>
|
|
<para>
|
|
An entity in your document is always surrounded by the
|
|
<quote>&</quote> and <quote>;</quote> characters. One
|
|
entity you'll need sooner or later is the one for the
|
|
<quote><</quote> character. Since SGML expects all
|
|
tags to begin with a <quote><</quote>, the
|
|
<quote><</quote> is a reserved character. To use it in
|
|
your document (as I am doing here), you must insert it
|
|
with the <literal>&lt;</literal> entity. Each time
|
|
the SGML processor encounters <literal>&lt;</literal>,
|
|
it will place a literal <quote><</quote> in the output
|
|
document. Similarly you must use the <literal>&gt;</literal>
|
|
and <literal>&amp;</literal> entities for the
|
|
<quote>></quote> and <quote>&</quote> characters.
|
|
</para>
|
|
<para>
|
|
The final term you'll need to know when writing simple
|
|
DocBook documents is the <acronym>DTD</acronym>
|
|
(<firstterm>Document Type Declaration</firstterm>). The
|
|
DTD defines the flavor of SGML a given document is written
|
|
in. It lists all the legal tag names, like <sgmltag
|
|
class="starttag">book</sgmltag>, <sgmltag
|
|
class="starttag">para</sgmltag>, and so on, and declares
|
|
how those tags are allowed to be used together. For
|
|
example, it doesn't make sense to put a <sgmltag
|
|
class="starttag">book</sgmltag> element inside a <sgmltag
|
|
class="starttag">para</sgmltag> paragraph element -- only
|
|
the reverse.
|
|
</para>
|
|
<para>
|
|
The DTD thus defines the legal structure of the document.
|
|
It also declares which attributes can be used with which
|
|
tags. The SGML processing system can use the DTD to make
|
|
sure the document is laid out properly before attempting
|
|
to process it. SGML-aware text editors like <link
|
|
linkend="emacs-psgml">Emacs</link> can also use the DTD to
|
|
guide you while you write, offering you choices about
|
|
which tags you can add in different places in the
|
|
document, and beeping at you when you try to add a tag
|
|
where it doesn't belong.
|
|
</para>
|
|
<para>
|
|
Generally, you will declare which DTD you want to use as
|
|
the first line of your SGML document. In the case of
|
|
DocBook, you will use something like this:
|
|
<programlisting><!doctype book PUBLIC "-//OASIS//DTD
|
|
DocBook V3.1//EN" []> <book> ...
|
|
</book></programlisting>
|
|
</para>
|
|
<para>
|
|
Note that you must specify your toplevel element inside
|
|
the doctype declaration. If you were writing an article
|
|
rather than a book, you might use this declaration instead:
|
|
<programlisting><!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
|
|
<article>
|
|
...
|
|
</article></programlisting>
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="sgml-document">
|
|
<title>The Document</title>
|
|
<para>
|
|
Once you're comfortable with SGML, creating a DocBook
|
|
document is quite simple and straightforward. Even
|
|
though DocBook contains over 300 different tags, you can
|
|
usually get by with only a small subset of those tags.
|
|
Most of them are for inline formatting, rather than for
|
|
document structuring. Furthermore, the common tags have
|
|
short, intuitive names.
|
|
</para>
|
|
<para>
|
|
Below is a (completely nonsensical) example to illustrate
|
|
how a simple document might be laid out. Notice that all
|
|
<sgmltag class="starttag">chapter</sgmltag> and <sgmltag
|
|
class="starttag">sect1</sgmltag> elements have <sgmltag
|
|
class="attribute">id</sgmltag> attributes. This is not
|
|
mandatory, but is a good habit to get into, as DocBook is
|
|
commonly converted into HTML, with a separate generated
|
|
file for each <sgmltag class="starttag">book</sgmltag>,
|
|
<sgmltag class="starttag">chapter</sgmltag>, and/or <sgmltag
|
|
class="starttag">sect1</sgmltag> element. If the given
|
|
element has an <sgmltag class="attribute">id</sgmltag>
|
|
attribute, the processor will typically name the file
|
|
accordingly. Thus, the below document might result in
|
|
<filename>index.html</filename>,
|
|
<filename>chapter-one.html</filename>,
|
|
<filename>blobs.html</filename>, and so on.
|
|
</para>
|
|
<para>
|
|
Also notice the text marked off with <quote><!--
|
|
</quote> and <quote> --></quote> characters. These
|
|
denote SGML comments. SGML processors will completely
|
|
ignore anything between these markers, similar to
|
|
<quote>/*</quote> and <quote>*/</quote> comments in C
|
|
source code.
|
|
</para>
|
|
|
|
<!-- Encase the following SGML excerpt inside a CDATA
|
|
block so we don't have to bother converting all
|
|
brackets to entities
|
|
-->
|
|
<programlisting>
|
|
<![CDATA[
|
|
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
|
|
<book id="index">
|
|
<bookinfo>
|
|
<title>A Poet's Guide to Nonsense</title>
|
|
</bookinfo>
|
|
|
|
<chapter id="chapter-one">
|
|
<title>Blobs and Gribbles</title>
|
|
|
|
<!-- This section contains only one major topic -->
|
|
<sect1 id="blobs">
|
|
<title>The Story Behind Blobs</title>
|
|
<para>
|
|
Blobs are often mistaken for ice cubes and rain
|
|
puddles...
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- This section contains embedded sub-sections -->
|
|
<sect1 id="gribbles">
|
|
<title>Your Friend the Gribble</title>
|
|
<para>
|
|
A Gribble is a cute, unassuming little fellow...
|
|
</para>
|
|
|
|
<sect2 id="gribble-temperament">
|
|
<title>Gribble Temperament</title>
|
|
<para>
|
|
When left without food for several days...
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="gribble-appearance">
|
|
<title>Gribble Appearance</title>
|
|
<para>
|
|
Most Gribbles have a shock of white fur running from...
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="chapter-two">
|
|
<title>Phantasmagoria</title>
|
|
|
|
<sect1 id="dretch-pools">
|
|
<title>Dretch Pools</title>
|
|
|
|
<para>
|
|
When most poets think of Dretch Pools, they tend to...
|
|
</para>
|
|
</sect>
|
|
</chapter>
|
|
</book>
|
|
]]>
|
|
</programlisting>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Common Elements</title>
|
|
<para>
|
|
Once you get used to the syntax of SGML, the next hurdle
|
|
in writing DocBook documentation is to learn the many
|
|
DocBook-specific tag names, and when to use them. DocBook
|
|
was created for technical documentation, and as such, the
|
|
tag names and document structure are slanted towards the
|
|
needs of such documentation.
|
|
</para>
|
|
<para>
|
|
To cover its target audience, DocBook declares a wide
|
|
variety of specialized tags, including tags for formatting
|
|
source code (with somewhat of a C/C++ bias), computer
|
|
prompts, GUI application features, keystrokes, and so on.
|
|
DocBook also includes tags for universal formatting needs,
|
|
like headers, footnotes, tables, and graphics.
|
|
</para>
|
|
<para>
|
|
We won't cover all of these elements here (over 300
|
|
DocBook tags exist!), but we will cover the basics. To
|
|
learn more about the other tags, check out the official
|
|
DocBook guide, at <ulink
|
|
url="http://docbook.org">http://docbook.org</ulink>. To
|
|
see how they are used in practice, download the SGML
|
|
source for this manual (the Wine Developer Guide) and
|
|
browse through it, comparing it to the generated HTML (or
|
|
PostScript or PDF).
|
|
</para>
|
|
<para>
|
|
There are often many correct ways to mark up a given piece
|
|
of text, and you may have to make guesses about which tag
|
|
to use. Sometimes you'll have to make compromises.
|
|
However, remember that it is possible to further <link
|
|
linkend="docbook-tweaking">customize the output</link> of
|
|
the SGML processors. If you don't like the way a certain
|
|
tag looks in HTML, that doesn't mean you should choose a
|
|
different tag based on its output formatting. The
|
|
processing stylesheets can be altered to fix the
|
|
formatting of that same tag everywhere in the document
|
|
(not just in the place you're working on). For example,
|
|
if you're frustrated that the <sgmltag
|
|
class="starttag">systemitem</sgmltag> tag doesn't produce
|
|
any formatting by default, you should fix the stylesheets,
|
|
not change the valid <sgmltag
|
|
class="starttag">systemitem</sgmltag> tag to, for example,
|
|
an <sgmltag class="starttag">emphasis</sgmltag> tag.
|
|
</para>
|
|
<para>
|
|
Here are the common SGML elements:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<title>Structural Elements</title>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">book</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
The book is the most common toplevel element, and is
|
|
probably the one you should use for your document.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">set</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
If you want to group more than one book into a
|
|
single unit, you can place them all inside a set.
|
|
This is useful when you want to bundle up
|
|
documentation in alternate ways. We do this with
|
|
the Wine documentation, using a <sgmltag
|
|
class="starttag">set</sgmltag> to put everything
|
|
into a single directory (see
|
|
<filename>documentation/wine-doc.sgml</filename>),
|
|
and a <sgmltag class="starttag">book</sgmltag> to
|
|
put each Wine guide into a separate directory (see
|
|
<filename>documentation/wine-devel.sgml</filename>,
|
|
etc.).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">chapter</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A <sgmltag class="starttag">chapter</sgmltag>
|
|
element includes a single entire chapter of the
|
|
book.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">part</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
If the chapters in your book fall into major
|
|
categories or groupings (as in the Wine Developer
|
|
Guide), you can place each collection of chapters
|
|
into a <sgmltag class="starttag">part</sgmltag>
|
|
element.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">sect?</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
DocBook has many section elements to divide the
|
|
contents of a chapter into smaller chunks. The
|
|
encouraged approach is to use the numbered section
|
|
tags, <sgmltag class="starttag">sect1</sgmltag>,
|
|
<sgmltag class="starttag">sect2</sgmltag>, <sgmltag
|
|
class="starttag">sect3</sgmltag>, <sgmltag
|
|
class="starttag">sect4</sgmltag>, and <sgmltag
|
|
class="starttag">sect5</sgmltag> (if necessary).
|
|
These tags must be nested in order: you can't place
|
|
a <sgmltag class="starttag">sect3</sgmltag> directly
|
|
inside a <sgmltag class="starttag">sect1</sgmltag>.
|
|
You have to nest the <sgmltag
|
|
class="starttag">sect3</sgmltag> inside a <sgmltag
|
|
class="starttag">sect2</sgmltag>, and so forth.
|
|
Documents with these explicit section groupings are
|
|
easier for SGML processors to deal with, and lead to
|
|
better organized documents. DocBook also supplies a
|
|
<sgmltag class="starttag">section</sgmltag> element
|
|
which you can nest inside itself, but its use is
|
|
discouraged in favor of the numbered section tags.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">title</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
The title of a book, chapter, part, section, etc.
|
|
In most of the major structural elements, like
|
|
<sgmltag class="starttag">chapter</sgmltag>,
|
|
<sgmltag class="starttag">part</sgmltag>, and the
|
|
various section tags, <sgmltag
|
|
class="starttag">title</sgmltag> is mandatory. In
|
|
other elements like <sgmltag
|
|
class="starttag">book</sgmltag> and <sgmltag
|
|
class="starttag">note</sgmltag>, it's optional.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">para</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
The basic unit of text is the paragraph, represented
|
|
by the <sgmltag class="starttag">para</sgmltag> tag.
|
|
This is probably the tag you'll use most often. In
|
|
fact, in a simple document, you can probably get
|
|
away with using only <sgmltag
|
|
class="starttag">book</sgmltag>, <sgmltag
|
|
class="starttag">chapter</sgmltag>, <sgmltag
|
|
class="starttag">title</sgmltag>, and <sgmltag
|
|
class="starttag">para</sgmltag>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">article</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
For shorter, more targeted documents, like topic
|
|
pieces and whitepapers, you can use <sgmltag
|
|
class="starttag">article</sgmltag> as your toplevel
|
|
element.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<title>Inline Formatting Elements</title>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">filename</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a file. You can optionally set the
|
|
<sgmltag class="attribute">class</sgmltag> attribute
|
|
to <literal>Directory</literal>,
|
|
<literal>HeaderFile</literal>, and
|
|
<literal>SymLink</literal> to further classify the
|
|
filename.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">userinput</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Literal text entered by the user.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">computeroutput</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Literal text output by the computer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">literal</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A catch-all element for literal computer data. Its
|
|
use is somewhat vague; try to use a more specific
|
|
tag if possible, like <sgmltag
|
|
class="starttag">userinput</sgmltag> or <sgmltag
|
|
class="starttag">computeroutput</sgmltag>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">quote</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
An inline quotation. This tag typically inserts
|
|
quotation marks for you, so you would write <sgmltag
|
|
class="starttag">quote</sgmltag>This is a
|
|
quote<sgmltag class="endtag">quote</sgmltag> rather
|
|
than "This is a quote". This usage may be a little
|
|
bulkier, but it does allow for automated formatting
|
|
of all quoted material in the document. Thus, if
|
|
you wanted all quotations to appear in italic, you
|
|
could make the change once in your stylesheet,
|
|
rather than doing a search and replace throughout
|
|
the document. For larger chunks of quoted text, you
|
|
can use <sgmltag
|
|
class="starttag">blockquote</sgmltag>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">note</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Insert a side note for the reader. By default, the
|
|
SGML processor usually prefixes the content with
|
|
"Note:". You can change this text by adding a
|
|
<sgmltag class="starttag">title</sgmltag> element.
|
|
Thus, to add a visible FIXME comment to the
|
|
documentation, you might write:
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
<note>
|
|
<title>FIXME</title>
|
|
<para>This section needs more info about...</para>
|
|
</note>
|
|
]]></programlisting>
|
|
<para>
|
|
The results will look something like this:
|
|
</para>
|
|
<note>
|
|
<title>FIXME</title>
|
|
<para>This section needs more info about...</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">sgmltag</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Used for inserting SGML tags, etc., into a SGML
|
|
document without resorting to a lot of entity
|
|
quoting, e.g., &lt;. You can change the
|
|
appearance of the text with the <sgmltag
|
|
class="attribute">class</sgmltag> attribute. Some
|
|
common values of this are
|
|
<literal>starttag</literal>,
|
|
<literal>endtag</literal>,
|
|
<literal>attribute</literal>,
|
|
<literal>attvalue</literal>, and even
|
|
<literal>sgmlcomment</literal>. See this SGML file,
|
|
<filename>documentation/documentation.sgml</filename>,
|
|
for examples.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">prompt</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
The text used for a computer prompt, for example a
|
|
shell prompt, or command-line application prompt.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">replaceable</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Meta-text that should be replaced by the user, not
|
|
typed in literally, e.g., in command descriptions
|
|
and <parameter>--help</parameter> outputs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">constant</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A programming constant, e.g.,
|
|
<constant>MAX_PATH</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">symbol</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A symbolic value replaced, for example, by a
|
|
pre-processor. This applies primarily to C macros,
|
|
but may have other uses. Use the <sgmltag
|
|
class="starttag">constant</sgmltag> tag instead of
|
|
<sgmltag class="starttag">symbol</sgmltag> where
|
|
appropriate.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">function</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A programming function name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">parameter</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Programming language parameters you pass with a
|
|
function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">option</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Parameters you pass to a command-line executable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">varname</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Variable name, typically in a programming language.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">type</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Programming language types, e.g., from a typedef
|
|
definition. May have other uses, too.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">structname</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a C-language <type>struct</type>
|
|
declaration, e.g., <structname>sockaddr</structname>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">structfield</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A field inside a C <type>struct</type>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">command</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
An executable binary, e.g., <command>wine</command>
|
|
or <command>ls</command>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">envar</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
An environment variable, e.g, <envar>$PATH</envar>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">systemitem</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A generic catch-all for system-related things, like
|
|
OS names, computer names, system resources, etc.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">email</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
An email address. The SGML processor will typically
|
|
add extra formatting characters, and even a
|
|
<literal>mailto:</literal> link for HTML pages.
|
|
Usage: <sgmltag
|
|
class="starttag">email</sgmltag>user@host.com<sgmltag
|
|
class="endtag">email</sgmltag>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">firstterm</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Special emphasis for introducing a new term. Can
|
|
also be linked to a <sgmltag
|
|
class="starttag">glossary</sgmltag> entry, if
|
|
desired.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<title>Item Listing Elements</title>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">itemizedlist</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
For bulleted lists, no numbering. You can tweak the
|
|
layout with SGML attributes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">orderedlist</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A numbered list; the SGML processor will insert the
|
|
numbers for you. You can suggest numbering styles
|
|
with the <sgmltag
|
|
class="attribute">numeration</sgmltag> attribute.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">simplelist</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A very simple list of items, often inlined. Control
|
|
the layout with the <sgmltag
|
|
class="attribute">type</sgmltag> attribute.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">variablelist</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
A list of terms with definitions or descriptions,
|
|
like this very list!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<title>Block Text Quoting Elements</title>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">programlisting</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Quote a block of source code. Typically highlighted
|
|
in the output and set off from normal text.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">screen</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Quote a block of visible computer output, like the
|
|
output of a command or chunks of debug logs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<title>Hyperlink Elements</title>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">link</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Generic hypertext link, used for pointing to other
|
|
sections within the current document. You supply
|
|
the visible text for the link, plus the name of the <sgmltag
|
|
class="attribute">id</sgmltag> attribute of the
|
|
element that you want to link to. For example:
|
|
<programlisting><link linkend="configuring-wine">the section on configuring wine</link>
|
|
...
|
|
<sect2 id="configuring-wine">
|
|
...</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">xref</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
In-document hyperlink that can generate its own
|
|
text. Similar to the <sgmltag
|
|
class="starttag">link</sgmltag> tag, you use the
|
|
<sgmltag class="attribute">linkend</sgmltag>
|
|
attribute to specify which target element you want
|
|
to jump to:
|
|
</para>
|
|
<para>
|
|
<programlisting><xref linkend="configuring-wine">
|
|
...
|
|
<sect2 id="configuring-wine">
|
|
...</programlisting>
|
|
</para>
|
|
<para>
|
|
By default, most SGML processors will autogenerate
|
|
some generic text for the <sgmltag
|
|
class="starttag">xref</sgmltag> link, like
|
|
<quote>Section 2.3.1</quote>. You can use the
|
|
<sgmltag class="attribute">endterm</sgmltag>
|
|
attribute to grab the visible text content of the
|
|
hyperlink from another element:
|
|
</para>
|
|
<para>
|
|
<programlisting><xref linkend="configuring-wine" endterm="config-title">
|
|
...
|
|
<sect2 id="configuring-wine">
|
|
<title id="config-title">Configuring Wine</title>
|
|
...</programlisting>
|
|
</para>
|
|
<para>
|
|
This would create a link to the
|
|
<symbol>configuring-wine</symbol> element,
|
|
displaying the text of the
|
|
<symbol>config-title</symbol> element for the
|
|
hyperlink. Most often, you'll add an <sgmltag
|
|
class="attribute">id</sgmltag> attribute to the
|
|
<sgmltag class="starttag">title</sgmltag> of the
|
|
section you're linking to, as above, in which case
|
|
the SGML processor will use the target's title text
|
|
for the link text.
|
|
</para>
|
|
<para>
|
|
Alternatively, you can use an <sgmltag
|
|
class="attribute">xreflabel</sgmltag> attribute in
|
|
the target element tag to specify the link text:
|
|
</para>
|
|
<programlisting><sect1 id="configuring-wine" xreflabel="Configuring Wine"></programlisting>
|
|
<note>
|
|
<para>
|
|
<sgmltag class="starttag">xref</sgmltag> is an
|
|
empty element. You don't need a closing tag for
|
|
it (this is defined in the DTD). In SGML
|
|
documents, you should use the form <sgmltag
|
|
class="starttag">xref</sgmltag>, while in XML
|
|
documents you should use
|
|
<sgmltag><xref/></sgmltag>.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">anchor</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
An invisible tag, used for inserting <sgmltag
|
|
class="attribute">id</sgmltag> attributes into a
|
|
document to link to arbitrary places (i.e., when
|
|
it's not close enough to link to the top of an
|
|
element).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">ulink</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Hyperlink in URL form, e.g., <ulink
|
|
url="http://www.winehq.com">http://www.winehq.com</ulink>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><sgmltag class="starttag">olink</sgmltag></term>
|
|
<listitem>
|
|
<para>
|
|
Indirect hyperlink; can be used for linking to
|
|
external documents. Not often used in practice.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Multiple SGML files</title>
|
|
<para>
|
|
How to split an SGML document into multiple files...
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="sgml-environment">
|
|
<title>The SGML Environment</title>
|
|
|
|
<para>
|
|
You can write SGML/DocBook documents in any text editor you
|
|
might find (although as we'll find in <xref
|
|
linkend="emacs-psgml">, some editors are more friendly for
|
|
this task than others). However, if you want to convert
|
|
those documents into a more friendly form for reading, such
|
|
as HTML, PostScript, or PDF, you will need a working SGML
|
|
environment. This section attempts to lay out the various
|
|
SGML rendering systems, and how they are set up on the
|
|
popular Linux distributions.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title>DSSSL Environment</title>
|
|
<para>
|
|
Explain tools and methodologies..
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>XSLT Environment</title>
|
|
<para>
|
|
Explain tools and methodologies...
|
|
</para>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="emacs-psgml">
|
|
<title>PSGML Mode in Emacs</title>
|
|
<para>
|
|
Although you can write SGML documentation in any simple text
|
|
editor, some editors provide extra support for entering SGML
|
|
tags, and for verifying that the SGML you create is valid.
|
|
SGML has been around for a long time, and many commercial
|
|
editors exist for it; however, until recently open source
|
|
SGML editors have been scarce.
|
|
</para>
|
|
<note>
|
|
<title>FIXME</title>
|
|
<para>
|
|
List the available commercial and open source SGML
|
|
editors.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
The most commonly used open source SGML editor is Emacs,
|
|
with the PSGML <firstterm>mode</firstterm>, or extension.
|
|
Emacs does not supply a GUI or WYSIWYG (What You See Is What
|
|
You Get) interface, but it does provide many helpful
|
|
shortcuts for creating SGML, as well as automatic
|
|
formatting, validity checking, and the ability to create
|
|
your own macros to simplify complex, repetitive actions.
|
|
We'll touch briefly on each of these points.
|
|
</para>
|
|
<para>
|
|
The first thing you need is a working installation of Emacs
|
|
(or XEmacs), with the PSGML package. Most Linux
|
|
distributions provide both as easy-to-install packages.
|
|
</para>
|
|
<para>
|
|
Next, you'll need a working SGML environment. See <xref
|
|
linkend="sgml-environment"> for more info on setting that
|
|
up.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="docbook-build">
|
|
<title>The DocBook Build System</title>
|
|
|
|
<sect3 id="docbook-infrastructure">
|
|
<title>Basic Infrastructure</title>
|
|
<para>
|
|
How the build/make system works (makefiles, db2html,
|
|
db2html-winehq, jade, stylesheets).
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="docbook-tweaking">
|
|
<title>Tweaking the DSSSL stylesheets</title>
|
|
<para>
|
|
Things you can tweak, and how to do it (examples from
|
|
default.dsl and winehq.dsl).
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="docbook-generating">
|
|
<title>Generating docs for Wine web sites</title>
|
|
<para>
|
|
Explain make_winehq, rsync, etc.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
|
|
End:
|
|
-->
|