zoggy a écrit 16 commentaires

Je veux dire, c'est le principe d'un outil que d'avoir certaines conventions : ce que je critique, c'est le fait d'en avoir inventé une nouvelle.

Mais avec l'expérience, j'ai tendance à préférer le lourdingue mais standard, à du moins lourdingue mais « exotique ».

Les outils existants et les conventions qui venaient avec ne me satisfaisaient pas, donc j'ai en effet créé (encore) un autre outil avec (encore) de nouvelles conventions. C'est un choix qu'on fait tout le temps: utiliser un outil existant et s'y plier, ou bien développer son propre outil. J'ai toujours aimé développer mes propres outils (j'utilise mon propre éditeur de code, notamment), c'est une façon d'être indépendant des évolutions faites dans des outils "standard" et d'avoir un outil conçu par rapport à mes pratiques. Bien sûr je n'utilise pas que des outils que j'ai développés, mais je suis attaché à l'idée que chacun puisse choisir d'utiliser les outils existants ou de développer les siens; c'est aussi de là que vient la diversité, avec les outils comme "véhicules" pour communiquer des idées.

si tu places ton système dans le monde « hypertexte », les références relatives des URL doivent se faire par rapport à l'emplacement du document lui-même.

Ok. J'avais commencé un greffon dans ce sens, que je ne n'ai pas eu encore le temps de finir. Puisque c'est la norme de faire ainsi, je pourrais en faire le fonctionnement par défaut. Merci.

Pour info, dans Stog, un document peut faire référence à un autre en indiquant son chemin depuis la racine du site, mais comme ça peut vite devenir lourd, on peut aussi indiquer seulement la fin du chemin, tant que celle-ci est unique (voir un exemple ici).

Je n'ai pas tout à fait compris cette phrase : tu veux dire que les balises « processées » par Stog sont seulement celles filles du nœud racine ?

Oui et non. Le premier nœud permet d'indiquer des métadonnées (titre du document, date, …) et le "corps" est dans les nœuds fils. Tout est donc utilisé par Stog, mais les attributs du nœud racine sont traités différemment: ils ne sont pas réécrits mais permettent d'enrichir l'environnement utilisé pour la réécriture. Plus précisément, tout le contenu du document permet d'enrichir l'environnement de réécriture appliqué au gabarit à utiliser (qui est celui indiqué par la balise racine), cf. mon exemple.

Ah… OK, c'est ce dont j'avais peur : ça semble beaucoup moins intéressant du coup, un nouveau « standard » particulier.

Hum, désolé mais je ne comprends comment le fait de n'avoir pas de schéma particulier entraîne un nouveau « standard » particulier. Il me semble au contraire que n'avoir aucune contrainte laisse davantage de liberté. Ensuite, tu peux toujours valider tes documents avant et/ou après compilation.

j'ai l'impression que tu as réinventé XSLT, en moins bien…

Selon quels critères ?

le fait de réinventer un algo de résolution d'URL…

Tu peux être plus précis ? de quel algo parles-tu ?

Je ne suis pas un expert de XSLT, le peu que j'en ai fait il y a longtemps m'a paru lourdingue au possible. De plus, quand je parle de réécriture, c'est dans un sens assez large: par exemple, certaines balises (typiquement <hcode>) font appel à un outil externe pour générer du xml ensuite inclus dans le document (pour <hcode>, une coloration syntaxique, mais il y a aussi des choses comme la balise <dot> du greffon stog-dot, ou <asy> du greffon stog-asy).

