From: dave <dave@pawfal.org>
Cc: guile-user@gnu.org, Kevin Ryde <user42@zip.com.au>
Subject: Re: docstrings and snarfing
Date: Sun, 16 Jul 2006 22:48:57 +0100 [thread overview]
Message-ID: <1153086537.8280.10.camel@localhost.localdomain> (raw)
In-Reply-To: <23454634.1152998392102.JavaMail.root@web22>
On Sat, 2006-07-15 at 17:19 -0400, dsmich@adelphia.net wrote:
> ---- Kevin Ryde <user42@zip.com.au> wrote:
> > "Dave Griffiths" <dave@pawfal.org> 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
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
next prev parent reply other threads:[~2006-07-16 21:48 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2006-07-15 21:19 docstrings and snarfing dsmich
2006-07-16 21:48 ` dave [this message]
2006-07-18 17:14 ` Neil Jerram
-- strict thread matches above, loose matches on Subject: below --
2006-07-15 18:21 dsmich
2006-07-13 10:15 Dave Griffiths
2006-07-15 1:57 ` Kevin Ryde
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1153086537.8280.10.camel@localhost.localdomain \
--to=dave@pawfal.org \
--cc=guile-user@gnu.org \
--cc=user42@zip.com.au \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).