<page title="Getting started"
navbar-doc="active"
with-contents="true"
>
<command prompt="#"><pre><prompt/> <contents/></pre></command>
<contents>
<prepare-toc depth="1">
<toc>Sections:</toc>
<section id="principle" title="Principle">
<p>
When launched on a given root directory, <icode>stog</icode> will read all files
and directories
from this starting point and generate the same hierarchy in the output directory.
</p>
<p>
Some of the files will be read as <i>elements</i>, i.e. xml files which will
be processed through a templating engine to produce the final file.
</p>
<div class="alert alert-warning">
<p>
The element files being handled as XML documents, the boolean attributes,
like in HTML5, are not allowed. So, when using Stog to generate HTML5 pages,
instead of writing
</p>
<hxml><tag att1="..." att2="..." boolean-attribute att3="..." ...>...</hxml>
<p>you have to give a
<ext-a href="http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#boolean-attributes">value
to the boolean attribute</ext-a>, for example</p>
<hxml><tag att1="..." att2="..." boolean-att="boolean-att" att3="..." ...>...</hxml>
<p>
or simply
</p>
<hxml><tag att1="..." att2="..." boolean-att="" att3="..." ...>...</hxml>
</div>
<p>
The <icode>.stog</icode> directory in the given root directory contains the
templates (in directory <icode>templates</icode>) and the
<icode>config</icode> file, containing stog configuration. In this file,
using regular expressions, one can indicate which files must be ignored,
and which files are elements. Files not being ignored nor being elements
will be copied by <icode>stog</icode> in the target directory.
The "follow-symlinks" option indicates whether to follow symlinks or not.
Default is to ignore symlinks.
</p>
<p>
Here is an example of <icode>.stog/config</icode> file:
</p>
<hcode lang="ocaml" defer_="1"><include file="./.stog/config" raw="true" depend="false"/></hcode>
<p>
A default file is generated by <icode>stog</icode> if it does not exist.
</p>
<p>
When launched, <icode>stog</icode> performs the following actions:
</p>
<ol>
<li>Read the given directory hierarachy;</li>
<li>Create the output directory;</li>
<li>Generate element files in this directory;</li>
<li>Copy all other files in the target directory, of course
keeping the source directory structure.</li>
</ol>
</section>
<section id="elements" title="Stog elements">
<p>
An element is an Xml tree, defined in a file matched by the regular expressions
given in the configuration file. It has one of the following forms. First form:
</p>
<hcode lang="xml">
<![CDATA[<type title="Element title"
attribute="value"
attribute2="value2"
...
>
Here is the body of the element.
</type>
]]>
</hcode>
<p>Second form, almost the same, except that <icode>with-contents="true"</icode>
indicates that more attributes are given in subnodes, and the body is in the
<icode>contents</icode> subnode:
</p>
<hcode lang="xml">
<![CDATA[<type title="Element title"
with-contents="true"
attribute="value"
...
>
<attribute2>value2</attribute2>
...
<contents>Here is the body of the element.</contents>
</type>
]]>
</hcode>
<p>
<icode>type</icode> can be any string (like "post", "page", ...) and defines the type
of the element. This allows different treatements according to the element type.
</p>
<p>
You can specify any attribute for an element. Some attributes are used
internally:
</p>
<ul>
<li><b>title</b>: this is the title of the element; use <icode><elt-title/></icode>
in templates to access it,</li>
<li><b>keywords</b>: the list of comma-separated keywords associated to the element;
use <icode><elt-keywords/></icode> in templates to insert the list of keywords
with links to by-keyword index,</li>
<li><b>topics</b>: same as keywords, but for topics (access with <icode><elt-topics/></icode>),</li>
<li><b>date</b>: the element date, used for sorting in list. The date in specified in
the form <i>YYYY/MM/DD</i>. Use <icode><elt-date/></icode> in templates to insert it,</li>
<li><b>published</b>: can be set to <i>false</i> to prevent the element from being generated;
useful when an element is not ready yet for publication,</li>
<li><b>sets</b>: a comma-separated list of set names; sets can be used to list elements
belonging to a set,</li>
<li><b>language-dep</b>: can be set to <i>false</i> to indicate that this page is not
language dependent, when generating multi-language sites (this affects the name of the
generated file),</li>
<li><b>doctype</b>: specify the doctype which will be printed into the final XML file. Default is "HTML".
If doctype is "HTML" (case-insensitive), tags are not self-closed, except
<ext-a href="http://www.w3.org/html/wg/drafts/html/master/syntax.html#void-elements">HTML5 void elements</ext-a>.
</li>
</ul>
<p>
Any other attribute will be available by its name in the environment when processing the template
associated to the element type. The element type can be accessed with <icode><elt-type/></icode>.
More details in <elt href="#functions"></elt>.
</p>
<p>
To generate the file corresponding to an element, <icode>stog</icode> will use the type of
the element (for example "post") to load the associated template (for example "post.tmpl" in
the templates directory).
</p>
<p>You can have a look at the source of the pages of this site at the bottom of each page.
The sources of this site can be a good starting point. You can browse it in the
<ext-a href="https://github.com/zoggy/stog/tree/master/doc">doc directory of the
distribution</ext-a>.
</p>
</section>
<section id="mainelement" title="Stog main element">
<p>
One element is called the main element. This element is a regular
element with the <icode>main</icode> attribute set to "true". There can be only
one main element.
</p>
<p>
Some attributes of this main element are used to specify site-wide information:
</p>
<ul>
<li><b>title</b>: The title of the blog is the same as this element and can be accessed
with <site-title/> in templates,</li>
<li><b>stog:site-description</b>: A short description of the site; use <site-description/>
to access it in templates;</li>
<li><b>stog:site-url</b>: The base url of the site, used to forge urls when generating pages;
use <site-url/> to insert it in templates,</li>
<li><b>stog:site-email</b>: A contact email for the site, accessible with <site-email/>,</li>
<li><b>stog:rss-length</b>: The default length of RSS feeds.</li>
</ul>
<p>
In the main element, any attribute beginning with "stog:" will be used as global attribute
and accessible in all templates by its name. Other attributes are associated to the element only.
</p>
</section>
<section id="running" title="Running Stog">
<p>
To compile your web site, use the following command:
</p>
<command-line><![CDATA[stog <root-directory>]]></command-line>
<p>Stog will generate your web site in <icode>./stog-output</icode>,
except if you use the <icode>-d</icode> option to specify another
output directory.
</p>
<p>You can specify a template directory with the <icode>--tmpl</icode>
option. By default, the templates are searched in the <icode>.stog/templates</icode> directory
of the specified root directory.
</p>
<p>
It is possible to give more than one directory to <icode>stog</icode>. In this case,
all pages and articles are merged as if all were defined in the last directory
given. It may be useful to gather blogs or page to generate one big site. Or not.
</p>
<p>The <icode>--site-url</icode> option is used to override the <icode>stog:site-url</icode>
field of the main element. It it useful to generate a local site, for example
</p>
<command-line>stog --site-url file:///tmp/website your-directory</command-line>
<p>
to test your site locally with correct links.
</p>
<p id="optiondef">
The <icode>--def</icode> option can be used to define an additional global rule. For example
</p>
<command-line>stog --def stogdir:`pwd`</command-line>
<p>
will make the current working directory accessible using <icode><stogdir/></icode>.
</p>
<p>The <icode>--plugin</icode> option makes <icode>stog</icode> dynamically
load the given OCaml object file. The loaded plugin can define new functions
to associate to some tags, or even override some pre-defined functions.
See <page href="plugins"/>.
</p>
<p>
If a plugin was installed with ocamlfind, the <icode>--package</icode> option can be used
to specify a list of comma-separated packages to load. <icode>ocamlfind</icode> will
then be used to get the location and required files to load these packages, in bytecode
for <icode>stog.byte</icode> or native-code for <icode>stog</icode>.
</p>
<p>At last, the <icode>--lang</icode> option is used to generate the website
for one language. By default, the only known languages are "en" and "fr".
If you use the <icode>--lang en</icode> option, then pages will be generated
in <icode>.en.html</icode> files and all <icode><fr></icode> nodes will be removed.
Then you can run <icode>stog</icode> with the <icode>--lang fr</icode>
to generate the "fr" part of your web site, removing all <icode><en></icode>.
</p>
<!--
<p>
If you need more languages, just define "stog:languages" in the main element
this way:
</p>
<hcode><![CDATA[<type main="true" ... stog:languages="es,de,fr,en">...</type>]]></hcode>
<p>This makes <languages/> returning the list of languages, and it is used by
the provided
-->
<p>
Stog will keep computed elements in directory <code>.stog/cache</code>.
To prevent stog from using this cache, use the <code>--nocache</code>
command line option. The cache won't be read, but it will nevertheless
be updated by contents of computed elements.
</p>
<p>
The caching strategy uses dependencies between elements: if an element
refers to another one (see <elt href="funs"/>), a dependency will be
added and stored in the cache directory, so that this dependency will
be used during the next run of stog. An element can also depend
on files: the templates used, the files included, ... Dependencies are
recursively computed.
</p>
<p>
In some cases, using recursive dependencies may be too complete. For example,
if you have a menubar appearing in all pages, all pages will depend on
the elements referenced by the menubar, leading to all elements depending
on all elements. A change in any element will then make every element recomputed
at each run. To prevent this, the <code>--depcut</code> option specifies
to use non-recursive dependencies in the caching strategy.
</p>
<p>
A convenient way to use stog is to create a Makefile with different targets,
to generate your site for a local test and for online publishing.
Have a look at <ext-a href="https://github.com/zoggy/stog/tree/master/doc/Makefile">this
Makefile</ext-a> used to build stog documentation.
</p>
</section>
<section id="templates" title="Evaluation and templating">
<p>
The final files corresponding to elements are built the following way.
</p>
<p>Various rewrite levels are defined in Stog, and plugins can add more levels.
</p>
<p>A level is composed of a list of functions, each function taking an element
and returning the (eventually modified) element. Pre-defined levels are composed
of functions applying rewrite rules to element body.
</p>
<p>Various levels are required to ensure some rules will be applied after
others, for example to verify cross-element links. Each level has a number,
and levels are applied in order from 0 to n. Pre-defined levels are
numbered like lines in BASIC programs: 0, 50, 100, 120, ... making
plugins able to insert new levels.
</p>
<p>The first application of a level to an element uses the
type of the element to load the corresponding template; for example,
if the element has type "page", then a template <icode>page.tmpl</icode> will
be looked for.
</p>
<p>An environment is built containing the
<a href="#mainelement">site-wide attributes</a> and the element attributes.
This environment is a set of rewrite rules.
</p>
<p>In each level, each function of the level is applied to the element current body
(the "first current body" is the template, where <icode><elt-body/></icode> will be
rewritten to the tree of the element body as given in the element file).
</p>
<p>The pre-defined levels contain pre-defined functions which apply
<page href="funs">default rules</page>, in addition to the rules from
the environment and rules added by plugins.
</p>
<p>When all levels were applied to elements, the contents of each element
is stored in the cache (the <icode>.stog/cache</icode> directory).
The final XML file is also created from this contents.
</p>
<p>Remark: If the element file was not modified since the corresponding
cache file was stored, nor its dependencies (see <elt href="#running"/>),
the contents of the element is read back from
the cache, and the level functions are not applied to this element.
</p>
<p>The environment is used in the following way.
For each encountered node with tag <icode>t</icode>, <icode>t</icode> is looked up
in the environment for its associated <em>function</em> <icode>f</icode>.
</p>
<p>If no <icode>f</icode> is found, then the XML node is left untouched
and the children of the node are then analysed.
</p>
<p>If <icode>f</icode> is found, then it is called, given the environment,
the attributes and the children of the node. Then the function returns
a list of XML trees which must then be analysed.
</p>
<p>When this analyze reaches a fixpoint, the final XML is returned.
</p>
<p>This work is performed by the <ext-a href="https://github.com/zoggy/xtmpl">Xtmpl</ext-a>
library.</p>
<p>Besides, the contents of the attributes are also analysed to perform such substitutions,
before looking up for the tag in the environment.
</p>
<p>Stog comes with <page href="funs">predefined functions</page>
associated to some tags, but more can be created in
<elt href="plugins">plugins</elt>.
</p>
</section>
<section id="functions" title="Attributes and functions">
<p>
When defining elements, you can add attributes, which will be added
to the base environment when applying level functions to this element.
For example:
</p>
<hcode lang="xml"><![CDATA[<page title="...."
...
author="Santa Claus"
>
.... <author/> ....
</page>]]></hcode>
<p>
Here the node <icode lang="xml"><author/></icode> will we rewritten to
"Santa Claus" (without quotes).
</p>
<p>The same can be achieved for more complex nodes, using the
<icode lang="xml">with-contents="true"</icode>
attribute:
</p>
<hcode lang="xml"><![CDATA[<page title="...."
with-contents="true"
...
>
<author><b>Santa Claus</b></author>
<contents>
.... <author/> ....
</contents>
</page>]]></hcode>
<p>here <icode lang="xml"><author/></icode> will we rewritten to
<icode lang="xml"><b>Santa Claus</b></icode>.
</p>
<p>
You can also define functions. A function is defined like an attribute
when having <icode lang="xml">with-contents="true"</icode>, except the
node defining the name of the function has XML attributes:
</p>
<hcode id="function-def" lang="xml"><![CDATA[<page title="...."
with-contents="true"
...
>
...
<command prompt="#"><pre><prompt/> <contents/><more/></pre></command>
...
<contents>
.... <command>ls -l</command>
</contents>
</page>]]></hcode>
<p>
Here we define a function <ixml><command></ixml> which allows to put some
XML into a <ixml><pre/></ixml> node, with a prompt before.
<ixml><contents/></ixml> is used to insert the "contents" parameter of the function,
that is the subnodes of the <ixml><command></ixml> node.
</p>
<p>So <icode lang="xml"><command>ls -l</command></icode> will be rewritten to
<ixml><command>ls -l</command></ixml>.
</p>
<p>
<icode>prompt</icode> is an argument for <icode lang="xml"><command/></icode>, with a default
value set to "# ". This argument can be changed when "calling" the function:
</p>
<hcode id="function-app" lang="xml">... <command prompt="mysql> ">select * from table</command> ...</hcode>
<p>will be rewritten to</p>
<hcode id="function-app-result" defer_="1" lang="xml">... <command prompt="mysql> ">select * from table</command> ...</hcode>
<p>
Only attributes of the <ixml><command/></ixml> nodes which are
"declared" in the rule attribute list are added to the environment used
when applying the <ixml><command></ixml> rule.
</p>
<p>It is not unusual to declare only one dummy parameter to create a function
so that <ixml><contents/></ixml> can be used in the rule body, this way:
</p>
<hcode lang="xml"><![CDATA[<page title="...." with-contents="true" ... >
...
<emph foo=""><b><i><contents/></i></b>
...
<contents>
... <emph>bla bla</emph> ...
</contents>
</page>]]></hcode>
<p>
To define functions available for all elements, you have to define them in
the main element and prefix their name with "stog:", like "stog:command". Then,
the <ixml><command></ixml> rule will be available in all elements; besides
it can be redefined in an element to change this rule for this element only.
</p>
</section>
</prepare-toc>
</contents>
</page>
