The figure on the side shows the global architecture of the Stog engine and the flow of data.
Two modules are represented on the figure (Module 1 and Module 2). More modules
can be present, for example when loading
These modules define functions associated to levels: Here the Module 1 has functions for levels 0, 20 and 30, while Module 2 has functions for levels 1 and 20.
For each level, in ascending order, the stog structure is passed to the function at this level, for each module where there is one. These functions take the stog structure and the list of documents to compute. They return a new stog structure (which may be unchanged, if no document was changed or created).
These "level functions" also take in parameter a data structure which is specific for each module. This data structure is also returned by the functions, as in a regular "fold" function.
When the functions of all levels have been applied, the documents in the
final stog structure are outputted to files in the target directory, according
to their path in the source directory. The cache is updated with information
about dependencies and contents of documents. For each module, a specific
function is called to cache the final data associated to the module.
All cache information is stored in the
The cached documents and dependencies will be used next time Stog is run, to know which documents must be recomputed, and cached module data will be used to initialize the data structure specific to each module.
Stog comes with two predefined modules, "base" and "blocks", each defining functions for various levels. The "level functions" often apply rewrite rules on the documents' contents (which are XML trees) but can also perform other actions like gathering information in the module-specific data structure to use it in a higher level.
Various levels are required to ensure some treatments or rewrite rules will be applied after others, for example to verify cross-document links. Levels used by predefined modules are numbered like lines in BASIC programs: 0, 50, 100, 120, ... making plugins able to insert new levels.
Modules can define functions for negative levels, for example to make sure they will be applied before level 0.
The first application of a level function to a document uses the
type of the document to load the corresponding template; for example,
if the document has type "page", then a template
An environment is built containing the
A "level function" can enrich this environment with the attributes of a document
(using
The environment is used in the following way to rewrite XML trees.
For each encountered node with tag
If no
If
When this analyze reaches a fixpoint, the final XML is returned.
This work is performed by the
Besides, the contents of the attributes are also analysed to perform such substitutions, before looking up for the tag in the environment.
Stog comes with