This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
RE: Doc Tasks (was RE: docstrings in Guile!)
- To: 'Greg Harvey' <Greg dot Harvey at thezone dot net>, Maciej Stachowiak <mstachow at alum dot mit dot edu>
- Subject: RE: Doc Tasks (was RE: docstrings in Guile!)
- From: "Reynolds, Gregg" <greynolds at datalogics dot com>
- Date: Mon, 20 Dec 1999 11:12:23 -0600
- Cc: guile at sourceware dot cygnus dot com
> -----Original Message-----
> From: Greg Harvey [mailto:Greg.Harvey@thezone.net]
> Sent: Friday, December 17, 1999 4:17 PM
> To: Maciej Stachowiak
>
> Maciej Stachowiak <mstachow@alum.mit.edu> writes:
>
> >
> > I can sympathize with the complaints about the way the
> markup looks, but I
> > think that's something we can live with. Docstrings don't
> need a huge
> > amount of markup internally.
> >
> > Of course, TexInfo is the official documentation format of
> the GNU project,
> > so we must ensure that the tools we believe will do the
> conversion work as
> > expected.
>
> A better approach that could keep all of us happy :) might be to
> define a simple set of tags that'll handle any formatting we might
> want for docstrings. We really don't need the kitchen sink of docbook
> (nor of texinfo, for that matter);
Even that could be sidestepped, by c-macroizing things and letting cpp do
the work:
#if defined(SCM_MAGIC_SNARF)
#define GDOC_ARG(typ, nm, etc) --whatever markup you like goes here--
#else
#define GDOC_ARG(typ, nm, etc) nm /* or whatever */
#endif
Then GUILE_PROC can be adjusted accordingly to create do the right thing for
doc snarfing both of the args and the docstring; markup-specific logic is
isolated in the c macros.
Then the args for e.g. char=? could be written:
(GDOC_ARG(char,c1, "special note for this arg"),
GDOC_ARG(char,c2))
One could even have SCM_MAGIC_SNARF_TEXINFO and SCM_MAGIC_SNARF_DOCBOOK
control the substitution text; for texinfo, GDOC_ARG --> @code{...} (or
whatever), and for some xmlish thing, we might have GDOC_ARG --> <varname
rep='norepeat' name='##nm##'/> or the like.
The fundamental issue would then be, which kinds of things do we want to
name in a macro, and what sort of stuff should be passed to the macro (or:
how much is too much)?
-gregg