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

Bon j'ai eu le temps ce soir de tout relancer. Voici donc une jolie archive de 18Mo.

J'avais un dump fait il y a plusieurs mois avec les 60 premiers articles. Sur les 60 :

• 1 fait planter pandoc (Bravo Spacefox)
• 3 font planter mon script (probablement facile à corriger et non critique)
• 5 génèrent un latex non compilable.

Les problèmes que j'ai repéré rapidement :

• Liens et abréviations mériteraient peut être d'etre précédé d'un page-break pour éviter de les couper sur deux pages
• Lisibilité d’un code source : Problème de tableaux
• Le C++14 est arrivé : problème de tableaux
• un zeste sans fin prologue: Mon script arrive pas a dl le logo (404) du coup la compilation plante. Pas critique donc.
• L’Énigme d’Einstein : tableaux - absence de lignes qui nuisent à la lecture, headers qui se chevauchent
• La vulnérabilité Shellshock : la syntaxe utilisé pour spécifier le langage n'est pas reconnu
• ZdS passe en version 1.1 quelques jours avant son anniversaire: tableau coupé en deux
• Interview : Rencontre avec nohar : Un & dans une abréviation n'est pas échappé dans le latex et fait planter la compilation
• Les signaux et slots dans Qt 5.4 : Problème avec un lien d'image que Python arrive pas à dl et qui fait planter mon code
• Le langage Ceylon passe en v1.1 : a priori un caractère non échappé fait planter la compil latex
• La GPL, la licence des cornus : il y a des alignements à droites, étrange, à vérifier
• Elasticsearch maintenant en version 1.4 : des notes de bas de pages et des abréviations ne sont pas parsé
• ZdS passe bientôt en version 1.3 : tableaux dans secret qui dépassent
• C'est toute une histoire : la cryptographie - Partie 2/3 : problème de compilation (a investiguer)
• On vous tient au jus ! : tableau qui dépasse
• L’énergie nucléaire dans l’espace : tableau non parsé
• Zeste de Savoir passe en version 1.5 : tableaux dans secret => comme pour v 1.3
• Et si des étudiants créaient des nanosatellites ? : vidéo et note de bas de page non parsés
• Le libre à la française : tableau non parsé
• La méthode Continuous Delivery : "Dimension too large" à la compil, à investiguer
• Dropbox a des fuites ! : problèmes de compilation à investiguer
• Introduction à la rétroingénierie de binaires : bug de numérotation des sections
• Rencontre avec Piwit : un 404 sur le dl d'une image fait planter mon script
• Un aperçu de la diversité du Metal : A priori un bug dans le parser fait planter Pandoc, à investiguer

Et dans plusieurs : L'absence de légende sur une figure ajoute un "Figure N" en légende, des figures avec liens semblent poser des problèmes de rendu (image petites), liens trop long qui dépassent, certains caractères spéciaux ne passent pas

J'invite tout le monde à tout regarder, j'ai pas vérifié dans le détail et encore moins le contenu.

Avec ça on a 3 options si on choisit de continuer dans cette voie :

• On considère que tous ces problèmes ne sont pas critique et que vaut mieux ça que rien, on vise à refaire une version equivalente pour l'intégrer.
• On considère qu'il faut un peu améliorer les choses et on cherche à les corriger. J'aurais probablement besoin de volontaires motivés pour me donner un coup de moins en particulier sur le latex (et trouver un moyen de rendre bien ces foutu tableaux)
• On considère qu'il y a trop de problèmes et on arrete cette voie.

A vous

Donc si je résume, en gros, les problèmes sont :

• Du texte pas échapé / mal parsé qui fait planter LaTeX : plutôt simple à corriger,
• Des 404 : à voir comment on fait, mais a priori pas trop complexe,
• Les tableaux à travailler : d'accord, là il y a un peu plus de travail.

Maintenant les solutions :

