Auto-maintaining the manual (modularity of zsh)?

[Derek Peschel <dpeschel@xxxxxxxxxx>]

Hi guys,

In a sense the documentation writer "simply" needs to take the code,
determine what code paths may be followed at run time, and translate
that into formal and correct English. :)  If the code changes, the writer
must remember to change the documentation.  And if some of the documentation
changes, the writer must remember to change the rest.

Would it be practical or useful to do any of this automatically?  I was
thinking of:

	a standard form for "see also ... in the ... manual page"
	  sentences, and a script to maintain them (useful if a section
	  gets moved to another manual page, which I am thinking of doing)

	a way to make sure every builtin and option (and similar
	  abstractions that come in groups) gets documented -- add a
	  new one or take one away, you get a warning

	lists of options and parameters that affect each builtin
	  or other part of the code

The last two will require information about the code (a call graph or
even details about the conditionals/loops/etc. inside each function)
and support from make (because the info depends on the actual code).

I could probably think of many other properties of the code that can be
used to generate the documentation, but I have no clue how to _find_ those
properties manually, let alone automatically.

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.

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?  I know about the regression tests but
I suspect they're at too broad a level.

Who are the people that understand each subsystem at the general level?
(Someone already mentioned that Wayne is the history person.)

Thanks,

-- Derek