Writing Documentation

Introduction

This page describes which tools are available for the various types of documentation one can contribute to.

Doxygen

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.

DocBook

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.

Man Pages (troff with "man" macros)

Commands and public API in client-side libraries are documented in the traditional roff man page format which involves a significant learning curve.

Commands:

• .\" Comment: the rest of the line is a comment.
• .TH Text 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.
• .SH Section 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. .PP Double 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
• .TP Tabulator: 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. .SH, .TP, .P are indented according to the number following the command relative to the normal indentation.
• .fi: (?)
• .nf: (?)
• Characters .,-, \ need to be escaped with a \. Ie: \.,\-.

Man Page Skeleton

.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.

Conditional Text

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
..

Current Module Documents (January 2014)

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
app/xfs	doc	xml	xmlto	txt/ps/pdf/html	not installed	xml	enable-devel-docs
app/xrx	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
doc/xorg-docs	general	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
						specs	enable-specs
lib/libICE	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
						specs	enable-specs
lib/libSM	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
lib/libX11	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
lib/libXaw	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
lib/libXdmcp	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
lib/libXext	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
lib/libXfont	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-devel-docs
lib/libXi	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
						specs	enable-specs
lib/libXmu	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
lib/libXt	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
lib/libxtrans	doc	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-docs
lib/libXtst	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/bigreqsproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/fontsproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/inputproto	specs	txt	asciidoc	txt/html	txt/html	txt	enable-specs
proto/kbproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/recordproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/scrnsaverproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/x11proto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/xcmiscproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
proto/xextproto	specs	xml	xmlto	txt/ps/pdf/html	txt/ps/pdf/html/xml	xml	enable-specs
xserver	doc	xml	xmlto	txt/pdf/html	not installed	xml	enable-devel-docs
xserver	doc/dtrace	xml	xmlto	txt/pdf/html	installed	xml	enable-docs
xserver	hw/dmx/doc	xml	xmlto	txt/pdf/html	not installed	xml	enable-devel-docs
xserver	hw/xfree86/doc	xml	xmlto	txt/pdf/html	not installed	xml	enable-devel-docs

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
lib/libXcomposite	man	xml	N/A	N/A	xmlto	troff	troff	xml+troff
lib/libXi	man	txt	asciidoc	xml	xmlto	troff	troff	txt+troff
lib/libXtst	man	xml	N/A	N/A	xmlto	troff	troff	xml+troff

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
xserver	hw/dmx/doxygen	*.[hc]	doxygen	html	not installed	enable-devel-docs
xcb/libxcb	doc/manual	*.[hc]	doxygen	html	not installed	enable-devel-docs

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)

Options

the name of the (./configure --help) option used to control the generation of documents

Default

the default value of the configure option if none is supplied

Documentation Tooling

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

Installing and Distributing

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 install.

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.

Generated files in the tarball

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.

Directory structure

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, sometimes doc is named spec or specs. The guidelines should be followed. When multiple documents are to be generated, subdirectories can be used as appropriate.