Getting Started Writing GNOME Documentation

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

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:

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.

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.

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.

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.

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.

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.

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.

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.

Converting documents from SGML to XML requires a few changes.

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.

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 http://mail.gnome.org/mailman/listinfo/gnome-doc-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.