Next: Doc Extraction from C Source, Up: Doc Maintenance
In addition to init snarfing (see Init Snarfing),
the libguile, ice-9 and SRFI sources are also subject to doc snarfing
so as to extract reference documentation for this manual as well as
for guile-procedures.txt, a non-resident compendium of
docstrings consulted when you use the help command.
Because there are multiple uses and formats for the documentation, the doc snarfing process is divided into several steps: extraction, indexing, insertion into a .texi file, and general insinuation into the overarching auto* tools methodology.
The first step creates files in the Guile Documentation Format Version 1 (GDFv1 for short), which is documented in the commentary of the (ice-9 documentation) module. See Documentation.
You can create GDFv1 files with your favorite text editor, or use the three provided guile-tools (see Miscellaneous Tools), each suited to a particular source language. See Doc Extraction from C Source, See Doc Extraction from C Headers, and See Doc Extraction from Scheme Source.
GDFv1 files can be concatenated so you can form your own non-resident compendium (e.g., my-procedures.txt) for immediate use following extraction. For example:
(use-modules (ice-9 documentation))
(set! documentation-files
(cons "/full/path/to/my-procedures.txt"
documentation-files))
(use-modules (ice-9 session))
(help 'my-proc)
Post-extraction doc snarfing steps are required for seriously pain-free reference documentation maintenance, where update of C or Scheme source triggers automatic update of the appropriate texinfo file(s). This is an involved undertaking because at the time of this writing (late-2003) the auto* tools support neither documentation dependency analysis nor generated documentation; the methodology presented here is experimental and may actually be incorporated into the auto* tools someday (after refinement).
Basically, the approach is to declare a new file type TWERP (Texinfo With Eval-Requiring Predelictions, you see), which is mostly texinfo with some directives that are substituted with specific docstrings collected from pre-extracted GDFv1 files. The .twerp file is then processed to create a .texi file. To keep things light, the directives don't specify source, only symbols. For example:
@twerpdoc (acons (C scm_acons))
This necessitates building an index to facilitate efficient docstring retrieval (see Doc Indexing), doing the insertion with dependency tracking as a side effect (see Doc Insertion), and tweaking the auto* tools flow slightly (see Doc Methodology Insinuation).
Here's a list of areas that can (and should) be improved: