Getting Started Writing GNOME Documentation
Prev |  | Next

## Getting Started Writing GNOME Documentation

### Selecting A Document

#### Document Something You Know

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 `<docs@gnome.org>`.

#### The GNOME Documentation Status Table

The GDP Documentation Status Table (DocTable) (http://www.gnome.org/gdp/doctable/) is a web page which tracks the status of all the various documentation components of GNOME. These components include application documentation, internal GNOME component documentation, user documentation, and developer documentation. For each documentation item, it tracks the current status of the documentation, who is working on the particular document, where the documentation can be found, and provides a forum for the discussion of each item.

You should use the DocTable to help you select a documentation item which needs work done. Once you have selected an item to work on, please register yourself as an author so that other authors do not duplicate your work and may contact you to help or offer suggestions. Also be sure to keep the status icons up-to-date so that the GDP team can easily identify which items need additional help. The DocTable also allows people to make announcements and suggestions and to discuss issues in the comments section.

### Note

Note that the information in the DocTable may not always be up-to-date or accurate. When you assign yourself to documenting an application, make sure you find out the latest status of documentation by contacting the application author.

### Installing and Using DocBook

All documentation for the GNOME project is written in SGML using the DocBook DTD. There are many advantages to using this for documentation, not least of which is the single source nature of SGML. 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.

#### Installing DocBook

Download and install the following DocBook Tools packages: jade, docbook, jadetex, sgml-common, and stylesheets. (RPM users should note that jade is platform dependent (eg. i386), while the other packages are in the `noarch` directory.) You can find more information on DocBook Tools here.

If you are an Emacs user you may want to grab the psgml package as well. This is a major mode for editing sgml files in Emacs.

#### GDP Stylesheets

The GDP uses its own DocBook stylesheets. To use the GDP stylesheets, you should download the file `gdp-both.dsl` from the `gnome-docu/gdp/dsssl` module in CVS (or from GDP Custom DSSSL Stylesheet)and copy it over the file `/usr/lib/sgml/stylesheets/cygnus-both.dsl`. Alternately, you can download and install the gnome-doc-tools package which will set up the stylesheets as well as the DTD discussed below.

#### GDP DTD (PNG Image Support)

Due to some license issues involved with the creation of gifs, the GNOME Documentation Project has decided to use the PNG image format for all images in GNOME documentation. You can read more about the issues involved with gifs at http://www.gnu.org/philosophy/gif.html.

The current DocBook DTD(3.1) does not include support for embedding PNG images in your documents. Since the GDP uses many screenshots in its documentation, we use our own variation on the DocBook DTD which has PNG image support. We encourage everybody to use this DTD instead of the default DocBook DTD since your source document header and your output document appearance subtly vary between the two DTD's. To install the GDP custom DTD with PNG image support by hand:

- Download the GDP DocBook DTD for PNG support and install it where you keep your DTD's. (On Red Hat use `/usr/lib/sgml/`.) Note that the 3.0 DTD is missing support for the `<legalnotice>` tag, so it is recommended that you use version 3.1

- Add the new DTD to your SGML CATALOG file. The location of your SGML CATALOG file may vary depending upon your distribution. (On Red Hat it is usually in /usr/lib/sgml/CATALOG.) Add the following line to this file:

      PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"

  If you are using the 3.1 DTD, use:

      PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"

Alternately, you can download and install the gnome-doc-tools package which will set up the custom stylesheets and DTD for you.

To include PNG files in your documents, you will need to indicate that you are using this special DTD. To do this, use the following headers:

Articles:

    <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
    V1.1//EN"[]>

Books:

    <!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
    V1.1//EN"[]>

#### Editors

There are many editors on Linux and UNIX systems available to you. Which editor you use to work on the sgml documents is completely up to you, as long as the editor is able to preserve sgml 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 sgml files which can save you time and effort in adding and closing tags. You will find the psgml package in DocBook Tools, which is the standard set of tools for the GDP. You may find out more about DocBook Tools in the section called “Installing DocBook”.

#### Creating Something Useful with your Docs

The tools available in DocBook Tools allow you to convert your sgml document to many different formats including html and Postscript. The primary tool used to do the conversion is an application called Jade. In most cases you will not have to work directly with Jade; Instead, you will use the scripts provided by DocBook Tools.

To preview your DocBook document, it is easiest to convert it to `html`. If you have installed the DocBook tools described above, all you have to do is to run the command `$`db2html mydocument.sgml. If there are no sgml syntax errors, this will create a directory `mydocument` and place the resulting html files in it. The title page of the document will typically be `mydocument/index.html`. If you have screenshots in your document, you will have to copy these files into the `mydocument` directory by hand. You can use any web browser to view your document. Note that every time you run db2html, it creates the `mydocument` directory over, so you will have to copy the screenshots over each time.

You can also convert your document to PostScript by running the command `$`db2ps mydocument.sgml, after which you can print out or view the resulting .ps file.

### NOTE

The html files you get will not look quite the same as the documentation distributed with GNOME unless you have the custom stylesheets installed on your machine. DocBook Tools' default stylesheets will produce a different look to your docs. You can read more about the GDP stylesheets in the section called “GDP Stylesheets”.

#### Images in DocBook Tools

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 scripts 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).

