Developer Documentation

Matt Dew

Doxygen
1. Doxygen example
Docbook/XML
Manual Pages
Wiki
Conclusions

The purpose of the developer documentation is to help developers understand how X works. One of the major goals is to centralize all X.Org documentation in the place it belongs, the X.Org project itself.

There are four formats commonly used for X documentation:

Doxygen for code comments. This is used to generate API documentation.
Manual pages, including commands and public API in client-side libraries, are documented in the traditional roff man page format.
Project wikis for changing documentation. Projects like XCB that have frequent changes relevant to developers use wikis (usually on freedesktop.org) to keep things up-to-date yet readable.
Docbook for most other documentation. This includes the X11 protocol specification and general X Window System documentation. Module-specific documentation is kept with the module to which it belongs.

Doxygen

Doxygen is the preferred method of commenting the code in the X repositories. While some of the code is doxygen-ated, much of the core code still is not. People are welcome to help add doxygen comments to code. Adding comments is a good way to learn about X.Org internals and get used to touching the code. It is also a service to the X community. TODO: more detail so doxygen can be more useful to devs.

Doxygen example

Here is a valid comment:

/*****************************************************************************
 **
 ** xcb_generic_iterator_t xcb_render_pictformat_end
 ** 
 ** @param xcb_render_pictformat_iterator_t i
 ** @returns xcb_generic_iterator_t
 **
 *****************************************************************************/

that doxygen will use to generate a simple API section for a C function. Generating the HTML documentation from the doxygen comments is as simple as "doxygen " once the config file is generated. A simple default config file can be generated by running doxygen with no arguments. Modifying the config file is beyond the scope of this document. More information can be found on the doxygen website.

Docbook/XML

X uses Docbook/XML for normal documentation. Other than manual pages, code comments used in generating doxygen documentation and a few legacy documents, everything is now kept in Docbook format (or its AsciiDoc variant). Docbook is an open standard that is freely available; Docbook files are plain text. This means that documents can be created and edited by anyone without the need for special tools.

Some documents in the tree are kept as AsciiDoc source, and converted to DocBook as needed. AsciiDoc syntax is more wiki-like, without the verbose tags and nested structures of DocBook XML, so code diffs are easier to read. Because Docbook can be generated from AsciiDoc, the danger of format proliferation that existed in the past is reduced.

A major conversion effort by Matt Dew and others recently moved most of X's documentation to Docbook from a variety of other formats. The intent is that DocBook and AsciiDoc will be preserved as the standard formats for X documentation going forward. The format proliferation of the past caused a great deal of pain for X developers and documentation managers. Formats became outdated, with difficult-to-find tools needed to process them. The arcane knowledge about how to work with these formats was partly lost. Thus, the X developers ask that only DocBook and AsciiDoc be used. Help is available if documentation needs to be converted to these formats.

DocBook example

Here is a DocBook example showing an initial cut at a document:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE article
          PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
          "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<article id='lbxalg'>
<title>LBX X Consortium Algorithms</title>
<sect1 id='introduction'>
<title>Introduction</title>
para>This is an introduction</para>
</sect1>
</article>

To format this example:

xmlto -x /path/to/xorg-xhtml.xsl --stringparam html.stylesheet=/path/to/xorg.css xhtml-nochunks abovefile.xml

Generating DocBook output

As all documents in the X.Org tree are now Docbook files, the normal X.Org Makefiles are used for maintaining documentation. Simply invoking "make" will format the Docbook documentation. Autotools flags can be set to turn on or off specific documentation.

Currently X.Org uses the xmlto utility to generate final output from the Docbook files in text, PostScript, PDF and HTML formats. Production of Epub is planned, but not yet implemented.

Styling DocBook

CSS stylesheets are used to style the generated HTML output. CSS styles are tied to tags in the XML. For example, the "" tag denotes a program listing (source code) and the corresponding css style is ".programlisting". So adding ".programlisting {color: red}" will make all source code sections red. This sort of common tag is easily identified, but more advanced styling may be trickier. For the most part, re-using existing X stylesheets is a good strategy.

XSL stylesheets are used to style DocBook XML for PDF and PostScript output. XSL stylesheets are quite different from CSS stylesheets; they have a very steep learning curve. However, proper use of XSL styling can result in highly professional-looking PDF. For example, the X documentation is setup to allow linking between documents in the X.Org tree. This style snippet will make these links blue:

<xsl:attribute-set name="xref.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>

XSL styles can be very complicated with conditionals and loops, so pretty much anything is possible. However, too much complexity is not preferred as it increases the work for others wanting to help.

Manual Pages

Here's an example manual page:

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

This troff manual file can be installed in the system as-is for access using the normal UNIX "man" command. To see what the manual page will look like without system-wide installation:

create a path man/man1
save the filename as man/man1/thiscommand.1
export MANPATH=$MANPATH:man
man thiscommand

You can use groff to format manual pages for other purposes. For example, to produce a PDF:

groff -man -Tps thiscommand.1 >thiscommand.ps
ps2pdf thiscommand.ps

See the groff documentation for more details.

Wiki

The X.Org wiki is located at http://www.x.org/wiki. It contains a great deal of useful information. However, navigating the wiki can be a bit tricky. You can usually find what you are looking for using the search feature, by clicking on the "FindPage" entry in the title bar. (Find this link at the top of every page, right underneath the "X.Org Foundation" logo.) Google search also works well. If you're looking for hot topics, "RecentChanges" shows what pages have been recently updated.

The wiki is a community resource, and everyone is encouraged to add (constructively) to it. Wiki-work is also a good way to learn about X.Org. However, please choose the location for new pages carefully. It is easier to find information on a well-structured wiki (even if the structure seems "weird" to you).

Conclusions

There is plenty of documentation work to do. The X community is grateful for any hep you can provide, be it working on the wiki, checking that the content in the XML files is correct and up-to-date, experimenting with CSS and/or XSL styles to change the look of the output, or whatever. One of the most important aids to developers is complete, clear, accurate documentation. Always remember that other developers are just like you: good documentation makes their jobs easier; if you keep that in mind as you work, everyone benefits.

More information on documentation can be found at: