In the following descriptions, the current document refers to the document whose path is retrieved by the <doc-path/> function.

Here are the functions of the module, which can be associated to levels (see ):

This function applies the following rules, mainly for simple formatting and referencing to the site or the current document information.

Plugins can add rules to this list, using the Stog.Html.register_base_rule function, possibly redefining pre-defined rules with the same names.

<archive-tree/> inserts the archive tree.

<as-cdata/> transforms the children of the node into simple CDATA. For example, <as-cdata><coucou/></as-cdata> will be replaced by <coucou/>

<as-xml/> parses the contents of the node as XML. For example, <as-xml>&lt;coucou/&gt;</as-xml> will be replaced by <coucou/>

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

<date-now/> returns the current date and time. It handles the format attribute (see. ).

<date-today/> returns the current date. It handles the format attribute (see. ).

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

The following optional attributes can be specified:

  • max="n" can be used to list only the n most recent documents.
  • rss="..." or alt-doc-path="..." triggers the creation of an alternative document listing the selected documents. If the given path is not absolute (i.e. it does not start with '/'), the path is appended to the parent path of the document. For example, if documents alt-doc-path="bar.rss" is used in a document with path "/foo/bar.html", the alternative document will have path "/foo/bar.rss". A link to this alternative document is also added before the list.
  • alt-doc-type="..." specifies the type of the alternative document if it is created; default type is "rss", and a default template will be created if no template for this type exists.
  • alt-doc-in-list-tmpl="..." specifies the template to use for each document in the list of documents in the alternative document. Default template is "rss-item.tmpl" and it is created if is does not exist.
  • set="name" can be used to select only the documents belonging to the given set.
  • type="type1,type2,..." filters the documents to keep only the ones with one of the given types.
  • alt-doc-title="title" specifies the title of the alternative document, if it is created. If no alternative document title is given, the document title is used.
  • By default, items are sorted according to the date of each document. Specifying sort="rule1,rule2,..." make documents sorted according to the given rules, expanded for each document.
  • By default, items are listed in descending order; reverse="false" make the documents listed in ascending order.
  • tmpl="..." specifies a template file to use for each document of the list. Default is .stog/templates/doc-in-list.tmpl.
  • list-tmpl="..." specifies a template file to use for the list. Default is .stog/templates/doc-list.tmpl. In this template, <alt-link/> is the url of the link to (tyically) the RSS feed, and <items/> is the tree of listed documents.
  • filter="p" specifies to keep only documents verifying the given predicate p. The predicate can be an expression such as attribute='value' The attribute refers to a field defined in the document header, or defined in the main document for the whole site if it has the form "id:id". The expressions accepted as filters follow this grammar:

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

<doc-body/> returns the body of the current document, or of the document referenced by the doc-path attribute.

<doc-date/> returns the date of the current document, or of the document referenced by the doc-path attribute, or an empty string if no date were specified.

The format attribute, if present, specifies the format used to print the date. This format can be:

  • "rfc3339": to print the date to RFC3339 format, like 2016-10-17T10:30:00+02:00.
  • "rfc822": to print the date to RFC822 format, like 2016-10-17T10:30:00+02:00.
  • any other string with % tags. Supported tags are :
    • %Y: replaced by the year
    • %M: replaced by the month on two digits
    • %D: replaced by the day on two digits
    • %h: replaced by the hour on two digits
    • %m: replaced by the minute on two digits
    • %s: replaced by the second on two digits
    • %%: replaced by the '%' character.

If the format is not specified, the current language specific form is used, as in 2016-10-17T10:30:00+02:00.

<doc-datetime/> returns the date and time of the current document, or of the document referenced by the doc-path attribute, or an empty string if no date were specified. It handles the format attribute (see. ).

<doc-path/> returns the path of the current document.

<doc-intro/> returns the introduction of the current document (or of the document referenced by the doc-path attribute), that is the body code before the <sep_/> marker.

<doc-navpath/> builds a navigation bar in the form of a list of links showing the hierarchy to the current document (or the document referenced by the doc-path attribute).

Suppose we're handling the document whose source file is STOGDIR/foo/bar/gee.html. Its doc-path is /foo/bar/gee.html. The path will contain two parts, one for foo and one for bar. If a document /foo exists, then a link to this document is added. Else, if a document /foo/index exists, then a link to this document is added. Else no link is added and the directory name is used, with no link. The same is done for the /foo/bar document.

The separator of path parts is the code given under the <doc-navpath> node.

To illustrate, the code

<doc-navpath doc-path="/foo/bar/gee"> / </doc-navpath>

will produce the following code:

/

which results in:

/

The with-root="..." attribute can be used to specify the path of a document used as root. For example:

