The Wsmake User Manual
Prev | Chapter 3. Configuration file syntax | Next

# Website Section

The Website section holds all information about a Wsmake project. There can only be one Website section for each configuration file. The PageGroup subsection is the only sub-section that can be defined within a Website section. There can be multiple PageGroups.

Table 3-1. Website Attributes

Name | Required / Optional | Description
--- | --- | ---
`name` | optional | The name of the website
`maintainer` | optional | The maintainer of the website
`url` | optional | The url of the website
`include` | optional | Include a file as part of the configuration

The name, maintainer, and url settings are identifiers only and do not play a role in the parse process.

When the value of an include attribute does not start with a '/', the file is looked for relative to the configuration file.

Example 3-1. Website

    Website {
      name       "Mike's Website"
      maintainer "Mike"
      url        "http://wsmake.org/~mike/"
      include    "pagegroups.ws"
    }

## PageGroup Section

The PageGroup section holds common information for a group of Pages. There can be multiple PageGroup sections in the Website section. The common content items fall into two categories: attributes and subsections. The following subsections can be defined within a PageGroup section:

- SubTagGroup

- PagePart

- PageOrder

- Theme

Attributes will be discussed first. Table 3-2 lists the PageGroup attributes.

Table 3-2. PageGroup Attributes

Name | Required / Optional | Description
--- | --- | ---
`lastmod_tagname` | optional | Internal subtag, replaced with last modification date of "source" file
`wsmake_version_tagname` | optional | Internal subtag, replaced with version of Wsmake
`output_page_tagname` | optional | Internal subtag, replaced with output_page of current page
`source_tagname` | optional | Internal subtag, replaced with the full path of the "source" page
`output_tagname` | optional | Internal subtag, replaced with the full path of the "output" page
`header_tagname` | optional | Internal subtag, replaced with the full path of the header output for use with CGI scripts
`footer_tagname` | optional | Internal subtag, replaced with the full path of the footer output for use with CGI scripts
`include_tagname` | optional | Internal subtag, replaced with contents of file referenced (see details below)
`time_format` | optional | Format of time/date printouts. This is the same format as defined by the strftime function in C (see the manpage for strftime for details)
`subtag_format` | optional | Specifies a generality about all subtags in a pagegroup (see details below)
`database_format` | required | Format of database. One of DB, CSV, or Timestamp. Defaults to CSV.
`database_filename` | required *** | Filename of database for the PageGroup
`source_dir` | required * | The default source directory
`output_dir` | required * | The default output directory
`part_dir` | optional * | The default PagePart directory
`include_dir` | optional | The backup include directory
`command` | optional | The default external command to use on the data after the wsmake parser. Default is none.
`options` | optional | The default options for the default command
`depend` | optional | A file that this PageGroup depends on
`include` | optional | Include a file as part of the configuration

* Can be overridden in PageParts and Pages. If part_dir is not specified, source_dir will be used for PageParts.

** Can be overridden in Pages.

*** The filename is optional when the Timestamp format is requested. But even if one is given, no data is stored in it. When the Timestamp format is requested, only the source pages have bearing on the update process. This means changing SubTags, Depends, or other entities that would normally be tracked, will not have there state cached.

The include_tagname subtag is used to specify a tag name for including a file during the make process. For instance:

      include_tagname    "include(%s)"

The specified tag name requires the characters "%s" somewhere in the string to represent the name of the file to be included. This means that for every occurrence in the source where the string "include(" is found, with some filename text and a ")" after it, Wsmake will replace it with the contents of the filename given:

    This is HTML. Now a file will be included:
    include(/web/include.txt).

This will take the entire string "include(/web/include.txt)" and replace it with the contents of the file `/web/include.txt`. The start and stop string before and after the filename is required.

If the filename doesn't begin with a '/' character, the file is first looked for relative to the source file that is being parsed, and the in the directory defined by include_dir, if specified. Globs, however, are only looked for relative to the source file.

The subtag_format definition can be used to abstract a common part of all subtags so that you can define them without the common part. For example, if every SubTag you use on a website is of the form:

    `subtag`

