GNOME Documentation System

DocBook is a markup language, like HTML, for technical and computer documentation, papers, and books. The GNOME Documentation Project uses DocBook to mark up GNOME documentation. The GDP currently uses version 4.1.2 of DocBook. DocBook SGML is used with gtk-doc for developer documentation while DocBook XML is used for end user documentation.

The main advantage of DocBook is its single-source multiple-output nature. Only one DocBook source file is needed to make many different outputs. From the same DocBook file the GDP lets the user view the documentation as HTML with Yelp and can provide a print copy, usually in PDF.

The GDP uses the XSL language to exploit DocBook's multi source nature. XSLT stylesheets convert DocBook into HTML, which Yelp displays. XSLT stylesheets are also used to convert DocBook into FO, an XML print specification, which is in turn converted to PDF or PS files. If any other format is needed the GDP could use an XSLT stylesheet to convert the DocBook files into another format such as man or info pages.

DocBook focuses on the document content, leaving presentation details to XSLT. For example all the applications within DocBook use the <application> tag. The stylesheets determine how the text inside the tag looks. Authors need not concern themselves, for example, with whether all applications will be in bold text or italics or whether the applications should not have any special formatting, focusing instead on what ideas the documentation should convey to the readers.

At the core of the GNOME help system is Yelp. Yelp provides a unified interface to several distinct documentation systems on Linux/Unix systems: man pages, info pages, Linux Documentation Project (LDP) documents, GNOME application documentation, and other GNOME documents.

Yelp works by getting a list of all documentation installed on your system from Scrollkeeper, documentation cataloging system used by GNOME, LDP, and other projects. Thus, the documentation that appears in the Yelp is specific to each computer and will typically only represent software that is installed on the computer.

GNOME uses the documentation presented by all the various GNOME components and applications installed on the system to present a complete and customized documentation environment. Yelp describes only components which are currently installed on a users system. Some of this documentation, such as the User's Guide, will be combined in such a way that it appears to be a single document.

By using such a system, you can be sure that any GNOME application you install that has documentation will show up in the index, table of contents, and any search you do in the help browser.

Yelp also integrates the conversion from DocBook to HTML. Yelp takes the DocBook document and runs a XSL processor, xsltproc, which uses a stylesheet to convert the DocBook file to a HTML file. Yelp also uses the GDP's own stylesheets on top of Norman Walsh's stylesheets. This allows the appearance of the all GNOME documentation to change with only altering one specific stylesheet. Using a custom stylesheet gives GNOME a custom help environment.

Scrollkeeper works with Yelp providing Yelp with the location of the local documentation, a TOC for that document, searching, and indexing abilities based on metadata gathered about the document. Scrollkeeper is a document cataloging system using Open Source Metadata Framework (OMF) files to provide metadata about each document installed in Scrollkeeper's catalog. Scrollkeeper is only meant to catalog documentation available locally on the user's system.

Scrollkeeper uses metadata from OMF files provided with each piece of documentation to categorize the document in its catalog. This catalog is then accessed by Yelp to build the links when Yelp starts up. Currently the OMF files aren't used for anything else, but in future versions of Scrollkeeper it will be utilized.

Scrollkeeper uses DocBook <indexterm> tags in the documentation to build an index. The index is a collection of words which refer to a specific document. In Yelp you can search through these words and view the document they coorespond to.

Subversion (SVN) is a tool that allows multiple developers to concurrently work on a set of documents, keeping track of the modifications made by each person. The files are stored on a server and each developer checks files out, modifies them, and then checks in their modified version of the files. Many GNOME programs and documents are stored in the Subversion repository. The GNOME Subversion server allows users to anonymously check out files. Most GDP members will access the repository without a login to download the most up-to-date version of documentation or programs. Modified documents will typically be emailed to the the application developer. Core GDP members may also be granted login privileges so they may commit modified files directly to the Subversion repositories. Below is a simple tutorial which will take you through the basics of using Subversion. A more complete guide is Version Control with Subversion.