# Getting Started Writing GNOME Documentation

## Selecting a Document

The most frequently asked question of new contributors who join the GDP is which document should I start with?. Because most people involved are volunteers, we do not assign projects and applications to write documents for. The first step is all yours - you must decide what about GNOME interests you most and find out if it has complete documents or not.

It is also important to spend some time with GNOME to make sure you are familiar enough with it to be authoritative in your writing. The best way to do this is to just sit down and play with GNOME as much as possible before starting to write.

The easiest way to get started is to improve existing documentation. If you notice some inaccuracies or omissions in the documentation, or you think that you can explain the material more clearly, just send your suggestions to the author of the original documentation or to the GNOME documentation project at gnome-doc-list@gnome.org.

## Installing DocBook

All documentation for the GNOME project is written in XML using the DocBook DTD. There are many advantages to using this for documentation, not least of which is the single source nature of XML. To contribute to the GDP you should learn to use DocBook.

### Note

To get started writing for the GDP you do not need to rush out and learn DocBook - if you feel it is too much to handle for now, you can submit plain ASCII text to the gnome-doc-list mailing list and a volunteer will mark it up for you. Seeing your document marked up will also be a great way for you to start learning DocBook.

There isn't a standard set of packages to install DocBook XML and make it work locally. Each distribution installs DocBook XML a bit differently with various degrees of support for needed features.

### RPM Users

Download and install the following RPM packages from Tim Waugh's DocBook page:

- xml-common

- docbook-dtds

- docbook-style-xsl

- libxml2

- libxslt

This will setup a basic build environment to convert DocBook XML documents into HTML. If you wish to convert your DocBook document into multiple formats, you will need to download and install the following RPM packages from Tim Waugh's DocBook page:

- xmltex

- passivetex

- xmlto

The RPMs for docbook-dtds and docbook-style-xsl might not install a correct entry in your XML Catalog. To check if there is a proper XML Catalog entry for the DTD run the command $ `xmlcatalog `/etc/xml/docbook` "-//OASIS//DTD DocBook XML V4.1.2//EN"`. If this command returns a URI which starts with `file://` then the DTD is correctly installed in the XML Catalog. However, if the command returns `No entry for PUBLIC` then the DTD is not installed in the XML Catalog.

To check if there is a proper XML Catalog entry for the stylesheets run the command $ `xmlcatalog `/etc/xml/docbook` "http://docbook.sourceforge.net/release/xsl/1.49/"`. If this command returns a URI which starts with `file://` then the stylesheet is correctly installed in the XML Catalog. However, if the command returns `No entry for SYSTEM` then the stylesheet is not installed in the XML Catalog.

### Debian Users

To fetch all required packages, simply run:

    			# apt-get install libxslt1
    			# apt-get install docbook-xsl

Debian packages do not install a XML Catalog currently. Since a XML Catalog is essential to view DocBook documents quickly and easily, you will need to install a XML Catalog by hand. This is not too hard because there is a nice script buildDocBookCatalog which will install a XML Catalog. If you want the XML Catalog to be installed in `/etc/xml/` you need to run the script as the root user. However, if you want the XML Catalog to be install in your home directory you need to run the script as a regular user.

If the program `xmlcatalog` is not installed in `/usr/bin` you might need to alter the buildDocBookCatalog script. Just edit the file in your favorite editor and replace /usr/bin/xmlcatalog with xmlcatalog. Then as long as the program `xmlcatalog` is in your path you should be fine.

### Installing from Source

To install the DocBook tools from source get the latest version of libxml2 and libxslt and compile it. This will install the basic tools for working with XML files. Next you will need to download the DocBook XML DTD and DocBook XSL Stylesheets (docbook-xsl). These need to be unpacked and placed in the `/usr/local/share/xml/docbook/xml-dtd-4.1.2` directory and the `/usr/local/share/xml/docbook/xsl-stylesheets-1.48` directory respectively. Now you need to install a XML Catalog so the DTD and stylesheets can be located locally. This is not too hard because there is a nice script buildDocBookCatalog which will install a XML Catalog. If you want the XML Catalog to be install in `/etc/xml/` you need to run the script as the root user. However, if you want the XML Catalog to be installed in your home directory you need to run the script as a regular user.

