Re: docstrings and snarfing

[dsmich]

---- Kevin Ryde <address@hidden> wrote: 
> "Dave Griffiths" <address@hidden> writes:
> >
> > I tried running the example through the C preprocessor, and it seems
> > the docstring is lost anyway:
> 
> There's some magic with a "-DSCM_MAGIC_SNARF_DOCS" to get them, then
> the scripts/snarf-check-and-output-texi program picks them out from
> the code.  (Or something like that.)  Not documented in the manual
> though (alas).

Doc snarfing of C code is done in several stages.

  1. The first stage is to extract all the docstrings from the C files
     using the C preprocessor.  (The guile-snarf-docs shell script)

  2. Then a filter program (guile_filter_doc_snarfage compiled from
     c-tokenize.lex) is used to convert the extracted strings into
     easily parsed scheme data.  These are the .doc files.  Because
     these files are basically scheme data structures, they can be
     easily read and manipulated with scheme.

  3. The next stage concatenates all the .doc files together and
     generates texinfo source. (guile script 
scripts/snarf-check-and-output-texi)
     Two texinfo files are created: guile.texi and
     guile-procedures.texi.  They are basically the same except the
     guile.texi file has extra C function names for Scheme primitives.

  4. Finally makeinfo is used to process guile-procedures.texi into a
     text file.  (guile-procedures.txt) The text file is used for
     Guile online help documentation.

-Dale