Lp4all 0.9.2 review
DownloadLp4all is a modern and efficient yet simple literate programming tool
|
|
Lp4all is a modern and efficient yet simple literate programming tool. According to Wikipedia, Literate programming is the writing of computer programs primarily for human beings to read, similar to a work of literature; hence the name literate programming. This contrasts with the traditional view that a programmer's primary creation is source code to be read by a computer.
Lp4all allows to document your code directly inside the language comments, using a simple Wiki-like syntax. Lp4all tool then generates an HTML browsable version of your code and documentation.
Lp4all is similar to the traditionnal Noweb literate programming tool, except that:
Noweb uses a special file markup to mix source code and documentation. Source files must be generated from the Noweb sources. It works great when one uses a simple text-editor to edit his code source. However, it doesn't work when one must use a specific third-party editor to edit the source code. In Lp4all, documentation is stored in the comments of the language: the original source code is still directly usable by the language compiler;
Noweb uses a LaTeX syntax, Lp4all uses a Wiki syntax.
Lp4all is neither a clone of Doxygen because Doxygen is only an API documentation system, while Lp4all is really intended to fully document your source code. Moreover, Lp4all is language-agnostic: it doesn't know anything about functions, methods, constants or classes.
Usage:
Documentation generation:
Using Lp4all is fairly simple:
lp4all.py -d outputdirectory list-of-source-files
will generate in outputdirectory the documentation for your project, where list-of-source-files is the list of all files that are part of your project.
There are other options to lp4all, available through the --help option.
Comment marking:
By default, Lp4all doesn't consider all comments to be part of the documentation. One must use a specific tag to mark comments that should be rendered by Lp4all. By default, this tag is the single character w, but it can be replaced by any other character, string using the option -t. It can also be set to nothing.
An example for the C language:
/*w
* This function computes the number of chocolate paste pots eaten
* by a pool of ^^n^^ open-source developers during ^^t^^ days.
*/
An example for the Python language:
#w This class implements a chocolate paste pots. It allows to keep
# track of the remaining quantity of chocolate paste, to keep
# statistics about chocolate paste consumption, and implements various
# methods to manipulate the chocolate paste pot.
Wiki markup:
The Wiki syntax is fairly simple:
Title level 1: ====title 1====
Title level 2: ===title 2===
Title level 3: ==title 3==
Strong text: **strong**
Emphasize text: //emphasize//
Strike-through text: ~~strike-through~~
Verbatim text: ^ ^verbatim^ ^ (without spaces between ^)
Verbatim block: % %verbatim block% % (without spaces between %)
External link with text: [[http://www.gnu.org/licenses/gpl1.txt|A link]]
External link: [[http://www.gnu.org/licenses/gpl2.txt]]
Cross-reference link with some text: [[#id1|link]]
Label: [@id1@]
The usage of all tags should be obvious, except probably cross-reference links. One can put labels anywhere in the source code using the [@labelidentifier@] syntax. Then, anywhere in your project, you can link to this label using [[#labelidentifier|Link]].
What's New in This Release:
Files with a .lp4all suffix and Wiki content now generate HTML files.
The HTML special characters in non-wiki code are escaped now.
The Target directory is automatically created if it does not exist, and Lp4all checks for the availability of source-highlight or python-ply.
Lp4all 0.9.2 search tags