Re: Auto-maintaining the manual (modularity of zsh)?

[Derek Peschel <dpeschel@xxxxxxxxxx>]

On Thu, Feb 28, 2002 at 03:50:00PM +0000, Bart Schaefer wrote:
> On Feb 28, 12:48am, Derek Peschel wrote:

> } If the documentation or code aren't very modular, or if the layout of the
> } documentation doesn't match the layout of the code, then I'm not going
> } to bother.
> 
> The documentation and the code are modularized differently.  In my opinion,
> the kind of automated documentation you're describing only works well for
> *technical* documentation; e.g. it may work for documenting a code library
> where the indended audience is programmers making use of the library, but
> (beyond very limited contexts such as describing the names and options of
> builtin commands) I do not feel it can be effective where the audience is
> potentially-nontechnical users of the whole system created from the code.

I wasn't talking about generating the documentation automatically, but
about making sure it stays in sync with the code.  If the code changes,
make regenerates the documentation's view of the code.  If the new view
is different than the old view, you get a warning.  You still have to write
the text.

(By "view" I mean the properties of the code as a whole that the
documentation describes.  As you say, the view could be very different
from the source files -- for example options.yo describes, for each option,
the effects across all source files of setting that option.)

> Perhaps I'm wrong, but I imagine that you envision something like Sun's
> Java documentation.  If so, stop it.  I find the Java docs to be only

I've never read the Java docs (or written even a line of Java).  The
structure of the documentation doesn't have to change.

My ideas are mostly a fantasy anyway, so don't worry about any huge
changes happening under your nose. :)

> superficially complete, and they're also an example of how bad it can be
> to have the documentation match the code structure even when documenting
> a library for a technical audience.

The whole point of this exercise would be to increase completeness, not
reduce it.

I'll look for DPUTS and check through Etc/CONTRIBUTORS.

-- Derek