Evolution du markdown : conséquences

Bonjour,

suite a la zep-05 concernant la refonte du traitement markdown, il a été choisi d'utiliser pandoc pour tout les resultats (html, pdf et ebook) contrairement au cas actuel (zmarkdown pour le html, pandoc pour le reste). Cela nous oblige a ré-developper nos extensions du markdown dans pandoc. Le dev est en cours.

Je fais ce sujet pour notifier, au fur et a mesure, les conséquences que va avoir ce changement.

Étapes de transitions

La migration va commencer par l'arriver d'une version personnalisé de Pandoc. Celle-ci va apporter le support de certaines de nos extensions dans le parseur d'entrée et son rendu PDF. Vous allez donc voir le rendu PDF s'améliorer au fur et a mesure. une fois toutes les extensions supportés par Pandoc, deux voies s'offrent à nous :

• Apporter ce support dans le format ebook, terminer par le html puis migrer le site vers cette solution.
• Apporter ce support dans le format html, migrer le site puis finir par le support des ebooks.

Pour vous donner une idée, voici ce que donne le rendu pdf sur ma branche de dev.

Incompatibilités

La version Pandoc en développement est calibré pour coller au mieux au comportement du markdown actuel pour faciliter la transition. Certaines caractéristiques de Pandoc pourrait nous permettre d'améliorer l'expérience utilisateur et/ou rajouter des fonctionnalités mais ces modifications arriveront une fois le site migré, pour faire des transitions par étapes. Cependant certaines incompatibilités vont rester. On va perdre quelques fonctionnalités, en gagner d'autres, en gagner beaucoup à terme et d'autres utiliseront une syntaxe différente. Je fais un petit état des lieux.

Fusion de cellules dans les tableaux en grille

Comme vous devez le savoir, nous supportons actuellement deux type de tableaux. Ceux sous forme de grille (grid_tables sous Pandoc) supportaient, sous certaines conditions, la fusion de cellules. Ceci n'est pas supporté par Pandoc et son développement risque de prendre du temps. Il est donc conseiller de considérer la fusion de celulles comme une fonctionnalité déprécié, elle ne sera probablement pas disponible à la mise en production de pandoc pour le HTML. Actuellement ces fusions de cellules sont déjà problématique car non dispo pour le rendu pdf. A éviter donc.

Alignement dans les tableaux simples

L'autre syntaxe, dite simple chez nous, pipe_tables sous Pandoc, des tableaux est plus avancé sous Pandoc. Elle est plus souple sur la syntaxe et permet de spécifier l'alignement des colonnes. Je ne pense pas désactiver cette possibilité donc nous pourrons l'utiliser quand la migration sera faite.

Légendes et sources

Actuellement il est possible d'ajouter une légende sur les tableaux, les figures, les vidéos et les équations et la source des citations. Ces éléments vont être repris. Cependant Pandoc supporte déjà les légendes des tableaux avant ou apres le tableaux. Je ne pense pas le désactiver donc il sera possible de spécifier la légende avant. Je pense du coup, pour plus de cohérence, étendre ce principe aux autres éléments : il sera donc possible de légender avant ou apres l'élément concerné.

Coloration syntaxique

Actuellement nous utilisons pygment pour le rendu html, et celui intégré à Pandoc pour les ebooks et PDF. Les possibilités à notre disposition sont :

• Pygment pour tous les formats
• Pandoc pour tous les formats
• listing pour Latex/PDF seulement

