aweave(1) 1.1 aweave "aweave command"

Name

aweave - Tools for asciidoc literate programming

Table Of Contents

Synopsis

  • aweave ?-version? ?-output outfile? ?-level loggerlevel? file

Description

The aweave program is a literate programming tool for asciidoc documents. Aweave copies file to outfile or the standard output adding cross reference and indexing directives to the output corresponding to the definitions and references contained in the literate programming chunks. File is assumed to be asciidoc source containing source blocks that in turn contain chunk definitions and references. The generated output contains a section after each source block that contains a chunk describing which chunks are defined and which are referenced. Index entries for each chunk definition are also inserted into the output. In keeping with most language agnostic literate programming tools, no pretty printing of the source is performed.

Options

-version

Print the aweave version and license and exit.

-output outfile

Write the generated output to outfile rather than the standard output.

-level loggerlevel

Set the logging level to loggerlevel. Setting the level to debug give detailed information about the internal operation. Setting the level to info gives details of the chunk parsing for the document. Setting the level to notice gives details of undefined chunks.

Literate Program Chunks

In asciidoc, the markup for source code is signified by enclosing it with lines of four or more hyphens. For example,

----
proc myproc {a b} {
    chan puts "$a $b"
}
----

So literate programming in asciidoc is somewhat different than other literate programming environments in that the literate program source is a valid asciidoc document that can be formatted on its own. The only addition is that of chunk defintions contained in otherwise normal source code markup.

Aweave looks for asciidoc source blocks that contain chunk definitions. A chunk is a name enclosed in "<<" and ">>" markers. There are both chunk definitions and chunk references. A chunk definition appends an equals sign (=) to the chunk marker. A chunk reference does not. For example,

----
<<utility procs>>=
proc ut1 {b} {
    return [string toupper $b]
}
<<common procs>>
----

In this example, <<utility procs>>=, is a chunk definition and <<common procs>> is a chunk reference.

There may be multiple definitions of the same chunk. In that case, the definitions are concatenated together in the order in which they occur in the file.