Installing Support Files

Pixmaps

To install datafiles from your Makefile.am you simply come up with a name for the install target---pixmap seems good---then create a variable for the directory and a corresponding variable for the files to install there. For example:

EXTRA_DIST = gnome-hello-logo.png

pixmapdir = $(datadir)/pixmaps

pixmap_DATA = gnome-hello-logo.png

The "pixmap" string connects the pixmapdir variable with the pixmap_DATA variable. automake interprets the _DATA suffix and generates appropriate rules in Makefile.in. This Makefile.am segment installs gnome-hello-logo.png into $(datadir)/pixmaps; $(datadir) is a variable filled in by configure. Typically $(datadir) is /usr/local/share (more precisely, $(prefix)/share), which is the standard location for architecture-independent data files (that is, files which can be shared between several systems with different binary file formats).

the section called EXTRA_DIST describes the EXTRA_DIST variable.

The standard location for Gnome pixmaps is $(datadir)/pixmaps, so we used that in the example. The Gnome Project encourages the use of PNG format for all pixmaps; this format is supported by gdk_imlib, the Gnome image-loading library. It is also small, fast, and unencumbered by patents.

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