Re: INFO on add-ons

[Richard Stallman]

    E.g., if we could automatically take the `;;; Commentary:' header from
    and the doc-strings an elisp file, and massage them appropiately,
    maybe the result would be a good start for making an info node.

A real manual is nothing like a collection of doc strings.  If you use
the doc strings as a starting point for writing a manual, you will
have to do a lot of rewriting to make it into a good manual.

    The problem, of course, is that the elisp file will get updated later,
    and if you re-run `makedoc' you'll have to go and re-do all the cleanup
    you had to do the last time,

Rewriting the doc strings into a real manual is a lot of work.  Nobody
who has done this job properly would consider redoing it just because
the doc strings have changed.  It is much less work to update the
manual directly, and that's what people do.

If you are using `makedoc' over and over, for different versions of
one program, you are not using it right.

                                 so anything we could do to make the
    automatic result better would be good.

This would be a grave mistake, because it would encourage people to
use the output of `makedoc' as a manual itself, without the necessary
rewriting to make a good manual.

In fact, I think that having a `makedoc' at all is a grave mistake
for the same reason.  Assuming you intend to write a manual starting from
doc strings, the work of collecting them from a .el file is nothing
compared with the work of rewriting them.

What I think might be useful would be a mode with interactive commands
that help convert from doc string style to Texinfo style.  They would
have to be interactive commands, because there is not enough info in a
doc string to produce proper Texinfo automatically.  Suitable commands
could make this editing task easier, but could not make it automatic.

As for indexing in doc strings, that might perhaps be a useful help
feature in its own right, and it might be worth implementing for that
reason, but that alone won't make `makedoc' produce adequate output.