Re: primitive documentation conventions

[marcusd@cathcart.sysc.pdx.edu (Marcus G. Daniels)]

>>>>> "MG" == Mark Galassi <rosalia@cygnus.com> writes:
>>>>> "MD" == Marcus G Daniels <marcusd@cathcart.sysc.pdx.edu> writes:
>>>>> "JB" == Jim Blandy <jimb@red-bean.com> writes:

MD> I mean, you aren't thinking of requiring that the user have Jade,
MD> are you?

JB> No, we're not considering that.  It's unacceptable to require the
JB> user to have Jade installed to read docstrings.

MD> And what about the manual?

MG> With docstrings there is a chance of a fresh start, and DocBook
MG> tags might be interesting.  If docstrings make their way into the
MG> manual (as a "quickref" appendix, for example) they would have to
MG> use tags with no depth that map quite easily to the equivalent
MG> TeXinfo tags.

The trivial (and by now, disconnected) point I am trying to make, is
that using a program like Emacs to extract documentation tags doesn't
mean that the user needs to have Emacs.

If the notion is that the documentation system ought to be all
self-contained, then you can forget about DocBook, since it would be
absurd to put all the needed capability into guiledoc. 

Using DocBook implies significant preprocessing by the maintainer(s),
just like with automake and makeinfo -- and maintainer(s) might as
well use the most powerful tools (Emacs being equal or more powerful
than than Perl when it comes to text processing, and far more powerful
than Guile.)

Granted, it would be nice to avoid entirely a separate pass over the
code, using the interpreter to store and report the documentation
encoded in Scheme code.  But how do you scan the bits implemented in C?