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: Maciej Stachowiak <mstachow at alum dot mit dot edu>
- Subject: Re: Doc Tasks (was RE: docstrings in Guile!)
- From: Greg Harvey <Greg dot Harvey at thezone dot net>
- Date: 17 Dec 1999 18:47:29 -0330
- Cc: "Dale P. Smith" <dpsm at bigbird dot en dot com>, Telford Tendys <telford at eng dot uts dot edu dot au>, guile at sourceware dot cygnus dot com
- References: <199912171615.LAA06607@bigbird.en.com> <385ACB30.F607AA71@alum.mit.edu>
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