Les deux premiers nous permettraient d'éviter d'avoir plusieurs moteurs différents pour la même chose ce qui minimise la maintenance (un langage a rajouté ne se fait qu'à un endroit, détection des mots clés identiques, etc.). Malheureusement ils posent tous deux un gros problème : lors de l'export PDF il n'y a pas la possibilité de gérer le wrapping des codes. Autrement dit, sur un PDF calibré comme mon screenshot plus haut, toute ligne de plus de 80 caractères dépasserait du cadre et de la page. J'ai cherché longtemps et il n'y a aucune façon de régler ça.

La solution la plus raisonnable est donc d'utiliser un systeme pour le HTML (celui intégré à Pandoc, pygment ou a la limite un système en JS) et le package listing pour le Latex/Pdf qui gère lui même la mise en forme du code. On aura donc deux systèmes de rendus mais on aura plus de textes qui dépassent de partout.

Options de colorations

Actuellement il est possible de spécifier le langage d'un code, pour avoir la coloration, le chiffre de début de numérotation et une liste de lignes a mettre en surbrillance. Ces fonctionnalités seront encore supportés mais avec une syntaxe légèrement différente. Ces deux derniers éléments sont actuellement peu utilisé, je ne pense donc pas qu'il soit pertinent et utile de backporter notre syntaxe.

Améliorations futures

Avec l'utilisation de Pandoc, on pourra facilement activer des fonctionnalités déjà dispo. Voici une liste d'extensions qui me semblent pertinent et facile a ajouter :

Mineurs :

• Ne plus forcer la présence d'un saut de lignes pour avoir une liste qui suit un paragraphe
• Permettre d'échapper un caractère de fin de ligne pour produire un br
• Permettre d'échapper un espace pour produire un espace insécable.
• Ajout d'ancrage sur les titres et permettre les liens interne à un document

Majeurs :

• Listes de définitions
• Liste d'exemples (Une liste qui peut se répartir sur tout un document, chaque numérotation de ce type de liste reprend où était arrêtée la précédente et où il est possible de faire référence au numéros dans le texte)
• Coloration des codes inlines
• Notes de bas de pages inlines
• Gestion des bibliographies

Ensuite il sera toujours possible de rajouter de nouvelles fonctionnalités.

Conclusion

C'est un bon aperçu de la transition. Je mettrai ça a jour si je vois d'autres incompatibilités.

Tu oublies de dire que si on utilise pandoc pour tout, ce dernier ne sera pas optionnel dans notre env de test, et qu'il n' est pas impossible que cela augmente fortement le temps de build pour travis. Il serait temps de créer de vraies solutions pour le build.

C'est pas faux mais a la limite ça ce sont des conséquences de dev, pas d'utilisateur.

Pour autant on peut se débrouiller pour que ce soit simple. Déjà on peut permettre d'utiliser un pandoc non modifié ce qui faciliterai l'installation quand tu n'a pas besoins de toutes nos fonctionnalités d'extensions. Ensuite ce qui prend beaucoup de temps c'est surtout installer toutes les dépendance latex. Générer un executable pandoc est simple et c'est un stand-alone. C'est donc facile à transporter.

C'est pas faux mais a la limite ça ce sont des conséquences de dev, pas d'utilisateur.

Sauf que le but de zds est d'être open source et libre. Donc les devs font partie des utilisateurs ^^.

Maintenant, je suis d'accord que c'est un détail.

Non ce que je voulais dire est que ce sujet ce concentrait sur les problèmes que va poser la transition coté utilisateur. Il faudra discuter de la mise en prod a part.

On peut aussi compter que passer à Pandoc seulement va éviter de devoir cloner et installer python-markdown. Mais bon on verra en temps voulu.

Concernant les tableaux, c'est uniquement la fusion de cellules qui ne sera pas supportée, ou toute la syntaxe grid_table ?

Que la fusion de cellules.

Ok, c'est parfait : pas de soucis avec les cours importés du SdZ.

Il y aura juste cette histoire de syntaxe de surlignage / numérotation, mais je pense que c'est assez marginal pour qu'on puisse gérer ça au cas par cas lors des publications futures.

Il y aura juste cette histoire de syntaxe de surlignage / numérotation, mais je pense que c'est assez marginal pour qu'on puisse gérer ça au cas par cas lors des publications futures.

Yep. on peut toujours chercher à porter notre ancienne syntaxe mais j'avoue etre peu motivé.

Sinon j'ai ajouté une remarques sur les légendes et source de citations. Pour résumé il sera possible de légender avant ou après l'élément contrairement à aujourd'hui où la légende devait forcément apparaitre après.

package listing pour le Latex/Pdf

Sinon, il y a le package minted qui utilise Pygment pour faire de la coloration de sources dans LaTeX. Cela permet d'utiliser le même parseur de partout.

Seulement, cela demande aussi d'utiliser l'option --shell-escape de pdflatex, qui pourrait poser des problèmes de sécurité à la compilation. Mais de toute manière, les utilisateurs ne peuvent pas entrer directement du LaTeX (Je ne sais pas quel est le statut des équations avec MathJax, mais c'est vérifié à la validation avant de générer le PDF ?). Du coup, trois solutions :

• Bien vérifier à la validation qu'il n'y a pas de commandes LaTeX suspectes (principalement \write18, mais aussi ses copines \read, \catcode, …)
• Utiliser un environnement séparé pour gérer ça. J'ai cru voir passer une possibilité d'utilisation de Docker, ça résoudrait parfaitement ce problème. Et peut-être celui des builds Travis aussi.
• Compiler le PDF depuis Python manuellement, avec une étape pdflatex, une étape pygment et une étape pdflatex.

Sinon, il y a le package minted qui utilise Pygment pour faire de la coloration de sources dans LaTeX. Cela permet d'utiliser le même parseur de partout.

Non en fait on a le même problème. minted utilise le générateur latex de pygment qui lui même utilise le package latex fancyvrb, tout comme pandoc. Et fancyvrb ne permet pas le wrapping. C'est bien dit sur la mailling list de minted par son créateur. Il dit qu'il est conscient du problème mais que ça représente trop de dev pour qu'il l'envisage a moyen terme.

edit: Bon manifestement ils ont avancé en réalité. C'est jeune mais si on utilise tout upstream, ça pourrait passer. Cependant il reste des soucis qui peuvent être gênant (entre autre le break aux espaces seulement, si tu as une expression qui dépasse cette taille, ce qui est courant avec des adresse web par exemple, du coup ça casse).

On peut cependant re-considérer cette question. Mais si ça pose des probs de sécurités, est ce que le plus simple n'est pas d'utiliser listings ?

Mais si ça pose des probs de sécurités, est ce que le plus simple n'est pas d'utiliser listings ?

Ça dépends de comment c'est déployé, et de comment c'est géré.

J'aime bien pygment, parce qu'il supporte quand même énormément de langages différents. Si je veux un jour faire un tuto sur Julia, et bien il y a déjà de quoi ! Listings propose moins de possibilités.

Si je veux un jour faire un tuto sur Julia, et bien il y a déjà de quoi ! Listings propose moins de possibilités.

Certes mais par exemple j'ai déjà trouvé un module pour rajouter le support de julia à listings.

BTW j'ai mit ça un peu de coté. J'étais plutot partit sur ça a la base mais comme ça pose pas mal de prob, j'ai finit par me résigner à passer à listings.

Certes mais par exemple j'ai déjà trouvé un module pour rajouter le support de julia à listings.

D'accord, mais le problème que je vois est surtout que le jour où il y aura besoin d'un langage peu utilisé ou tout neuf (swift, julia, cobol, ou rien que des templates Django), ça risque d'être galère à utiliser avec listings.

Avant tout rien n'est acté et j'aimerai bien l'avis de d'autres personnes. On a le temps d'en parler, je pensais régler ça a la fin, la priorité étant sur les éléments qu'on ne parse pas du tout.

Pour en revenir au niveau coloration, je comprend bien ton point de vue, c'est ce que je comptait faire aussi au début. Je me suis résigné a passer le latex a listing car en première approche c'était la seule solution pour avoir un wrapping des lignes de codes : on ne peut pas se permettre de générer des pdf avec des codes qui dépassent de la page.

Vu leur github, si on utilise une version upstream, il semble que minted le propose. Pourquoi pas donc. Mais j'avoue être refroidi par les probs de sécurité que tu pose car même si on peut mettre en place des trucs pour y palier, il faut le faire. J'entends par la que compiler les pdf dans un docker oblige a mettre en place tout une architecture lourde sur le serveur pour palier a un problème qui n'existe pas encore. C'est rajouter des maintenant des contraintes de dev sur un morceau ou on est déjà en sous effectif.

L'autre solution, passer pygment nous même, peut être fait avec un filtre pandoc. Mais il va falloir regarder ce que minted fait pour que le wrapping marche et le porter dans notre template.

Le dernier point qui me gêne sont les limitation actuel cité dans le github de minted. Ça a l'air anodin mais ne l'est pas. Si il y a une limitation, on va avoir le droit a un rapport de bug la dessus. Sans chercher les ennuies, en prenant un tuto dispo sur ce site pour faire mes essais, je suis déjà tombé sur une ligne de plus de 80 caractères sans espace. Donc on va avoir des remontés de bugs a propos de ça. Et la il faudra aller patcher pygment, ça me motive moyen.

Bref on peut en parler mais instinctivement et de manière pragmatique je serais plus tenter d'utiliser en première approche listing pour les pdf et pygment ou pandoc pour le HTML, et attendre d'avoir un réel cas problématique avant de changer, ou que quelqu'un s'y mette pour remplacer proprement listing. Car côté dev, listing ça me demande juste de la configuration (couleurs, options d'affichage,…) alors que pygment ou minted demande un dev non négligeable en plus tout en ayant deja des limitations connues.

Je crois que tu t'embêtes pour rien. J'ai fait le rendu pdf pour l'article sur le C++14 et j'ai du corrigé le markdown pour éviter des problèmes de rendu (http://guillaume.belz.free.fr/cpp/cpp14.pdf). J'ai testé aussi listings pour ne pas avoir des morceaux de code qui dépasse de la page, mais au final je suis revenu dessus (j'utilise simplement –highlight-style=tango quand je lance pando).

Il y a trop de choses qui ne vont pas avec les retours à la ligne automatique (mots coupés) et il y avait d'autres problèmes (tableaux qui dépasse - dans le pdf de l'article C++14, j'ai séparé le tableau en 2 tableaux, pour que cela fasse plus joli et tienne sur la largeur), ligne en début de page, etc. A mon sens, c'est à l'auteur de vérifier le rendu des documents générés et de faire les corrections du markdown en conséquence.

Par contre, il faut que les documents générés soient disponible dans le module de rédaction, que l'on ne soit pas obligé d'attendre la validation pour voir qu'il y a un problème.

EDIT : je pense à une autre chose. Est ce qu'il est possible de mettre dans le markdown des éléments spécifiques pour un format. Je pense par exemple à ajouter un saut de page qui ne serait pris en compte que dans la version pdf par exemple.

Autre exemple, dans le pdf de C++14, j'ai déplacé l'introduction "Le lundi 18 août, Herb Sutter1 a annoncé sur le site du comité…" dans le chapitre 1 "Un peu d'histoire", sinon on avait ce texte collé au sommaire, cela faisait étrange. Donc il faudrait pouvoir mettre ce texte au dessus du chapitre 1 dans le HTML et dans le chapitre 1 pour le PDF. (ou une autre solution)

En effet, il y aura toujours des problèmes de rendus mais si on peut en éviter un maximum, ce serait peut être mieux.

Je suis d'accord avec toi que dans l'idéal les auteurs peuvent corriger eux même le rendu mais tu peux être sûrs que pour un auteur qui va corriger sa source, tu va en avoir un autre qui va nous faire un rapport de bug.

Dans la pratique c'est pas plus compliqué pour moi d'utiliser listing ou le système intégré à pandoc (c'est juste une option type "–use-listing", ou un truc du genre, à passer à pandoc). Du coup si je peux miniser les problèmes pour pas plus cher, autant le faire.

L'une des choses qui m'on fait retourner sur –highlight-style plutôt que listings est que j'ai trouvé la coloration moins jolie, il y avait plein de mots-clés non colorié avec listing (par exemple, avec –highlight-style, toute la ligne contenant #define a une coloration spécifique alors que ce n'est pas le cas avec listings)

Mais j'avoue sans problème ne pas être un pro de pandoc et latex (j'ai découvert ça quand j'ai voulu faire le pdf de l'article), tu arriveras sans doute mieux que moi à régler ce genre de problèmes.

Par contre, tu parles d'auteur qui font un rapport de bug, je suppose que tu penses donc à un auteur qui voit un problème dans le pdf après validation. Je crois qu'il faut que la validation concerne aussi les autres formats de génération, pas simplement le HTML (ie si le validateur voit un problème dans le pdf, il ne valide pas et demande à l'auteur de faire des corrections). Mais bien sûr, il faut que l'auteur ait accès au pdf/epub/etc avant la validation

(c'est -listings pour activer dans pandoc)

Je crois qu'il faut que la validation concerne aussi les autres formats de génération, pas simplement le HTML (ie si le validateur voit un problème dans le pdf, il ne valide pas et demande à l'auteur de faire des corrections).

Je ne suis pas certain que cette solution soit réaliste dans l'état actuel de la validation

Je rajouterai même que ce n'est pas judicieux. Les problème de mise en page dans les formats alternatifs que nous proposons ne doivent pas être un frein à la publication de contenu sur le site.

Donc si un valido est consciencieux, il peut décider de vérifier le PDF une fois le tuto publié, et faire un MP à l'auteur pour l'avertir des éventuels soucis. Voire proposer à l'auteur de faire les corrections pour lui, s'il est vraiment chaud. Mais ça s'arrête là, ça ne doit pas entraver la publication sur le site.

Publier un pdf qui présente des problèmes n'est peut être pas non plus une solution, cela ne fait pas très pro. A la rigueur, il faudrait dissocier la publication d'un tuto de la publication des versions pdf/epub/etc, mais le risque est d'avoir pleins de tutos sans pdf (on a donc l'alternative "pas de pdf" ou "pdf non validé")

Je trouve dommage qu'il n'y a pas de validation des autres formats, cela me semble aussi important que la version html