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

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxx>]

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.

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
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.

} Also it looks like there are not many specs, invariants, assertions,
} etc. at the level of subsystems (history, parameter expansion,
} arithmetic, parsing, etc.) Is that true?

It's not entirely untrue.  The DPUTS() macro is typically used for this
sort of thing, because it compiles away entirely when --enable-zsh-debug
is not configured, but there could be more DPUTS() calls than there are.

} Who are the people that understand each subsystem at the general level?

The best source of this information is Etc/CONTRIBUTORS, though you have
to look back through it fairly far in some cases as each section describes
only the things that people have worked on since the last release (and in
some cases certains "subsystems" haven't changed much in many releases).

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net