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

For most of the examples, we are going to practice with the traditional
"Hello, World!" example.

We cover the basics in this example. We are going to use wsmake for
maintaining the state of 3 webpages. This example can be found in the
doc/examples/ex1/ directory of the source distribution.

The first thing we should do is figure out what our directories look like.
Here is the directory structure of our first example:

  ./
  ./html/
  ./docs/

We are in the ./ directory. And we have two directories beneath this one.
The first one is named 'html'. This is where the "source" location will be
defined. It is where we keep our original data before it is used by
wsmake. The last directory is named 'docs'. This is where we want wsmake
to output it's results to. (Note: we need not create the 'docs' directory
like we have for this example, wsmake will create all directories it
needs after we define them in the configuration. Let's look at the files
now:

  ./ex1.ws
  ./ex1.final.ws
  ./html/index.html
  ./html/about.html
  ./html/help.html

The first file holds the configuration for this example, which you will be
modifying. The second is what ex1.ws should closely resemble at the end of
this example. The last three are our original HTML files. In each of the html
files we have some basic structure. There is a title, a content section, and
then a menu at the bottom. Look at the files now to see. You should also view
them with a browser to see how the content ends up.

Now, there is currently nothing in the ./docs/ ("output") directory. In
order for wsmake to put data there, we need to write the configuration
file. Let's do that now. If you open the ./ex1.conf file you will see
the basic template that wsmake requires. There is the Website section
and a PageGroup section inside it. In the PageGroup section we have
defined the name of the database to use. Note: If the value for the
database_filename does not lead with a '/', the location is considered
to be relative to the configuration file. So in this case, the database
file will be in the same directory as the configuration file.

So far this configuration doesn't do anything for us. Let's add the
./html/index.html page to the pagegroup.

To define a webpage for the website, we simply create a new section
inside the pagegroup with the label "Webpage" or "Page" (your choice).
So in the PageGroup section, put:

  Page {

  }

This Page section has one required attribute:

  web_page
    or
  source_page

Both do basically the same thing. You can use either one. In this case,
'index.html' will be the name. Web_page's value is the same as the 'path' part
of a URL. For instance:

  http://wsmake.org/index.html
    web_page "index.html"

  http://wsmake.org/download/index.html
    web_page "download/index.html"

So in the Page section let's add the web_page attribute:

  web_page "index.html"

Now we need to define which output and source directories that wsmake should
use for the web_page. Add these after the web_page:

  source_dir "html"
  output_dir "docs"

Note, if the source_dir and output_dir values do not lead with a '/', the
directories are determined relative to the location of the configuration file.
So in this case, wherever ./ex1.ws is placed, the locations of the directories
above will be looked for in the same directory that ex1.ws is in.

Ok, now we are ready to run wsmake for the first time. Type 'wsmake -f ex1.ws'.
You should get output like:

New Webpage: index.html                    [.]

This tells us it found a new webpage named index.html. Then we see how the
page is "made" between the [ and ] characters. Now look in the docs area.
There should be an index.html that is the same as the one in the "source"
area.

Run wsmake again on the configuration file. It should return no data,
because nothing was changed since the last run. Using a higher debug
setting we see: (using 'wsmake -f ex1.ws -d 2')

Loading configuration (ex1.ws):
1 PageGroup, 1 Page.
Synchronizing database with filesystem:
Making website:
--- Webpage: index.html                    

This tells us that the database is working. The index.html in the "source"
area hasn't updated, so the only report is that there was no change. For
more information on what the --- means, see chapter 2 of the User Manual.

Now update the last modification time of the "source" index.html:

$ touch html/index.html

Run wsmake again, it should return (with debug level 1):

Upd Webpage: index.html                    [.]

Wsmake saw that the index.html file was updated since the last run, so it
makes it again.

Ok, now that the first page is working, the next two pages can be added
after the first one. But before doing that, let's use another feature of
wsmake to make things easier. All 3 of the source files are in the html
directory. And all 3 output areas will be the same directory as well. It
is possible to put the source_dir and output_dir attributes in the
PageGroup section, and then leave them out of the Pages:

  PageGroup {
    database_filename "ex1.db"
    source_dir "html"
    output_dir "docs"

    Page {
      web_page "index.html"
    }

    Page {
      web_page "about.html"
    }

    Page {
      web_page "help.html"
    }
  }

Now re-run wsmake (using a debug level of 2), you should see:

Loading configuration (ex1.ws):
1 PageGroup, 3 Pages.
Synchronizing database with filesystem:
Making website:
--- Webpage: index.html                    
New Webpage: about.html                    [.]
New Webpage: help.html                     [.]

It tells us that index.html hasn't changed, but it found the two new files
and then it makes them. They should also be in the docs directory. Running
wsmake again yields (or nothing if no debug level is specified):

Loading configuration:
1 PageGroup, 3 Pages.
Synchronizing database with filesystem:
Making website:
--- Webpage: index.html                    
--- Webpage: about.html                    
--- Webpage: help.html                     

Nothing was updated. So nothing was made.

Now that we've covered the main pieces, let's add some comments to our
configuration file. Comments are started by using the '#' character. Comments
are then placed anywhere after the '#' on the same line. A comment may start
anywhere except within double quotes. So let's add at the beginning of the
config file a comment:

# This is the configuration file for example 1

Ok, this is the end of example 1.