• Arréter cette voie : pour développer un hack du même genre à un autre bout de la chaine de compilation ? AMHA ça ne resoudra pas plus les problemes.
• Repartir de la branche récente de pandoc vs. continuer le dev sur ce que tu as (si j'ai bien compris ce que tu voulais dire) : je suis partagé, les deux ont des avantages.

L'avantage de l'autre chaine est, au formules mise-à-part, un simple CSS à gérer. Plus simple à maintenir. On évite aussi le fork de pandoc en haskell et la dépendance à Latex (qui font des dépendances lourdes pour les devs)

Si on continue dans cette voie, il faudrait je pense refaire sur une version récente de Pandoc. C'est probablement pas la mort (avec le diff je peux savoir ce que j'ai changé et déjà réglé le gros des problèmes) et mon code actuel est dans un état "prototype", il mériterait dans tous les cas un bon nettoyage.

Merci pour le travail que tu as fait Kje. Malheureusement je n'ai pas le temps de m'y pencher, mais je vais regarder ça dans un petit mois =) .

Donc, sur 60 articles testé, il y en a 9 dont les pdfs plantent avec ta version de pandoc (notons que tous les tutoriels du site ne passent pas non plus). Les 51 articles qui passent bien nous offrent un rendu excellent par rapport à ce qui est généré aujourd'hui.

Est-ce qu'on ne pourrait pas déjà faire profiter à la communauté du travail réalisé jusqu'ici avant de se "relancer" dans la suite du chantier ? J'ai bien peur que si on attend que tout soit parfait, on ne sort jamais rien.

On verra ensuite ce qu'on fait pour la suite.

C'est le fond de ma question : est ce suffisant ou pas ? Dans tous les cas faut mettre ça un peu au propre mais bon, la question est de savoir si c'est la bonne voie

Personnellement a la question "est-ce suffisant ?" je reponds "c'est vlairement mieux que ce qu'on a aujourd'hui donc GO". Pour ce qui est de "est-ce la bonne voie ?" je n'en suis pas forcément persuadé et j'aime bien l'idée de dire "celui qui veut s'y coller choisie la voie".

Je devrai avoir globalement du temps ces prochaines semaines, et si je n'y connais rien en pandoc ou haskell, j'ai à peu près l'habitude de latex. Je peux aider de ce côté là.

Juste histoire que ça ne soit pas que des impressions, j'ai fait un petit script qui nous donne une métrique sympa et plutôt en faveur de ton travail:

• Nombre de tutos bien générés 116
• Nombre de tutos mal générés 31 => 21% d'échec
• Nombre d'articles bien générés 104
• Nombre d'articles mal générés 8 => 8% d'échecs

Soyons clairs : les articles en mode "zep_12" on été plutôt bien générés. Et je pense que depuis le temps tu devrais avoir des résultats similaires.

Donc je propose que nous allions droit avec ce qu'on a. Si le rendu est meilleur, qu'il est plus stable et qu'en plus on monte globalement en compétence, gogogo.

Petit témoignage : j'ai essayer de compiler pandoc via leur nouvel outil recommandé (Stack). Et ben, j'en ai eu pour environ 1h30 de build et un message d'avertissement de mon OS comme quoi je n'ai plus d'espace disque … je n'ose pas imaginer la lourdeur du truc s'il faut le rajouter dans la stack de développement.

Je pense que ça serait un choix très raisonnable de ne pas utiliser pandoc pour produire la partie HTML du site, contrairement à l'idée de départ de la ZEP.

Dans ce cas là il ne faut pas l'utiliser du tout.

Je pense que ça serait un bon point à soulever pour l'AG.

Ce n'est clairement pas dans les compétences ni le rôle de l'AG. Par contre, il faut en parler probablement au prochain zest meeting.

Notez que moi quand je l'ai compilé chez moi ça a prit un peu de temps mais pas autant que ça (30min je dirai) et pourtant mon PC doit avoir + de 5 ans. Tu as bien prit une release ?

