[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Tim Daly
Subject: [Axiom-developer] Under-appreciated aspects of literate programming
Date: Fri, 5 Aug 2016 16:55:56 -0400

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]