Then you can specify a ssubtag_format of:

    subtag_format "`%s`"

Then when you specify SubTags, it is not necessary to include the extra information in the subtag_format:

    SubTag "test" "here is the value"

With the subtag_format definition above, Wsmake will look for `test` when it parses the source data.

As in the Website section, the include files will be looked for relative to the configuration file if not prefixed with a '/'. The same is true for the depend attribute.

Example 3-2. PageGroup

    PageGroup {
      database_filename      "website.db"
      lastmod_tagname        "`LASTMOD`"
      wsmake_version_tagname "`WSMAKEVERSION`"
      web_path_tagname       "`FILEPATH`"
      source_tagname         "`FILESOURCE`"
      output_tagname         "`FILEOUTPUT`"
      include_tagname        "include(%s)"
      header_tagname         "`CGI_HEADER`"
      footer_tagname         "`CGI_FOOTER`"
      source_dir             "/web/source"
      output_dir             "/web/docs"
      part_dir               "/web/templates"
      include_dir            "/web/includes"
      command                "myparser.pl"
      options                "<%i >%o"
      depend                 "pagegroups.ws"
      include                "pages.ws"
    }

### SubTagGroup Sections

The SubTagGroup section defines a group of SubTags which can be re-used by PageParts and Pages. The following attributes can be defined in a SubTagGroup section:

Table 3-3. SubTagGroup Attributes

Name | Required / Optional | Description
--- | --- | ---
`name` | required | The name of the SubTagGroup
`SubTag` | optional | A SubTag attribute

There can only be one name for a SubTagGroup. SubTags may be defined 0, 1, or many times.

Example 3-3. SubTagGroup

    SubTagGroup {
      name "default"
      SubTag "`EMAILLNK`" "<a href=\"mailto:`EMAIL`\">`EMAIL`</a>"
      SubTag "`EMAIL`"    "mike@wsmake.org"
      SubTag "`FONTFACE`" "Arial, Helvetica"
      SubTag "`HOST`"     "http://wsmake.org/~mike/"
    }

Note in this example how a SubTag was used inside of another SubTag. This is valid as long as the SubTag being used inside is defined after its use. Remember that SubTags are parsed in the order that they are declared. You cannot nest a SubTag within its own value.

### PagePart Sections

The PagePart section defines a file to be used as a piece of a PageOrder. It also references any PageOrders it needs to complete itself. The following attributes can be defined in a PagePart section:

Table 3-4. PagePart Attributes

Name | Required / Optional | Description
--- | --- | ---
`name` | required | The name of the PagePart
`filename` | required | The filename of the pagepart (no directory!)
`directory` | optional * | The directory that the file is in
`SubTag` | optional | A SubTag to use for this PagePart
`subtaggroup` | optional | A SubTagGroup to use for this PagePart
`pageorder` | optional | A PageOrder to use for this PagePart
`theme` | optional | A Theme to use for this PagePart
`parse` | optional | A value of `NO`, `YES`, or `INCLUDES_ONLY` which tells how Wsmake should parse this PagePart. The default is `YES`
`depend` | optional | A file that this PagePart depends on

* If the directory is not defined here, it will use the part_dir attribute defined in PageGroup.

There can only be one name, filename, directory, and parse attribute for each PagePart. The rest can have multiples definitions, and they are applied to the PagePart in the order that they are defined.

Example 3-4. PagePart

    PagePart {
      name      "header"
      filename  "header.html"
      directory "templates"

      SubTag    "`INFO`" "Header piece"

      subtaggroup "default"
      parse     YES
    }

### PageOrder Sections

The PageOrder section defines a group of files to be used by PageParts and Pages for ordering content. The following attributes can be defined in a PageOrder section:

Table 3-5. PageOrder Attributes

Name | Required / Optional | Description
--- | --- | ---
`name` | required | The name of the PageOrder
`part` | optional | A PagePart name to use
`data` | required | A placeholder for the unique content of the page. It has no value.

Example 3-5. PageOrder

    PageOrder {
      name "default"
      part "header"
      data
      part "footer"
    }

