Contents:
0. Using devhelp
1. Building documentation
2. Custom scripts
3. Makefile rules
4. Cruft

===[ 0. Using devhelp ]======================================================

If you install Gwyddion to a system directory, its API documentation should
appear in the table of contents automatically.  To find documentation in a
nonstandard location, let's assume $HOME/opt/gwyddion, do either:

  export DEVHELP_SEARCH_PATH=$HOME/opt/gwyddion/share/gtk-doc/html

or

  mkdir -p ~/.devhelp/books
  cd ~/.devhelp/books
  for x in $HOME/opt/gwyddion/share/gtk-doc/html/*; do ln -s $x .; done

To integrate devehelp to vim, define

  function! DevHelpCurrentWord()
      let word = expand("<cword>")
      exe "!devhelp -s " . word
  endfunction

and map

  :call DevHelpCurrentWord<cr>

to a keystroke of your choice.


===[ 1. Building documentation ]=============================================

Building docs takes too much time, they are not built automatically whenever
source code changes.  If gtk-doc is found the documentation rebuild rules are
only enabled, not executed.  Change to the appropriate dir and run

  make docs

if you want to update the API documentation.


===[ 2. Custom scripts ]=====================================================

Almost everything is generated, pay attention as other gtk-doc employing
projects often let humans maintain much more files.  The ONLY human-edited
files are:

- libgwy*-docs.sgml (driver files)
- libgwy*.overrides (symbol overrides)
- content files (optional)
- Makefile templates

The rest is generated:

- libgwy*.types (supported by gtk-doc since 1.8)

- libgwy*-sections.txt (supported by gtk-doc since 1.8)
  rationale: if header files are organized reasonably they naturaly form
             sections, therefore sections created by gtkdoc-scan are directly
             used
  tools: add-objects.py adds GwyFoo and GwyFooClass to appropriate sections
         for classed types (using libgwy*.hierarchy as class list)

- template/*
  rationale: the usual approach when these files are partially generated and
             partially human-edited is a source of neverending revision
             management pain, therefore *all* section documentation is in the
             source code
  this directory is usually called tmpl, but it confused CVS if it was kept
  after removal


===[ 3. Makefile rules ]=====================================================

gtk-doc.mk are universal rules to be included in every documentation
Makefile.am.


===[ 4. Cruft ]==============================================================

gtk-doc scan may place a slightly broken doctype declaration to
MODULE-docs.sgml

  <!doctype book PUBLIC "-//DavenPort//DTD DocBook V3.0//EN" [

fix it to

  <!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [

or else you'll get really weird errors.