Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Mail Systems
Eclipse Documentation

How To Guides
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Problem Solutions
Privacy Policy




Gtk+/Gnome Application Development
Prev Home Next


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:


Here is doc/C/

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

gnome_hello_help_DATA =         \
        gnome-hello.html        \

SGML_FILES =                    \

# 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'
        topic.dat               \

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


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

Gtk+/Gnome Application Development
Prev Home Next

  Published under free license. Design by Interspire