This level also applies the base rules.

Some rules are pre-defined and can be used in your elements and templates. They are gouped in different levels (see ). We give here the list of pre-defined rules applied at each pre-defined level.

For most of the rules, 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 directory of the stog sources.

In the following descriptions, the current element refers to the element whose hid is retrieved by the <elt-hid/> function.

These rules are applied in each level:

<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.

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: ... ... ... ]]>

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.

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

The following rules are called base rules: they are applied on level 0 but also in some other levels. They are used for simple formatting and to use information about the current element.

The base rules defined by plugins are also added to this list, possibly redefining pre-defined rules with the same names.

<archive-tree/> inserts the articles archive tree.

Not documented yet.

<command-line> works like <hcode> with the lang attribute already set to "sh".

is reduced to the current value of the counter associated to the given name.

<elements .../> inserts the list of published elements.

The following optional attributes can be specified:

  • max="n" can be used to list only the n most recent elements.
  • rss="filename" triggers the creation of a RSS file corresponding to the selected elements. The given filename is appended to the stog output directory. A link to the RSS file is also added before the list.
  • set="name" can be used to select only the elements belonging to the given set.
  • type="type" filters the elements to keep only the ones of the given type.
  • title="title" specifies the title of the RSS channel, if a RSS file is created. If no title is given, the site title is used.

Example: <elements type="post" max="10" rss="index.rss"/>

<elt-body/> returns the body of the current element.

<elt-date/> returns the date of the current element, or an empty string if no date were specified.

<elt-hid/> returns the hid of the current element.

<elt-intro/> returns the introduction of an element, that is the body code before the <sep_/> marker.

<elt-src/> returns the source filename of the element.

<elt-title/> returns the title of the current element.

<elt-type/> returns the type of the current element.

<elt-url/> returns the final url of the current element.

<ext-a attributes>...</ext-a> is reduced to <span class="ext-a"><a attributes>...</a></ext-a>. This can be used to add specific style for links to external sites.

<graph/> computes the graph of elements in SVG format, and returns a link to this graph displayed as a small graph. One can click on an element in the generated SVG graph to jump to the element.

your code]]>

This function inserts the given pre-formatted code. It uses the highlight tool to add syntax highlighting. For example, the code examples of this page are inserted using ...]]>

<icode> works like <hcode> but is used to generate inline highlighted code instead of using a box.

]]>

The if function tests whether each condition expressed as attr="value" is verified. If so, the first XML child is returned, else the second one is returned. To test the value of attr, attr is looked up in the current environment. If its value is the same as the given value, the condition is verified. For this evaluation, a tag t not found in the environment in not reduced to itself but to the empty string, so that the condition in <if foo="">...</if> will be verified if foo is not in the environment.

The "value" part of the condition must be valid XML, and can contain calls to functions, as in: ....]]>

Other example: Testing whether a variable is empty to known whether to output a block or not:

The list is not empty, let's print it:
]]>

...]]>

This function will load the file template from the template directory (or fail if the file does not exist). The contents of the file will then be evaluated. The code between <include ...> and </include> is added to the environment used to evaluate the contents of the file, associated to the name contents.

With the additional attribute raw="true", the contents of the loaded file is considered as PCData. This is useful for example to insert code.

If the file attribute begins with "." or "..", that is the filename is explicitely relative, the file path is concatenated to the current element source file path.

If the file attribute is an absolute filename, then this absolute filename is used.

By default, using <include> adds a dependency of the current element on the given file. Use depend="false" to prevent adding this dependency.

At last, all additional attributes to <include ...> will be added to the environment used to evaluate the contents of the file.

Here is an example. If we have the foo.tmpl file in the template directory, with the following contents: key= value=

]]>

The following code

the value of bar]]>

will be reduced to

key=bar value=the value of bar

]]>

legend]]>

This inserts an image using an <img .../> node. The legend is optional.

The float attribute can be used to change a class in the generated code, so you can set the style of the image to be left or right floating.

Additional attributes are passed to the generated img node.

<keyword/> inserts the name of the current keyword, when computing keyword list (in template keyword.tmpl).

<elt-keywords sep="..."/> and <elt-topics sep="..."/> respectively return the keyword and topic list of the current element, as defined in the element. The optional sep attribute can be used to specify a separator between each keyword or topic.

Each keyword will be displayed using a keyword.tmpl template file. Each topic will be displayed using a topic.tmpl template file.

In these templates, <keyword/> (resp. <topic/>) inserts the name of the current keyword (resp. topic), when computing keyword (resp. topic) list.

<latex>...</latex> is used to compile latex code and display it as SVG in the page. Read this post for details.

.........

will is reduced to the list of subnodes, separated by the given sep attribute.

For example:

applebananaorange

will be reduced to

applebananaorange

<previous/> and <next/> respectively return a link to the previous and next element according to the chronological order of element dates.

