This is example 9 as described in the Wsmake User Manual.

We cover external parsers in this example. We are going to use a similar
configuration as example 1.

This example can be found in the doc/examples/ex9/ directory of the source
distribution.

External parsers allow the use of a program outside of wsmake in addition
to the one built in. In the current version of wsmake, the internal parser
is used before any external processing. It is possible to by-pass the
internal parser and only do the external parser. There are many
pre-processors available on the internet. A good place to look is at:

http://freshmeat.net/browse/751/

In this example two simple pre-processors are used:
 cat
 myparser.pl

Cat is the concatenate program on unix. Myparse.pl is a simple perl script
that does pretty much the same thing cat will do, expect that it outputs
how many lines it has parsed.

The minimal configuration needed in the PageGroup section to use an
external command are the attributes "command" and "options".

PageGroup {
  database_filename "ext.db"
  command "myparser.pl"
  options "<%i >%o"
}

The command is the default command to execute for all Pages in that group.
The options are what is passed to the command when run. There are currently
6 format specifiers in the definition:

  %i  - The full source filename (after wsmake processing)
  %s  - The full source filename (the original source)
  %o  - The full output filename
  %w  - The web path (includes the filename)
  %ds - The full source directory
  %do - The full output directory

In the PageGroup example above, it feeds the input file as standard input
to the command, and the standard output is redirected to the output file.
Of course the options are not dependent on the pre-processor in that way.
If the pre-processor expects switches for the input and output filenames,
that can easily be specified. For instance, if the pre-processor expects
'-i' for the source file and '-o' for the output file, you could specify
the options like:

  options "-i %i -o %o"

Or maybe it uses both switches and redirection:

  options "-i %i > %o"
    or
  options "-o %o < %i"

For Pages to override the default actions, we define the same attributes
"command" and "options":

Page {
  web_path "index.html"
  source_dir "html"
  output_dir "docs"

  command "/bin/cat"
  options "<%i >%o"
}

So for this page, the "cat" command will be used instead of "myparser.pl". Note
that in this case it is still necessary to specify the options, even though
they are the same as the default options. This is because a command was
specified. What you could do, though, is specify only options, and use the
default command:

Page {
  web_path "index.html"
  source_dir "html"
  output_dir "docs"

  options "<%i >%o && echo \"   \`--> Hi!\""
}

To summarize, if you override a command, the options do not carry through
to the Page. If you override only options, the command does carry through.

So the above Page will do the same as it would if it used the default options,
except at the end of the "make" for this file, the following would print out:

    `--> Hi!

Notice I "and" (&&) the two commands together. You want to do this so that
wsmake will know whether the parse command succeeded. If you put a semicolon
instead, only the return value of the echo returns, and that tells wsmake
that the external command succeeded even if the pre-processor part failed.
This will in turn update the database to indicate it was a successful make.

This example also demonstrates a binary copy and the use of md5sum to
verify the various copy processes.

If you run the example, the output the first time should look like:

New Webpage: index.html                    [.]
New Webpage: about.html                    [.]
   `--> myparser.pl - 12 lines processed.
   `--> Hi!
New Webpage: help.html                     [.]
   `--> myparser.pl - 12 lines processed.
New Webpage: binary.file                   [.]
7b7531e696d0109254b93b954107309d  /trees/wsmake/doc/examples/ex9/html/binary.file.wsm
7b7531e696d0109254b93b954107309d  /trees/wsmake/doc/examples/ex9/html/binary.file
7b7531e696d0109254b93b954107309d  /trees/wsmake/doc/examples/ex9/docs/binary.file

The paths for the last two lines there will probably be different from
your system, but the checksum should be the same.

When a command fails to run for one reason or another, it will report the
errno setting. For instance, the following output was generated when I took
the execute bit off of the myparser.pl script:

New Webpage: index.html                    [.]
New Webpage: about.html                    [.]
sh: /trees/wsmake/doc/examples/ex9/myparser.pl: Permission denied

wsmake error: command errno = 17
wsmake error: make error = -1

The directory would be different for your server probably. Notice how
the config file directory was prepended to the path because the command
did not start with a '/'.

Ok, this is the end of example 9.