The design
Wsmake was made to simplify website maintenance. It does this using a parser, a configuration file, and configuration file syntax which describes the website to be generated. The default configuration filename is wsmakefile and files that end with .ws, but you can use a specific name.
Input
Inputs to Wsmake are:
Command line options and arguments. These inputs alter the behavior of the make process and amount of feedback.
Configuration file (wsmakefile and .ws) . This file defines the website structure and make process.
Source Files. Any file on the filesystem in any format. Certain conditions may need to be set for binary files.
Processing
Wsmake was made to reduce the effort required to maintain a website. However, it is not limited to a website "filesystem". It's programming is abstract enough to allow a developer to order any group of files to be compiled into a final version. A website "filesystem" happens to be a good example. As such, it is the primary focus for this discussion.
Processing first handles the command line options and arguments. It then loads the configuration file(s). The configuration file is needed for Wsmake to know what to do. Much the same way that GNU Make uses a Makefile. Each configuration file can define one website. In the file there are page groups. In each group, the parser is setup and one or more pages are declared. Wsmake loads the entire configuration file and then processes each group in the order they occur. Each page represents a source file which will be compiled into one or more output files.
PageGroup Section
Each PageGroup section is made up of attributes and declarations that identify website components and structure. The section also defines how the output should be generated. These attributes and declarations will be described in order of terminology dependency. Detailed definitions are described in Chapter 3.
SubTag Attribute
SubTag means Substitution Tag. The SubTag has two parts, a tag name, and a value. When the parser in Wsmake parses the source text, it looks for a tag name. When one is found, the value for the tag is put in place of the tag before the text output is written. You can also create a SubTag whose value is the output of an external command.
SubTagGroup Section
A SubTagGroup is a group of SubTags. Defining a SubTagGroup allows a set of SubTags to be re-used. Each SubTagGroup has a name attribute which can be referenced by some of the other parts of a processing section.
PageOrder and PagePart Sections
A PageOrder is used to define the order of a set of files that will be compiled into an output page. PageOrders use PagePart declarations to identify those files. The focal point of a PageOrder is the unique content. This data is not known to the PageOrder. However, a placeholder for the unique content is placed in the order to identify its occurrence. The label "data" is used for the placeholder. This allows a PageOrder to be re-used to create the common content for many unique content (data) pages.
PageParts define a source file and whether or not it should be parsed in preparation for a Page output. They can define SubTags and reference SubTagGroups. Each page part also has a name attribute. The PagePart name is what is referenced by PageOrders. For any given PageOrder, PageParts can be referenced either before or after the unique content. For instance:
header
unique content
footer
In this case "header" represents a PagePart that will be pre-pended to the unique content. Similarly, "footer" represents a PagePart that will be appended to the unique content.
Theme Section
A Theme is a way to group SubTags, SubTagGroups, and PageOrders into one place so that the group as a whole can be referenced by Pages.
Page Section
A Page represents a page on the website. It defines which PageOrder(s) and which unique content source file will be composed into a website page. It also defines whether or not the unique content file will be parsed, and the output path for the new composite file. A Page may also include SubTag definitions and references to SubTagGroups. The following discussions describe how each Page is handled by Wsmake.
Parser
The parser works on a line by line basis. It reads in a line from the source page, manipulates it, and writes it out to the output page. The parser will create the file if it does not exist. It also creates directories when necessary.
References
There are three references that a Page can use: subtaggroup, pageorder, and theme. When references are used, the output page takes on the characteristics of the referenced information. In the case of a referenced SubTagGroup, the SubTags in that SubTagGroup are added to the list of SubTags already defined for the Page. For referenced PageOrders, the order they are defined is the order in which they are applied, so that the first pageorder referenced will be used for header and footer additions to the output. Then the next pageorder adds to the previous definitions, and so on. When a Theme is referenced, the page acquires all of the properties defined in the theme.
Clones
Each Page has the capability of being cloned. This means that Wsmake will process the source of the page not only for the original definition, but for each clone as well. Clones are treated just like real Pages, and can have all of the properties that the Page can have. Depending on where the Clone is defined inside a Page, certain properties of the Page are inherited by the clone.
Output
There are three types of output: Normal Feedback, Error Feedback, and File Output. See Chapter 3 for a detailed description of these types.
Normal Feedback
Several "debug" levels are provided which can alter the verbosity. The default feedback consists of showing the user the current state of updated Pages, and the process of making (parsing) the particular Pages that are in need of an update. With debugging set to higher levels, more information is reported about what Wsmake read from the configuration file.
Error Feedback
When Wsmake fails in some part of its run-time, errors are reported to the standard error output for your operating environment. Types of errors include: Configuration file load errors, Database errors, Synchronization errors, and Make errors.
File Output
The files created by Wsmake will take on the same permissions as the source version it was created from. The timestamp is not replicated by default.