This is the mail archive of the guile@cygnus.com mailing list for the guile project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: generating a manual from annotations in source code


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.

Perry