Next: , Previous: gnome gw support defs, Up: Top


14 (gnome gw support gtk-doc)

14.1 Overview

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.

14.2 Usage

— Function: gtk-doc->texi-stubs files

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 named defuns-file.texi, which should probably be created using gtk-doc->texi-defuns.

— Function: gtk-doc->texi-defuns overrides method args . files

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 @deffn overrides will be taken. method should be either g-wrap or heuristics, 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).

— Function: check-documentation-coverage modules texi

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.

— Function: generate-undocumented-texi modules texi

Verify the bindings exported by modules against the documentation in texi, writing documentation for any undocumented symbol to undocumented.texi.

modules is a list of module names, and texi is a path to a texinfo file.