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

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.

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.

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:

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"[]>
          

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

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.

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.

There are many resources available to help you learn DocBook. The following resources on the web are useful for learning DocBook:

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:

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.

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.

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.

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.

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