ZEP-05 : Refonte du traitement markdown pour l'export

Pour les tableaux c'est plus complexe. C'est lié aux limitations de latex qui ne permet vraiment que de spécifier la largeur de chaque colonne. Pour cela il faut donc la largeur relative de chaque colonne vis a vis des autres. Et Pandoc ne le fait pas pour ce genre de tableaux. Donc soit on l'ajoute (mais comment évaluer ça ?), soit encore une fois on préviens les auteurs du risque d'utiliser ce genre de tableaux

xtab pourrait aider, non ?

@artagis : tu es surs de ça ? Je crois que la dernière fois que j'ai regardé ce n'étais pas le cas et pour cause, pandoc le fais tout seul. Dans tous les cas je peux le faire a la main proprement (et pas à coup de regex comme ça pourrait l'etre actuellement)

@lethom : ce package ne permet pas simplement de gérer les tableaux sur plusieurs pages ? Mon problème actuel est plutot faire un tableau qui ne dépasse pas en largeur de la page.

@artagis : tu es surs de ça ? Je crois que la dernière fois que j'ai regardé ce n'étais pas le cas et pour cause, pandoc le fais tout seul. Dans tous les cas je peux le faire a la main proprement (et pas à coup de regex comme ça pourrait l'etre actuellement)

oui j'en suis sûr, ça causait même pas mal de 500 à une époque.

Je confonds avec tabularx, qui lui doit faire ce que tu veux (mais pas certain, à vérifier).

Pour le coup des images distantes, l'idéal serait d'ajouter l'import des images en local comme critère de validation des tutos et articles. Comme ça, plus de problèmes avec pandoc. On le forçait sur le SdZ, et ça se passait très bien (et évitait les p*tains de croix rouges sur les vieux articles/tutos dont les images distantes n'existaient plus…).

Le souci pour l'instant sur ZdS, c'est qu'avec l'interface d'images/galeries actuelle, ça ne serait pas raisonnable, c'est pas assez pratique.

Yellow !

J'ai voulu essayer le bouzin en récupérant ton dépot Kje. Ca marche presque, sauf que j'arrive pas à spécifier le parseur perso. Comme qu'on fait ?

Tu dois normalement passer sur la branche zds_flavored_markdown et compiler pandoc. Pour tester la conversion il faut passer par le format markdown_zds.

En principe ça donne la commande suivante dans mes souvenirs :

pandoc --latex-engine=xelatex --template=./template.tex -s -S -N --toc -V documentclass=scrbook -V lang=francais -V mainfont=Merriweather -V monofont="Andale Mono" -V fontsize=12pt -V geometry:margin=1in -V links-as-notes -f markdown_zds essai.md -o essai.pdf

En fait tout marche je pense, c'est juste faire le lien avec le markdown zds que je vois pas comment faire (ce bout la -f markdown_zds)

Regarde par ici ça devrait t'aider

Ahhhh ok, je comprend maintenant ! Bon bah plus qu'à voir comment compiler ste bestiole Merfi firm1

Pour compiler le bousin ma procédure c'est la suivante :

Installation des packages systèmes

1

sudo apt-get install haskell-platform git

récupération des sources

1
2

git clone -b zds_flavored_markdown https://github.com/cgabard/pandoc.git /opt/pandoc/
cd /opt/pandoc/

Installation des dépendances (la ligne 2 est particulièrement longue, c'est normal, mais tu ne le fait pas tous les 4 matins)

1
2
3
4

cabal update
cabal install --force-reinstalls --upgrade-dependencies --only-dependencies
cabal install -- only-depedency
cabal configure

Compilation

1

cabal build

Avec ça, tu devrais retrouver dans ton répertoire dist l’exécutable pandoc.

Ce sujet est sans activité depuis plus de 90 jours. Êtes-vous certain de vouloir y contribuer ?

Oui.

Cette ZEP a été évoquée dans le précédent Zest'Meeting, et l'on s'était dit que ça pourrait être pas mal de la remonter. Voilà, c'est fait.

Apparemment, pas de nouveau ? Serait-il possible d'avoir un petit point sur ce qui a été fait, ce qui reste à faire ?

Kje semble être revenu d'entre les fantômes, peut-être aurait-il un mot a en dire ?

Bin en gros je n'y ai pas touché depuis cet été et mon hibernation prolongé.

Je vais voir pour faire un point…

Je suis aussi intéressé pour avoir une mise au point sur cette ZEP. Si tout se passe bien, dans un bon mois j'aurais le temps d'y jeter un coup d'oeil.

Idem. Pandoc a l’air d’un sacré morceau, avoir quelques infos sur par quel bout l’attaquer ne serait pas de refus.

J'ai eu une discussion en MP avec les chefs de projets, voici un petit résumé.

L'idée de cette zep était de faire une transition tranquille depuis notre fork de Python-Markdown vers un fork de Pandoc. En commençant par apporter nos ajouts dans le parser markdown et la génération de pdf, permettant de tester et contrôler le nouveau parser sur du contenu. Une fois cela fait, l'utilisation de pandoc pour le html aurait été trivial.

Lorsque j'ai fais une pause, j'avais :

• un fork de pandoc qui comprenait notre syntaxe et produisait le latex correspondant,
• un template latex a peu pret complet
• un module python par dessus cela pour gérer le rendu (le but étant qu'il s'occuper d'assembler directement les différents extraits d'un tuto/Article proprement).

Cependant l'ensemble était à un niveau de prototype et nécessitait un beau coup de nettoyage.

Malheureusement il y a pas mal de problèmes :

• Il restait des problèmes difficile à résoudre. En particulier je n'arrivais pas à rendre correctement certains articles, principalement lié aux difficultés qu’engendre latex : il y avait régulièrement des bug de rendue entre autre dans les tableaux.
• Pandoc avait commencé à faire un ménage dans leur code et il était déjà quasi impossible à rebaser.

Les choses ne se sont pas amélioré :

• Le code de Pandoc a finit de changer et malheureusement il faudrait reprendre tous les changements de syntaxes pour se baser sur la nouvelle version.
• Cela ne réglerais pas les problèmes de génération de pdf via latex qui sont compliqué.

J'en ai profité pour refaire un petit point sur ce qui pourrait être utilisé :

• sphinx ne gère toujours pas officiellement le markdown en entrée même si quelques projets le font,
• Python-Markdown prépare la sortie d'une v3 qui va, entre autre, casser ce qui sert actuellement d'AST (a raison, le fonctionnement actuel est tout pourri) mais qui va casser probablement une partie de notre fork quand on voudra rebaser.

Bref c'est un peu le bordel.

Pour faciliter la pipeline j'ai soumis l'idée de se passer de latex pour la génération de pdf. On peut par exemple générer des pdf depuis du html avec un css dédié à l'impressions. Il existe des modules tels http://weasyprint.org/ pour le faire directement en python. L'avantage évident est qu'on aurait qu'un convertisseur, seul le css s'arrangerait à gérer le rendu. Cela mériterai un POC je pense.

J'utilise WeasyPrint sur un autre projet (pour créer des factures en CSS). C'est un outils très intéressant mais moins puissant que Pandoc selon moi. Il faut effectivement une POC.

La question est surtout de savoir si weasyprint peut permettre de rendre des pdf propres avec moins de défaut que latex. Techniquement c'est juste cette partie de pandoc qu'on utilisait (générer du latex pour produire du pdf) mais qui pose d'autres soucis (tout ce que pose comme problème latex entre autre sur les tableaux).

Cette solution aurait le gros avantage de nous éviter une dépendance en haskell à maintenir, d'avoir tous latex en dépendance et d'avoir une chaîne plus simple, la production de pdf étant gèré par du css.

Est-ce qu’une solution ne pourrait pas être d’utiliser sphinx, et de passer une bonne fois pour toutes au ReST ? Je sais que cela serait une décision à ne pas prendre à la légère, et cela nécessiterait une conversion (unique, cela dit) en ReST de l’ensemble du Markdown actuellement sauvegardé, mais cela me semble la solution la plus simple sur le long terme.

Sphinx permet l’export en LaTeX (et de là, en PDF), en HTML et en ePub, donc précisément ce qu’on cherche à obtenir. La syntaxe ReST est assez comparable à celle du zMarkdown en termes de complexité :

• quelques trucs sont plus difficiles, comme l’insertion d’image inline, ou la mise en exposant (:sup:`texte`) ;
• un certain nombre d’autres sont équivalents, comme le gras, l’italique, les titres, les listes à puces, ou encore les tableaux « complexes » ;
• quelques trucs sont plus simples, comme les citations ou les blocs « attention » qui utilisent l’indentation plutôt que | en début de chaque ligne.

Quant aux fonctionnalités, voici ce que j’ai pu relever.

Fonctionnalités présentes dans le zMarkdown et qu’il est possible d’obtenir de manière parfaitement identique avec le ReST étendu de sphinx :

• gras et italique ;
• titres de toutes sortes de niveaux ;
• listes à puces, et listes numérotées, avec niveaux d’imbrication multiples ;
• exposants et indices ;
• ligne horizontale ;
• liens ;
• images inline et block : dans ce dernier cas, possibilité de la mettre à droite, au milieu ou à gauche, de réduire sa taille, de lui ajouter une légende ;
• notes de bas de page ;
• code inline et block : dans ce dernier cas, possibilité de coloration syntaxique grâce à Pygments, de numéroter les lignes et de surligner certaines lignes, et de fournir une légende ;
• blocs de citation, avec possibilité de donner l’auteur de la citation ;
• blocs de maths et maths inline, les maths étant rédigées en LaTeX : l’export peut se faire en HTML+CSS, en MathML, ou de telle manière que MathJax prenne le relai ;
• blocs "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition" ;
• mise en forme spécifique pour des touches de clavier (||Espace|| chez nous) ;
• tableaux simples et tableaux complexes, avec possibilité de fournir une légende ;
• commentaires.

Fonctionnalités présentes dans le zMarkdown dont je n’ai pas trouvé d’équivalent exact :

• texte barré ;
• abréviations : il est possible de définir une abréviation en un endroit donné du texte, mais je n’ai pas l’impression qu’elle s’applique aux autres occurrences du même mot (à vérifier) ;
• mettre un bloc de texte en centré / à droite : il existe une balise pour centre du texte, mais elle est deprecated et elle ajoute du gras à la mise au centre ;
• remplacement automatique de certains caractères, comme --- pour — ;
• smileys ;
• insertion d’une vidéo ;
• bloc secret (mais cf. ci-dessous, ça peut s’implémenter avec les blocs génériques) ;
• il ne semble pas possible d’imbriquer les balises inline, genre ***one shot*, gros !** (c’est la principale limitation).

Fonctionnalités qui ont été demandées dans le zMarkdown sans être encore intégrées, mais disponibles en ReST sphinx :

• blocs génériques pour les théorèmes, les démonstrations, etc. ;
• liens internes au document, en particulier vers les titres intérieurs aux sections ;
• syntaxe spécifique pour les citations d’ouvrage ou d’article.

Fonctionnalités du ReST sphinx qui n’ont pas été demandées mais pourraient trouver preneur si elles étaient proposées :

• encart sur le côté ;
• les balises de code inline sont utilisées pour plein de choses qui disposent d’un marquage spécifique en ReST, notamment le nom d’un exécutable, le nom d’un fichier ou répertoire, et une série de menus à suivre pour accéder à une fonctionnalité donnée.

Par ailleurs, ReST a explicitement prévu dans sa syntaxe la possibilité de créer facilement de nouveaux types de blocs ou de syntaxe inline. J’ajouterais que ReST permet de définir des titres et sous-titres de document, et d’inclure du ReST provenant d’autres fichiers, ce qui permettrait sans doute de simplifier le regroupement des différents extraits d’un même contenu.

Bref, je pense que l’idée mérite d’être étudiée.

EDIT : je reviens sur le fait que ReST a prévu explicitement dans sa syntaxe de pouvoir créer de nouveaux types de blocs ou de syntaxe inline. Cela a pour conséquence que parmi toutes les fonctionnalités du zMarkdown qui sont manquantes à l’heure actuelle :

• le barré peut être obtenu en créant une nouvelle syntaxe inline à l’aide des moyens fournis nativement par ReST ;
• le texte centré / à droite, le bloc secret et les vidéos peuvent être obtenus en créant une nouvelle directive, là encore selon les moyens prévus nativement par ReST ;
• les abréviations (si elles ne sont réellement pas disponibles) nécessitent d’étendre la syntaxe des liens / notes de bas de page / citations d’ouvrage, qui fonctionnent toutes selon la même logique ;
• les smileys et la typo seraient plus compliquées, parce que ReST ne semble pas prévoir nativement la possibilité de modifier juste le texte brut ;
• le plus compliqué, ce serait à priori l’imbrication de différents codes inline : je soupçonne que le parseur ne refait pas un tour sur le contenu d’une « unité inline », et que c’est ça qui manque pour pouvoir faire de l’imbrication.

Je suis assez mitigé. J'adore ReST mais je préfère largement MarkDown pour le grand public.

Sinon merci de la POC, ça va permettre à tout le monde de se faire une idée