Noweb Syntax for PUBcrawl

The syntax for writing noweb style literate programs is very simple. By default, your article begins in documentation mode. To start defining a code chunk you enclose the name of the chunk within double angle brackets followed by a trailing = sign. You end a code chunk definition with a single @ symbol in the left margin followed by a newline or a space.

--------------------------
Beginning of article, this is a documentation chunk until 
we see the beginning of a code chunk:

<<chunk>>=
real code goes;
in here;
@

More documentation goes here...
--------------------------

A program is fully represented by its root chunk (the top-level chunk) which should be given the same name as the program itself. This root chunk may contain references to other chunks which are to be inserted in their place in the extracted program. Such referenced chunks are represented by a chunk name in double angle brackets without the trailing = sign.

--------------------------
This is a program to count lines in a file that match 
a certain pattern and print the total on STDOUT. This 
literate version is needlessly verbose for example purposes 
only. The main program has the following outline:

<<chunk>>=
#!/usr/bin/perl -w
use strict;
<<initialize variables>>
<<process file>>
print "$sum\n";
@

Check argument list and initialize the pattern and the sum:

<<initialize variables>>=
die "Usage: $0 pattern filenames\n" unless @ARGV > 1;
my $pattern = shift @ARGV;
my $sum = 0;
@

Loop over the file incrementing the sum for every 
line that matches the pattern:

<<process file>>=
while(<>){
    $sum++ if m/$pattern/o;
}
@

That's the whole program.
--------------------------

And, in case it's not obvious, the extracted program would appear as:

#!/usr/bin/perl -w
use strict;
die "Usage: $0 pattern filenames\n" unless @ARGV > 1;
my $pattern = shift @ARGV;
my $sum = 0;
while(<>){
    $sum++ if m/$pattern/o;
}
print "$sum\n";

You can also manually specify certain identifiers to be recognized for indexing and cross-reference purposes in the typeset version. This is done by adding a %defs directive to the final @ line which ends the code chunk. The syntax for this is to end the chunk with the @ symbol followed by a space followed by %defs followed by a space-separated list of identifiers. You specify such identifiers at the end of the chunk they are defined in. For example, I might have written the variable initialization chunk above as:

<<initialize variables>>=
die "Usage: $0 pattern filenames\n" unless @ARGV > 1;
my $pattern = shift @ARGV;
my $sum = 0;
@ %defs $pattern $sum

Within a documentation chunk, if you wish to mention variable names or other code fragments) in the text, place them inside double square brackets like: 'the variable [[$foo]] represents...'

This is enough information to write articles that can be read and typeset for the PUBcrawl newsletter. If you want further details see the noweb page for a pointer to a one page syntax guide or for the noweb distribution.