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

[Greg Harvey <Greg dot Harvey at thezone dot net>]

"Greg J. Badros" <gjb@cs.washington.edu> writes:

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

Like? We aren't writing a manual here; sure, someone might think "hey,
it'd be cool to stick in this vrml model of guile's type tags here",
but that doesn't mean it's a good idea. We are talking about a very
limited markup language, restricted to only what's necessary for the
documentation of procedures, variables and types in guile. This means
a handful of distinguishing types, and a way to reference them from
other doc strings. Everything else should be destined for a full
manual, which is going to be more complex in any case. It'd be simple,
it'd require a one page reference to figure out exactly what you can
and can't do, and it wouldn't tie the documentation to any one
representation (regardless of potential future applications, it's
currently a choose one or the other situation, and neither does
exactly what we want).

-- 
Greg