Publier et braconner (2)

Un point important est que l'écriture d'articles (ou d'autres types de documents) doit être facile, du moins la plus facile possible compte tenu du fait qu'il s'agit d'écrire pour la machine, comme c'est déjà le cas lorsqu'il s'agit d'écrire en LaTeX.

Comme je l'ai évoqué dans le précédent billet, l'écriture pour le web suppose de produire des documents HTML, et nous pourrons mettre des morceaux de LaTeX dedans, mis en forme par MathJax¹

Plutôt que les auteurs écrivent tout le HTML à la main, ce qui se révèle d'une part pénible et d'autre part provoque une duplication du code HTML pour avoir un style homogène sur toutes les pages du site, je propose d'utiliser Stog.

L'intérêt est triple:

1. faciliter l'écriture de documents en se concentrant sur le fond et sur le "type" des éléments: section, preuve, proposition, théorème, figure, paragraphe, ...; il s'agit donc de fournir à l'auteur des balises XML simples qui seront traduites vers le HTML final; de plus, Stog permet de:
   • gérer les références entre documents et à l'intérieur d'un document (comme les \label et \ref en LaTeX),
   • gérer les notes de bas de "page",
   • gérer la bibliographie (voir un exemple dans ce billet),
   • gérer les numérotations de sections, théorèmes, figures, etc., et d'y faire référence,
   • générer des identifiants pour les paragraphes non identifiés explicitement par un attribut id="..."; ainsi on peut faire référence à n'importe quel paragraphe d'un article², par exemple depuis une review.
   Quand j'écris qu'il est possible de faire référence, cela signifie que Stog vérifie que la référence existe et affiche une erreur si ce n'est pas le cas. Dans le HTML final, la référence se présente habituellement sous forme d'un lien permettant d'aller à l'élément référencé (document ou élément d'un document).
2. donner du sens aux éléments du document: avoir une balise proof indique déjà la nature du contenu de la balise. Cela peut être utile dans le cas où l'on souhaiterait faire une traduction des articles dans un autre format, dans le cas d'un changement d'outil de génération par exemple; c'est un avantage pour la pérénité,
3. associer à ces balises spécifiques des traitements permettant d'enrichir automatiquement le graphe RDF associé au site (cf. plus bas).

Voyons maintenant rapidement comment fonctionne Stog, puis ce que l'auteur d'un document aurait à écrire pour publier.

Stog est principalement un moteur de réécriture de documents XML. Les documents HTML finaux étant du XML, Stog peut donc être utilisé pour les produire à partir de fichiers XML écrits par les auteurs.

Stog prend en paramètre un répertoire et fonctionne en trois phases:

1. Analyse du contenu du répertoire et de ses sous-répertoires, afin de déterminer quels fichiers doivent être soit recopiés directement dans le répertoire de destination, soit être transformés par le moteur de réécriture avant d'être copiés dans le répertoire de destination³.
2. Application de règles de réécriture aux fichiers XML qui doivent être réécrits. Ces règles de réécriture sont présentes dans différents niveaux. Chaque niveau possède une ou plusieurs règles de réécriture, appliquées jusqu'à arriver à un point fixe. Lorsque l'application des règles d'un niveau ne modifie plus le document, on passe au niveau suivant. Un exemple de règle est la transformation de
   

   <section id="foo" title="Titre de section">...</section>

   en
   

   <div class="section">
     <div class="section-title" id="foo">1. Titre de la section</div>
     ...
   </div>
   

   Des règles un peu plus complexes permettent de gérer les notes de bas de page, les tables de matières, la bibliographie, etc. Il est également possible d'écrire ses propres règles pour ses propres besoins. Lorsque tous les niveaux de règles de réécriture ont été appliqués aux documents à réécrire, les documents résultants sont copiés dans le répertoire de destination.
3. Copie des autres fichiers (images, ...) dans le répertoire de destination.

Voyons maintenant concrètement ce que doit écrire un auteur d'un article.

Nous nous plaçons dans le cas où le site est déjà mis en place, et où l'ajout d'un article se résume à écrire un fichier XML, qui sera traité comme les autres documents du site. Dans un prochain billet, j'exposerai une façon de travailler collaborativement à l'écriture d'articles, en utilisant un gestionnaire de configuration.

Imaginons que l'auteur souhaite écrire un article de mathématiques, avec propositions, théorèmes, figures, preuves, bibliographie. Voilà un exemple de ce qu'il devrait écrire dans un fichier, par exemple mon_article.html:

<!-- type du document: ici article -->
<article
title="Titre de l'article"
date="2013/02/08"
keywords="variable length markov chains, tries, comb"
with-contents="true"
>
<!-- with-contents="true" indique que le contenu du document sera
  dans la balise contents, de façon à pouvoir
  spécifier quelques informations supplémentaires avec des balises -->
<bibliographies>
   <!-- nous spécifions les bibliographies, ici une seule que nous
        appelons "mybib" et qui contient les références présentes
        dans les fichiers "commonbib.bib" et "morebib.bib" -->
  <bibliography name="mybib"
                files="commonbib.bib,morebib.bib"/>
</bibliographies>
<authors>
  <!-- une façon d'indiquer les auteurs; ce format n'est pas arrêté -->
  <author href="http://chauvin.perso.math.cnrs.fr/"
          affiliation="Université de Versailles Saint Quentin etc."/>
  <author href="..." affiliation="..."/>
</authors>
<abstract> <!-- l'abstract -->
  <p>
  In this article, ...
  </p>
</abstract>

<contents> <!-- ici commence le contenu de l'article -->

<abstract/> <!-- ici on insère l'abstract défini plus haut -->

<section id="introduction" title="Introduction">
  <p>
  Iamque non umbratis fallaciis res agebatur, sed qua palatium est
  extra muros, armatis omne circumdedit.
  </p>
  <p>
  Martinus agens illas provincias pro praefectis aerumnas
  innocentium graviter gemens saepeque obsecrans, ...
  </p>
</section>
<section id="construction" title="Construction">
  <p>
  ...
  </p>
  <p>
  An example is shown on <figure href="figcons"/>.
  </p>
  <!-- une figure, qui sera numérotée et référençable par
       son id "figcons" -->
  <figure id="figcons" title="Example of construction">
    <img src="..."/>
    <legend>This figure shows the construction for $n=1$.</legend>
  </figure>
</section>
<section id="depth" title="Properties on depth">
  <p>
  ...
  </p>
  <prop id="propdepth1" title="Depth of the trie">
    <p>
    The depth of the trie after $n$ insertions is ...
    </p>
  </prop>
  <proof id="proofdepth1" of="#propdepth1">
    <!-- ci-dessus nous indiquons que la preuve prouve la proposition
         ayant pour id "propdepth1" -->
    <p>
    For a finite word $w$ ...
    </p>
    <p>Then, according to <cite href="thisref"/>, ... </p>
    <qed/>
  </proof>
  <p>
  ...
  </p>
</section>
...
<section id="conlusion" title="Conclusion">
  <p>
  ...
  </p>
</section>

<section id="biblio" title="References">
<!-- insertion des références de la bibliographie "mybib" -->
<bibliography name="mybib"/>
</section>
</contents>
</article>

On pourra voir un exemple de rendu final avec cet article.

Certaines des balises utilisées dans l'exemple ci-dessus peuvent enrichir le graphe RDF associé au site.

Ainsi,

<proof id="proofdepth1" of="#propdepth1">..</proof>

provoquera l'ajout d'un arc

sc:proves représente la relation entre les deux éléments, et doit être définie dans un vocabulaire spécifiant les relations possibles entre éléments. Il faudra donc définir ce vocabulaire pour pouvoir exprimer des relations telles que "utilise" (pour une preuve qui utilise un théorème par exemple), "prouve", "est auteur de", "est une review de", "n'est pas d'accord avec", "est d'accord avec", ...

Le graphe final obtenu avec toutes les relations exprimées dans les documents du site pourra ensuite être utilisé pour des requêtes:

• quels sont les articles de tel auteur ?
• où est utilisé ce théorème ?
• ...

L'intérêt de publier également ce graphe est de permettre à d'autres sites de l'utiliser et le fusionner avec d'autres graphes. Symétriquement, on peut imaginer récupérer régulièrement les graphes similaires produits par d'autres sites fonctionnant sur le même principe, pour faire des requêtes impliquant des documents scientifiques publiés ailleurs.

On voir alors apparaître un mode de publication distribué mais qu'il est pourtant possible d'exploiter par des requêtes.

L'exemple ci-dessus montre que la rédaction pour le web, en utilisant Stog, reste très facile: quelques balises à utiliser, tout en restant libre d'utiliser au besoin du HTML brut pour des effets de présentation spécifiques.

La vérification des références à la génération du site permet d'obtenir un site correct au niveau des liens internes. L'utilisation de balises spécifiquement adaptées à un type de documents (ici des articles scientifiques) fournit une mise en page homogène et soulage l'auteur en terme de code HTML à taper. Enfin, les informations précisées par l'auteur permettent la génération d'un graphe RDF à des fins de recherches, croisements, etc. Le tout me semble rester léger pour l'auteur, ce qui est un point important.