Zsh Mailing List Archive
Messages sorted by:
Auto-maintaining the manual (modularity of zsh)?
- X-seq: zsh-workers 16740
- From: Derek Peschel <dpeschel@xxxxxxxxxx>
- To: zsh-workers@xxxxxxxxxx
- Subject: Auto-maintaining the manual (modularity of zsh)?
- Date: Thu, 28 Feb 2002 00:48:58 -0800
- Mailing-list: contact zsh-workers-help@xxxxxxxxxx; run by ezmlm
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
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
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.)
Messages sorted by: