Journal frundis : langage de markup pour exporter vers LaTeX, XHTML et EPUB

Posté par (page perso) . Licence CC by-sa
19
26
déc.
2014

Bonjour 'Nal,

je viens te parler d'un nouveau langage de markup, frundis, avec une syntaxe roff-like, et de l'outil libre du même nom qui permet d'exporter vers les formats LaTeX, XHTML et EPUB, et qui cible divers types de documents peu ou moyennement complexes.

Il a été initialement conçu pour le développement de la saga libre du Cycle de Shaedra, dont il a déjà été question ici il y a quelques mois, mais peut répondre à d'autres besoins que ceux d'un roman.

Les deux raisons principales qui m'ont poussé à écrire frundis ont été d'abord quelques limitations rencontrées avec pandoc pour lire fiablement du LaTeX, mais aussi l'élimination de dépendances : frundis est un simple script perl qui dépend juste du module assez commun URI pour échapper des urls, et optionnellement de Data::UUID pour la génération d'un identifiant unique d'EPUB.

Aperçu

L'objectif du langage est d'être relativement simple tout en contrôlant au besoin assez précisément la sortie, et de permettre d'ajouter des informations sémantiques arbitraires au texte. L'utilisation du langage suppose de connaître la partie du langage cible que l'on veut utiliser, contrairement à beaucoup de langages légers comme markdown.

La syntaxe étant roff-like, il y a deux types de lignes: des lignes de texte libre, et des lignes de macro qui commencent par un point. Avant d'entrer dans les détails, voilà à quoi ressemble un document écrit en frundis:

.X set lang fr
.Ch Nom du chapitre
Premier paragraphe.
.P
Deuxième paragraphe. Frundis dit:
.D
Bonjour, 
.\" un peu d'emphase
.Sm Nal .
.P
Etc ...

Tags

L'ajout de sémantiques arbitraires se fait avec un système de tag. Par exemple:

.X mtag -f xhtml -t latin -c em

spécifie l'ajout d'un nouveau tag latin pour le format de sortie xhtml, qui sera rendu par l'élément em (mnémotechnique: -c de "commande" en LaTeX). Le tag sert aussi de nom de classe. On peut ensuite l'utiliser pour marquer un bout de texte avec la macro .Sm (semantic markup) :

.Sm -t latin Alea jacta est

Comme pour beaucoup d'autres macros, il y a une version avec un .Bm (begin markup) et un .Em (end markup) si le texte à marquer tient sur plusieurs lignes.

On peut de même définir des tags pour des blocs (par exemple un div html ou un environnement LaTeX).

Définir des macros, inclure des fichiers…

Le langage permet aussi de définir de nouvelles macros avec des arguments, d'inclure d'autres fichiers et d'inclure du texte tel quel pour un format spécifique. De plus, souvent, une option permet de spécifier qu'une certaine macro ne doit s'exécuter que lors de l'export vers tel ou tel format, ce qui permet de contrôler avec précision l'export de certaines parties spécifiques.

Quelques détails sur l'export

La génération de xhtml peut se faire vers un seul fichier ou vers un ensemble de fichiers indexés. Que ce soit pour un format ou un autre, des paramètres dans le langage permettent de personnaliser la sortie pour utiliser son propre css, préambule LaTeX, etc.

Documentation

Le programme en ligne de commande et le langage sont documentés dans les pages de manuel frundis(1) et frundis_syntax(5) respectivement.

Quelques remarques

Le programme est encore tout jeune et a quelques limitations vu qu'il a été surtout écrit pour les besoins d'un projet en particulier. Par exemple, il n'y a pas de tables ni de références bibliographiques, même si elles peuvent être écrites en cas de nécessité dans le format cible directement. Par contre, on trouvera une macro spéciale pour les paragraphes de type dialogue, et ajout automatique d'espaces insécables devant certains caractères de ponctuation si le paramètre lang est ajusté à fr.

frundis sert actuellement à exporter sept livres en deux langues vers trois formats différents ainsi que pour générer un certain nombre de pages html dont celle de présentation du projet, et ça a l'air de marcher à peu près correctement, donc j'espère qu'il pourra être utile à d'autres !

