Auto-maintaining the manual (modularity of zsh)?

Auto-maintaining the manual (modularity of zsh)?

[Derek Peschel]

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

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

[Bart Schaefer]

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   

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

[Derek Peschel]

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