This module exports two high-level procedures to transform the Docbook files generated by GTK-Doc into texinfo.
GTK-Doc is commonly used to document GObject-based libraries, such as those that Guile-GNOME wraps. In a typical build setup, GTK-Doc generates a reference manual with one XML file per section. The routines in this module attempt to recreate those sections, but in Texinfo instead of Docbook, and which document the Scheme modules instead of the upstream C libraries.
The tricky part of translating GTK-Doc's documentation is not the vocabulary
(Docbook), but that it documents C functions which have different calling
conventions than Scheme. For example, a C function might take four
double* arguments, but in Scheme the function would return four rational
values. Given only the C prototype, the code in this module will make an attempt
to determine what the Scheme function's arguments will be based on some
heuristics.
In most cases, however, we can do better than heuristics, because we have the G-Wrap information that describes the relationship between the C function and the Scheme wrapper. In that way we can know exactly what the input and output arguments are for a particular function.
The gtk-doc->texi-stubs function is straightforward. It extracts the
"header" in a set of GTK-Doc files, translates them into texinfo, writing them
out one by one to files named ‘section-foo.texi’, where foo is
the name of the XML file. It is unclear whether it is best to continously
generate these sections when updating the manuals, or whether this "stub"
generation should be run only once when the documentation is initially
generated, and thereafter maintained by hand. Your call!
gtk-doc->texi-defuns is slightly more complicated, because you have the
choice as to whether to use heuristics or the g-wrap method for determining the
arguments. See its documentation for more information.
Both of these functions are designed to be directly callable from the shell. Here is a makefile snippet suitable for using the heuristics method for defuns generation:
GTK_DOC_TO_TEXI_STUBS = \
'((@ (gnome gw support gtk-doc) gtk-doc->texi-stubs) \
(cdr (program-arguments)))'
GTK_DOC_DEFUN_METHOD = heuristics
GTK_DOC_DEFUN_ARGS = (your-module-here)
GTK_DOC_TO_TEXI_DEFUNS = "(apply (@ (gnome gw support gtk-doc) \
gtk-doc->texi-defuns) (cadr (program-arguments)) \
'$(GTK_DOC_DEFUN_METHOD) '($(GTK_DOC_DEFUN_ARGS)) \
(cddr (program-arguments)))"
GUILE = $(top_builddir)/dev-environ guile
generate-stubs:
$(GUILE) $(GUILE_FLAGS) -c $(GTK_DOC_TO_TEXI_STUBS) \
$(docbook_xml_files)
generate-defuns:
$(GUILE) $(GUILE_FLAGS) -c $(GTK_DOC_TO_TEXI_DEFUNS) \
./overrides.texi $(docbook_xml_files)
To make the above snippet work, you will have to define
$(docbook_xml_files) as the set of docbook XML files to transform. To use
the G-Wrap method, try the following:
wrapset_module = (gnome gw $(wrapset_stem)-spec)
wrapset_name = gnome-$(wrapset_stem)
GTK_DOC_DEFUN_METHOD = g-wrap
GTK_DOC_DEFUN_ARGS = $(wrapset_module) $(wrapset_name)
Set $(wrapset_stem) to the stem of the wrapset name, e.g. pango,
and there you are.
Generate a section overview texinfo file for each docbook XML file in files.
The files will be created in the current directory, as described in the documentation for
(gnome gw support gtk-doc). They will include a file nameddefuns-file.texi, which should probably be created usinggtk-doc->texi-defuns.
Generate documentation for the types and functions defined in a set of docbook files genearted by GTK-Doc.
overrides should be a path to a texinfo file from which
@deffnoverrides will be taken. method should be eitherg-wraporheuristics, as discussed in the(gnome gw support gtk-doc)documentation. files is the list of docbook XML files from which to pull function documentation.args should be a list, whose form depends on the method. For
g-wrap, it should be two elements, the first the name of a module that, when loaded, will load the necessary wrapset into the g-wrap runtime. For example,(gnome gw glib-spec). The second argument should be the name of the wrapset, e.g.gnome-glib.If method is
heuristics, args should have only one element, the name of the module to load to check the existence of procedures, e.g.(cairo).
Check the coverage of generated documentation.
modules is a list of module names, and texi is a path to a texinfo file. The set of exports of modules is checked against the set of procedures defined in texi, resulting in a calculation of documentation coverage, and the output of any missing documentation to the current output port.