Default scheme

As explained in Evaluation and templating, modules provide named functions associated to levels, and the documents are succesively modified by these functions. Additionaly, a function of a module can be associated to various levels.

The following modules are available by default: Base, Blocks.

Here is the list of default levels and their associated functions defined by these modules:

LevelFunction(s)
0base (Base), init (Blocks)
30add-docs (Base)
50toc (Base)
60cut (Base)
61base (Base), base (Blocks)
100sectionning (Blocks)
120gather-ids (Blocks)
150doc (Blocks)
160inc (Base)
500clean (Base)

For most of the rules applied by module functions, you should look at the generated XML to modify your CSS stylesheet according to the classes used. You can start from the .less files in the doc/less directory of the stog sources.

Configuring the scheme

The default scheme can be changed, using the levels option in the .stog/config file. This option contains a list of associations of the following form:

[
  { module: "module-name",
    levels: [ ("fun1", [ l1 ; l2 ; ...]),
              ("fun2", [ l3 ; l4 ; ...])
            ]
  },
    ... ;
]

The list is used to set the levels a function is associated to in a given module. The default scheme could be expressed with:

levels: [
  { module: "html",
    levels: [
      ("base", [ 0, 61 ]),
      ("add-docs", [ 30 ]),
      ("toc", [ 50 ]),
      ("cut", [ 60 ]),
      ("inc", [ 160 ]),
      ("clean", [ 500 ]),
    ]
  },
  { module: "blocks",
    levels: [
      ("init", [ 0 ]),
      ("base", [ 61 ]),
      ("sectionning", [ 100 ]),
      ("gather-ids", [ 120 ]),
      ("doc", [ 150 ]),
    ]
  }
]

It is possible to change only the levels of some functions. In the example below, the inc function of module Base will not be called (as it is associated to an empty list of levels) and the base function of the same module will be associated to levels 2 and 230, while the rest of the scheme remains unchanged:

levels: [
  { module: "html",
    levels: [
      ("base", [ 2, 230 ]),
      ("inc", [ ]),
    ]
  }
]

Each module can associate only one function to a given level: for a level and a module, the last associated function hides the previous function associated to this level, if any.

Common base rules

Some predefined rules are applied in various functions of the predefined modules. They are listed here.

contents

<contents/> is the generic function to insert some contents in an included file or template. It may be available or not depending on the context.

env_

The special tag env_ can be used to modify the environment before analysing children. For example, here we add an association between "login" and "zoggy". This will add to the environment an association between the key "login" and the function returning the one-element list ["zoggy"], which is used later in the "login" attribute:

<env_ login="zoggy">
  ...
  <user login="&lt;login/&gt;">...</user>
  ...
</env_>

Such a function cannot be created in plugins, since functions only return XML trees, not a new environment. But your functions can return XML trees containing env_ tags to modify the environment used to evaluate the returned XML trees.

langswitch

If stog is launched with option --lang language, the <langswitch> function returns some code to access to pages in other languages than language.

For information you can see the source code of the page.

<page title="Predefined modules and functions"
navbar-doc="active"
with-contents="true"
>
<contents>
<section id="default_scheme" title="Default scheme">
<p>
As explained in <doc href="engine"/>, modules provide named functions associated
to levels, and the documents are succesively modified by these functions.
Additionaly, a function of a module can be associated to various levels.
</p>
<p>
The following modules are available by default:
<doc href="module_base">Base</doc>, <doc href="module_blocks">Blocks</doc>.
</p>
<p>Here is the list of default levels and their associated functions
defined by these modules:
</p>
<table class="table table-bordered table-condensed">
<tr><th>Level</th><th>Function(s)</th></tr>
<tr><td>  0</td><td><doc href="module_base#base"/> (Base), <doc href="module_blocks#init"/> (Blocks)</td></tr>
<tr><td> 30</td><td><doc href="module_base#add-docs"/> (Base)</td></tr>
<tr><td> 50</td><td><doc href="module_base#toc"/> (Base)</td></tr>
<tr><td> 60</td><td><doc href="module_base#cut"/> (Base)</td></tr>
<tr><td> 61</td><td><doc href="module_base#base"/> (Base), <doc href="module_blocks#base"/> (Blocks)</td></tr>
<tr><td>100</td><td><doc href="module_blocks#sectionning"/> (Blocks)</td></tr>
<tr><td>120</td><td><doc href="module_blocks#gather-ids"/> (Blocks)</td></tr>
<tr><td>150</td><td><doc href="module_blocks#doc"/> (Blocks)</td></tr>
<tr><td>160</td><td><doc href="module_base#inc"/> (Base)</td></tr>
<tr><td>500</td><td><doc href="module_base#clean"/> (Base)</td></tr>
</table>
<p>For most of the rules applied by module functions, you should look
at the generated XML to modify
your CSS stylesheet according to the classes used. You can start from
the <icode>.less</icode> files in the <icode>doc/less</icode> directory
of the stog sources.
</p>
</section>

