On Mon, 23 Aug 2004 [EMAIL PROTECTED] wrote: >>OK, there's one non-incremental idea: documentation that you can write >>in one place and display in some completely different order. (Shades of >>literate programming!) And although there are good reasons for keeping >>the docs in the same file as the code, there are equal but opposite >>reasons to keep it separate (if it's all piled up at the end of the file >>anyway). What gets presented to the user as "one page" could be bits >>and pieces from all over the place. > Literate Programming handles reordering by allowing you to specify a > hirearchical number as part of each doc piece.
I am not sure I understand *why* you need reordering of documentation. Literate programming is useful because it reorders *code* while writing documentation in the intended order. Could somebody provide a concrete example of the need to reorder documentation? I was extensively using literate programming for the project I am working on. But after a while (7000 lines of p5 code, about 50 files) the cost of maintaining it seemed more than the gain even though I was heavily preprocessing the code to take the drudgery out, and I have come back to good ol' POD. I have come to believe that for short nasty pieces of code (implementing complicated algorithms) LP is a fantastic idea, but for larger systems that are not exactly "imperative" and have weird control flow (with hooks and such; or with an event loop of Tk), LP is no advantage. IMHO, for the few people who'd want to use LP, it would be easier and lazier to hack something like noweb to understand your annotations (perchance even understand POD :) ) than to make POD jump through hoops. --abhijit
