httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From (Ralf S. Engelschall)
Subject Re: apache api documentation
Date Thu, 10 Jul 1997 07:35:18 GMT

In article <> you wrote:
> On Thu, 10 Jul 1997, Stanley Gambarin wrote:

> Also, I'm not sure the source is the proper place for this
> documentation. A web page (on, maybe) would be probably
> more useful. Although a quick one-line summary in the source might be
> useful, if only to remind people to update the docs when they
> change/add/delete an API function.

For this problem there exists a really nice solution by D. Knuth: Literate
Programming, also known via its tool "WEB". The idea is to mix code and
documentation and one the one side to extract the code for compilation
(tangle) and on the other side to convert the source into nice looking program
documentation (docs plus pretty printed code).

While WEB itself is only for Pascal and CWEB is only for C, I don't recommend
to use Knuth's WEB itself, because it is too complex and too language
dependend for what we need it. For some projects I used Norman R.'s noWEB in
the past which only has 5 control directives and is language independend.  It
works fine and produces directly fine LaTeX (for DVI, PDF and PS) and HTML
markup. I can recommend it, it is a nice approach.

The other nice approach is Perl's POD which also is a minimalistic but
powerful way to embed documentation into source. It also has really nice
filters for generating documentation in LaTeX, HTML, ROFF or ASCII.  And to
retrieve the plain code a simple "sed" call can be used. POD is my favorite
documentation language because it is really simple and produces nice output.

Summary: For a more sophisticated way where the documentation also should
contain the source parts it documents, I recommend a WEB approach. When we
only want to get nice documentation without embedded source parts, I recommend
POD. But either way, it is really useful to embed the documentation right into
the source code. Because when one hacks at the source, one need direct access
to the corresponding docs.

                                       Ralf S. Engelschall

View raw message