If the program `xmlcatalog` is not installed in `/usr/bin` you might need to alter the buildDocBookCatalog script. Just edit the file in your favorite editor and replace /usr/bin/xmlcatalog with xmlcatalog. Then as long as the program `xmlcatalog` is in your path you should be fine.

### Editors

There are many editors on Linux and UNIX systems available to you. Which editor you use to work on the XML documents is completely up to you, as long as the editor is able to preserve XML and produce the source in a format that is readable by everyone.

Probably the two most popular editors available are Emacs and vi. These and other editors are used regularly by members of the GDP. Emacs has a major mode, psgml, for editing DocBook files which can save you time and effort in adding and closing tags. You will find the psgml package in your distribution of Linux. If your distribution does not use binary packages, the source code for psgml is available at http://psgml.sourceforge.net.

## Using DocBook Tools

There are three tools used with DocBook documents. Xmllint checks the documentation to make sure it is valid DocBook and follows all the rules of XML and the DTD. Xsltproc transforms the document from DocBook to a variety of document formats, including HTML, using XSL stylesheets. Xmlcatalog generates, updates, and checks to make sure the XML catalog is working. You may have used these tools installing DocBook. This isn't meant to be a complete guide to these tools, but an introduction to famaliarize you with the common DocBook tools. If you want more information about any of them consult http://xmlsoft.org or view their respective man pages.

### Using xmllint

There are many different ways to use xmllint. Xmllint can check the document conforms to the XML specification. It can check the document validates against the declared DTD or you can force xmllint to use another DTD. Xmllint resolves Xinlcudes and can then check the document validates against a DTD after the Xinclude resolution is complete. There are many options to use with xmllint.

The standard way to use xmllint to show just the errors is to type: `xmllint --noout --noent --valid filename.xml` . The option `--noout` suppresses the output of the XML document. Xmllint normally outputs the XML document to the screen and this option stops that behavior. The option `--noent` resolves any entities which are declared in the document. This allows xmllint to check the validity of the document once the entities are replaced in the document. The last option `--valid` validates the document against the declared DTD. By default xmllint just checks to see if the document is well-formed XML. This option tells xmllint to check and make sure the document conforms to the DTD too.

When xmllint does not display any errors and returns to the command prompt, the document is valid.

Occasionally you want to validate a document against another DTD. The way to use xmllint to check for errors is to type: `xmllint --noout --noent --dtdvalid file:///path/to/dtd/filename.dtd filename.xml`. The option `--dtdvalid` lets you validate the document against a different DTD than the one which was declared in the document. The option has two parts. The first part is the option itself and the second part is the URL to the DTD. In the example above the URL is for a DTD on your local file system. Xmllint can also retreive the DTD from the internet with a valid URL. This is useful to test if the document will conform to two different versions of the DTD.

Sometimes you have a large document and use XIncludes so you have multiple XML files each with their own DTD. The way to use xmlllint to check for errors is to type: `xmllint --noout --noent --xinclude --postvalid filename.xml`. There are two new options `--xinclude` and `--postvalid`. The option `--xinclude` processes the the document using the XInclude namespace. After the processing is complete you want to check to make sure the entire document conforms to the DTD. The option `--postvalid` validates the document once all the processing is complete. So, after the XInclude processing is done xmllint is told to validate the document.

### Using xsltproc

The program to convert DocBook XML to a variety of output formats is xsltproc. It is a very quick and powerful XSLT processor. This means it can transform large documents from DocBook to HTML using XSLT stylesheets in seconds instead of minutes.

