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

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

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:

1. A way to determine what type of docstring it is. This can be
   automatically inserted by the snarfing process, so no one ever has
   to see that tag (though it's not difficult to define).

2. A way to reference other docstrings. This is a bit iffier. Maybe
   something like (ref PROC(assoc)) or (ref (PROC assoc))
         note schemelyness, it should be a given we can agree on that
         and we could write the generator easily in guile :)

3. A way to state that something is an argument (to a function) or a
   literal string that should be typed. So you'd have something like

"Assoc takes (argument x) and (argument alist), and returns the cons
 of (argument alist) that contains (argument x) in the car 
(ref (proc car)) if such a cons exists, or (literal #f) if it doesn't."

4. An example tag (we could also generate an index of examples). So
you'd have:

"(example
guile> (define a '((a . b) (c . d)))
guile> (assoc 'a a)
(a . b)
)"

The only issue I can see is with having parenthesis (for those of us
always putting in little parentical comments like this one), but I
think I could live with having to escape parenthesis \(might break me
of the habit, tho I doubt it ;)\). It should be fairly simply to turn
those into a form that either docbook or texinfo could use, and we
don't have to deal with the much more difficult task of translating
one full markup language to another.

-- 
Greg