Wiki

Clone wiki

pweave / Home

Unification of pweave Variants

The goal here is to unify the following independent "pweave" (python weave) projects on bitbucket into a common extensible code base so that users have a "definitive" complete version. I know of the following (listed chronologically):

  • mpastell: Matti Pastell's original version. The original version was simple and straightforward, but did not support all of the features I required. I have not looked closely into version 0.2 yet.
  • edgimar: Edgimar's modifications. Adds an interface so that plugins can be written to modify the behaviour.
  • mforbes: My version. Unique/important features:
    • Chunk reordering. This is a key feature for me.
    • Chunk accumulation into "blocks". Allows reuse of same code for generating multiple figures for example. Blocks may be listed in the document (in an appendix for example).
    • Maple processing (probably could be easily wrapped in an edgimar plugin) including display of generated LaTeX output as equations.
    • Optional automatic figure management vs manual control.
    • Allows indented chunks (different from original noweb) to be allow inclusion of chunks in .. note:: and similar indented environments. (That being said, I only use the LaTeX formatter extensively, so the RST/Sphinx capabilities have fallen behind).
    • Caching of computations, and regeneration iff dependent code parts change.
    • Debugging features: failed code with error message is inserted into document with a red background so that it stands out. debug=True mode suppresses output capture so that a debugger can be used to find problems.
    • Control over chunk visibility. (Can generate figures without showing the code, or hide imports).
    • Programming language dependent chunks.
    • Extensible framework for adding new command-line options and chunk options.
    • Separate weave and tangle commands.
  • brownberry: Brownberry's modifications. I have not looked at this.

Similar Programs

There are many similar programs:

  • noweb: Developed the language-independent chunk syntax.
  • Sweave: An implementation of a noweb-like engine that is distributed with the R language.
  • knitr: An R variant of Sweave that attempts to overcome some of Sweave's limitations.

Use Cases

mforbes

I use my version on a daily basis to produce LaTeX working notes including figures, code generation. The processor must be fast enough to reasonably update in real-time upon save (I no longer use sphinx for notes because it simply took too long to run and build moderately complex documents.) I use Maple to check equations (the output of which is typeset in LaTeX using Maple's conversion).

Chunk reordering is a key feature. I use this everywhere, from defining a <<boilerplate>> chunk to do all my imports, to a lightweight "macro" feature to avoid duplicating repeated blocks of code for which abstracting a function would be cumbersome.

Chunk Syntax

Perhaps the first step is to make sure a consistent chunk syntax is defined that will allow for all the require behaviour.

One important issue is to ensure that reasonable editor support is maintained. I.e. emacs noweb mode should be able to recognize and work with the chunks.

mforbes

I use a syntax in the form <<chunk name:opt1=...,opt2=...,>>=. The chunk is closed by a @ on a line of its own at the same indent level. The chunk name is forbidden from having a colon or equal sign to facilitate parsing. The colon is optional if there are no options to support backwards compatibility. Each option needs an = to simplify parsing. If the chunk name ends in a known extension such as .py}}, then the chunk is output to a file of that name. Chunk reordering is implemented simply by including a references {{{<<chunk name>> inside another chunk. The referred chunk will be expanded at the specified point with an added indentation for each line.

Several different types of chunk options are provided through an extensible framework, such as fig=True (which can be shorted fig= but not just fig). This will generate a figure in the appropriate output environment (wrapped in \begin{figure}\end{figure} in LaTeX for example). Another format fig=file.pdf will generate the named figure file, but will not insert the figure. The user then has complete control over figure formatting.

Configuration

The other part of the user interface is how to specify the pweave configuration. Should a global config file be supported? Only command line options?

Updated