This section explains how to integrate the written document as help of any GNOME application. You will need to place the DocBook file in an specific folder and make several changes on source code (mainly C and Autotools files).
If you are not a developer and you do not have any knowledge about programming, you should skip this section and send your manual directly to the developers of the program, usually via the mailing list or bug tracker of the project. They will take care of integrating your tutorial in their application.
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.
Inside the help folder you need a file called
Makefile.am with the next content:
include $(top_srcdir)/gnome-doc-utils.make dist-hook: doc-dist-hook DOC_MODULE = <document-name> DOC_ENTITIES = legal.xml DOC_INCLUDES = DOC_FIGURES = DOC_LINGUAS =
Where:
DOC_MODULEThe name of the document, the file name without extension.
DOC_ENTITIES
List of files included in the manual as
entities. legal.xml is
always included.
DOC_INCLUDESList of files included in the tutorial.
DOC_FIGURES
List of figure paths of the images included in
the document. Figures are usually inside a
folder called
help/C/figures/.
DOC_LINGUASList of language codes for which the document is translated.
Furthermore, a template OMF file is required inside the directory
help and it must be called
<document-name>.omf.in. The content of this
template will be like:
<?xml version="1.0" standalone="no"?>
<omf>
<resource>
<subject category="<categories>"/>
<type>manual</type>
<relation seriesid="<generated-series-id>"/>
<rights type="GNU FDL" license.version="1.1" holder="<holder-name>"/>
</resource>
</omf>
Where:
<categories>
List of categories separated by
"|". These categories
have to belong to
a concrete list.
<generated-series-id>The first time you can generate this number with the command uuidgen. You should not change this identifier anymore.
The next step will be modify the configure.ac file,
just to add the next lines:
GNOME_DOC_INIT ... AC_CONFIG_FILES([ ... help/Makefile ... ])
It is also needed to modify the top-level
Makefile.am in order to:
Add gnome-doc-utils.make to
EXTRA_DIST.
Add gnome-doc-utils.make to
DISTCLEANFILES.
Add --disable-scrollkeeper to
DISTCHECK_CONFIGURE_FLAGS.
Add a dependency on gnome-doc-utils module.
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:
At line 3345 of file eog-window.c
(version 2.25.3).
At line 4486 of file ev-window.c
(version 2.25.2).
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:
At line 47 of file eog-util.c
(version 2.25.3).
At line 3412 of file ev-window.c
(version 2.25.2).