[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstrings and snarfing
From: |
dave |
Subject: |
Re: docstrings and snarfing |
Date: |
Sun, 16 Jul 2006 22:48:57 +0100 |
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