[Axiom-developer] Under-appreciated aspects of literate programming

[Tim Daly]

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.