# GNOME Documentation System

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

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.

### Learning DocBook

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:

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

## GNOME Help Browser

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

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.

## GNOME Documentation Components

### GDP Stylesheets

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 Subversion. The GDP stylesheets are in the module `gnome-doc-utils/trunk/xslt/` of the GNOME Subversion.

### GDP DTD

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.

### Application Manuals

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 writingapplicationmanuals below.

### Application Help

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.

### GNOME User Guide

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.

### User Documents

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.

### Developer Documents

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 find general developer documentation on the Developer section of the GNOME Documentation Library.

### Project Documents

Some GNOME projects have documentation to maintain consistency in their product and to help new contributors get up to speed quickly. Among these are the GDP documents, such as the one you are reading now.

## Using Subversion

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.

### Initial Checkout

You can download files anonymously from the server to create a local working copy. As an example, we will check out the files for this handbook. To check out for the first time, type `svn checkout http://svn.gnome.org/svn/gnome-devel-docs/trunk/gdp-handbook/` . After you have this document checked out and you would like to download any updates from the Subversion repository, use `svn update`.

### Committing Changes

If you are a registered GNOME developer, you may use your SSH key to authenticate yourself so you can commit changes back to the Subversion repositories. Be sure to read the following section on Subversion etiquette before making any commits. To authenticate to the Subversion server as user ``username``, you will use a slightly different URL. To commit ``filename`` to the Subversion server, type `svn commit svn+ssh://`username@`svn.gnome.org/svn/gnome-devel-docs/trunk/gdp-handbook/`filename`` . You will be given an 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 ``--editor-cmd`` option.

### SVN Etiquette

Because files in Subversion are typically used and modified by multiple developers and documentation authors, users should exercise a few simple practices out of courtesy towards the other Subversion users and the project leader. First, you should not commit changes back to the Subversion repositories 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 Subversion user commits a file, they should make an entry in the Subversion 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.