Any page that uses this pageorder will have the PagePart whose name is "header" prepended to it and will have the PagePart whose name is "footer" appended to it in the "output" file. The "part" definitions are applied in the order that they are defined. There can only be one name and data definition for each PageOrder.

### Theme

The Theme section defines a set of SubTags, SubTagGroups, and PageOrders to be reused by Pages. The following attributes can be defined in a Theme section:

Table 3-6. Theme Attributes

Name | Required / Optional | Description
--- | --- | ---
`name` | required | The name of the Theme
`SubTag` | optional | A SubTag to use for this Theme
`subtaggroup` | optional | A SubTagGroup to use for this Theme
`pageorder` | optional | A PageOrder to use for this Theme
`command` | optional | The external command to use on the data after the wsmake parser.
`options` | optional | The command line options to use for the parser specified by command
`depend` | optional | A file that this Theme depends on

Example 3-6. Theme

    Theme {
      name "home"
      SubTag "`SECTION`" "Home"
      subtaggroup "home"
      pageorder "home"
    }

## Page Section

The Page section defines a Page on the website. Each Page represents an item to be "made" by the make process. The following attributes can be defined in a Page section:

Table 3-7. Page Attributes

Name | Required / Optional | Description
--- | --- | ---
`web_page` | required ** | The web page of the Page, i.e., the directory after the http://servername/ including the page filename.
`source_page` | required ** | A string that, when appended to the source_dir attribute, represents the filename of the source for this Page.
`output_page` | optional | A string that, when appended to the output_dir attribute, represents the filename of the output for this Page. If this is not set, the corresponding web_page or source_page value will be used.
`source_dir` | optional | The directory prefix to `web_page` and/or `source_page` that represents the "source" location
`output_dir` | optional | The directory prefix to `output_page` that represents the "output" location
`time_format` | optional | Format of time/date printouts. This is the same format as defined by the strftime function in C (see the manpage for strftime for details)
`subtag_format` | optional | Specifies a generality about all subtags in a pagegroup (see details in PageGroup section above)
`SubTag` | optional | A SubTag to use for this Page
`subtaggroup` | optional | A SubTagGroup to use for this Page
`pageorder` | optional | A PageOrder to use for this Page
`theme` | optional | A Theme to use for this Page
`page_type` | optional | A value of `NORMAL`, or `CGI` which tells Wsmake the way it should output the header/footer information. The default is `NORMAL`
`parse` | optional | A value of `NO`, `YES`, or `INCLUDES_ONLY` which tells how Wsmake should parse this PagePart. The default is `YES`
`cgi_header` | optional | This defines the name of the header file to output to (relative to the location of the output) for CGI page_types
`cgi_footer` | optional | This defines the name of the footer file to output to (relative to the location of the output) for CGI page_types
`command` | optional | The external command to use on the data after the wsmake parser.
`options` | optional | The command line options to use for the parser specified by command
`depend` | optional | A file that this Page depends on

** Either web_page or source_page may be defined. They are both considered the same. It may be more readable to use web_page if both the source_page and output_page are the same value.

There can only be one web_page/source_page, source_dir, output_dir, page_type, parse, cgi_header, and cgi_footer definition for each Page. When the page_type is CGI, the output of the header and footer information (if any) goes to the files defined by cgi_header and cgi_footer. If cgi_header or cgi_footer is not defined, "header.html" or "footer.html" is used as a default, respectively.

For `options`, '%i' is replaced by the full path to the wsmake parsed source file and '%o' is replaced by the full path to the output file at make time. Other options are '%s', the full path to the source file, '%w' the web path of the page, '%ds', the full path to the directory of the source file, '%do', the full path to the directory of the output file. If `options` is not specified, but the command is, the default `options` from the PageGroup section are not used.

Example 3-7. Page

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

      SubTag "`FONTFACE`" "Courier"

      subtaggroup "default"
      pageorder   "default"

      page_type   NORMAL
      parse       YES
    }

Prev | Home | Next
Configuration file syntax | Up | Examples