Re: generating a manual from annotations in source code

[Christian Lynbech <lynbech@tbit.dk>]

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

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

I would claim that it is close to empirically demonstrated that
volunteer programmers produce a lot more code than documentation.

That code and documentation should live next to each other, is one of
the fundamental concepts underlying the notion of Literate Programming
(invented by Knuth, see for instance `TeX: the Program').

I am not so bold as to promise that mingling code and doc-strings will
make programmers write more new documentation, but I think that it
will make it easier to keep existing documentation in sync with the
code, as it evolves.

How ambitious the extraction process should be, is one good
question. Knuth can make entire books (and good ones) directly from
source, but he is of course also Knuth. Going with some skeleton
and/or predefined structure, is probably more viable for us.

---------------------------+--------------------------------------------------
Christian Lynbech          | Telebit Communications A/S                       
Fax:   +45 8628 8186       | Fabrik 11, DK-8260 Viby J
Phone: +45 8628 8177 + 28  | email: chl@tbit.dk --- URL: http://www.telebit.dk
---------------------------+--------------------------------------------------
Hit the philistines three times over the head with the Elisp reference manual.
                                        - petonic@hal.com (Michael A. Petonic)