Before start to write the manual you should read the style guidelines, in order to keep a common style appearance in all the documents related with the GNOME project. You can find this guide and many others at GNOME Documentation Library web page.

Anyway, just in case you can not read it, the next list tries to summarize the main advices extracted from the guide:

If you like that your work, the application help manual, to be included on future releases of that program, you should take care to follow the standards defined in the style guide. Otherwise, the application developers could not accept your collaboration, so this guide is very important and is highly recommended reading it.

In order to write a standard manual for a GNOME application you have to use DocBook. DocBook is a language for writing structured documents using XML, currently maintained by OASIS (Organization for the Advancement of Structured Information Standards) .

Documents in DocBook are just simple XML files with some special tags, these tags define the structure of the document. The writer do not have to take care about the final appearance of the document, and he can be centered only on the content. This is the main advantage of this kind of systems to write documentation, like DocBook or LaTeX. Moreover the final result could be published in a lot of different formats (HTML, PDF, RTF, etc.)

You do not need any special editor to write a document in DocBook, just use your favorite text or XML editor. However, in order to generate the final document you need some tools that will be explained at the section called “Compiling the manual”.

There are a lot of references about DocBook on the web, but the most important are at the official website.

In the next list you can see the most common tags that you need to write an application manual for a GNOME application, from more to less used:

Finally, DocBook allows to define entities in order to assign a name to some chunk of data. For example, these entities give the possibility to divide a document in different files.

You can define entities with something like the following line:

<!ENTITY app "<application>MY-GNOME-APPLICATION</application>">
	

GNOME manuals always define some entities that you should use in your document, for example you could refer to the application with &app;.

Other entities are already defined to use some special characters, for example < for < or & for &.

The GDP (GNOME Documentation Project) provides some DocBook templates to write GNOME tutorials, in order to avoid start a manual from an empty document. You can download these templates at GDP Document Templates or GNOME Doc Utils repository.

There are three available templates:

The next list enumerate some things that all the manuals should have, all of them are included in the standard templates:

To sum up, the best way to write a good manual for a GNOME application is to use a template, as base document, and make all the needed modifications on the template.

The required packages for Debian users are:

Optionally, you could install the next packages to generate the output in different formats:

Firstly, you should check that your document is valid. You can use xmllint to do it:

xmllint --noout --noent --valid filename.xml

If it does not display any error then the document is valid. Otherwise you should modify your XML file to follow the DocBook reference.

Once you are sure that you have a proper document, you could see the final output using yelp:

yelp ghelp:/path/to/filename.xml

This program will open a GNOME help browser with your manual, you can navigate and see the different sections, checking that everything is right.

This will be the same result as when the manual will be integrated as application help.

On the other hand, you can generate different output formats from your document with different applications.

In order to get an HTML you could use xmlto:

xmlto html filename.xml or xmlto html-nochunks filename.xml

If you like to generate a PDF it is easier to use dblatex.

dblatex filename.xml

Moreover you could define your own stylesheet to generate a customized output.

First of all, you need to be sure is that gnome-common package is installed in your computer. After that, you could start the process defined below.

Usually DocBook manuals are placed inside a folder called help, moreover the name of the tutorial file is like the application name. Actually, the XML document in English should be inside the directory help/C/. As in the case of po directory, inside the folder help there is a ChangeLog file to keep a track about the changes related with the tutorial.

Once you have done all the steps defined above, the DocBook manual will be part of the program. It does not appear in application menu, but it will be installed on the system when the program is installed. You can check it opening the GNOME Help and looking for the name of your application.

If you like that your manual appears in the application menu you should modify the source code of that application, so you will need to respect the guidelines to write source code in that project.

Usually the application uses GtkActionEntry to define the menu, so you will need to add the next lines in order to have a new entry called "Help", with an option "Contents" that will show your tutorial:

static const GtkActionEntry entries[] = {
	...
	{ "Help", NULL, N_("_Help") },
	...
	{ "HelpContents", GTK_STOCK_HELP, N_("_Contents"), "F1", NULL,
	G_CALLBACK (<application-function-help>) },
	...
}
	

Here you can see how to define a callback to execute the function <application-function-help>, so here you need to use a function where you will open the help manual.

You can see some code snippets about how to do this in a lot of GNOME projects, for example:

When the new option appears in the menu, you should implement some functionality inside the callback defined. The callback function has to open yelp and show the application help manual.

In order to open the tutorial you should use the function gtk_show_uri, passing as second argument the application name preceded by the prefix ghelp::

gtk_show_uri (NULL,
	"ghelp:<application-name>",
	gtk_get_current_event_time (),
	&error);
	

As in the previous point you can see some code snippets in a lot of GNOME projects, for example: