Re: generating a manual from annotations in source code

[Maciej Stachowiak <mstachow@mit.edu>]

perry@piermont.com writes:
> 
> It seems painfully clear to me that the problem here is the
> distinction between "tutorial" and "reference manual".
> 
> It seems fine to me for a skeletal reference manual to somehow slurp
> in (in an intelligent way) the contents of doc strings in order to
> assure the reference manual is always 100% up to date.
> 
> It also seems equally clear that a human organized manual must exist
> that points people at how to figure out how the parts fit together --
> such a manual is either the "programmers guide" or "tutorial" or
> something similar, but it is not the reference manual. Hopefully,
> hyperlinks exist from the one to the other (in the online version) to
> assure that you can find out the exact definition of a function or
> where it fits in to the wider scheme of things.
> 


In case it wasn't previously clear, this is my intention and my point:
the reference manual can be generated semi-automatically, and I
believe there are benefits to doing so. However, there still needs to
be a user's guide or tutorial or whatever you want to call it. In the
case of scwm, these may end up just being different chapters or groups
of chapters in the same manual, but the general idea is the same.

 - Maciej