My pages Projects Community
 

If you were registered and logged in, you could join this project.

Summary A literate programming suite with a programmable build tool.
Categories construction, process
License Other OSI-certified license
Owner(s) cpoirier

Description

Summary

The lptools suite provides a complete, programming-language independent, literate programming environment. The suite targets XML documentation, but the underlying system has no bias that would disadvantage other documentation languages. (more...)

Also included, and probably worth the price of admission on its own, is a programmable build tool (a make replacement) that can handle very complex and dynamic dependency graphs. (more...)

Status

All tools mentioned below are code complete and have had some testing. We'll call it beta quality. Also, all the important documentation is complete and correct.

Currently, the tools are likely to run on *NIX systems only. Specifically, Windows directory delimiter support is untested and expected not to work. This will be fixed when I receive one of two things: enough complaints; or working code.

Releases

The CVS source directory always has the best code (well, in theory). Alteratively, you can find a tarball of the most recent release (1.03b) in the file sharing section.

Examples are now available, also in the file sharing section.

Literate Programming

Literate programming is a style of programming, invented by Knuth, which targets human readers first, and the compiler second. In literate code, the documentation is the important thing, and the code organization is subject to it. The literate programming tools then take on the responsibility of assembling compilable code and cross-referenced documentation from the sources.

The lptools suite provides a complete literate programming environment. The tools are programming language independent. Directives to the system are designed to have minimal effect on readability.

Core tools

lpcc
  • assembles code fragments from lp source files into compilable code
  • provides macro substitution facilities
  • can be used to produce an lp source file from the assembled code
lproots
  • given an lp source, lists the names of all code blocks marked as a root
lpblocks
  • given an lp source, lists the names of all blocks it defines
lpdeps
  • given an lp source, lists all lp files it references
lptags
  • given an lp source, generates ctags for lp and (optionally) code symbols
lphelp
  • outputs a complete explanation of the lp system

Documentation languages

The suite ships with an XML documentation engine. The engine aims to make it easy to mix XML documentation with plain code, by automating the quoting of incidental XML special characters. The engine converts embedded lp directives to XML tags, and will also perform automated text markup.

The XML engine does define a namespace and schema for its structures, but you are free to use any XML schema in your documentation.

lpdoc
  • assembles fully cross-referenced XML output from lp source files
  • appropriately converts lp directives to tags
  • applies automatic cross-reference directives

Build System

Included with the suite is a programmable build tool. Unlike make, jam, and others, the dependency graph is not declared directly. Instead, you supply programming fragments that the build system calls as necessary to determine what can be built, if it needs building, and how to go about building it. This flexibility enables you to build even the most dynamic and intricate source webs.

The tool features a scheme-like syntax that avoids quoting file names in most intances, and an extensive library of builtin functions for handling everything from IO to wildcard processing.

build
  • can build very dynamic and intricate source webs
  • arranges work into zones, which are loaded as declared, and which can be mutually dependent
  • uses a scheme-like syntax for its instruction files
  • includes a library of builtin functions, and the means to define your own

Project Information

The lptools suite aims to provide a complete, flexible literate programming environment in which the computer assumes as much of the bookkeeping work as is possible.

It aims to provide high functionality in three areas:

  • Flexibility in language and platform support;
  • Programmability for when needs change;
  • Usability (because otherwise, what's the point?).

The system is written in Ruby. The reasons are simple. First, writing Ruby is a joy! If that isn't enough reason, it seems likely that understandable, easily modified code will be more appreciated than blazing performance.

Related resources

The lptools suite is the programming environment written for the Tapestry operating system project. See tapestry-os.org for more details.