[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstrings and snarfing
From: |
dsmich |
Subject: |
Re: docstrings and snarfing |
Date: |
Sat, 15 Jul 2006 17:19:52 -0400 |
---- 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