Re: [ANN] LuaDoc 3.0 Released

["Frans Slothouber" <frans.slothouber@...>]

On 15/08/07, David Kastrup <dak@gnu.org> wrote:
> "Frans Slothouber" <frans.slothouber@gmail.com> writes:
>
> > The only tool that allows you to put both the big picture and detail
> > information in the source code are literate programming tools, such
> > as cweb or nuweb.  But these work in such a different way that they
> > do not integrate well with debuggers and editors, or IDEs.
>
> Donald Knuth _championed_ Literate Programming, and yet there is a
> TeXbook and a METAFONTbook to go with "TeX, The Program" and
> "METAFONT, The Program", and the latter two are not really useful
> without having worked with the former two.
>
> Indeed, for most people it is the latter which are dispensable.

I indeed own the latter two.  I don't have "TeX, The Program" nor
"METAFONT, The Program".   But I guess they both describe the
design and implementation details.
Both TeXbook and a METAFONTbook are more like user manuals.
(Though they do contain a some information about the design of
TeX en METAFONT).

So you might be compare a user manual with a design document
which is not a valid comparison.

In a project of medium size there are likely to be a lot of documents.
If you follow the DoD standard you likely have:
Requirements Specification
Functional Design
Technical Design
Detailed Design
User Manual
Installation Manual
(and these are just a few are)

JavaDoc like tools are useful to create the detailed design.
Literate programming tools are useful for the detailed design
and the technical design.
For the other documents you need something else.

Only for very small projects you can combine all these documents in
one document.

Have fun,
Frans.