6.4 Help Documents

Good applications not only have a well-designed interface, but also provide extensive online documentation. GNOME uses the widely known DocBook standard. The preferred format is DocBook XML, and you may use DocBook SGML or plain HTML if you prefer. However, you should stick with DocBook, because it has organizational advantages over plain old HTML.

The easiest way to learn DocBook is to look through the help files that come with GNOME. The specifics on GNOME style and structure are in [GDSG]; the official GNOME Documentation Project manual is in [Mason]. [Walsh] is a good reference to DocBook in general.

6.4.1 Installing Documentation

An application's help files go in $(DATADIR)/gnome/help/ appname /locale , where appname is the application name and locale is the locale identifier. Files with no locale go in C . Any images go in figures , under the locale directory.

For example, if your installation prefix is /opt/gnome , you'll find the original documentation for the GNOME terminal in /opt/gnome/share/gnome/help/ terminal/C and the images for the German documentation for Gnumeric in /opt/ gnome/share/gnome/help/gnumeric/de/figures.

If you put everything in the right place, you can use the URI functions described in Section 4.2.2 to access the help files from your application.

There's only one task left to do: Write a description file so that you can register your documentation with ScrollKeeper . Description files are in OMF format and carry a .omf extension. Here is an example:

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE omf PUBLIC "-//OMF//DTD Scrollkeeper OMF Variant V1.0//EN" "http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd"> <omf>   <resource>     <creator>      gric@example.com (George Ricshaw)     </creator>     <maintainer>      gric@example.com (George Ricshaw)     </maintainer>     <title>       MiracleText Manual     </title>     <date>     2003-06-24     </date>     <subject category="GNOMEApplicationsOffice"/>     <format mime="text/xml"/>     <identifier url="file://opt/gnome/share/gnome/help/miracletext/C/miracletext.xml"/>     <language code="C"/>     <relation seriesid="2619c82a-a636-11d6-8522-d29c286dcc64"/>   </resource> </omf>

For more information on writing and installing OMF files, open a GNOME help browser and look at System > Other > Writing ScrollKeeper OMF Files [Mueth] (it's under the Additional documents header).

You can install an OMF file with

 scrollkeeper-install  file  .omf