This is a minimal example of how to use Lir.  Here, we will use
the command line tool `wc` (**w**ord **c**ount) to count the
lines, words, and characters in this Lir source file.  We will
display the output in the final document.

We start by declaring a placeholder in a code chunk:
<<:listing size>>=
title: Line, word, and character count
caption: The output of `wc`, when applied to this Lir source file.
@
The name of the code chunk defined above is the string "`:listing
size`".  The prefix, "`:listing`", tells Lir that this is a
placeholder for a file that should be displayed verbatim, as a
listing.  The prefix is followed by a single space character and
the name of the file that should be displayed, "`size`".  Inside
this code chunk, we have defined a title and a caption for the
display item.

The file will be generated by running the command `wc` on this
source file (`show-size.lir`), and saving the output to `size`:
<<:make Generate the file `size`>>=
size: show-size.lir
	wc show-size.lir > size

@
The name of this code chunk has the prefix "`:make `".  This
prefix tells Lir that the code chunk contains a rule, in Make
syntax.  This particular rule reads:

> The file `size` should be generated.  It depends on the file
> `show-size.lir`.  To generate it, run the command `wc` with a
> single argument, `show-size.lir`, and put the output of that
> command in the file `size`.

**NB**: in the rule above, there must be a single tab character
at the beginning of the second line!

Normally, input files have to be declared as "sources" to the
data analysis.  This can be done using the following declaration,
again in a code chunk:
<<:source show-size.lir>>=
@

To use Lir to interpret this source file, you can invoke `lir`
with the filename as the only argument:
<<: Use Lir to interpret this source file>>=
$ lir show-size.lir
@
(This last code chunk has a name that begins with a colon, "`:`",
followed by a space.  This will be ignored when interpreting the
source file, but it will show up in the final document.)

An HTML document named `show-size.html` will be generated in the
same directory.  Open it with your web browser!