$$

</h1> <contents/> </div> </slide> <showeval codefile=""> <div class="centered"> <div class="row"> <div class="span10"> <hxml defer_="1"><include raw="true" defer_="1" file="<codefile/>"/></hxml> </div> </div> <div class="row"> <div class="span1 showeval-arrow">↳</div> <div class="span11"> <div><include defer_="1" file="<codefile/>"/></div> </div> </div> </div> </showeval> <contents> <sep_/> <slide title="History"> <ul> <li> Started in August 2011, for my personal needs: website + blog. </li> <li> Improved for my professional needs: OCaml course, software documentation and web sites. </li> <li> Around 9500 lines of OCaml. </li> <li> Development hosted on Github: </li> <ul> <li>code: <ext-a href="http://www.github.com/zoggy/stog">http://www.github.com/zoggy/stog</ext-a></li> <li>website+doc: <ext-a href="http://zoggy.github.io/stog">http://zoggy.github.io/stog</ext-a></li> </ul> <li> Some sites generated with Stog: <ul> <li><ext-a href="http://gallium.inria.fr/blog/">Gallium's blog</ext-a>,</li> <li><ext-a href="http://form-ocaml.forge.ocamlcore.org/">Introduction au langage OCaml</ext-a>,</li> <li><ext-a href="http://zoggy.github.io/vlmc-suffix-trie/articles/uncommon-suffix-tries.html">a math article</ext-a>,</li> <li>software websites (<ext-a href="http://zoggy.github.io/chamo/">Chamo</ext-a>, <ext-a href="http://zoggy.github.io/genet/">Genet</ext-a>, <ext-a href="http://zoggy.github.io/erssical">Erssical</ext-a>).</li> </ul> </li> </ul> </slide> <slide title="What I wanted"> <ul> <li>a static site: easy to deploy, less security problems,</li> <li>handling of blog posts, with dates, topics, keywords and associated RSS feeds,</li> <li>dynamic comments for blog posts (⇒ using Disqus),</li> <li>no new syntax,</li> <li>using custom tags (e.g. <icode>section</icode>) to provide semantics in code,</li> <li>avoid code duplication,</li> <li>ability to use all HTML5 or any XML,</li> <li>check internal references,</li> <li>displaying evaluated OCaml code,</li> <li>support for multiple languages (fr, en, ..),</li> <li>ability to add specific features with plugins.</li> </ul> </slide> <slide title="How it works"> <p> Three steps: </p> <ol> <li>Read configuration file <icode>.stog/config</icode> and directory tree: <hcode lang="ocaml" defer_="1"><include raw="true" file="../.stog/config"/></hcode> </li> <li>Handle "elements",</li> <li>Copy other files, i.e. files not ignored and not elements. </li> </ol> </slide> <slide title="Step 2: handling "elements""> <div class="center centered"> <img src="how_it_works.svg" width="800px" alt="Handling element files"/> </div> </slide> <slide title="Step 3: copying other files"> <div class="center centered"> <img src="how_it_works2.svg" width="800px" alt="Handling other files"/> </div> </slide> <slide title="Example of element"> <p>Example: file <icode>doc.html</icode> from Stog's web site: </p> <hcode lang="xml" defer_="1"> <include raw="true" file="../doc.html"/> </hcode> </slide> <slide title="Another example of element"> <p>Example: file <icode>posts/release-0.7.0.html</icode> from Stog's web site: </p> <hcode lang="xml" defer_="1"> <include raw="true" file="../posts/release-0.7.0.html"/> </hcode> </slide> <slide title="Templates (1)"> <p> Templates are regular XML documents, with some XML nodes which will be rewritten. </p> <p>Templates are in the <icode>.stog/templates/</icode> directory.</p> <p>A template can be used in three ways:</p> <ul> <li>according to an element type, this type being the root node tag of the element: <hxml><page title="...">...</page></hxml> <hxml><post title="...">...</post></hxml> <icode>page</icode> will result in using the <icode>.stog/template/page.tmpl</icode> file has template for the element (and <icode>post.tmpl</icode> for <icode>post</icode> element). </li> <li>referenced in the <ixml>file</ixml> attribute of a <ixml><![CDATA[<include file="..."/>]]></ixml> node,</li> <li>used by other rewrite rules.</li> </ul> </slide> <slide title="Templates (2): Example"> <p> The template file <icode>.stog/templates/page.tmpl</icode>: </p> <hxml><include file="page.tmpl" raw="true"/></hxml> </slide> <slide title="Templates (3): Example (2)"> <p> The template file <icode>.stog/templates/doc-in-list.tmpl</icode>: </p> <hxml><include file="doc-in-list.tmpl" raw="true"/></hxml> </slide> <slide title="Rewrite rules"> <p> An environment is a map associating tag names to rules. We note <lx>\Gamma(t) = f</lx> to say that a function <lx>f</lx> is associated to the tag <lx>t</lx> in the environment <lx>\Gamma</lx>. If no function is associated to <lx>t</lx>, then <lx>\Gamma(t) = \bot</lx>. </p> <p> A rule is a function <lx>$f$</lx> taking in parameters: an environment <lx>$\Gamma$</lx>, a list of XML node attributes <lx>$l_a$</lx>, a list of XML (sub)nodes <lx>$l_{xml}$</lx>. A rule, when applied, returns a list of XML nodes. </p> <p> Let <lx>\mathcal{R}(\Gamma, n)</lx> be the function applying an environment <lx>\Gamma</lx> to an XML node <lx>n = (t, l_a, l_{xml})</lx>. <lx>\mathcal{R}_l(\Gamma, l)</lx> applies <lx>\mathcal{R}(\Gamma, x)</lx> on each element <lx>x</lx> of the list <lx>l</lx>. The algorithm of <lx>\mathcal{R}</lx> is the following: </p> <ol> <li>Apply <lx>\mathcal{R}</lx> on each attribute value, parsed as valid XML, to get a new list of rewritten attributes <lx>l_a'</lx>, </li> <li> If <lx>\Gamma(t) = \bot</lx>, then return [<lx>(t, l_a', \mathcal{R}_l(\Gamma, l_{xml}))</lx>].<br/> Else, with <lx>\Gamma(t) = f</lx>, return <lx>f(\Gamma, l_a', l_{xml})</lx>. </li> </ol> <p><lx>\mathcal{R}</lx> is called until a fixpoint is reached.</p> <p> This rewrite engine is implemented in the <ext-a href="http://zoggy.github.com/xtmpl/">Xtmpl</ext-a> library. </p> </slide> <slide title="Rewrite rules (2)"> <p> When we define an element, we're defining an environment <lx>\Gamma</lx>. </p> <p>Example: consider the following element:</p> <hxml><page title="Example page" author="Maxence Guesdon"> This is the body of my page </page></hxml> <p> Here we defined an environment <lx>\Gamma</lx> with the following rules: </p> <ul> <li><lx>\Gamma("doc-title") = f_1</lx> with <lx>f_1(\_,\_,\_) =</lx> [ "Example page" ]</li> <li><lx>\Gamma("author") = f_2</lx> with <lx>f_2(\_,\_,\_) =</lx> [ "Maxence Guesdon" ]</li> <li><lx>\Gamma("doc-body") = f_3</lx> with <lx>f_3(\_,\_,\_) =</lx> [ "This is the body of the page" ]</li> </ul> <p> To <strong>compute</strong> the element's final XML, we apply this environment to the template associated to the page type. </p> <p>Remarks:</p> <ul> <li>Of course, the initial environment is not empty. So defining an element adds rules to this initial environment. </li> <li> Predefined rules and user-defined rules can be more complex. </li> </ul> </slide> <slide title="The main element"> <p> One of the element must be marked has "main", with a <ixml>main="true"</ixml> attribute. This is usually the top <icode>index.html</icode> file but this is not mandatory. </p> <p> The main element is the place to define rules for the initial environment. These rules are defined using the <icode>stog:</icode> prefix (like an XML namespace). Defining <icode>stog:foo="bar"</icode> will make this rule appear in the initial environment with the name "foo". </p> <hxml><![CDATA[<page main="true" title="Stog" stog:site-description="Static blog and web site generator" stog:site-email="zoggy 'AT' bat8 'DOT' org" stog:site-url="http://zoggy.github.com/stog" stog:rss-length="10" navbar-home="active" > .... </page>]]></hxml> </slide> <slide title="A powerful rule: <icode>&lt;eval-ocaml&gt;</icode>"> <showeval codefile="./inria_code1.xml"/> <showeval codefile="./inria_code2.xml"/> <showeval codefile="./inria_code3.xml"/> <showeval codefile="./inria_code4.xml"/> </slide> <slide title="A powerful rule: <icode>&lt;eval-ocaml&gt;</icode> (2)"> <div class="center centered"> <img src="ocaml-sessions.svg" alt="Stog and OCaml sessions" width="800px"/> </div> <p> Having separate sessions is useful to prevent name pollution in your OCaml environment. </p> </slide> <slide title="Some predefined rules"> <ul> <li><icode><archive-tree></icode>,</li> <li><icode><block></icode>: to do the equivalent of LaTeX's <icode>\newenvironment</icode>,</li> <li><icode><elements></icode>: list elements according to type or other fields, associate RSS feed;</li> <li><icode><graph></icode>: include a graph of elements, linked by keywords,</li> <li><icode><hcode> and <icode></icode>: include syntax highlighted code (using Highlight),</li> <li><icode><if></icode>,</li> <li><icode><inc></icode>: include a node, to share code between elements,</li> <li><icode><latex></icode>: include latex rendered as SVG (using latex+dvisvgm),</li> <li><icode><list></icode>: add a separator between the sub nodes,</li> <li><icode><prepare-toc> and <toc></icode>: compute and insert table of contents,</li> <li><icode><section>, <subsection></icode>: default sectionning.</li> </ul> </slide> <slide title="Templates + rewrite rules = not enough!"> <p> We must ensure some rules will be applied before or after others. For example: </p> <ul> <li>computation of table of contents must occur before the <ixml><section></ixml> nodes are rewritten, but after all <ixml><include></ixml> have been resolved,</li> <li>most of rules must have been applied before resolving internal links.</li> </ul> </slide> <slide title="Levels of rewrite rules"> <p> Various levels of rewrite rules are defined, in a way mixing Linux run levels and BASIC line numbering 😃 </p> <ul> <li>each level is numbered,</li> <li>for each level, starting from level 0, the set of rewrite rules is applied to each element content: <ul> <li>rules of level 0 are applied to all elements,</li> <li>rules of next level are applied to all the resulting elements,</li> <li>and so on until the last level.</li> </ul> </li> <li>predefined levels are numbered 0, 50, 100, 120, 150, 160; this lets room for additional levels defined in plugins.</li> </ul> </slide> <slide title="Functions"> <p>One can define "functions" with parameters, to factorize code:</p> <late-inc href="atts-functions#function-def"/> <p>Now the <icode>command</icode> function (rule) can be "called" with a specific value for the <icode>prompt</icode> parameter:</p> <late-inc href="atts-functions#function-app"/> <p>This will produce the following code:</p> <late-inc href="atts-functions#function-app-result"/> </slide> <slide title="Plugins"> <p> Developing plugins consists in writing some OCaml code: </p> <hcode lang="ocaml" defer_="1"> <include file="../../plugins/plugin_example.ml" raw="true"/> </hcode> <p>More complex plugins can define new levels of rewrite rules.</p> </slide> <slide title="Plugins (2)"> <late-inc href="writing_plugins#codecompilation"/> <late-inc href="writing_plugins#usingcode"/> </slide> <slide title="Existing plugins"> <p> By now, two plugins are already available: </p> <ul> <li><strong>Stog-writing:</strong> bibliography management, footnotes and automatic ids for paragraphs,</li> <li><strong>Stog-RDF:</strong> definition of an RDF graph associated to the generated site. Some XML nodes are used to (easily) insert edges in the graph.</li> </ul> <p> These two plugins aim at being able to write scientific artiles with semantic information about elements of articles: </p> <ul> <li>"this block is a proof of this proposition",</li> <li>"this proof applies this theorem",</li> <li>...</li> </ul> <div class="center centered"> <img src="example_rdf2.svg" alt="example of RDF graph" /> </div> </slide> <slide title="Modules"> <p> A module system will allow reusing functions and definitions. A simple system already exists: </p> <hxml><![CDATA[ <page title="My page" use="math" ...> ]]></hxml> <p>The code above indicates to use definitions from <icode>.stog/modules/math.stm</icode>:</p> <hxml><![CDATA[ <module name="math"> <math:qed>∎</math:qed> <math:hasauthor href="" affil=""> <rdf pred="math:hasAuthor" href="<href/>"/> </math:hasauthor> <math:proof-of href=""> <rdf pred="math:proves" href="<href/>"/> </math:proof-of> <math:isproof><rdf pred="rdf:Type" obj="math:proof"/></math:isproof> <figure id="" title="" href=""><block counter-name="figure" class="figure" label="Figure" href="<href/>" id="<id/>" title="<title/>" > <div class="<class/>" id="<id/>"> <div class="title"><title/></div> <div class="contents"><contents/></div> </div></block></figure> ... ]]></hxml> </slide> <slide title="This is the end"> <h2>Thanks for your attention !</h2> <h2>Questions ?</h2> </slide> </contents> </slideshow>