WritingDocumentation

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.

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.

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.

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.