Re: generating a manual from annotations in source code

[Eric Buddington <eric@napm13.vgernet.net>]

My $.02:

I use manuals in two distinct ways. First, as a tutorial when first
learning about a project. Once I know the basics, I mostly need a
reference source. In most well-written info docs, this means reading the
first few sections when I'm starting out, and later heading straight to
the indices to find what I want.

I imagine that source-embedded documentation would be a good way to
produce reference material; if it's in a suboptimal order, that won't hurt
too much if people access it through indices.

The tutorial/background sections, of course, would be better written
outside of source files, since they're more general.

Eric