Perso j'arrive pas à trouver le courage de reprendre un fork de Pandoc. Soit il faut que quelqu'un d'autre s'y frotte, soit il faut envisager sérieusement une autre solution moins lourde. J'ai déjà cité la transformation CSS du html pour générer des PDF propre (le seul hic est de devoir passer pour les formules par un convertisseur latex -> image, éventuellement avec celui fournit par matplotlib, si on ne veut pas avoir à faire tourner mathjax coté serveur), on peut aussi envisager faire un convertisseur vers latex. Il y a probablement d'autres solutions.

Je pense que ça serait un bon point à soulever pour l'AG.

Comme dit SpaceFox, c'est une discussion pour le Zest-Meeting ça

Tu as bien prit une release ?

Je me suis posé sur la dernière release oui. Mais j'ai un PC pas très performant aussi (i5 de plus de 5 ans). Mais 1h30 de build quoi …

Il faudrait qu'on refasse un état des lieux des alternatives qui s'offrent à nous aujourd'hui.

Beaucoup de trucs se sont dit en off sur ce sujet.

Ces derniers jours j'ai décidé que j'en avais marre de bosser avec pandoc pour écrire mes tutos, je suis donc passé à Sphinx en utilisant le parseur markdown de readthedocs.org (ReCommonMark). Après avoir regardé successivement le code de python-zmarkdown, commonmark-py et recommonmark, j'en suis arrivé à la conclusion que c'était jouable d'utiliser Sphinx avec un markdown compatible zds, notamment pour :

• bosser sur des tutos en local et les compiler en html, latex, pdf, epub, etc.,
• créer une sortie zds-archive, à savoir un zip compatible avec le système d'import de ZdS,
• régler la question des maths (Sphinx dispose à la fois d'un plugin mathjax et d'un autre qui crée des images, on doit certainement pouvoir le reprendre).

Mais cela demande d'avoir un parseur markdown à la fois propre (AST), et extensible (pour gérer les extensions de ZdS). Le problème c'est que le ZMarkdown actuel est extensible mais moche, et que CommonMark-Py est à l'opposé très clean, mais jeune (donc instable) et n'a aucun mécanisme d'extension.

Après avoir discuté un peu avec Kjé, je pense que ce serait une bonne idée de :

• réparer les tests unitaires de zmarkdown pour les remettre au propre et s'assurer qu'ils passent tous (donc corriger les bugs actuels au passage),
• envisager, une fois qu'on a des beaux tests et une couverture suffisante, une refacto de python-(z)markdown.

Bref tout ça pour dire que je vais secouer ce sujet dans les prochains jours.

Pour info voici ce que j'ai dis dans le zest-meeting quelques jours avant :

