Quick Tour

If you have followed the instructions in the README file, then you have already used STOWS. You have used it for generating this manual. In this quick tour we shall recapitulate what you have done and explain why.

In order to generate a web site, you generally need three ingredients: the contents, the design, and the instructions how to link the pages to form a site. STOWS combines them and produces a completed web site. One of the nice features of STOWS is that all three ingredients are HTML-based, so if you are familiar with HTML, you should have no problems using STOWS.

The source files, containing the contents for this manual have been placed in the src directory. Those are pure HTML files containing only the text and graphics of the manual itself (like this text), but no navigational elements or information common to all pages, like a copyright notice. The navigational elements are created by STOWS based on the site structure information. These information are found in the manual.html file. This file - in STOWS terminology it is the site description file - is basically a HTML file, with some extensions used by STOWS. These extensions are hidden in HTML comments ( <!-- ... --> ), so the file can be displayed in any HTML browser. And finally, the design of the manual is controlled by a couple of template files, like Template.html, which are also extended-HTML files.

As you have entered

    stows manual.html

you have invoked STOWS with manual.html as the description file. This file contains all necessary information for generating the site: where to find source files, which templates to use, in which order to process the source files and how to link them, and some more. During processing, STOWS has generated the manual directory (from which you are presumably accessing this manual) stored the generated linked web pages and copied the graphic files.

If you take a look into the description file, you'll see that it contains a block of variables at the beginning and nested HTML "definition lists" in the body. Some of the variables -- those beginning with a dollar sign ($) -- have a reserved meaning. For example, $SOURCE defines the directory with the source (pure content) files. Other variables are user defined. When they appear in a source or template file, they get substituted for their value, as given in the description file.

The nested definition lists define the site structure. In most cases, definition terms contain a HTML link, defining a site page. The way how they are nested reflects the hierarchical organization of the site. Their order is important if you have a preferred path through the site and want to provide for links to the next and the previous page. You may note that some of the definition terms also include some additional data, like a template name. Those are STOWS-specific extensions which control the publishing process. For example, stating a template name for a page means that from that page on the stated template file will be used.

Template files are used for controlling page parts that repeatedly appear in all pages, such as logotypes, navigation bars, copyright notices etc. They normally contain a BODY CONTENT tag, which marks the place in the file where the content (the body) of the currently processed page is inserted. Also, the header of the processed page, e.g. containing keywords and page description for search engines, can be inserted at the place of HEAD CONTENT tag in the template file. Another very useful tag is INDEX, which is used for generating navigation bars. It is actually a block, closed with the closing /INDEX tag, which includes one or more nested L (for level) blocks. These blocks include the HTML code to be used for generating navigation entries at defined hierarchical levels. For example, you might want to indent entries corresponding to the pages at lower levels. Also, you might want to have the index entry corresponding to the current page highlighted. For that purpose, L tags include type specifiers like CURRENT and OTHER. STOWS supports up to 6 hierarchical levels, named L1 to L6, which should suffice for most medium-sized web sites.

In the following chapters we shall in details describe the keywords used by STOWS.