Je ne sais pas (il ne m'a pas semblé à première vue) si XSLT permet ce genre de choses, ou encore s'il permet de compiler plusieurs fichiers à la fois avec inclusion d'un bout de l'un dans l'autre à une certaine étape de la compilation. Il y a peut-être un moyen de le faire avec des transformations XSLT successives, mais c'est simple dans Stog. J'insiste sur le fait que ce dernier est orienté publication, donc influencé par le format de sortie, notamment (X)HTML, et qu'il offre donc des facilités pour viser une sortie de ce type.

en l'état je n'écrirais personnellement pas mes documents avec ton format.

Tu n'y es heureusement pas obligé :)

Après, je ne critique pas l'approche de se faire une syntaxe perso pour faciliter l'écriture de documents : c'est très bien ! Mais plutôt la manière de le réaliser.

Encore une fois, il n'y a pas de syntaxe nouvelle dans Stog, c'est du XML. Ensuite, il y a une sémantique par défaut pour certaines balises pour le nœud racine d'un document.

Stog ne gère que ce qui est du XML, les autres fichiers de ton arborescence source sont copiés tels quels dans l'arborescence de destination.

Il est sans doute possible de générer des fichiers avec du php ou du javascript dedans, mais le XML en sortie utilise des entités comme " au lieu de ", ce qui pose en général un problème lors de l'interprétation du code.

Donc Stog est plutôt orienté contenu statique, avec référencement de scripts javascript de la forme <script type="text/javascript" src="..."></script> plutôt que du code javascript inclus directement.

Merci pour le lien, je ne connaissais pas.

Pour info, stog vient avec un équivalent du livereload, en l'occurrence un serveur http qui envoie des patches xml au navigateur client quand le fichier source d'un document (en général une page html) a été modifié; le serveur recompile la page et envoie le patch au navigateur.

Stog gère aussi un cache ainsi qu'un peu d'i18n (utilisation de balises par langue + internationalisation possible du format des dates, avec anglais et français connus par défaut). Pour le format, le greffon stog-markdown permet de mettre du markdown entre des balises <markdown>; il est automatiquement transformé en xml via une commande externe (markdown par défaut, mais l'utilisateur peut la changer).

Voici un exemple.

Développer un site web statique consiste surtout à écrire ou générer des fichiers
HTML (dans la suite je parlerai d'HTML, mais il s'agit dans le cas de Stog de
fichiers (X)HTML, puisque Stog fonctionne surtout par réécriture d'arbres XML).

On peut tout faire à la main, mais on se retrouve rapidement confronté à devoir
assurer, à travers tous les fichiers, la cohérence de différentes choses,
typiquement une barre de menu identique sur toutes les pages, et en général
un <header> commun, à quelque chose près (comme le <title>).

Pour cela, Stog offre un système de gabarits. Ainsi, je peux définir un
gabarit page, dont le contenu sera stocké dans toto/.stog/templates/page.tmpl
(si je suis en train de faire un site dont les sources sont dans toto).
Ce gabarit aura un contenu de la forme suivante:

<html>
<header>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title><doc-title/></title>
...
</header>
<body>
<div id="page-title"><doc-title/></div>
<div id="page-body">
<doc-body/>
</div>
</body>
</html>

Là, c'est un contenu simple mais on a déjà deux balises qui seront remplacées
à la compilation par un contenu: <doc-title> (le titre du document) et
<doc-body> (le contenu du document).

Ce gabarit me permettra donc de générer des pages de la même forme pour tous les
documents du type "page".
Pour écrire des documents du type "page", par exemple toto/foo.html, il suffit
qu'il commence par un nœud "page" dans lequel on donne des métadonnées comme
le titre:

<page title="Ma page foo">
bla bla bla
</page>

Avec un tel document, lorsque le gabarit "page" sera appliqué,
<doc-body/> sera remplacé par bla bla bla et <doc-title/> par Ma page foo.

Lors de la compilation du site, Stog génère un fichier pour chaque document.
Ce fichier se retrouve dans le répertoire de destination avec le même chemin
que le fichier source dans le répertoire des sources. Ainsi, si j'ai en plus
du fichier toto/foo.html un fichier toto/bonjour/monde.html, je peux compiler
ce site avec la commande stog -d dest toto; stog générera les fichiers
dest/foo.html et dest/bonjour/monde.html en utilisant le gabarit indiqué
dans chaque document et le contenu du document pour faire les substitutions
qui vont bien.

L'écriture d'un site web, ou même d'un simple document, ne se résume cependant
pas seulement à l'utilisation de gabarit. On souhaite avoir également une cohérence
interne, par exemple si on a des exercices, on souhaite que ces derniers
soient toujours présentés de la même façon. Stog permet donc d'ajouter ses propres
règles de réécriture, pour utiliser par exemple des balises <exercice> et
avoir moins d'XML à taper.

Voyons un exemple. Imaginons que je souhaite écrire un document foo/cours.html
qui soit une page et dans lequel j'aurais plusieurs fois à donner un exercice.
Je voudrais donc pouvoir utiliser une balise <exercice> en donnant un titre
et un corps, de la façon suivante:

<exercice title="Palindrome">
Ecrire une fonction ...
</exercice>

Je souhaite que lorsque je mettrai ce code dans mon document, la réécriture
me donne dans le document final

<div class="exercice">
  <div class="exercice-title">Palindrome</div>
  <div class="exercice-body">Ecrire une fonction ...</div>
</div>

Dans mon document foo/cours.html, je définirai donc une règle de réécriture,
de la façon suivante:

<page title="Cours de machin"
      with-contents="true">
<exercice title="">
  <div class="exercice">
    <div class="exercice-title"><title></div>
    <div class="exercice-body"><contents/></div>
  </div>
</exercice>
<contents>
...
<exercice title="Palindrome">
Ecrire une fonction ...
</exercice>
...
</contents>
</page>

Quelques explications: Dans le premier nœud <page> du document,
with-contents="true indique que le corps du document sera dans un nœud
<contents> au lieu d'être juste sous le nœud racine. Cela permet d'ajouter
des définitions de règles de réécriture supplémentaires, comme c'est le cas
avec <exercice>, définie ainsi:

<exercice title="">
  <div class="exercice">
    <div class="exercice-title"><title></div>
    <div class="exercice-body"><contents/></div>
  </div>
</exercice>

Ce bloc indique qu'on définit une nouvelle règle qui s'appliquera pour les
nœuds <exercice>. S'il n'y a pas d'attribut title, alors on indique une
valeur par défaut qui est vide. Le contenu de <exercice> est ce qui remplacera
le nœud <exercice> lors de la réécriture. On retrouve les balises <div>
que je souhaite obtenir dans le document final. Dans cet arbre, on trouve
également <title/> et <contents/>. Le premier sera remplacé par la valeur
associé à title dans l'environnement (soit "vide" soit le contenu de l'attribut
title de la balise <exercice> en cours de réécriture). <contents/> sera
remplacé par le contenu de la balise <exercice> en cours de réécriture.
Ainsi, lorsque dans le corps de mon document on trouve

<exercice title="Palindrome">
Ecrire une fonction ...
</exercice>

ce nœud est réécrit avec la règle définie, en associant la valeur Palindrome
à <title/> et Ecrire une fonction ... à <contents/>.

Si je souhaite changer la façon dont apparaissent les exercices dans le document
final, il me suffit de changer la règle de réécriture mais pas chaque occurrence
d'un exercice dans mon document.

Stog permet de définir de nouvelles règles par document, mais aussi pour tout
un site. Enfin, des greffons peuvent définir de nouvelles règles plus complexes,
en ayant accès au nœud en cours de réécriture.

Stog est utile (pour moi en tout cas) quand je veux faire des documents xml (donc xhtml) sans écrire des tonnes de xml, mais utiliser plutôt des balises plus sémantiques.

Oui, il est possible sans doute de faire la même chose en xslt, mais je trouve xslt disons peu pratique :-) Avec stog, je peux partager une cohérence dans tout un site (avec les templates), avoir les liens internes vérifiés, et surtout enrichir la compilation facilement selon mes besoins avec de nouvelles règles, pour me simplifier l'écriture.

A titre informatif, comment développes-tu et maintiens-tu un site web statique ? tout à la main ? ou avec des outils ? lesquels ?

Il n'y a aucun schéma, seulement les règles décrites ici: https://zoggy.github.io/stog/funs.html, réparties en modules.

Les fichiers sources sont des fichiers XML, dont le nœud racine définit des métadonnées (titre, mots-clés, …) et le reste le contenu du document. Ce contenu peut être du (X)HTML5, mais c'est plutôt du XML utilisant certaines règles prédéfinies (, , , …) pour avoir du contenu davantage sémantique et surtout plus léger à taper que du (X)HTML5.

Le contenu passe ensuite dans le moteur de réécriture qui transforme certains nœuds XML en d'autres nœuds XML, de façon à obtenir le document XML final voulu, souvent du (X)HTML5. De cette façon, on peut mettre ce que l'on veut dans les sources, seules les nœuds XML auxquels sont attachées des règles de réécriture seront modifiés. On peut donc utiliser tout (X)HTML5, mais aussi n'importe quel DTD de document XML.

Enfin, il est possible de définir ses propres règles de réécriture, soit pour un document, soit pour tout un site.

Il n'y a donc pas vraiment de format spécifique. J'espère que cela répond à ta question.

Oui, c'est bien Dynlink qui est utilisé.

Il est vrai que c'était un peu pénible à une époque pas si lointaine, mais avec le gestionnaire de paquets opam, ce n'est plus un problème. Le gestionnaire fait les recompilations nécessaires d'après les dépendances déclarées entre les paquets.

[Je suis l'auteur de Stog]
Merci à leowzukw pour ce billet. Voici quelques compléments d'information sur Stog.

Il s'agit bien originellement d'un outil pour la génération de sites web statiques, i.e. donc principalement des fichiers (X)HTML, bien que Stog gère n'importe quels fichiers XML en général.

Il ne permet pas spécialement de faire des interfaces utilisateur; bien sûr chacun peut mettre le javascript qu'il souhaite dans les pages web pour les faire bouger un peu.

Un point important était de ne pas introduire de nouvelle syntaxe, ni de se limiter à un sous-ensemble de HTML, comme c'est souvent le cas avec de nouveaux langages comme markdown.

Je l'ai originellement développé pour mes propres besoins (un site web, un blog et un support de cours OCaml. Par la suite, certains développements ont été faits pour pouvoir utiliser Stog pour la rédaction de documents "standalone", notamment des articles scientifiques (un exemple ici et un autre là).

L'idée sous-jacente est de pouvoir facilement publier "pour" le web (en utilisant les formats et les possibilités du web: HTML, web sémantique, etc.) plutôt que simplement "sur" le web, comme c'est le cas avec les fichiers PDF. Donc faire de Stog une sorte de LaTeX pour le HTML.

Stog se rapproche donc de LaTeX par la possibilité de définir de nouvelles commandes dans un document, pour en faciliter l'écriture. Un système de modules et de gabarits devrait permettre un équivalent des paquets et des classes de LaTeX.

Des greffons offrent des fonctionnalités supplémentaires, notamment stog-writing pour les bibliographies et les notes de bas de page, stog-rdf pour la génération et l'utilisation de graphes RDF à la compilation d'un site/document. Toujours dans l'optique de publier pour le web, en l'occurrence à la fois pour les machines (graphes RDF) et pour les humaines (texte). Plus de détails ici, là et encore là.

Stog vient avec un serveur de prévisualisation: il recompile les documents lorsque les fichiers correspondant sont modifiés. L'aperçu est affiché dans le navigateur (http://localhost:8080/preview/index.html par défaut). Lorsqu'un document est modifié, un patch XML est envoyé au navigateur (via un websocket) pour mettre à jour le document. Le but est d'éviter le réaffichage de toute la page, ce qui peut devenir lourd lorsque Mathjax est utilisé pour mettre en forme les formules de maths. Une vidéo de ce fonctionnement est disponible en ligne.

Enfin, la version 0.15.0 ajoute un "multiserveur", non encore documenté car encore largement incomplet. Le but est de fournir un environnement à la sharelatex. L'utilisateur crée une session en indiquant un dépôt git contenant des sources Stog. Le dépôt est cloné et le serveur fournit un lien vers la prévisualisation et un lien vers un éditeur en ligne. L'utilisateur peut donc éditer les sources et avoir la prévisualisation sans rien installer sur sa machine. Il peut faire des git commit, git pull et git push. A terme, un objectif est d'avoir un éditeur collaboratif.

J'espère que cette petite présentation complémentaire vous donnera envie d'y jeter un œil.

Pour aller au bout: n'est-ce pas participer/ajouter au mouvement du troupeau que de mettre les formulations et autres buzzwords attirant l'oeil du "décideur pressé" ? Ne vaudrait-il pas mieux exposer les fonctionnalités et situations dans lesquelles le produit est intéressant, laissant chacun juge de l'opportunité de l'utiliser, y compris "professionnellement" ?

Zoggy

> Donc avec des phrases comme ça, souvent, on cherche à rassuré le décideur pressé...

Au risque d'être taxé d'idéaliste, tant pis pour le décideur s'il choisit en se pressant sans réfléchir. A la place d'une boîte, je cherche de la stabilité, certes, mais peut-être et surtout de la pérennité; dans ce cas ça vaut le coup d'investir du temps (au contraire de le perdre).

Il est vrai qu'actuellement l'investissement n'a pas le vent en poupe, le résultat à court terme, si.

Zoggy

C'est ce que j'avais compris mais je préférais que cela soit dit.

Cependant, je trouve dommage les formulations de ce genre, qui laissent à penser qu'il y a deux mondes, le monde professionnel et le monde non-professionnel, qui semble induire qu'il y a le monde "sérieux" (professionnel) et le monde "non-sérieux". Avec l'opposition récurrent faite à tort entre "professionnels" (=qualité, sérieux, responsable) et "amateurs" (="touristes"), on donne à penser que les outils de ce genre ne sont pas faits pour les amateurs.

Enfin, c'est peut-être moi qui perçoit un tel message un peu diffus mais cela me semble dommage. Surtout quand il n'y a pas d'opposition entre amateur et professionnel, l'un n'empêchant pas l'autre.

Ca me fait penser à je ne sais plus qui qui écrivait que son code n'était pas commenté car il n'en avait pas besoin: c'était du "code professionnel" :-)

Zoggy

Bonjour,

Quels sont ces besoins que d'autres (non-professionnels, donc) n'auraient pas ?

Zoggy

On trouvera sur
[http://arsindustrialis.org/audio]
un enregistrement audio d'une conférence de B. Stiegler 'Socrate et les hackers', dans laquelle les hackers sont cités dans un discours sur les amateurs (au sens propre du mot, pas dans le sens péjoratif indiquant un manque de compétence), piliers d'une économie de la contribution.

Zoggy

Bonjour,

Je vois un obstacle à l'utilisation d'éditeurs spécialisés pour le XML, c'est l'édition collaborative de documents par exemple avec subversion. En cas de conflit, le document XML a des chances de ne plus être valide.
Questions donc:
- Y a-t-il des éditeurs XML qui gèrent-ils les marquages de conflits dans le document ?
- Y a-t-il des outils de merge de modifications qui peuvent utiliser une DTD pour proposer un fusion des différences ou un marquage des conflits tout en conservant un document correct ?