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

Have you read example 4 yet? We assume that you have, so if you haven't
read it yet, please do so now.

We cover file inclusion in this example. We are going to use the same
configuration from example 4.

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

The idea behind file inclusion is to allow for a large piece of text to
act as a SubTag. Right now, SubTags can only be on one line. This is not
very convenient when you want to replace a tag with many lines of data.
So an include would be helpful here. Being able to include a file can
have many uses other than this though. For instance, if you have users
that you want to let modify a piece of the page, but you don't want them
to modify the rest of the source. You can have a separate file for them
to modify under correct privileges. But deny them access to the core
parts of the website.

There is one catch regarding includes. They aren't detected in the
dependency checks unless you use a "depend" attribute in the Page
section.  This is discussed further in example 12.

So what do we want to include for our example? How about a list of
popular sites about Linux? Once again, some files have already been made
for you at

html/linuxlinks.txt
html/mikeslinks.txt

Of course you should change the links to the ones that are popular to
you.  Now how do we include these files? Well, there are two steps,
first we need to define how we will be including files to wsmake in the
configuration file, then we will put the include statement in the file
that we want to include the information in.

Let's say that again so we get it. The first thing we setup is HOW
wsmake knows to include a file. The second is changing the source pages
to tell wsmake to include one.

In the PageGroup section we have the option of specifying a tag for
includes.  This is a special type of SubTag that doesn't have a value
part.  Instead, the name part has a special piece: "%s". That %s
represents where in the SubTag name to read the filename for inclusion.
Now, if that didn't make any sense, that's ok. Here is an example:

  Let's say that our include tag is "%s". This means that where wsmake
  finds a string in the source files, it is going to try and include it
  as if it were a filename. I wouldn't recommend using "%s".

  What if we used "<[%s]>". Well, this is better, now for every string
  that wsmake finds, starting with a "<[" and ending with a "]>", it
  will include the file whose name is in between. An example:

    This month there were <[/business/thismonth/stuff.txt]> computers
    destroyed because they previously contained sensitive information.

  So if the file at /business/thismonth/stuff.txt had "42" as it's
  content, the following would appear in the "output" page:

    This month there were 42 computers
    destroyed because they previously contained sensitive information.

Now that we know how a include subtag works, we need to define it in the
configuration file. For the include we just used, it could look like:

  include_tagname "<[%s]>"
  
According to the manual, this definition belongs in the PageGroup section.
Go ahead and add it now.

Now look in the html/index.html file and see how we have included the
two text files. Note that when there is no leading '/' for the filename,
it is looked for relative to the file that is including it first, and
then relative to a special "include_dir" which we talk about shortly.
Also, we used a glob instead of two include statements. In other words,
we could have done it like this:

<[linuxlinks.txt]><[mikeslinks.txt]>

But instead we just told it to include all files ending with .txt:

<[*.txt]>

Now run wsmake on the configuration file. You should notice that the
output for the make process has changed:

New Part   : header.html                   
New Part   : footer.html                   
New Webpage: index.html                    [.ii..]
New Webpage: about.html                    [...]
New Webpage: help.html                     [...]
New Webpage: incdirtest/index.html         [.i..]

The 'i' in the make process indicates that wsmake has included a file.

Now look at the "output" file docs/index.html. The files should have
been included.

Now about the "include_dir" I mentioned. It can be used in the
PageGroup section to be used as a 2nd directory to look for files.
For instance, to check for files in a directory named "includes"
you could use:

   include_dir "includes"

Now when a file is included like <[linuxlinks.txt]> in a directory
that doesn't have the file, it will look in the backup include_dir
include it from there if it can be found.

When the value of include_dir doesn't begin with a '/' it starts
relative to the path of the configuration file.

Ok, this is the end of example 5.