<section id="config_funs" title="Configuring the scheme">
<p>
The default scheme can be changed, using the <code>levels</code>
option in the <code>.stog/config</code> file.
This option contains a list of associations of the following form:
</p>
<hcode lang="json">[
  { module: "module-name",
    levels: [ ("fun1", [ l1 ; l2 ; ...]),
              ("fun2", [ l3 ; l4 ; ...])
            ]
  },
    ... ;
]</hcode>
<p>
The list is used to set the levels a function is associated to in a
given module. The default scheme could be expressed with:
</p>
<hcode lang="json">levels: [
  { module: "html",
    levels: [
      ("base", [ 0, 61 ]),
      ("add-docs", [ 30 ]),
      ("toc", [ 50 ]),
      ("cut", [ 60 ]),
      ("inc", [ 160 ]),
      ("clean", [ 500 ]),
    ]
  },
  { module: "blocks",
    levels: [
      ("init", [ 0 ]),
      ("base", [ 61 ]),
      ("sectionning", [ 100 ]),
      ("gather-ids", [ 120 ]),
      ("doc", [ 150 ]),
    ]
  }
]
</hcode>
<p>It is possible to change only the levels of some functions.
In the example below, the <doc href="module_base#inc"/> function
of module <doc href="module_base">Base</doc> will not be called
(as it is associated to an empty list of levels)
and the <doc href="module_base#base"/> function of the same module
will be associated to levels 2 and 230, while the rest of the scheme
remains unchanged:
</p>
<hcode lang="json">
levels: [
  { module: "html",
    levels: [
      ("base", [ 2, 230 ]),
      ("inc", [ ]),
    ]
  }
]
</hcode>
<p>
Each module can associate only one function to a given level:
for a level and a module, the last associated function hides the
previous function associated to this level, if any.
</p>
</section>


<section id="base" title="Common base rules">
<p>
Some predefined rules are applied in various functions of the
predefined modules. They are listed here.
</p>

<subsection id="contents" title="contents">
<p>
<icode lang="xml">&lt;contents/&gt;</icode> is the generic function to insert some
contents in an included file or template. It may be available or not depending
on the context.
</p>
</subsection>

<subsection id="env_" title="env_">
<p>The special tag <icode>env_</icode> can be used to modify the environment
before analysing children. For example, here we add an association
between "login" and "zoggy". This will add to the environment
an association between the key "login" and
the function returning the one-element list ["zoggy"], which is used
later in the "login" attribute:
</p>
<hcode lang="xml"><![CDATA[<env_ login="zoggy">
  ...
  <user login="&lt;login/&gt;">...</user>
  ...
</env_>]]></hcode>
<p>Such a function cannot be created in plugins, since functions only return
XML trees, not a new environment. But your functions can return XML trees
containing <icode>env_</icode> tags to modify the environment used to
evaluate the returned XML trees.
</p>
</subsection>

<subsection id="langswitch" title="langswitch">
<p>
If <icode>stog</icode> is launched with option <icode>--lang language</icode>, the
<icode lang="xml">&lt;langswitch&gt;</icode> function returns some code to access
to pages in other languages than <icode>language</icode>.
</p>
</subsection>

</section>

</contents>
</page>