Matt Dew
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 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.
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
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.
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
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.
CSS stylesheets are used to style the generated HTML output.
CSS styles are tied to tags in the XML. For example, the
"
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.
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.
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).
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: