Re: literate programming

[David Z Maze <dmaze@debian.org>]

Jason Pepas <j.pepas@mail.utexas.edu> writes:

> On Sunday 20 October 2002 02:13 pm, Carlos A P Gomes wrote:
>> I've been looking for a way to improve the quality of my code, making it
>> more readable and understandable and easier to mantain embeding in it
>> some documentation. I think the answer is literate programming and I'd
>> like to know if anybody uses it in gnu environment to produce source
>> and documentation following the gnu standards. It seems that there is no
>> web software (cweb, noweb) that produces texinfo or docbook output. Is
>> there a way to accomplish this task?
>
> not sure if this is what you want, but you might try doxygen

doxygen is pretty different from what the "literate programming"
people try to do.  doxygen is useful for producing javadoc-like
extracts of documentation for individual functions or classes.  But
"literate programming" is generally about being able to produce
integrated documentation of source code and annotations.  For example,
you can go into a technical bookstore and often buy a printed copy of
the source to TeX (see
http://www-cs-faculty.stanford.edu/~knuth/abcde.html for details).

Practically, I've found tools like noweb useful for producing an
integrated header file and documentation on a program's interface.
That is, I can say:

  The functions in <<Mumblefrotz Initialization>> are use to set up
  the Mumblefrotz library.  [[mumblefrotz_init]] needs to be called
  before any other function in the library; [[mumblefrotz_alloc]]
  allocates memory for static buffers, and should be called with the
  maximum number of queebles that will be in use at once.  Note that
  [[mumblefrotz_alloc]] runs in $O(n^2)$ time in the number of buffers
  allocated.

  <<Mumblefrotz Initialization>>=
  void mumblefrotz_init(void);
  void mumblefrotz_alloc(int limit);
  @

Then I can create a printed manual, HTML, and a working header file,
all from the same source.

I don't know of any literate programming tools that do anything other
than TeX.  Most of them are derived at least in spirit from Knuth's
WEB tool.  Having something that does DocBook would be neat (though
possibly klunky; TeX and derivates have the advantage of being compact
and not having to put <para>...</para> around each paragraph).

-- 
David Maze         dmaze@debian.org      http://people.debian.org/~dmaze/
"Theoretical politics is interesting.  Politicking should be illegal."
	-- Abra Mitchell