Re: generating a manual from annotations in source code

[karlheg@inetarena.com (Karl M. Hegbloom)]

>>>>> "Jim" == Jim Blandy <jimb@red-bean.com> writes:

    Jim> If the goal is to provide on-line documentation associated
    Jim> with SCWM procedures, I would be much happier with a system
    Jim> that extracted in the reverse direction: from a manual to a
    Jim> database accessible by the code.

    Jim> For example, go ahead and write texinfo or DocBook describing
    Jim> the SCWM functions, then have a program grunge through the
    Jim> @deffn's (or the DocBook equivalent) and build a database,
    Jim> then have SCWM retrieve that text upon user request.

    Jim> Or, if you think it is valuable to have the text mingled with
    Jim> the source code, add a notation to your manual format that
    Jim> says "extract the docstring for this function from the
    Jim> source, and insert it here."  That way, the layout of the
    Jim> source has no influence on the layout of the manual.

 This is like the dream I had...  Where `info' does that in GTK XEmacs
 2000 beta 666, making it possible to write a good manual without having
 to paste in those darn docstring snippets.  Let the viewing tool do
 it for you.

    Jim> Do people feel that, if the documentation is a separate file,
    Jim> programmers will be discouraged from writing docs, whereas,
    Jim> if the documentation were mingled with the source, then
    Jim> programmers would naturally write docstrings as they go
    Jim> along?

 No...  but the function/variable documentation belongs in the code
 next to what it's talking about.  It occurs to me that you could have
 specially marked up comments that are extracted also, so they'll be
 inserted at the point of the @inserthere{comment:thisfile.c:identXX}.

 Hmm.  XML, SGML, or Texinfo?  I'm just a new gnu...