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. Using this system and the variety of tools is necessary to write good documentation for GNOME. This chapter gives a brief overview describing all 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 markup GNOME documentation. DocBook SGML is used with gtk-doc for developer documentation while DocBook XML is used for end user documentation.
The main advantage of using DocBook is its multi source nature. This means 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. This lets the GDP provide the user many different output formats from a single source file.
The GDP uses the XSL language exploit DocBook's multi source nature. XSLT stylesheets are used to convert DocBook into HTML which Yelp displays. XSLT stylesheets are also used to convert DocBook into FO, a XML print specification, which is in turn converted to PDF or PS files. If any other format is requested the GDP could use a XSLT stylesheet to convert the DocBook files into another format such as man or info pages.
The multi source nature of DocBook allows the markup tags to concentrate on content of the document instead of how the content is presented. DocBook only marks up the content of document. For example all the applications within DocBook use the <application> tag. The role of the stylesheets is to determine how the text inside the tag looks. Whether all applications will be in bold text or italics or whether the applications should not have any special formatting. With this powerful idea the documenter need not worry about how the document will be displayed, but rather 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 type 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:
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, texinfo pages, Linux Documentation Project (LDP) documents, GNOME application documentation, and other GNOME documents.
Yelp works by searching standard directories for documents, through Scrollkeeper, which are to be presented. 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 Writing Application and Applet Manuals below.
Applications should have a Help button on screens on which users may need help. These Help 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.
Context sensitive help is a system which will allow the user to query any part (button, widget, etc.) of an application window. This is done by either entering a CS Help mode by clicking on an icon or by right clicking on the application part and selecting "What's This" or whatever is decided on at the time. Context sensitive help is described in more detail in Writing Context Sensitive Help (coming in GNOME-3.0) below.
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 and only source of documentation. 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. This document will supplement the various documentation in critical applications.
Aside from the GNOME User Guide, there are several other documents to help new users learn GNOME, including the GNOME FAQ, GNOME Installation and Configuration Guide, and the GNOME Administrators Guide.
There are many White Papers, Tutorials, HOWTO's and FAQ's to make programming GNOME and GNOME applications as easy as possible.
API documentation is also available for the GNOME libraries. This is detailed documentation of the code that is used to build GNOME apps. You can keep up with the GNOME API docs on the GNOME API Reference page.
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.
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.