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

["Greg J. Badros" <gjb at cs dot washington dot edu>]

Greg Harvey <Greg.Harvey@thezone.net> writes:

> 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); all that the docstrings need is:

I'm pretty severely opposed to developing our own complete markup
language.  There are always going to be places where we want to do more
than our custom language supports.

I do support having some common cases handled by simpler markup -- e.g.,
in Scwm, if you stick `foo' in the docstring, it gets converted to
<parameter>foo</parameter> if "foo" is the name of a formal parameter to
the function, otherwise it gets converted to <function>foo</function>.
This simplifies and condenses docstrings quite a lot.

Greg