Bon point sur la zep-5 (j'ai préparé quelques lignes)

1. Le fork de pandoc était une erreur je pense. Je n'ai plus ni le temps ni la motivation de le remettre en place et de le maintenir. Si on veut rester sur cette option, je pourrais aider en donnant des infos mais je ne bosserai pas dessus.
2. L'option "re-créer un parseur" n'en est pas une a court terme je pense. Markdown est un langage ambigüe avec plein d'edge case. Si quelqu'un fait quelque chose qui fonctionne, pourquoi pas, mais je n'y crois pas à moyen terme.
3. Si on veut avancer de façon pragmatique je pense qu'il faut faire évoluer notre parser actuel qui est loin d'etre parfait mais fait le job
4. Pour la production d'ebook, c'est globalement simple, du html + css zippé avec du xml pour les méta-data. En s'y mettant sérieusement on l'a en peu de temps

5. Le point problématique sont les pdf. Je vois deux solutions pragmatiques:

   A. Générer du latex depuis "l'ast" de python-markdown ce qui revient grosso modo actuellement a générer du latex depuis du html. Python-Markdown prévois de changer leur ast pour un truc plus générique mais pour le moment ce n'est pas pret (et pas commencé, ils sont toujours au stade de discussion du format). C'est ce qui peut créer les meilleurs pdf mais ça demande pleins de boulots pour rendre ça propre je pense (en plus d'a

   B. Générer des pdf en utilisant le html avec du CSS dédié à l'impression. En plus de pouvoir l'utiliser pour la version "html hors-ligne", voir directement sur le site (quand les gens font imprimer), c'est simple a maintenir (et il existe un projet python qui fait les pdf avec du html et css pour impression qui semble bien fonctionner). Le principal hic ce sont les equations maths. Je vois 3 possibilités :

   • Utiliser latex (mais du coup on le récupère en dépendance)

   • Utiliser le module matplotlib qui fait ça en python

   • Voir si il n'y a pas d'autres modules en C ou C++ qui le font, on pourrait les wrapper en Python si il n'y a que ça.

Perso je pense que la solution B) est la plus pragmatique et "voir en temps voulu" pour les maths.

Enfin propositions pour avancer dans le dev, mon plan de bataille si ça vous va :

• Reprendre le dépot de ZMarkdown et traiter les PR en attente.
• Rebaser sur l'upstream.
• Cleanner le code, fixer les bugs connus, fixer les tests pour avoir un dépot propre.
• Mettre en place deux configurations du parseur : online et offline. La version actuel est la online, la version off-line devra générer ce qu'il faut pour les rendus pdf (sommaire, image en lieu et place de vidéo, etc.).
• Rajouter une gestion direct du contenu en entier (tuto, article) pour regrouper proprement les extraits et générer des documents propre.
• Générer les pdf à partir de ça en rajoutant du CSS
• Générer les ebooks

Les deux dernières étapes peuvent se permuter. A la fin de chaque étape faire une release pour zds.

vu que nohar est motivé pour aider, on va se faire une réunion scrum pour en parler

Moi je suis chaud pour filer un coup de main si besoin !

En fait s'il y a un point à retenir, c'est que la priorité n°1 est de passer tous les tests au vert, merger les PR urgentes et corriger les bugs courants.

Une fois ceci acquis, on compte travailler plus ou moins sur deux fronts en ayant comme point d'ancrage les tests unitaires : d'un côté, refactoriser le parseur quitte à casser définitivement la compatibilité avec l'upstream, de l'autre se servir de zmarkdown pour gérer toutes les sorties qu'on veut. Mais ça sera a rediscuter / planifier quand on n'aura plus de PR "dûes" (au sens projet) ni de bugs dans la version actuelle.

Utiliser le module matplotlib qui fait ça en python

Je me trompe peut-être, mais j’ai l’impression qu’il ne gère pas tout le module amsmath. En particulier, à lire la doc, je n’ai pas l’impression qu’il gère des trucs comme l’environnement align.

Bon des nouvelles. On ne peut pas dire que la zep a avancé mais le markdown est ressorti de sa torpeur :).

Comme je l'avais annoncé lors du zest-meeting qui est arrivé en même temps que l'arrivé de nohar sur le projet, on a avancé. Pas grand chose d’exceptionnel pour le moment, on a simplement remis les tests en place et au vert (j'ai corrigé un bug sur les liens au passage). Ça nous a permit de faire une première release vers zds depuis très longtemps.

Là l'objectif est de consolider l'existant : Blinder de tests avant de faire n'importe quel modifications car le markdown a plein de cas particuliers un peu con. J'ai déjà commencé en rajoutant un tuto de zds en tant que test, faisant grimper la couverture de plus de 22% (on arrive aux 90%). Il va probablement nous falloir une très bonne couverture et surtout beaucoups de hits par lignes car on aura vite fait de casser des fonctionnalités. L'avantage c'est qu'on peut utiliser pleins de tutos de zds comme référence (au moins ceux en CC et avec accord de l'auteur).

Avec l'arrivée de nohar, on se review aussi mutuellement ce qui devrait améliorer un peu la qualité et j'ai fais le tri dans les vieux tickets et PR.

Une fois les tests blindés, l'étape suivante sera probablement de couper dans le code à la hache : L'upstream ne bouge pas beaucoup et on a besoin de faire des modifications du coeur pour y arriver. Mais pour cela il faut simplifier le code et on va donc virer tout ce qui est inutile pour nous.

Entre temps il est probable qu'on traite la PR sur les ping car elle bloque une autre zep. On reprendra ensuite les évolutions pour la zep-5 avec de meilleurs bases.

Voila pour les news coté markdown