Python-ZMarkdown

Bonjour les agrumes,

je suis un de ses membres anonymes qui traînent dans l'ombre de zds. J'ai décidé aujourd'hui de sortir du silence pour vous présenter un projet en liens avec Zds : son moteur de rendu markdown.

Présentation

Liens vers le github du projet

Un peu d'histoire

Ce site a commencé comme un fork du site progdupeu.pl et utilisait déjà le markdown comme langage de rédaction. Il a été choisi de continuer à utiliser le markdown mais de l'étendre. Ayant un peu de temps à ce moment là, j'ai prit ça en charge et compléter le parser pour prendre en charge des balises de rendus supplémentaires.

J'ai toujours été, et je suis toujours, globalement le seul à maintenir et développé le projet. Le projet a été un peu abandonné pendant un an. Lors de la discussion de la ZEP-5 il avait été décidé de créer un fork de Pandoc pour faire évoluer le markdown. Un mix entre difficultés techniques et démotivation a entraîné l'abandon de ce projet.

Depuis quelques semaines, Python-ZMarkdown revit. Le projet est sorti de sa léthargie et avance.

Aperçu rapide

Actuellement le projet est un fork du module Python-Markdown ajoutant les syntaxes nécessaire au site majoritairement sous forme d'extensions. Il transforme donc le markdown que vous écrivez sur le forum ou dans vos tutos sous forme de html affiché par le navigateur.

Etat d'avancement

Actuellement le projet est en phase de stabilisation. L'objectif est de le mettre au propre, de bien tester toutes nos spécificités et de corriger les bugs actuellement connues. De (grosses) évolutions sont prévus par la suite mais le coeur doit être propre avant cela.

Versions courantes

Les versions de Python-Zmarkdown sont mise en lien avec la version du site qui les utilise.

• Zds-v20 / zmarkdown 0.11 (version actuel du site) : Une majorité des extensions sont propres et testés.

• Zds-v21 / zmarkdown 0.15 (prochaine version du site) : Fin du nettoyage et test des extensions, début de suppression de codes morts et historiques, support du ping et assistance pour la typographie française!

• zmarkdown 0.dev (version en cours de développement) :

  • Prévu - PR de firm1 pour avoir des ancres sur les titres à compléter.
  • Prévu - Retirer tout ce qui n'est pas intéressant pour le zmarkdown.

Roadmap

Voici le plan de développement à court/moyen/long terme

Quelques remarques supplémentaires

• Bien qu'en soit le projet ne soit pas dépendant de zds, il en est fortement lié. Zds est et restera la raison d'être de ce projet à court terme. Ce sont les besoins de zds qui guident la roadmap. Je ne suis pas contre des ajouts non-nécessaire à zds mais je ne garanti pas leur maintenance. Je pense qu'avant l'arrivée de la 1.0 cela n'a aucun intérêt (car je vais tout casser).
• Le projet est testé et supporte Python 2.7, Python 3.4 et Python 3.5. Le support de Python 2.7 sera peut-être retiré dès que zds sera passé à Python 3 (sauf si quelqu'un arrive à me convaincre de l'intérêt de le conserver).