Thus, you should never explicitly include the extension of the image file, since DocBook Tools will automatically insert it for you. For example:

    <figure>
     <title>My Image</title>
     <screenshot>
      <screeninfo>Sample GNOME Display</screeninfo>
      <graphic  format="png" fileref="myfile" srccredit="me">
      </graphic>
     </screenshot>
    </figure>

You will notice in this example that the file `myfile.png` was referred to as simply `myfile`. Now when you run db2html to create an html file, it will automatically look for `myfile.png` in the directory.

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 - img2eps - from http://people.redhat.com/dcm/sgml.html (look for the img2eps section). Note that this script is included in the gnome-doc-tools package, so if you are using this package, you should already have img2eps on you system.

#### Learning DocBook

There are many resources available to help you learn DocBook. 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.

- 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:

- the section called “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.

### GDP Document Templates

Templates for various types of GNOME documents are found in Appendix A. Document Templates. They are kept in CVS in gnome-docu/gdp/templates. The easiest source to get them from is probably the GDP Document Templates web page, which is typically kept completely up-to-date with CVS and has a basic description of each file from CVS.

### Screenshots

Most GNOME documents will have screenshots of the particular applet, application, GNOME component, or widget being discussed. As discussed above in the section called “GDP DTD (PNG Image Support)” you will need to install the special GDP DocBook DTD which supports PNG images, the format used for all images in GNOME documentation. For the basic DocBook structure used to insert images in a document, see the section called “Images in DocBook Tools” above.

#### Screenshot Appearance

For all screenshots of windows that typically have border decorations (e.g. applications and dialogs, but not applets in a panel), GDP standards dictate the appearance of the window. (This is to minimize possible confusion to the reader, improve the appearance of GNOME documents, and guarantee the screenshot is readable when printed.) All screenshots should be taken with the SawFish (formerly known as Sawmill) window manager using the MicroGui theme and Helvetica 12pt font. (A different window manager can be used provided the MicroGui theme is available for this window manager and the appearance is identical to that when using the SawFish window manager.) The default GTK+ theme(gtk) and font (Helvetica 12 pt) should be used for all screenshots. If you are unable to provide screenshots in this form, you should create screenshots as you wish them to appear and send them to the gnome-doc-list mailing list requesting a GDP member reproduce these screenshots in the correct format and email them to you.

#### Screenshot Tools

There are many tools for taking screenshots in GNOME/Linux. Perhaps the most convenient is the Screen-Shooter Applet. Just click on the window icon in the applet and then on the window you would like to take a screenshot of. (Note that at the time of this writing, PNG images taken by screenshooter do not appear properly in Netscape or the GNOME Help Browser. You should save your screenshot as a GIF and then use convert filename.gif filename.png.) For applets in a Panel, xv can be used to crop the screenshot to only include the relevant portion of the Panel. Note that xv and gimp can both be used for taking screenshots, cropping screenshots, and converting image formats.

#### Screenshot Files

Screenshots should be kept in the main documentation directory with your SGML file for applets, or should be kept in a directory called "figs" for application and other documentation. After you use db2html to convert your SGML file to HTML (see the section called “Creating Something Useful with your Docs”), you will need to copy your screenshots (either the individual PNG files for applet documentation, or the whole "figs" directory for other documentation) into the newly created HTML directory. Note that every time you use db2html the HTML directory is erased and rewritten, so do not store your only copy of the screenshots in that directory. If you wish to create PostScript or PDF output, you will need to manually convert the PNG images to EPS as described in the section called “Images in DocBook Tools”, but will not need to copy these images from their default location, as they are included directly into the output(PostScript of PDF) file.

### 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 the Bug Buddy applet which is part of the gnome-applets package.

### Using CVS

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.

#### Anonymous 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.

#### Login CVS

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

#### CVS Etiquette

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.

Prev | Home | Next
The GNOME Handbook of Writing Software Documentation | Up | The GNOME Documentation System