The bug list brings out several aspects of literate programming that are not obvious at first glance but make a qualitative difference in maintaining code. Previously people have turned to IDEs to provide these features. IDEs are just more code to maintain, often with very task-specific hacks that are, sigh, undocumented. IDEs also require more learning to be effective.
In particular, if we contrast bug tracking using an online bug tracker like github/savannah/sourceforge and a literate form we can see some differences. 1) Organizing bugs in book form makes it easier to search. No search tool is needed. We know how to search books, by chapter/section titles or by index or by provided tables. Search tools can be used if necessary because the latex sources are just ascii text and some tools can search PDFs. 2) The ability to intertwine words with the bugs Here we have the full power of latex rather than restrictions like "no html". If the issue is mathematics we can include equations. If the issue is html we can use verbatim. We can use hyperlinks to external sources (just like bug trackers). We can also include images for things like graphics bugs. 3) Bugs can be organized Traditional bug trackers tend to use a stack architecture so that the latest bugs appear on top. Time is not necessarily the most useful organization. They do have a useful feature of capturing discussions from emails but this could be achieved using patch on the literate document. They also track severity which is useful. This could be achieved with simple color-coding in the literate doc. 4) The ability to extract literate chunks Since sources are maintained in literate documents it is trivial to extract bugs from a literate document. These can be pulled into test files at build time and checked for changes. So a change that fixes multiple bugs can all be highlighted at once. Axiom uses a character-compare mechanism so any behavior change will be obvious. Thus bug review is part of the build process. 5) Bugs can be cited and hyperlinked Bugs can be cited in the source code so a known issue can refer to the particular bug. Hyperlinking between documents means that it is possible to link from code-to-bug or bug-to-code in the actual sources. 6) Bugs are part of the source tree Promoting bugs to book form also means that they get regular review. They are not "someplace else", such as a bug tracker on a website. Submitting a bug report is the same process as submitting a patch. So bug review is part of the release process. 7) Bugs are part of every program Bugs are just another aspect of programming, like testing, build systems, and documentation. It makes sense to treat them as first-class source control objects. Having a "bug book" makes it obvious where to look for bug reports. Some points in the diatribe are bug-specific. But literate programming in a pervasive form really does enhance the many ways that code can be organized, maintained, tested, searched, explained, and understood.
_______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org https://lists.nongnu.org/mailman/listinfo/axiom-developer