Lowdown, ses options et script d’édition - 20 décembre 2023

Auteurice : Elsa Van Kote

Temps de lecture : ~8 minutes

L’objectif

Nous partions d’une édition, celle de claude rameau, qui n’apparaissait plus sur mon site. Le but était de la faire réaparaitre pour essayer de régler le problème d’encodage utf-8 qui n’arrivait pas à prendre les caractères spéciaux. Les caractères ‘é’ par exemple, apparaissaient comme ceci : é

Les étapes

La recette

reprendre le fichier xml

En effet lors lu lancement du makefile, on avait une erreur indiquant la ligne 33 du fichier. Il se trouvait que je m’étais trompée én écrivant la balise autofermante (j’avais mis par habitude !).

créer un fichier md qui accueillera l’édition

On s’est alors rendu compte que mon édition, qui commencait par de simples balises n’avait pas de structure html valide. Il manquait pleins d’informations (balises , etc.). Alors qu’une balise html apparaissait quand j’utilisais l’outil de développement avec f12 pour regarder la structure de la page. Arthur m’a donc fait comprendre que l’outil de visualisation que j’utilisais ajoutait lui même une balise à la racine, qui n’existait pas dans le code source de la page ! Il l’ajoute juste pour interpréter le code, mais cette balise n’existe pas en réalité. Et comme la création de mon édition était décorélée du fonctionnement de francium (je passais uniquement par basex et des feuilles xq et xsl), tout le contenue du fichier lib/htmlhardcoded de francium n’était pas là non plus.

contenu du fichier lib/htmlhardcoded