To transform a XML file using a XSLT stylesheet type: `xsltproc --noout -o output stylesheet.xsl filename.xml` . This takes the file `filename.xml` and applies the XSL stylesheet `stylesheet.xsl`. The output of this transformation is saved in the file `output`. The option `--noout` surpresses the output of the transformation to the screen. Using the option `-o` the output of the transformation is saved in the `output` file. If the stylesheet you are using saves the document in multiple files, also called chunking, the option `-o` will save the files in the specified directory. This is an important distinction. When the stylesheet saves the document to a single file, `-o` specifies the output file. When the stylesheet saves the document in multiple files, `-o` specifies the output directory.

### Using xmlcatalog

The program xmlcatalog is a versatile application which creates, edits, and deletes entries in the XML catalog. The XML catalog is similar to the SGML catalog in function, but very different in implementation. XML catalogs are XML files which provide lookup and redirection for DTDs and URIs. This allows the URL given in the DTD declaration of a XML file to be used in the lookup of the DTD locally in your system. XML catalogs can also cascade so one XML catalog can be redirected to another.

To create an XML Catalog type: `xmlcatalog --noout --create /etc/xml/catalog`. An empty XML Catalog will be created in the directory `/etc/xml` as the file `catalog`. Make sure you have write permissions to the directory so the file can be created. Now that you have an empty XML Catalog you need to populate the catalog. To add a DTD to the catalog type: `xmlcatalog --noout --add "public" ""-//OASIS//DTD DocBook XML V4.1.2//EN" "file://usr/share/xml/docbook/docbookx.dtd" /etc/xml/catalog`. This will redirect all queries for the DocBook V4.1.2 DTD to the location of the DocBook DTD, in this example `file://usr/share/xml/docbook/docbookx.dtd`. The last option in the command is the location of the XML Catalog. This should be the same place you created the XML Catalog.

### Creating Something Useful with your Docs

To view your DocBook documents you've made you need to run Yelp from the commandline. This can be done by typing `yelp `ghelp:/path/to/filename.xml`` to have Yelp display the XML file.

If you do not want to use Yelp to view your documentation, you can use xsltproc with the GNOME stylesheets. The program xsltproc takes the DocBook file and using the GNOME stylesheets makes a new HTML file. The HTML file can be viewed from your favorite web browser. You will need to download the GNOME XSL stylesheets in the module gnome-docu/gdp/xsl in GNOME SVN. To run xsltproc type `xsltproc `general-customizations.xsl` `filename.xml`` to produce the HTML.

Producing the HTML directly from the XML is not recommended. The user documentation will be viewed in Yelp. Therefore to see how the docs will look to the user the GDP recommends you use Yelp to view the documentation. An alternative way to view the documentation is given to those who may not have Yelp installed.

## GDP Document Templates

Templates for various types of GNOME documents are found at the GDP Document Templates website. They are kept in SVN at `gnome-doc-utils/trunk/data/templates`. These templates are meant to guide you through the process of making documentation. They contain the structure of the `articleinfo` section. The basic structure of a document is outlined. Many different elements are marked up in DocBook such as itemized lists, variable lists, and figures. It is okay to change the templates to fit the application you are writing documentation for. Changing the format of the `articleinfo` section is not recommended as the output will not look nice.

## Converting GNOME 1.x Documentation to GNOME 2

GNOME 2 documentation is written in DocBook XML, version 4.1.2.

We use DocBook because it provides structured semantic markup, allowing publication in a variety of media. We use XML because of the more flexible tool kit available to use with it.

### Conversion

Converting documents from SGML to XML requires a few changes.

The DTD

  A new DTD is needed at the start of the document:

      <?xml version="1.0"?>
      <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
      ]>

  Note that the system identifier is required.
