This page describes which tools are available for the various types of documentation one can contribute to.
If you're describing an API, the best choice is probably Doxygen. Doxygen allows you to comment your C files and headers inline, and later generates documents from same. For a good example of how to use Doxygen, take a look at the X server Distributed Multihead X Design.
Larger documents are maintained in DocBook/XML format. As of X11R7.6, almost all documentation have been converted from DocBook/SGML, Framemaker, troff, Linuxdoc and TeX to DocBook/XML. The doc/xorg-docs module contains general X Window System documentation, anything specific has been moved to the appropriate module.
Commands and public API in client-side libraries are documented in the traditional roff man page format which involves a significant learning curve.
.\"Comment: the rest of the line is a comment.
.THText Header: This is the header of a line. It contains the name of the page in capital letters followed by the section the page is to be located in. Then it contains
__vendorversion__which is replaced by the vendor version when the system is built.
.SHSection Header: Man pages contain several sections. Some are ordered according to a standard conventions. Their names are capitalized.
.B: Boldface: Print following text in boldface.
.I: Italic: Italic/underline the following text.
.P: Paragraph: Start a new paragraph.
.PPDouble paragraph (?).
.br: Break: insert a linebreak.
.R: Roman: Non-italic non-bold font
- `.BR : alternating bold and regular font
- `.RB : alternating regular and bold font
.TPTabulator: May optionally be followed by a indentation width. The next line is indented normally, any lines following this line up to the next paragraph command (ie.
.Pare indented according to the number following the command relative to the normal indentation.
\need to be escaped with a
.TH THISCOMMAND 1 ''''vendorstring'''' .SH NAME thiscommand \- describe this command .SH SYNOPSIS .B "thiscommand" .RB [ -help ] .SH DESCRIPTION Here we describe what .I thiscommand does. .PP .SH OPTIONS The following options are supported: .TP .B \-h Help. .SH FILES .SH KNOWN BUGS .SH "SEE ALSO" OTHERCOMMAND(1)
One may add additional commands between DESCRIPTION and FILES section as fit.
Just like C code is conditionally included using #ifdef, manual page text can be conditionally included as well. Use .if to test a variable and place the text between .ig and '..'.
.if !'x.VARNAME'x.' .ig If $(VARNAME) is empty, this text is shown ..
.if 'VARNAME'' .ig If $(VARNAME) is empty, this text is skipped ..
This table summarizes modules with User's documentation, Developer's documentation or functional specifications in DocBook/XML format. The DocBook/XML input format is converted to HTML, PDF, PS and plain text. When installed, the documentation input source (xml) is also installed as it can be read directly by platform help delivery system such as gnome-help.
|Module||Dir||In Fmt||Tool||Out Fmt||Inst Fmt||Dist Fmt||Options|
This table summarizes modules with man pages that are not hand written in the troff format. The input format may be DocBook/XML or asciidoc. The generated man pages files are included in the tarball.
|Module||Dir||In Fmt||Tool||Mid Fmt||Tool||Out Fmt||Inst Fmt||Dist Fmt|
This table summarizes modules with API Developer's documentation generated using Doxygen. The source for the generated HTML files is the C code which is already included in the tarball.
|Module||Dir||In Fmt||Tool||Out Fmt||Inst Fmt||Options|
- In Fnt
- the original source format stored in git (xml refers to docbook xml)
- Mid Fmt
- an intermediate format that is sometimes distributed in the tarball with the original source format
- Out Fmt
- the final format generated by the named tool
- Inst Fmt
- the formats in which the documents are installed in $docdir
- Dist Fmt
- the formats in which documents are included in the tarball. May contain generated formats (shown in bold)
- the name of the (./configure --help) option used to control the generation of documents
- the default value of the configure option if none is supplied
A number of tools are required to generate the documentation. They are not all available on all platforms, and if they are, not always at a recent enough level. It is already common practice to skip the generation process if a tool is missing. In addition, some platforms have asked for a configure option to turn any tool off. This prevents breaking the build when the level of the tool is known to be too old.
A number of macros have been written in the util-macros package which provide such facility. When used consistently, it makes controlling the documentation build process easier. Some macros can be invoked with a desired minimum version. The documentation will not be generated if the installed tool does not meet this request. Consult util/macros/xorg-macros.m4.
XORG_WITH_XMLTO --with-xmlto XORG_WITH_ASCIIDOC --with-asciidoc XORG_WITH_DOXYGEN --with-doxygen XORG_WITH_FOP --with-fop XORG_WITH_XSLTPROC --with-xsltproc XORG_CHECK_SGML_DOCTOOLS
In the simpler scenario, when a document is generated in it's output format, say pdf, it is installed in a location known by it's makefile variable $docdir. This is done by the makefile target
Distributing refers to the creation of a compressed archive file (tarball) containing all the package source suitable to be independently built by a third party. These are published on the X.Org web site. It must contain the documentation input format, so the output can be regenerated and installed on the target computer.
As discussed above, some platforms do not have all the documentation tools to generate the documents from a tarball. This prevents them from installing the documents to the target computer. To solve this issue, generated files have been added in the tarball, either in the final output format or in a format for which tools are known to be available on all platforms.
The makefiles have to tweak the targets to take the availability of the tools into consideration. This is where the macros are useful in providing the necessary makefile variables. It is understood that platforms lacking documentation tools will not be able to create a tarball for distribution, as it would be missing the generated files.
The wiki New Module Guidelines describes the directory structure for each module. It generally states that man pages are to be in the
man directory and that documents of any kind go in the
doc directory. There are a number of modules where documents and man pages are in the same directory. Sometimes
man is under
doc is named
specs. The guidelines should be followed. When multiple documents are to be generated, subdirectories can be used as appropriate.