# Building Documentation within a Program

## Documentation Files

Documentation in GNOME application repository and packages should be kept under `help/locale/`, where `locale` is typically replaced with C for the default (English) documents or the locale for other documents. In some cases, doc is used in place of help however it is preferrable to use help to remain consistent with the path under which these documents are installed.

Most applications will have screenshots, images, or other figures. To keep the directories reasonably clean and easy to navigate, screenshots, images, and other similar items should be placed in a directory called `figures`. While in some cases the directory is called `images` since most figures consist of images (well, screenshots really), it is preferable to use `figures` for consistency and to allow for figures which contain things other than images.

Most packages have a COPYING file in the tree which explains the rules or the license used to be able to copy any parts of the package. There should also be a COPYING-DOCS file which will contain the FDL or other licenses the documenter and maintainer agrees on. An example file is found in Subversion in the module `gnome-docu/gdp/` `COPYING-DOCS` which contains the GNU Free Documentation License. The `COPYING-DOCS` file should be placed in the same place the `COPYING` file is located or in the top level of the package tree. If you wish to use the GFDL, you must have this file in the top level of the package.

## Adding Documentation to the Build Setup

A new build system has been developed for GNOME 2.4. Each package will no longer be required to have its own copy of `xmldocs.make` and `omf.make`. Instead, the files are pulled from gnome-common whenever the package is built from Subversion.

To use the new system, in `autogen.sh` change the line that invokes `gnome-autogen.sh` from:

    USE_GNOME2_MACROS=1 . gnome-autogen.sh

to

    USE_GNOME2_MACROS=1 USE_COMMON_DOC_BUILD=yes . gnome-autogen.sh

In addition, `xmldocs.make` and `omf.make` need to be removed from packages that used previous versions of the build system.

For programs that do not use gnome-common, the files `xmldocs.make` and `omf.make` need to be manually installed. They can be found in gnome-common Subversion in `doc-build`. They should be installed in the package's root directory.

In the docs directory, a `Makefile.am` then is required that calls them:

    figdir = figures
    docname = gnome-calculator
    lang = C
    omffile = gnome-calculator-C.omf
    entities = legal.xml
    include $(top_srcdir)/xmldocs.make
    dist-hook: app-dist-hook

## Listing Documents in the Help Menu

### Developer Information

This section is for developers. Documentation authors generally do not need to know this material.

Typically the application manual and possibly additional help documents will be made available to the user under the Help menu at the top right of the application.

A macro is used in your menu definition to specify inclusion of the help item on the menu, as follows:

    static GnomeUIInfo help_menu[] = {
    	GNOMEUIINFO_HELP("gnome-calculator"),
    	GNOMEUIINFO_MENU_ABOUT_ITEM(about_cb,NULL),
    	GNOMEUIINFO_END
    };

the line specifying `GNOMEUIINFO_HELP` causes GNOME to create a menu entry which is tied to the documentation in the directory mentioned above. When the user selects Help from the menu, the default help browser, generally Yelp will display the documentation.

## Adding Help Buttons

An example of adding a help button can be found in `main.c` of gfloppy in the gnome-utils package. It bascically requires connecting `gnome_help_display` to a button and testing for an error if the documentation is not found:

    while ((button = gtk_dialog_run (GTK_DIALOG (toplevel))) >= 0)
    	GtkWidget *density_option;
    	GtkWidget *dialog;

    	if (button == GTK_RESPONSE_CLOSE)
    		break;

    	if (button == GTK_RESPONSE_HELP) {
    		GError *error;

    		error = NULL;
    		gnome_help_display ("gfloppy", NULL, &error);
    		if (error) {
    			GtkWidget *dialog;

    			dialog = gtk_message_dialog_new (GTK_WINDOW (toplevel),
    							 0,
    							 GTK_MESSAGE_ERROR,
    							 GTK_BUTTONS_CLOSE,
    							 _("Could not display help for the "
    							   "floppy formatter.\n"
    							   "%s"),
    							 error->message);
    				g_signal_connect_swapped (dialog, "response",
    						  G_CALLBACK (gtk_widget_destroy),
    						  dialog);
    			gtk_widget_show (dialog);
    				g_error_free (error);
    			}