Documentation

Installing documentation uses the same principles, with a little more complication. Gnome documentation is typically written in DocBook. DocBook is an SGML DTD ("Document Type Definition") just as HTML is. However, DocBook's tags are designed for technical documentation. Documentation written in DocBook can be converted to several other formats, including PostScript and HTML. Standardly, you want to install the HTML format so users can read it with their web browser or the Gnome help browser.

The Gnome libraries and help browser understand a file called topic.dat, which is simply a list of help topics with corresponding URLs. It serves as an index of help topics for your application. Here's an example, with only two entries:

gnome-hello.html        GnomeHello manual 
advanced.html           Advanced Topics

URLs are relative to the directory where you install your help files.

You should consider in advance that your documentation will be translated into other languages. It is nice to make a subdirectory in your source tree for each locale; for example, the default C locale or the es (Spanish) locale. That way translations don't cause clutter. Gnome expects help to be installed in a directory named after the locale, so this arrangement is convenient from that point of view as well. Your documentation directory might look like this one from the GnomeHello example application:

doc/
  Makefile.am
  C/
    Makefile.am
    gnome-hello.sgml
    topic.dat
  es/
    Makefile.am
    gnome-hello.sgml
    topic.dat

Here is doc/C/Makefile.am:

gnome_hello_helpdir = $(datadir)/gnome/help/gnome-hello/C

gnome_hello_help_DATA =         \
        gnome-hello.html        \
        topic.dat

SGML_FILES =                    \
        gnome-hello.sgml

# files that aren't in a binary/data/library target have to be listed here
# to be included in the tarball when you 'make dist'
EXTRA_DIST = \
        topic.dat               \
        $(SGML_FILES)


## The - before the command means to ignore it if it fails.  that way
## people can still build the software without the docbook tools

all: 

gnome-hello.html: gnome-hello/gnome-hello.html
    -cp gnome-hello/gnome-hello.html .

gnome-hello/gnome-hello.html: $(SGML_FILES)
    -db2html gnome-hello.sgml

## when we make dist, we include the generated HTML so people don't
## have to have the docbook tools
dist-hook:
    mkdir $(distdir)/gnome-hello
    -cp gnome-hello/*.html gnome-hello/*.css $(distdir)/gnome-hello
    -cp gnome-hello.html $(distdir)

install-data-local: gnome-hello.html
    $(mkinstalldirs) $(gnome_hello_helpdir)/images
    -for file in $(srcdir)/gnome-hello/*.html $(srcdir)/gnome-hello/*.css; do \
    basefile=`basename $$file`; \
    $(INSTALL_DATA) $(srcdir)/$$file $(gnome_hello_helpdir)/$$basefile; \
    done

gnome-hello.ps: gnome-hello.sgml
    -db2ps $<

gnome-hello.rtf: gnome-hello.sgml       
    -db2rtf $<

In particular notice the install directory for the generated HTML files: $(datadir)/gnome/help/gnome-hello/C. The Gnome libraries look for help here. Each application's help goes in its own directory under $(datadir)/gnome/help. Each locale's documentation is installed in its own subdirectory of the application directory. Other rules in Makefile.am run the DocBook-to-HTML converter, include HTML in the distribution tarball, and create PostScript and Rich Text Format targets. (Users can create PostScript by typing make gnome-hello.ps explicitly.)