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:
>
> > 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.
> > But I guess they both describe the design and implementation
> > details.
> You can get those two books (modulo per-page indexes and maybe a
> preface, don't remember) by running
>
> weave tex.web
[snip]
> dvips metafont
>
> That will both give you an excellent example of what you are talking
> about as well as show you the limitations of that approach.

> > So you might be compare a user manual with a design document which
> > is not a valid comparison.
> No need to guess.  Please check the above out.  It will make the
> discussion so much more worthwhile.  And it definitely provides good
> reading, anyway.

So I did have a look.  "TeX, the Program" is a design document.  You
were comparing the design document with the user manual.
Those two can not be compared in my opinion.  It is logical that most
people prefer 'The TeX Book' over 'TeX, the Program' as many more
people use TeX than that work on extending or fixing bug in it.

It even says in the "TeX, the Program":
   "Detailed comments about what is going on,
   and about why things were done in certain ways,
   have been liberally sprinkled throughout the program.
   These comments explain features of the implementation,
   but they rarely attempt to explain the \TeX\ language itself,
  since the reader is supposed to be familiar with {\sl The \TeX book}."

The design document is useful if you want to extend the program
or fix a bug in the program.  (A this task is easier with literate
documentation than with JavaDoc like documentation).

The user manual is useful for to find out how to use the program.

Only exception I can think of is a library. Then the
design document will be close to the user manual.

> > Only for very small projects you can combine all these documents in
> > one document.
>
> Can we agree that TeX is not a very small project?

Most definitely. I was not arguing that TeX is a small project.
A small project would be something of a few hundred lines of
code.  My point was that only if you have such a small project
you can put the documentation for the design, user manual, and
installation manual as comments in the sourcecode without
it getting in the way.

For larger project makes not sense to all sorts of documentation
in the source code.  Only some of the design information makes
sense to add to the source code.

My second point was that JavaDoc like programs are only usefull
for the detailed design.  The documentation they create consists
of many little sniplets without any story-line or structure.
It is useful documentation but requires additional documentation
to make sense of the program.   With ROBODoc you can add
a bit more structure, but this is still limited.

Literate programming does allow you to add a story-line.  I think
"TeX, The Program" demonstrates this.  It is a quite wonderful
document, and offers information at many detail levels.
You can read it from top to bottom without getting lost.

However the method of combining the source and the documentation
as it is currently done is a bit awkward.
The tex.web is a single file of 1 Mbyte.  This works fine if a single
person works on it. It gets more difficult when a team of programmers
have to work on it.   When I used nuweb it was also difficult when debugging
to figureout where in the webfile a particular line of source code was.
But this might be easier with weave.

Tools like JavaDoc are useful but they are not the answer to
all the documentation needs only for a tiny fraction of it.

Literate programs work for a bigger fraction of these needs.
But they need better integration with the existing tool-chain.

Or fix the existing tool chain :)  writing programs by only manipulating
individual characters is rather stone-age.

Have fun,
Frans.