<doc-navpath doc-path="/foo/bar/gee.html" with-root="/index"> / </doc-navpath>

will produce the following path:

/

<doc-src/> returns the source filename of the document or of the document referenced by the doc-path attribute.

<doc-title/> returns the title of the current document or of the document referenced by the doc-path attribute.

<doc-type/> returns the type of the current document or of the document referenced by the doc-path attribute.

<doc-url/> returns the final url of the current document or of the document referenced by the doc-path attribute:

]]>

is reduced to

<dummy_/> is replaced by the contents of the node. It is useful to insert an empty tree where a tree is required, for example in a .

When encountered, <error_/> will produce an error message from the contents of the node. It is useful with to ensure some condition is verified, for example to make sure a variable is not empty in the environment.

Execute shell commands. See details.

<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 documents in SVG format, and returns a link to this graph displayed as a small graph. One can click on a document in the generated SVG graph to jump to the document.

your code]]>

This function inserts the given pre-formatted code. If the language is not natively known by the Higlo engine in Stog, the external highlight tool is used 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:
]]> 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).

...]]>

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 document 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 document on the given file. Use depend="false" to prevent adding this dependency.

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

]]>

It is possible to include only the contents of the XML node read in the file, by setting the attribute subs-only="true".

Instead of including a file, it is possible to include a block of a document, by referring to its path and id in the href attribute:

]]>

This code includes the XML node referenced by the href attribute. An error is raised if the document does not exist, if no fragment id is provided, or if the fragment id does not exist in the referenced document. If an id attribute is provided, the included node has this new id, else the original node id is kept; this is useful to avoid conflicts with other ids.

This rule is useful to avoid code duplication. It is used in this site to show changes of a release both in the page and in blog post such as .

For example, the following code will include the paragraph with id "optiondef" of document "running":

This is the result:

<doc-keywords sep="..."/> and <doc-topics sep="..."/> respectively return the keyword and topic list of the current document, as defined in the document. 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.

<latex-body>...</latex-body> is not documented yet. You can try to put some LaTeX code as contents and see...

.........

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

For example:

applebananaorange

will be reduced to

applebananaorange ...]]>

This adds the given prefix to all id and href attributes in the subnodes. This is useful when including generated SVG files to prevent conflicts in ids.

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

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

This rule evaluates OCaml code. See details.

This rule returns a formatted string from the arguments. See the following blog post: .

This rules returns a human readable representation of the date given in the node. Example:

2014-09-25]]>

will return 2014-09-25.

The rule handles the chosen language (see command line options) and the format attribute to format the output.

This rules returns a human readable representation of the date and time given in the node. Example:

2014-09-25 10:12:57+01:00]]>

will return 2014-09-25 10:12:57+01:00.

The rule handles the chosen language (see command line options) and the format attribute to format the output.

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

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

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

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

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

]]>

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 function creates new documents:

  • The archive pages, one for each month when there is at least one document in this month (see also ),
  • The keyword pages, one for each keyword appearing in documents,
  • The topic pages, one for each topic appearing in documents.

This function 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 the function of the .

By default, sectionning nodes without id attribute are not kept. Set attribute show-without-ids="true" to keep all sectionning nodes.

This function applies the <cut-doc> rule to cut a document in pieces according to some specified nodes.

... ...
...
...
... ]]>

If the document has path /foo, this will create two more documents, /foo-sec1 and /foo-sec2, of the same type of the document (here foo). Their titles will be respectively "Section 1" and "Section 2", i.e. the titles of the cut nodes.

The path of each created document is forged by appending "-" and the cut node id to the path of the document.

Each created document has the subnodes of the cut node as body. Each cut node is replaced by a link to the corresponding created document. In our example, after <cut-doc> has been applied, our document body becomes:

... ]]>

If a node has no id or no title attribute, then it is not cut and a warning is issued.

The following attributes can be added to <cut-doc> to change the behaviour:

  • insert-link can be set to false to prevent adding links to the new documents in the original document,
  • type can be set to a string to specify the type of the created documents, instead of inheriting the type of the original document,
  • path-sep specifies the separator used to forge the new paths; by default it is - but it can be for example /,

At last, various <cut-doc> can be nested, for example to cut according to <section> and <subsection> nodes:

... ...
]]>

Of course, nodes which are not under the <cut-doc> nodes remain untouched, allowing to cut only a part of the document.

This function applies the <late-inc> rule, which works like but, having a different name, it can be applied later, typically to include blocks which were not available earlier in the rewrite process.

It also applies the <late-cdata> rule, which works like but, having a different name, it can be applied later, typically to transform into CData an XML tree after it has been rewritten in the previous levels.

This function closes the OCaml sessions previously opened with <ocaml-eval>.