layout() <<@@ cat
<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="utf-8">
    <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title>
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    ${STYLE:+<link rel=\"stylesheet\" href=\"$STYLE\"/>}
    <meta name="description" content="$description">
    <meta name="author" content="$author" />
    <link rel="icon" href="/semis.png" />
    <meta property="og:type" content="website" />
    <meta property="og:title" content="$title" />
    <meta property="og:description" content="$description" />
    <meta property="og:url" content="http://77.132.38.235" />
    <meta property="og:image" content="http://77.132.38.235/semis.png" />
    <meta name="twitter:card" content="summary_large_image">
    <meta property="twitter:domain" content="77.132.38.235">
    <meta property="twitter:url" content="http://77.132.38.235">
    <meta name="twitter:title" content="$title">
    <meta name="twitter:description" content="$description">
    <meta name="twitter:image" content="http://77.132.38.235/semis.jpg">
</head>
<body>
    <main id="main" class="main">
        $(the main)
    </main>
</body>
</html>
@@

A ce stade, nous avions donc deux choix :

Si je choisis la première option, j’aurais à réécrire cette règle html pour chaque édition ou alors créer un fichier xQuery commun aux éditions qui comprendrait cette structure html… Je me voyais plus utiliser les fonctionnalités de francium pour coller le mieux à l’outil.

Nous avons donc décidé de coupler la création des éditions qui à ce stade était décorélée de francium. J’ai donc copié le contenu d’un fichier.md classique pour le retravailler. Le résultat est le fichier src/editions/claude_rameau.md

contenu du fichier src/editions/claure_rameau.md

#! edition
%T SEMIS - sentier d\'exploration de la micro-informatique en SHS
%A semis
%D accompagnée de personnes dévouées et extrêmement inspirantes, je sillonne les chemins de croisement entre la micro\-informatique et le monde de la recherche en sciences humaines et sociales
%S main

# Mes éditions
Auteurice : Elsa Van Kote

Temps de lecture : ~8 minutes

---------


Voici un extrait de ma première édition

## Claude Rameau, l'optimiste invaincu

#%

/home/pi/app/basex/bin/basex -c 'RUN /home/pi/Documents/these/francium/src/editions/rameau.xq' | save_md main

#%S main

## Règles de transcriptions :

**??** : mot illisible pour la transcription

Ici ce fichier markdown fonctionne comme les autres : il se compose d’une succession de texte (présent entre %S main et %) et un bout de code (présent entre % et %S main). Ici, contrairement au fonctionnement de mon édition jusqu’à présent, j’ai rendu dépendante la création de mon édition aux scripts de transformation de francium. On peut remarquer deux choses dans ce fichier :

la création du script édition

Pourquoi avoir créé ce comportement particulier ? Parce qu’au moment de générer notre page, en lancant la commande make, le résultat de la commande home/pi/app/basex/bin/basex -c 'RUN /home/pi/Documents/these/francium/src/editions/rameau.xq' | save_md main n’affichait rien dans le navigateur, alors qu’elle renvoyait bien le texte correspondant dans le terminal.

Arthur s’est alors rappelé que lowdown, par défaut, cache le html quand il en rencontre… il faut donc lui donner des arguments particuliers pour éviter ce comportement.

Pour rappel, Lowdown est appelé dans le script common qui lui même est appelé dans le script page, qui se lance au moment de la commande make.

//: # (echo ‘digraph G {)

//: # (node [shape="oval” fillcolor="red” style="dashed, tapered” gradientangle="90”]) //: # ( cluster1 {)

toto

comme on peut le voir ci dessous :

script page que appelle le script common

#! /bin/sh

. ./common

. lib/htmlhardcoded
[ "$1" ] || set -
. "$@"
layout

lowdown appelé dans le script common

#! /bin/sh

the=$(mktemp -d) ; trap "rm -rf $the" EXIT
save_md() lowdown >> "$the/$1"

alias %T="title"
title() title="$*"

alias %A="author"
author() author="$*"

alias %P=":"

alias %D="description"
description() description="$*"

the() (
    cd $the; cat "$@"
)

alias '%S=<<\%  save_md'
alias 'S%%=<<%% save_md'

Deux choix s’offraient à nous alors :

Nous avons retenu cette deuxième option, estimant que le comportement des éditions était spécifique et ne nécessitait pas modification directe du code de fonctionnement de francium.

Nous avons donc créé le script appelé edition qui se constitue ainsi :

#! /bin/sh

. ./common

# On surcharge save_md pour accepter l'html
Auteurice : Elsa Van Kote

Temps de lecture : ~8 minutes

---------

save_md() {
    lowdown --html-no-skiphtml >> "$the/$1"
}

# Deuxième solution, nouvelle fonction qui copie simplement stdin
Auteurice : Elsa Van Kote

Temps de lecture : ~8 minutes

---------

save_xsl() {
    cat >> "$the/$1"
}

. lib/htmlhardcoded
[ "$1" ] || set -
. "$@"
layout

On peut voir que deux solutions existent également dans ce choix ! La première, celle retenue, est de surcharger save_md pour accepter l’html. La seconde est de carrément créer une autre fonction qui copie le stdin et contourne le problème d’options de lowdown. Personnellement j’ai préféré garder la première solution qui rend plus visible l’attention portée à cette histoire d’option de lowdown.

C’est donc bien ce script edition que l’on retrouve dans notre page markdown src/edition/claude_rameau.md

CEEEEEPEEENENNNDAAAANT !! De l’html ignoré à l’html échappé

Jouons la carte de l’honnêteté : je n’ai pas copié mot pour mot le code du script edition… En effet, si on laisse le script ainsi, qu’on lance la génération de pages avec make, on option ce résultat en ligne :

image illustrant le html échappé de la page

On peut voir que le html apparaît dans la page, il n’est plus ignoré mais il est échappé ! Au lieu de s’insérer dans la structure de la page web, il est simplement affiché comme une chaine de caractères.

Pour remédier à cela, il faut combiner notre option lowdown avec une seconde option : lowdown --html-no-escapehtml --html-no-skiphtml

Comme ça notre html n’est plus échappé et la structure de l’édition est bien intégrée à la page web.

revoir la règle de création des éditions dans le makefile

Maintenant que la création de nos éditions est couplée à francium, il faut tout de même créer une règle spéciale dans le makefile, car les éditions prennent quand même plus d’arguments à la création : les fichiers xml, xq ou encore xsl.

On met donc en commentaire l’ancienne réègle de création des éditions, pour en créer une nouvelle : 

root/editions/%.html : src/editions/%.md lib/htmlhardcoded src/editions/%.xml edition ~/app/basex/bin/basex src/editions/rameau.xq src/editions/rameau.xsl rc/style.css
        STYLE=/style.css $< | ${mk} $@

On peut voir que la création de cette règle n’appelle plus basex mais qu’elle appelle beaucoup d’arguments. Si le moindre de ces fichiers est modifié, cela provoque le lancement de la règle. Il faut bien penser à mettre comme premier argument le fichier markdown qui sera transformé (ici src/editions/%.md) sinon ça ne fonctionne pas.

Conclusions

Il est déconseillé de se fier au navigateur et à son outil de développement appelé via la touche f12. En effet celui-ci nous avait rajouté une balise inexistante, et qui m’avait troublé pour cette histoire d’utf-8. Quand on souhaite vérifier la qualité de la structure de son fichier, il vaut mieux le faire en regardant le code source ou bien dans son terminal.