Re: INFO on add-ons

[Miles Bader <miles@lsi.nec.co.jp>]

Alex Schroeder <alex@emacswiki.org> writes:
> Only if doc strings and commentaries (readable via package finder in
> Emacs, perhaps there needs to be a better interface?) fail, should we
> need to write Info.  As I said this is for newbies, and pulling stuff
> together.

I use doc-strings more often in my daily work, but I think info files
are very useful for getting a broader view of a package.  I don't think
we should avoid writing manual entries just because there are
doc-strings (and the package finder is so pathetic that it's not really
much of a contender for anything; at best, it's a way of seeing a list
of what packages there are).  Other source of documentation tend to be
scattered all over the place, and would be much more useful if they
were pulled together -- and what better way than by using info (perhaps
automatically generated info)?

Usually when I write manual entries I mostly copy the doc-strings I
wrote earlier, make mechanical changes like replacing FOO with
@var{foo}, and change the wording slightly to fit the manual format
better (e.g., remove duplicate text that can be shared more easily in
the manual page).

Perhaps what we ought to do is make it easier to produce a coherent
info node(s) from a package's existing information.

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.  Like
checkdoc, but even more whizzy (call it `makedoc' :-)...

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, so anything we could do to make the
automatic result better would be good.  [note that currently it's very
common for doc-strings and manual entries to go out of sync, though]

One thing that might make the job easier would be embedding various
formatting directives in doc-strings, which would be removed or
intepreted at display-time by the help commands (I think computers are
fast enough these days that this wouldn't be a problem), and could be
used to perform more coherent documentation.  A simple example would be
allowing the use of texinfo forms like @var{foo} or @code{foo} in
doc-strings.

An alternative to the above might be a real on-demand info-page creator
that would prodce more `mechanical' results than a real manual, but
could still benefit from all the power of the info browser (which
really is a good tool; we should use it!).  [I've long thought that the
current `package browser' should be replaced by automatically generated
info nodes.]

-Miles
-- 
Suburbia: where they tear out the trees and then name streets after them.