<ocaml> works like <hcode> with the lang attribute already set to "ocaml".

This rule evaluates OCaml code. See the following blog posts: and .

<sep_/> is the tag used to indicate the end of the introduction of an element. It is reduced to an empty string.

<site-description/> returns the site description as specified in the main element.

<site-email/> returns the site contact email as specified in the main element.

<site-title/> returns the site title as specified in the main element.

<site-url/> returns the site url as specified in the main element.

]]>

This will put the two given XML nodes in a two-columns layout. Note that the tag used to enclose the left and right contents is not kept, so you may use any tag you want, for example:

bla bla blabla bla bla ]]>

<n-columns> works the same way but produces as many columns as there are children in the node.

This level only contains two rules: toc and prepare-toc.

... text ...
...
... ]]>

The <toc> node is used to insert a table of contents. If a text is given, it is added ahead of the table of contents.

Since the toc node does not include the sections and subsections, it is not sufficient to build the table of contents. So it will use what is returned by the function associated to "toc-contents" in its environment.

This function is added to the environment by the prepare-toc node, which includes all the sections and subsections. The depth attribute is used to specify the depth of the table of contents.

The nodes used for sectionning can be changed, see .

...
... ]]>

This is used to insert sections and subsections, with a given title. The id, if given, will be associated to the section title node.

"section" and "subsection" are the default sectionning nodes. You can specify other nodes:

  • for one element, using the "sectionning" attribute in the element, for example: ... will define "section", "subsection" and "paragraph" as sectionning nodes.
  • for all the site elements, using the "stog:sectionning" attribute in the main element (see ): ...

When a sectionning node is reduced, a is created, so that refering to the section (or subsection, or ...), will use the title of the section (or subsection, or ...) for the produced link default text.

To prevent a sectionning node having a counter associated, you can use section-counter="false" in the element attribute, or stog:section-counter="false" in the main element. "section" can be replaced by "subsection" or any other node to prevent this node having a counter.

This level does not contain any additional rule. The only function pre-defined in this level gathers all ids of all element, so that cross-links in next levels can be verified.

This function will issue a warning when an id is defined twice in the same element.

The default rules defined in this level are the following: elt, post, page and block.

text]]>

This will return a link to the element specified by its hid. The hid of an element is its absolute name from the root directoty of your project. You are not forced to give the full path, but can also give only one or more of the last parts of the path, as long as it uniquely identifies an existing element.

For example, suppose you want to refer to the element defined in file <root dir>/foo/bar/hello.html. The hid of this element is "/foo/bar/hello". You can refer to it in various ways:

  • with its absolute hid, providing the heading '/': /foo/bar/hello,
  • with only the last part of its hid: hello,
  • with an ending subpart of its hid: bar/hello.

In the last two cases, an error will be raised if more than one elements match the incomplete hid. You can provide an additional attribute type to prevent ambiguities, for example:

]]>

Refering to an unknown element will raise an error. If no hid is given, <elt-hid/> is used instead, i.e. the string associated to elt-hid in the environment, to retrieve the current element hid.

A node id can also be specified, like thisblock in href="blabla#thisblock". Refering to an unknown block id will raise an error.

If no text is given for the link, the title of the element will be used instead (or, if a node id is given, the title associated to the node id, if any). Specifying in attributes quotes="true" indicates to add quotes around the element title.

<page ...> and <post ... > are equivalent respectively to <elt type="page" ...> and <elt type="post" ...>.

The block rule in this level hides the base rule. In this level,

text

is used to refer to a block using the given href attribute. Here the href only contains an id, it is not of the form "hid[#id]". This will be reduced to a link to the corresponding element, using the given text.

If the node matching the href was defined with the base rule (i.e. without href attribute), then the title associated to this node is used as text for the procuded link, if no text was given ().

So,

is equivalent to

or

But the purpose of block rule is not to be used directly, but rather by defining other rules reducing to block, like environments in latex for figures, proofs, propositions, ...

Here is an example of definition of a function in an element definition:

</div> <div class="contents"><contents/></div> </div></block></theorem> <contents>...</contents> </article></hcode> <p>This defines a new rule <icode>theorem</icode> used this way to define a new theorem:</p> <hcode lang="xml"><theorem id="thmain" title="Main result">...</theorem></hcode> <p>Elsewhere, this theorem can be referred to using</p> <hcode lang="xml"><theorem href="thmain"/></hcode> <p>which will be reduced to a link with "Theorem 1" as text, if this theorem was the first defined in the article. </p> </section> <section id="level160" title="Level 160: Including blocks"> <include file="syntax.tmpl"><![CDATA[<inc href="..."/>]]></include> <p> This rule is used to insert the XML node specified by the <icode>href</icode> attribute. See <elt href="#level150"/> for details about how to specify an element. The id of the node if mandatory for this command. </p> </section> </prepare-toc> </contents> </page>