• La prochaine version verra probablement l'arrivée du projet sur PyPi. Je vais donc devoir fixé le nom. N'hésitez pas à en proposer. Actuellement je vois comme possibilités :

  • Python-ZMarkdown (l'actuel)
  • zmarkdown (le nom d'usage sur le site)
  • Zeste De Markdown (qui pourra être abrégé zdm)

  Qu'en pensez vous ?

N'hésitez pas à poser des questions si necessaire et à reporter les bugs que vous trouvez sur le site, dans l'idéal sur le github du projet, sinon dans le forum bug et suggestions ou ici.

Quid d’une documentation pour implanter zmarkdown dans d’autres langages ?

Le soucis avec "les autres langages" est qu'il est très difficile d'avoir deux parseurs différents avec le même comportement. Si tu pense au JS par exemple pour en faire un preview on-line, ça peut engendrer un paquet de bugs étrange : des choses qui sont interprété d'une certaine façon par un module et différemment pour l'autre. Et c'est particulièrement vrai pour le markdown qui possède une syntaxe ambiguë : il y a plusieurs interprétations possibles valide de certains textes.

A court terme rien ne sera fait pour aller dans ce sens car il n'y a pas de solutions miracles et, comme je vient de le dire, c'est très casse-gueule.

Cependant on peut considérer que la doc présente sur ce site représente la doc de syntaxe (même si elle est peu détaillé), les tests qui sont rajoutés peuvent servir à implémenter une autre version du parseur. Si quelqu'un veut vraiment faire ça, je peux donner des conseils/avis mais c'est vraiment plus compliqué qu'il n'y parait. Dans tous les cas le module Python-ZMarkdown peut servir de référence.

En fait la solution miracle existe. C'est GObject. Avec ce système tu peux utiliser une lib dans beaucoup de langages différents, à partir du même code. Par exemple, une bibliothèque écrite en Vala, et qui a un sytème d'OO qui repose sur GObject donc, peut être utilisée dans plein de langages différents, comme Lua, JavaScript, Python, Perl, Ruby, PHP, OCaml, Haskell et autres.

Après je ne sais pas si on peut « exporter » une bibliothèque écrite en Python pour l'utiliser dans d'autres langages, mais si c'est le cas, le problème de la compatibilité vers d'autres langages serait résolu.

C'est cool si le projet débarque sur Pypi, ça permettra peut-être d'avoir quelques contributions externes. Pour le nom, ZMarkdown ou Python-ZMarkdown me semblent être ce qui est de mieux.

En tout cas, merci pour ton boulot !

@Bat' : le problème n'est pas de l'interfacer avec d'autres langages. L'intérêt principal du multi langage serait le js pour pouvoir être utilisé dans le navigateur. Gobject ou les trucs du même genre ça ne résout pas le problème.

@Emeric : le principal intérêt d'être sur pypi est en fait de simplifier la vie des dev de zds qui actuellement doivent retelecharger les sources dès qu'ils mettent à jour les requierement même si la version n'a pas changé.

Pour l'instant, Zest-Writer ne peut fonctionner correctement que si Python-zMarkdown est compatible python2.7. Je ne sais pas si ça suffit à convaincre, mais en attendant que je trouve une alternative, j'aimerai bien que le support soit conservé.

Pour l'instant, Zest-Writer ne peut fonctionner correctement que si Python-zMarkdown est compatible python2.7.

Tu as une idée pour contourner ça ? Car si c'est à cause de Jython, le support de la version 3 est prévu pour bientôt… depuis quelques années déjà.

Je pense que c'est ça le problème justement, le support est pour un bientôt aussi proche que l'inversion de la courbe du chômage en France…

Concernant Python 2.7, a court terme de toute façon zds l'utilise encore. Ensuite ça dépendra beaucoup du contexte à ce moment là. Je ne le retirerai pas comme une brute de toute façon, je te propose qu'on en reparle à ce moment là. Il y a peu de chance que je le retire avant la 2.0 de toute façon, avant c'est du refacto. Il n'y a qu'à ce moment là que beaucoup de codes sera ré-écrit et où ça pourra mériter de se poser la question.

je te propose qu'on en reparle à ce moment là.

ça me va.

Le sujet m'intéresse, mais pour le nom, j'aime bien "Zeste de Markdown".

Et si tu veux suivre le semantic versioning pour la lib markdown, une 2.0 sera en effet l'occasion de faire le full refacto (et éventuellement passer sur Python 3). Par contre, le fait de passer de 1.0 a 1.5, ca me choque un peu ; tu devrai y aller étapes par étapes (1.1, 1.2, …), qui ajoute donc des features petit à petit, plutot qu'un gros paquet d'un coup (limite en décorrélation avec les versions du site, qui lui utilisera la stable du moment en faisant ses upgrades… ?)

Oh et avoir un langage spec serait cool aussi, bien qu'en effet la doc actuelle du site peut s'y approcher pour l'instant.

J'ai mit 1.5 mais en effet je compte le faire par petite touches. C'était indicatif.

Le problème de la spec est que ça va être long et chiant a faire et j'ai clairement pas le temps d'y passer du temps. Si quelqu'un veut s'y coller, je peut énumérer le gros mais bon avec le markdown c'est la misère, il y a pleins de subtilités et de cas ambiguë.

Un peu de news :

• j'ai pas eu beaucoup de temps libre ces derniers jours mais la re-ecriture des légendes est en bonne voie. Ça a été plus simple que prévu et j'ai un code beauuuuuuuuucoup plus propre que le précédent. Ça devrait grandement fiabiliser cette partie et fermer 7-8 tickets au passage. Je vais devoir au passage mettre au propre l'extension des équations de math car les légendes ne peuvent pas fonctionner actuellement pour.
• je vais probablement ensuite bousculer le plan de dev prévu pour intégrer le ping. Pour que ce soit propre il faut que le markdown renvoie des méta donné, ce que je comptais faire plus tard. Mais pour pas bloquer ça, je vais l'integrer rapidement.

Comme proposé dans ZWriter, mais ça me semble plus pertinent ici, je propose l’implantation de CriticMarkup, notamment dans le fait de pouvoir annoter un texte. L’idée est d’aider dans la relecture, pratique pour des correcteurs ou un validateur.

Je ne vois pas spécialement l’intérêt pour les les validos. Pour des relecture a plusieurs auteurs à la limite…

Mais bon en soit je ne peux pas l’implémenter. Plusieurs raisons à ça :

• Actuellement on est en feature-freeze : je ne rajoute pas de fonctionnalités et de syntaxe sauf cas exceptionnels, mineurs et décidés dans une ZEP.
• Ce n'est pas moi qui vais décider d'implémenter un non un nouvel élément de syntaxe. C'est a la communauté de choisir et il faut bien prendre en compte les problèmes que ça peut poser niveau syntaxe.

Bref a court terme on est en stabilisation. A moyen terme il faut travailler sur la génération pdf et ebook qui est attendu de longue date. Quand ça sera fait on pourra discuter changement de syntaxe majeur mais a court terme j'ai pas assez de temps pour tout faire. Et rajouter de la syntaxe en parallèle du travail de fond, c'est contre productif. Surtout pour un changement si peu important (je trouve). Il y a bien d'autres propositions plus impactantes.

Ta proposition me fait tout de même réfléchir… Il est vrai que la syntaxe est bloqué depuis longtemps. Quand la v1 sera atteinte (donc code clean, testé et nettoyé de ce qui n'est pas nécessaire pour zds), je pense que je ferai un sujet pour décider quel doit être l'évolution prioritaire : zep-5, zmarkdown1.5 (ajout/changements de syntaxe mais pas trop lourd) ou zmarkdown2 (changement en profondeur de la syntaxe) avec leur conséquences et implications de chacun. Tant que ça discute (avant le vote ou pendant les discussions sur la syntaxe si c'est ça qui ai choisi), j'aurai toujours des choses à faire. Puisque ça fait longtemps que ça n'a pas bougé, je préfère demander l'avis de la communauté.

T’inquiète pas, c’est juste une proposition comme une autre à éventuellement proposer dans une ZEP

Justement je préférerai que toutes les modifications de syntaxe soit dans la même ZEP et pas éparpillé dans plusieurs. Ça sera plus facile pour que ça ai de la cohérence. Donc si la communauté préfère qu'on fasse des modifs de syntaxes, pourquoi pas. On arrive bientot au point ou c'est possible. Car quand j'aurais commencé à faire des gros changement, ce sera beaucoup moins pratique.

Bon du coup j'ai un peu réfléchit et avancé hier, donc des infos/détails :

Concernant le dev en cours

• ma nouvelle gestions des légendes fonctionne très bien. A part les images, tous les autres sont géré de manière automatique par la même classe qui fonctionne très bien et est très simple. En gros pour rajouter le support de légendes sur des éléments il m'a suffit de rajouter une ligne a chaque fois (qui définit juste quel parseur doit supporter la légende avec quel nom). Cela vient remplacer l'ancien parseur par un nouveau qui rajoute le support des légendes. Ça marche très bien à condition que tous les parseurs qu'on veut rajouter soient bien des parseur de blocks et c'est là que le problème ce pose…
• Les balises math de blocs étaient paradoxalement jusqu’à maintenant détecté et traité comme un élément inline. J'ai dut reprendre l'extension proprement et le support de légende a été instantané.
• Là ou ça va se compliquer est le support des fenced code, c'est à dire les blocs de codes séparés par des ``` . L'implémentation actuel provient du projet Python-Markdown et est, soyons clair, pourri. Je l'ai déjà modifié pour supporter entre autre la mise en surbrillance des lignes de codes et la numérotation. Mais le plus gros problème est que ce n'est pas une extension de type block. L'extension fonctionne en passant en pré-process sur le texte, détecte ce qui ressemble à des blocs de codes et remplace ça par une chaine de caractère aléatoire complexe. Enfin tout à la fin, elle va remplacer ces chaines dans le texte par le html qui va bien. C'est ultra moche et pourri comme fonctionnement. Le premier problème est que l'extension ne peut pas fonctionner quand le code est par exemple dans un bloc citation. J'avais réglé le problème en créant une extension qui passait les pré-process avant chaque evaluation de blocks. Mais là pour les légendes ça ne va pas être possible de contourner le problème. Donc je vais retravailler l'extension pour en faire une vraie extension de block. Je la proposerai peut-être upstream du coup car c'est une demande de longue date de leur coté. Je comptais pas trop passer sur les extensions du projet upstream mais ça me semble nécessaire.

Du coup ça avance.

Road-map vers v1

J'ai décidé de changer un peu mes plans. Je vise une 1.0 propre avec une API minimal stable. Globalement dedans il y aura :

• Comme prévu, toutes nos extensions nettoyés et testés.
• Une gestion des meta-donné simple implémenté.
• Une API externe simple (globalement : création de l'instance, convertir un text en html, convertir un text en html + méta-donné)
• Le support des ping
• Enfin, un gros nettoyage des tests et de la codebase pour virer tout ce qui n'est pas utilisé par zds ou Zest Writer (les deux seuls vrais utilisateurs de cette lib).

A partir de là, j'aurai une version 1 propre et qui devrait convenir pour les évolutions qui suivent. l'API ne devrait pas être modifié avant une hypothétique v2 (ce qui n’empêche pas de rajouter des choses à l'API mais je garantirai à zds et Zest Writer que les fonctions qu'ils utilisent continueront à fonctionner sur la branche 1.x au delà de ce point).

La suite de la roadmap

Comme dit plus haut, je pense à ce stade (ou un peu avant) demandé à la communauté son avis. Je vois trois suites directs possibles :

• Je me lance dans la zep 5 et tout ce que ça implique (vrai AST, gestion de plusieurs extraits, gestion de plusieurs types de rendus (web/papier) et génération des types de sorties html, pdf et ebook)
• Le zmarkdown étant bloqué depuis longtemps, une autre possibilité serait de faire des modifications de la syntaxe à ce stade pour combler ce qui est demandé.
• Enfin, une solution intermédiaire ou on ferai quelques modifs "rapides et sans conséquences" (ie rétrocompatible) pour supporter le plus urgent avant de basculer sur la zep-5 ou un zmarkdown v2.

Je détaillerai un peu plus ces 3 points au moment de lancer le sujet (en particulier faire un markdown v2 ou on casse la rétrocompatibilité de la syntaxe impose lui aussi presque obligatoirement d'avoir une AST pour pouvoir faire une migration du contenu).

Bon j'ai un peu avancé et ré-écrit a peut prêt proprement l'extension des fenced-code. Je dit a peut prêt car sans AST et avec le fonctionnement actuel du parseur, je suis obligé de faire des trucs encore un peu moche.

Je me retrouve cependant avec un problème : les autres partit du codes qui utilisent des préprocesseurs (entre autre commentaires, note de bas de page et abréviations) passent donc maintenant avant cette extension et sont donc intercepté.

Tous ces éléments sont en effet interprété avant la détection de code et donc ça casse le tuto d'exemple de la syntaxe. Que les commentaires markdown soient strippés et ne peuvent pas être mit dans des blocs de codes ne me choc pas plus que ça. Les autres par contre c'est plus gênant.

Je sais pas trop comment m'en sortir a moins soit :

• De faire marche arrière sur cette extension et de faire un hack pas beau pour l'extension de légende.
• De refaire aussi ces extensions sous forme plus normale et ne pas utiliser de pré-processeurs.

Aucune des deux solutions ne me satisfait…

Bon a défaut d'avoir le temps d'avancer, je suis en train de préparer une nouvelle version du markdown pour que les améliorations des tableaux et balises maths arrivent sur zds.