This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

RE: Doc Tasks (was RE: docstrings in Guile!)


> -----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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]