Graphic

  The `graphic` tag is deprecated in DocBook version 4, and while it will still work, we plan to change to `figure` and `mediaobject` of several flavors, depending on whether the image is a large figure, a small figure, or a screenshot. This will utilize the greater flexibility of DocBook 4.1.2 and specify the content of the images more accurately.

  A large figure is a large image which isn't a screenshot. This can be a variety of images. The markup for a large figure:

      	<figure id="id">
      	  <title>Figure Description</title>
      	  <mediaobject>
      	    <imageobject>
      	      <imagedata fileref="path/to/image.png" format="PNG"/>
                  </imageobject>
      	    <imageobject>
      	       <imagedata fileref="path/to/image.eps" format="EPS"/>
                  </imageobject>
      	    <textobject>
      	       <phrase>Acessibility description</phrase>
      	    </textobject>
            </mediaobject>
          </figure>

  A small figure is a small image which isn't a screenshot. This can be a variety of things. The markup for a small figure:

        <mediaobject id="id">
      	<imageobject>
      	  <imagedata fileref="path/to/image.png" format="PNG"/>
      	</imageobject>
      	<imageobject>
      	  <imagedata fileref="path/to/image.eps" format="EPS"/>
      	</imageobject>
      	<textobject>
      	  <phrase>Acessibility description</phrase>
      	</textobject>
        </mediaobject>

  A screenshot is an image which is taken of the desktop or of an application or a dialog box. The markup for a screenshot:

        <figure id="id">
          <title>Figure Description</title>
      	<screenshot>
      	  <mediaobject>
      	    <imageobject>
      	      <imagedata fileref="path/to/image.png" format="PNG"/>
                  </imageobject>
      	    <imageobject>
      	       <imagedata fileref="path/to/image.eps" format="EPS"/>
                  </imageobject>
      	    <textobject>
      	        <phrase>Acessibility description</phrase>
      	    </textobject>
            </mediaobject>
          </screenshot>
        </figure>

xref

  The `xref` tag also must be closed:

      <xref linkend="mainwindow-fig" />

Artheader

  `artheader` must be replaced with `articleinfo`. The contents of the meta data for documentation has changed considerably. Refer to the GNOME 2.x templates for more information on how to write the `articleinfo` section.

## GDP Style Guide

The GDP Style Guide should be read in conjunction with this document. The Style Guide tells how to write documentation, ways to structure the documentation, and technical writing techniques. The GDP Style Guide is located at http://library.gnome.org/devel/gdp-style-guide/stable/.

## Screenshots

Most GNOME documents will have screenshots of the particular applet, application, GNOME component, or widget being discussed. As discussed previously all images for GNOME documentation should be in the PNG format. Alternatively if you wish the documentation to be printed you should also include the same images in EPS format. For the basic DocBook structure used to insert images in a document, see below.

### Screenshots in DocBook

If your document uses images you will need to take note of a few things that should take place in order for you to make use of those images in your output.

The DocBook tools and applications are smart enough to know that when you are creating html you will be using PNG files and when you are creating Postscript you will be using EPS files (you must use EPS with Postscript).

    <figure id="id">
      <title>My Picture</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="myfile.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Acessibility description</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>

If you want to create PostScript ouput, you will need to create an EPS version of your image file to be displayed in the PostScript file. There is a simple script available which allows you to change a PNG image into an EPS file easily. You can download this file - png2eps - from http://dmason.net/download/png2eps.

### Screenshot Appearance

Screenshots of windows should show GNOME's default theme, Clearlooks. (Your distribution may be using a different default.)

This is to minimize possible confusion to the reader, improve the appearance of GNOME documents, and guarantee the screenshot is readable when printed.

If you are unable to provide screenshots in this form, you should create screenshots as you wish them to appear and send an email to the gnome-doc-list mailing list requesting a GDP member reproduce these screenshots in the correct format and email them to you. Please do not send the actual images in the email but wait until you contact someone to do the screenshots for you and mail them the images.

## Application Bugs

Documentation authors tend to investigate and test applets and applications more thoroughly than most users. Often documentation authors will discover one or more bugs in the software. These bugs vary from small ones, such as mis-spelled words or missing About dialogs in the menu, to large ones which cause the applet to crash. As all users, you should be sure to report these bugs so that application developers know of them and can fix them. The easiest way to submit a bug report is by using Bug Buddy located in Applications Programming Bug Report Tool .