The GNOME Documentation System consists of DocBook, Yelp (GNOME Help Browser), Scrollkeeper (document cataloging system), and the XML tools (called DocBook Tools) to transform and check the documentation. Use of this system is necessary to write good documentation for GNOME. This chapter gives a brief overview describing the tools in the 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.
There are many resources available to help you learn DocBook, including this manual. The following resources on the web are useful for learning DocBook:
http://www.docbook.org — Norman Walsh's DocBook: The Definitive Guide. Online O'Reilly book on using DocBook. Contains an excellent element reference. May be too formal for a beginner.
A Practical Introduction to DocBook — The Open Source Writers Group's introduction to using DocBook. This is an excellent HOW-TO article on getting started.
Getting Going with DocBook: Notes for Hackers — Mark Galassi's introduction to DocBook for hackers. This has to be one of the first introductions to DocBook ever - still as good as it ever was.
Dave Pawson's DocBook FAQ — Dave Pawson's FAQ on everything DocBook related. He discusses references, tools, catalogs, and stylesheets in a concise FAQ format. One of the best resources to find answers to common questions and problems about DocBook.
FreeBSD Documentation Project Primer for New Contributors — FreeBSD documentation project primer. Chapter 4.2 provides a very good introduction to writing documentation using DocBook. Note that it also describes some custom extensions of DocBook; fortunately, they are clearly marked as such.
Norman Walsh's book is also available in print.
The following sections of this document are designed to help documentation authors write correct and consistent DocBook:
Section , “DocBook Basics ” - Descriptions of commonly used DocBook tags.
You may also discuss specific DocBook questions with GDP members on the #docs IRC channel at irc.gnome.org and on the gnome-doc-list mailing list.
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.
The GDP uses its own DocBook stylesheets. These stylesheets are integrated into the Yelp help browser. This means you do not need to install any specific stylesheets. All you need are the standard DocBook stylesheets installed and a working XML Catalog.
If you do not wish to use Yelp to view your completed documentation, the specific GDP stylesheets can be obtained through CVS. The GDP stylesheets are in the module gnome-docu/gdp/xsl of the GNOME CVS. The top level stylesheet and the one you run through the XSL processor is general-customizations.xsl.
Since DocBook 4.0 the DocBook DTD has included support for PNG graphic files. Therefore the GDP recommends documenters use the standard DocBook DTD.
The GDP used to use a customized DTD for DocBook SGML which added support for PNG graphic files. This is no longer needed.
Every GNOME application should have an application manual. An application manual is a document specific to the particular application which explains the various windows and features of the application. Application manuals typically use screenshots (PNG format) for clarity. Writing application manuals is discussed in more detail in Section , “Writing Application and Applet Manuals” below.
Applications should have a button on screens on which users may need help. These buttons should pull up the default help browser, determined by the File Types and Programs dialog, typically Yelp. The help browser should show either the first page of the application manual, or else the relevant page thereof.
The GNOME User Guide describes the GNOME desktop environment and core components of GNOME such as the panel and nautilus. In GNOME 1.x this was the main source of documentation while sometimes duplicating existing documentation of various components. In GNOME 2.0 this is a document for the web and for printing that is derived from various parts chosen in the system that are necessary for the new user to understand. The User Guide is the main source of documentation for basic components of the GNOME desktop such as the panel, Nautilus, and customizations.
Aside from the GNOME User Guide, there are several other documents to help new users learn GNOME, including the Introduction to GNOME, GNOME Installation and Configuration Guide, and the GNOME Administrators Guide.
CVS (Concurrent Versions System) 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 CVS. The GNOME CVS server allows users to anonymously check out CVS files. Most GDP members will need to use anonymous CVS 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 CVS privileges so they may commit modified files directly to CVS. Below is a simple tutorial which will take you through the basics of using CVS. A more complete guide is Open Source Development with CVS. The free chapters are a good guide to using CVS and can be found at http://cvsbook.red-bean.com/cvsbook.html.
To anonymously check out documents from CVS, you must first log in. From the bash shell, you should set your CVSROOT shell variable with export CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome' and then login with cvs login(there is no password, just hit return). As an example, we will use the "gnome-docu/gdp" module which contains this and several other documents. To check these documents out for the first time, type cvs -z3 checkout gnome-docu/gdp. After you have this document checked out and you would like to download any updates on the CVS server, use cvs -z3 update -Pd.
If you have been given a login for the GNOME CVS server, you may commit your file modifications to CVS. Be sure to read the following section on CVS etiquette before making any commits to CVS. To log in to the CVS server as user username with a password, you must first set your CVSROOT shell variable with export CVSROOT=':pserver:username@cvs.gnome.org:/cvs/gnome'. Log in with cvs login and enter your password. You may check out and update modules as described above for anonymous CVS access. As a login CVS user, you may also check modified versions of a file into the CVS server. To check filename into the CVS server, type cvs -z3 commit filename. You will be given a vi editor window to type in a brief log entry, summarizing your changes. Note the default editor can be changed using the EDITOR environment variable or with the -e option. You may also check in any modifications to files in the working directory and subdirectories using cvs -z3 commit. To add a new file to the CVS server, use cvs -z3 add filename, followed by the commit command.
Because files in CVS are typically used and modified by multiple developers and documentation authors, users should exercise a few simple practices out of courtesy towards the other CVS users and the project leader. First, you should not make CVS commits to a package without first discussing your plans with the project leader. This way, the project leader knows who is modifying the files and generally, what sort of changes/development is being done. Also, whenever a CVS user commits a file to CVS, they should make an entry in the CVS log and in the ChangeLog so that other users know who is making modifications and what is being modified. When modifying files created by others, you should follow the indentation scheme used by the initial author.