Creating New Documentation with GNOME Doc Utils

Note: This is all from my experience. It's also pretty rough. The best route to adding documentation is to ask for help either on gnome-doc-list@gnome.org or in #docs on irc.gimp.org

Steps for creating a new documentation with GnomeDocUtils

0. These instructions assume your document is all written nicely in DocBook already and is found at <app>/help/C/<app>.xml. If not, go grab a template from CVS at /gnome-doc-utils/data/templates/ -- get the template file and rename it to <app>.xml. You'll also need the file legal.xml.

1. In <app>/help, create a Makefile.am. Contents should be something like:

# First off
include $(top_srcdir)/gnome-doc-utils.make
dist-hook: doc-dist-hook

# The basename of the docbook file.  Generally, you want it to be the same 
# as your app name 
DOC_MODULE = <appname>
#Any entities you use (?)
DOC_ENTITIES = 
# If your file is split into different files, list all the files that
# are included here.  Paths are relative to the C/ subdir
DOC_INCLUDES = legal.xml

# List of figures to include.  Paths are relative to the C/ subdir
DOC_FIGURES = \
             figures/first_fig.png

2. Create an omf.in file in help, called <appname>.omf.in Its contents should look like:

<?xml version="1.0" standalone="no"?>
<omf>
  <resource>
    <subject category="<categories>"/>
    <type>user's guide</type>
    <relation seriesid="<use the program uuidgen to generate a unique identifier"/>
    <rights type="<License type>" license.version="<version, if desired>" holder="<Writers name>"/>
  </resource>        
</omf>

3. Ensure your docbook file has relevant fields in it

• An <abstract role="description"> in your <articleinfo>

• Both <author> and <corpauthor> in your <articleinfo>

• Any of <author>, <corpauthor>, <editor>, <othercredit>, or <publisher> with the attribute role="maintainer"

• A <title> element of the <article> or <articleinfo>

• A <date> element in the last <revision> in your <revhistory>

• A <revnumber> element in the last <revision> in your <revhistory>

4. Add "help/Makefile" to the top-level configure.{ac,in} AC_CONFIG_FILES list

5. Ensure "help" is listed in the "SUBDIRS" of the top-level Makefile.am

6. In the configure.ac, add: GNOME_DOC_INIT on a separate line, somewhere near IT_PROG_INTLTOOL

7. If you don't have one yet, create a m4 directory in your toplevel source directory; and create a .cvsignore file in it containing at least gnome-doc-utils.m4. Add this directory and its .cvsignore to cvs.

8. Add gnome-doc-utils.make to EXTRA_DIST and DISTCLEANFILES, and --disable-scrollkeeper to DISTCHECK_CONFIGURE_FLAGS in the top-level Makefile.am

9. Add gnome-doc-utils.make to the top-level .cvsignore

10. Add *.omf to the help directory's .cvsignore

11. Add help/ChangeLog analogous to po/ChangeLog so that translation changes can be tracked separately and be found easily

CategoryDocumentationProject