Liens

  • # Et {t,g}roff ?

    Posté par . Évalué à 3.

    Hors markdown et LaTeX, je ne m'y connais que très peu en langages de balisage.

    Mais pourquoi en inventer un nouveau plutôt que d'utiliser troff, qui semble être assez bien fourni en extensions en tout genre ?

    • [^] # Re: Et {t,g}roff ?

      Posté par (page perso) . Évalué à 6.

      En fait, il y a plusieurs raisons.

      Tout d'abord, les objectifs ne sont pas vraiment les mêmes : groff et ses macro-packages sont plus à comparer avec TeX et LaTeX, c'est un programme complexe, qui fait un excellent travail pour produire un document final de bonne qualité typographique. Tout comme LaTeX, c'est difficile à apprendre, il y a énormémement de pages de man, des commandes pour contrôler le moindre espace, etc, mais pour l'export html (ou epub) beaucoup de ces choses ne sont pas utilisées, et ce n'est pas évident à partir du code groff de prévoir à quoi va ressembler le html produit. Ce qui aurait du sens serait d'exporter de frundis vers groff pour produire une sortie ps ou pdf, mais vu qu'exporter vers LaTeX remplit des objectifs similaires, ce n'est pas trop une priorité. Et un avantage de frundis pour la sortie html, c'est qu'il ne doit pas passer par un de ces gros programmes.

      frundis de son côté est un langage sémantique qui permet de prévoir exactement comment seront le html et le LaTeX produits : quelles commandes seront utilisées, quelles classes, etc.. frundis se limite à être un langage intermédiaire plus dans l'esprit de markdown, mais avec la possibilité d'ajouter des infos sémantiques arbitraires : par exemple, dans le Cycle de Shaedra, il y a des tags spécifiques pour les dialogues mentaux, les noms de lieux, les noms de livres, les noms des chansons, les phrases dans une autre langue, etc. et dans le préambule frundis il y a une définition explicite de comment seront rendus ces tags en latex et xhtml, ce qui permet pour ce dernier de faire un css qui tienne compte de ces différences.

      Je pense que ce qui se rapprocherait le plus de frundis, ce serait d'écrire directement en html ou un format xml inventé, et d'exporter vers les différents formats cible avec des feuilles de style. Ceci dit, frundis permet d'inclure dans le fichier lui-même des informations pour dire que telle ou telle macro ne doit s'utiliser que pour un certain format, ainsi que de définir des macros, et le langage est moins lourd à l'écriture.

      Ensuite, je l'ai aussi fait parce que ça m'amusait ;)

      • [^] # Re: Et {t,g}roff ?

        Posté par . Évalué à 6.

        L'esprit de markdown est plutôt de pouvoir être lu facilement sans interpréteur.
        Ce qui n'est pas le cas ici

        • [^] # Re: Et {t,g}roff ?

          Posté par (page perso) . Évalué à 3.

          En effet, que le code source ressemble au résultat ne fait pas partie des objectifs de frundis, ça aurait rendu impossible certaines choses à moins de compliquer énormément l'analyse du programme (le parseur de frundis est très simple, et rapide à l'exécution) et l'apprentissage du langage, alors j'ai préféré utiliser une syntaxe qui a déjà fait ses preuves, et dans laquelle la différence entre le texte et les commandes est la plus claire possible, donc de ce point de vue c'est assez à l'opposé du markdown, tout à fait. Ceci dit, la plupart du texte d'un roman écrit en frundis ne diffère du markdown que par le fait que les lignes blanches contiennent .P ou .D au début.

  • # Limites de pandoc Markdown ?

    Posté par (page perso) . Évalué à 2.

    Je suis curieux de savoir quelles sont les limites de Markdown rencontrées. Dans mon cas, c'était les références bibliographiques propres (sémantiques).

    Du coup, j'ai utilisé des références en latex au milieu de mon Markdown et le résultat était exactement comme désiré, sauf dans le cas de l'export HTML.

    Du coup, je ne comprend pas cette phrase :

    L'utilisation du langage suppose de connaître la partie du langage cible que l'on veut utiliser, contrairement à beaucoup de langages légers comme markdown.

    • [^] # Re: Limites de pandoc Markdown ?

      Posté par (page perso) . Évalué à 2.

      Je suis curieux de savoir quelles sont les limites de Markdown rencontrées.

      Je crois qu'on a écrit en même temps, et que mon message du dessus répond (au moins en partie), à ta question ;)

      Du coup, je ne comprend pas cette phrase :

      Par cette phrase j'entendais que pour écrire du "pur" markdown tu n'as pas besoin de connaître le langage cible. Avec frundis tu définis dans le préambule des tags (en pur frundis), dans lesquels tu dois préciser l'élément html ou la commande LaTeX qui sera utilisée pour le rendu, puis tu l'utilises ensuite en pur frundis, sans avoir à répliquer pour les différents formats. Et puis, frundis permet aussi de distinguer l'epub de l'export en html, et d'inclure certaines choses que pour l'un ou l'autre.

      • [^] # Re: Limites de pandoc Markdown ?

        Posté par (page perso) . Évalué à 2.

        Effectivement, la définition de nouveaux contextes sémantiques et leur transcription respective en HTML/ePub/TeX n'est pas supporté par Markdown.

        Merci, je n'avais pas pensé à ce genre de choses.

  • # Le standard qui réunit les standards

    Posté par . Évalué à 6.

    Je ne peux pas m'empêcher de penser à ce XKCD :

    How standards proliferate (XKCD)

    • [^] # Re: Le standard qui réunit les standards

      Posté par (page perso) . Évalué à 5.

      Je ne vois pas trop pourquoi, frundis n'a pas l'intention de devenir un quelconque standard : il a été conçu pour des besoins assez spécifiques, puis j'ai juste pensé que, au cas où ça pourrait être utile à d'autres, j'allais partager. Je dirais qu'au contraire, frundis ne réinvente pas trop la roue : il se contente d'être, pour certains types de documents, un bon langage source pour exporter vers des formats qui eux sont assez standard, et le script perl en question fait même pas trois mille lignes (bon, il y a les tests et les pages man aussi), et ça m'a pris tout juste un peu plus de deux semaines de travail.

  • # Quelques modifs…

    Posté par (page perso) . Évalué à 4.

    il n'y a pas de tables

    Finalement j'ai rajouté un support basique pour les tables. Au passage, j'ai corrigé quelques erreurs dans les pages mans, la page de titre automatique et les tables de matières en epub.

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n'en sommes pas responsables.