Building Documentation within a Program

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.

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
      

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.

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
	

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
};

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);
			}