Re: docstrings and snarfing

[dave]

On Sat, 2006-07-15 at 17:19 -0400, address@hidden wrote:
> ---- 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.

This makes it all a lot clearer, thankyou - I didn't realise the
documentation was seperate from the api in this way, and was all dealt
with as post processing. In the absence of a working official method,
I'll probably roll my own system like this in a way that I can merge it
in with guile in the future.

cheers,

dave