Using AntWeave

Using the plugin is relatively simple; the syntax of the source file is identical to that of the original NoWeb (that I can detect). For the purposes of this explanation there is a sample source code here written in Objective-C. The Ant statements to run the noweb plugin are very similar to the Ant task javac.

Producing the code (tangle)

To produce the code the simplest Ant file would be (assuming the build.xml is in the same folder as the source file):

<?xml version="1.0"?> <project name="test" basedir="."> <taskdef name="antweave"classname="uk.org.hsfr.antweave.AntWeave"/> <property name="sourceDir" value="."/> <target name="tangle"> <antweave srcdir="${sourceDir}" ext="m"/> </target> </project>

This would processes all the "*.nw" and "*.noweb" files in the sourceDir folder using the tangle filter and will output the code starting at chunk named "*". Assuming that the source file is called convertInteger.nw the output will be placed in convertInteger.m in the sourceDir folder. Typical output would be

bramley:test hsfr$ ant tangle Buildfile: build.xml tangle: [antweave] Processing (tangle) 1 source file to ...../convertInteger [antweave] ...../convertInteger/convertInteger.nw [antweave] Output to ..../convertInteger/convertInteger.m BUILD SUCCESSFUL Total time: 0 seconds bramley:test hsfr$

This produces a file convertInteger.m

Producing the documentation (weave)

A similar process is used to process the documentation to TeX or LaTeX:

<?xml version="1.0"?> <project name="test" basedir="."> <taskdef name="antweave"classname="uk.org.hsfr.antweave.AntWeave"/> <property name="sourceDir" value="."/> <target name="weave"> <antweave srcdir="${sourceDir}" action="weave"/> </target> </project>

The output is similar to the tangle process:

bramley:test hsfr$ ant weave Buildfile: build.xml weave: [antweave] Processing (weave) 1 source file to ...../convertInteger [antweave] ...../convertInteger/convertInteger.nw [antweave] Output to ..../convertInteger/convertInteger.tex BUILD SUCCESSFUL Total time: 0 seconds bramley:test hsfr$

This produces a TeX file which can be processed (with the noweb style file available from here with the master distribution) to convertInteger.pdf.

Using the attributes

There are several attributes for the Ant task, many based on the javac Ant task, which make the process more versatile than setting a single input file and output file. The following examples are typical.

<target name="tangle"> <antweave srcdir="${sourceDir}" root="convertInteger"/> </target>

Tangles all NoWeb files in sourceDir with each output starting at convertInteger. The output is written to the file convertInteger (root overrides everything here). This does not work unless there is only one file to be processed; if there were multiple files they would all overwrite the file convertInteger with the last to be processed being the one written to convertInteger. It is worth noting that because a file extension hasn't been given the task outputs a warning message:

[antweave] Warning! Comment strings not fully specified.

This would make the tangle output fragile as the comments for file, line etc which tangle outputs potentially invalid for the language.

<target name="tangle"> <antweave srcdir="${sourceDir}" root="book-example.xml"> <include name="diffXML.nw"/> </antweave> </target>
<target name="tangle"> <antweave srcdir="${sourceDir}" root="book-example.xml"> <exclude name="diffXML-*.nw"/> </antweave> </target>

Assuming there are three files, diffXML.nw, diffXML-0.nw and diffXML-1.nw in the current folder both of the above are equivalent. The file diffXML.nw is written to book-example.xml.

Splitting source files

When a source become too big it is usual to split it up into a series of files with a master file including the various parts of the source. Consider a source file diffXML.nw with two included parts, diffXML-0.nw and diffXML-1.nw. The parts are included in the diffXML.nw file using the includeNoweb statement:

\includeNoweb{diffXML-0.nw} \includeNoweb{diffXML-1.nw}

The Ant task is

<antweave srcdir="${sourceDir}" root="book-example" ext="xml"/>

Running this will produce the following output

tangle: [antweave] Processing (tangle) 3 source files to .....test/diffXML [antweave] .....test/diffXML/diffXML-0.nw [antweave] Output to .....test/diffXML/diffXML-0.m [antweave] .....test/diffXML/diffXML-1.nw [antweave] Output to .....test/diffXML/diffXML-1.m [antweave] .....test/diffXML/diffXML.nw [antweave] Output to .....test/diffXML/diffXML.m [antweave] Including file .....test/diffXML/diffXML-0.nw [antweave] Including file .....test/diffXML/diffXML-1.nw BUILD SUCCESSFUL Total time: 0 seconds

However, this is not necessarily what we want as the two parts are also tangled. We need to tell the task not to process the part files. We rewrite the build file:

<antweave srcdir="${sourceDir}" root="book-example" ext="xml"> <exclude name="diffXML-*.nw"/> </antweave>
[antweave] Processing (tangle) 1 source file to .....test/diffXML [antweave] .....test/diffXML/diffXML.nw [antweave] Output to .....test/diffXML/book-example [antweave] Including file .....test/diffXML/diffXML-0.nw [antweave] Including file .....test/diffXML/diffXML-1.nw
Copyright 2016 Hugh Field-Richards. All Rights Reserved.