Jason Pepas <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] http://people.debian.org/~dmaze/ "Theoretical politics is interesting. Politicking should be illegal." -- Abra Mitchell -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]