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

De toute façon actuellement notre fork de pandoc n'est pas pret, la sortie HTML de nos éléments n'a pas du tout été commencé. Il y a encore un peu de temps avant que ça remplace le module soit utilisé comme seul parseur du site.

Nan mais même à terme je pense que je vais rester sur cette version là.

Elle a l'immense avantage pour moi d'être "embarquable" sans avoir à toucher au système, ce qui permet de l'inclure comme une lib dans n'importe quel soft et de pouvoir bénéficier des extensions zds au markdown de base.

Cette version est complètement agnostique de ce qui est installé sur le système du coup ça m'arrange plutôt bien en tant qu'alternative à Pegdown ou autres. Directement "invocable" par Jython. Mais je comprends que ce soit pas le meilleur choix pour zds par contre

Comme tu veux mais a terme elle ne sera plus maintenue (déjà que la je fais rarement des bug fix).

Apres très honnêtement si on avait trouvé un équivalent de pandoc en python, j'aurais été le premier content mais là il n'y a pas photo.

En fait il y a un truc qui n'est pas loin de ce qu'on veut : docutils/sphinx. Ce code en pur python produit de l'html, des epub et du latex/pdf (+ 2-3 formats) a partir d'un langage de markup. Le principal soucis est qu'en entrée c'est du restructured text et non du markdown.

Je pense que ça mérite d'être envisagé. Les avantages :

• code pur python (portable, meilleur intégration a zds, plus de dev potentiel, etc.)
• support de nos sorties indispensable
• vrai convertisseur, il y a un AST propre entre les entrées et sorties (contrairement a Python-Markdown).
• AST riche : supporte déjà des blocs perso comme warning, etc.
• Techniquement on pourrait imaginer l'utiliser pour notre doc de code et ainsi intégrer cette doc directement sur le site sous forme de tuto.

Par contre ça a quelques désavantages :

• il y a un peu moins de sorties que Pandoc
• il faut faire un parseur markdown en entrée

Pour le premier point ce n'est pas très gênant pour zds : nos formats sont supportées.

Pour le deuxième point il est probablement possible de le faire sans trop de difficultés depuis celui restruredtext. On peut probablement gagné du temps pour une v1 en utilisant le fork Pandoc (convertir l'ast pandoc vers l'ast de docutils) ou Python-Markdown (meme si là ca va etre plus compliqué).

Des avis ?

J'avoue ne pas tout comprendre aux infos que tu donnes (genre, le dernier paragraphe tient beaucoup de l'hébreu pour moi ), alors je voudrais m'assurer de certaines choses avant de me faire un avis définitif.

• On est bien d'accord qu'à même entrée, le résultat en HTML sera identique entre le système actuel et celui-ci ?
• Sera-t-il possible de faire de l'identification à l'échelle du paragraphe, comme cela est souvent demandé, et comme cela sera possible avec Pandoc ?
• Est-ce que cela prendra un temps équivalent ou inférieur de basculer tout le fonctionnement du site sur cet outil que de terminer le travail entamé sur Pandoc ?

Si la réponse à ces trois questions est oui, alors je ne vois aucune raison de ne pas adopter cet outil.

En outre, j'ai jeté un œil à reStructured text, et il est vraiment pas dégueu comme système : sur un certain nombre de choses, la syntaxe est la même qu'en markdown, et sur d'autres, il est vachement plus puissant que le markdown (les images, par exemple). Du coup, je propose qu'on discute aussi de la faisabilité et de l'opportunité de passer à ce système de représentation-là.

Alors le dernier paragraphe dit, en gros, qu'en première étape, avant de faire un module de lecture de markdown propre pour le convertisseur, on peut très bien réutiliser ce qui a déjà ete fait en utilisant le module d'entrée de notre fork de pandoc. Il suffit pour cela de mettre en place un convertisseur entre le format interne de pandoc vers celui de docutils. Ce sera assez rapide a faire.

Pour tes questions :

• oui, enfin c'est le but. Soyons honnête, avec des convertisseurs aussi complexe et un langage d'entrée aussi merdique et peu normé que le markdown, il y aura forcément quelques différences d'interprétation. Mais le but est qu'il y en est le moins possible.
• ca dépend de ce que tu entend par la mais probablement que oui. Pour plus de précisons, ca dépend de ce que tu entend vraiment par là et du code reel de docutils (que je n'ai pas encore regardé). Mais a première vue les deux sont philosophiquement proche. La seul différence entre les deux est, a première vue, que pandoc découpe chaque mot indépendamment, et les espaces sont aussi séparé du reste tandis que docutils, a première vue, va faire un seul objet par morceaux de phrases.
• difficile a dire. A court terme ca rajoute du travail mais ca peut en faire gagner sur le long terme.

Pour le reste, le but n'est pas de passer au restructured text mais ca reste philosophiquement proche du markdown. Une fois la zep-5 bien avancé j'en lancerai une nouvelle pour discuter d'un markdown zds v2.

Même si le restructured text est plus verbeux que le Markdown, il a l'avantage de proposer pas mal de truc en plus assez sympa. Du style des ancres/liens vers des zones quelconques du texte, une gestion de pas mal de rôles différents, …

Ça pourrait être cool de proposer les deux: md pour les forums, et les articles/tuto avec mise en page simple, et ReST pour les trucs plus poussés. Je ne sais pas combien de boulot en plus cela demanderai par contre.

On pourra en parler mais apres cette zep.

Mais je rappel que rien ne nous empêche d'étendre le markdown.

De mon point de vue, je ne pense pas qu'il faille s’éparpiller encore sur un autre outil. On a choisit pandoc comme pierre centrale parce qu'il nous permet de tout faire et ne pose pas de limite. Le markdown est notre format d'entrée, de base il n'est pas très agréable mais avec des améliorations simples on arrive à avoir quelque chose de sympa. Changer de format d'entrée ou d'outils ne fera que déplacer le problème à coté.

Je constate que les idées fusent, on a envie de beaucoup de choses et c'est normal, mais il faut laisser les développeurs absorber la charge que représentent les demandes. En l’occurrence ici, Kje a visiblement besoin de bras pour l'épauler.

Moi ce que j'ai proposé ce n'est pas de passer au restructured text mais d'utiliser docutils au lieu de pandoc pour justement avoir plus de bras, des dev python seront plus facile a trouver que des dev haskell. Je reste assez partagé pour le moment.

Ce qui me dérange c'est que docutils reste limité. Si on envisage (chose que j'aimerai bien un jour) de proposer du LaTeX aux auteurs pour en faire ce qu'ils veulent, ça risque d’être compliqué, et on est reparti pour une autre refonte.

Après le problème de ressources est un vrai problème, mais je reste dubitatif sur le fait que changer d'outil le résolve. Cette ZEP n'est pas la seule à manquer de bras par exemple.

Ce qui me dérange c'est que docutils reste limité. Si on envisage (chose que j'aimerai bien un jour) de proposer du LaTeX aux auteurs pour en faire ce qu'ils veulent, ça risque d’être compliqué, et on est reparti pour une autre refonte.

Mauvais exemple. Docutils/sphinx possède moins de formats de sorties que Pandoc mais si tu avais lu mon message tu saurais que lui en fais en partie.

En fait docutils propose comme sortie HTML, LaTeX, man-pages, open-document et XML. Sphinx rajoute des builders par dessus pour produire des pdf (depuis le latex) et des epub (en dérivant le HTML). Donc le latex brut est parfaitement disponible.

Après le problème de ressources est un vrai problème, mais je reste dubitatif sur le fait que changer d'outil le résolve. Cette ZEP n'est pas la seule à manquer de bras par exemple.

Je suis assez d'accord mais c'est aussi valable pour moi. Je suis bien plus rapide et efficace en Python qu'en Haskell, surtout là ou le code des parseurs a 4 Monads imbriqués où je me perd régulièrement. Sur certains ajouts dans le parseurs de markdown j'ai prit parfois des heures a régler ce genre de trucs. Mais dans tous les cas ça ne serait pas pire.

Le gros avantage de Pandoc est son coté plus complet et général tandis que docutils a celui d'être dev en Python.

Je rajoute cette possibilité dans la liste, je ne dis pas qu'il faut le faire. En fait il faut que je creuse un peu le code pour voir.

J'ai du mal à comprendre une chose : Kje, tu proposes une nouvelle solution où tu dois tout reprendre depuis 0 la ZEP ? Si oui, ça serait un peu décevant de te voir repartir à 0 mais les avantages que tu cites à docutils/sphinx sont quand même séduisants (notamment son langage, là où le Haskell me rebutait un peu).

Oui et non. Actuellement sur la zep-5 il y a deux types de modifs qui m'ont prit du temps : la mise a jour du parseur markdown de pandoc et le template latex. Le convertisseur AST -> latex de pandoc a eu quelques modifs aussi mais ça a été ultra rapide, facile et mineur. Sur ces deux grosses taches, tout le travail sur le latex est récupérable puisque c'était au niveau latex qu'on conserverai.

Pour clarifier la situation je pense que l'idéal pour moi (en tant que dev de la fonctionnalité) et pour zds serait qu'on est un unique convertisseur propre markdown vers AST et, a minima, deux convertisseurs de sorties (AST vers Latex et AST vers HTML, les ebook sont a 95% du HTML) et tout ça en python.

Python-ZMarkdown a comme principal soucis de ne pas passer par la case AST ce qui rend très compliqué la mise en place d'une sortie latex sans un gros travail de refacto (et accessoirement le code n'est ni efficace ni propre, ca mélange allègrement parsage du markdown d'entrée et génération du HTML de sortie).

Pandoc forme déjà la chaine complète propre mais est en haskell. Outre les complications de déploiement ça me fait peur pour les dev futur. Par exemple pour la zep de firm1 sur les corrections de tuto, bien que je suis surs qu'il est possible de faire enregistrer la position dans le markdown de chaque bloc, je ne sais pas comment il faut le faire et ca me prendra pas mal de temps a le faire fonctionner parce que je ne maitrise pas terriblement le haskell.

Enfin docutils a l'architecture propre, en python, au gros bémol pret qu'il ne comprends pas le markdown en entrée.

La conclusion va etre pragmatique. A court terme il ne semble plus aujourd'hui y avoir de gros frein a utiliser pandoc. Pour la génération des pdf on va passer aux tests et ce serait dommages de retarder ça le temps de refaire un parseur markdown pour docutils. Cependant je garderais cette idée en tête car a terme ce serait mieux pour tout le monde. Mais vu l'avancée actuelle il vaut mieux attendre avant de changer ça.

Du coup, si on doit passer par une étape où l'on fonctionnera en prod avec Pandoc (que donc on a du temps devant nous avant d'intégrer docutils), j'insiste pour que l'on discute sérieusement de l'idée de passer du markdown au ReST avant de bosser sur docutils : autant faire d'une pierre deux coups.

Pour moi c'est un problème a part. Tu peux lancer le débat dès maintenant (dans un autre sujet) si ça t'intéresse. Pour moi c'est un faux débat car on a déjà prit le partit de modifier la syntaxe de markdown pour rajouter nos propres extensions. Donc toutes fonctionnalités que tu aimera dans le ReST on peut très bien l'adapter dans notre markdown.

Au passage une fois la ZEP-05 bien avancé je pensais justement lancer une autre ZEP pour préparer un zmarkdown-v2. La solution peut être de passer au ReST mais je doute que tu réussisse a convaincre la majorité.

A titre personnel je préfère qu'on étende notre markdown (en rajoutant de nouvelles fonctionnalités avec une syntaxe optionnel) pour permettre des transissions en douceur plutot que de supporter deux langages d'entrée ou un seul totalement différent (qui aménerait à devoir faire un convertisseur Notre-markdown -> ReST).

Je t'invite donc à en faire un sujet dédié pour préciser ta demande. Car Pandoc supporte déjà le ReST comme format d'entrée donc ça peut être discuté en parallèle.

Pour revenir au sujet, j'ai été regarder le dépot de Sphinx. Le support du markdown dans sphinx est une fonctionnalité très demandé. Il y a moins de 15 jours, une PR est venu préparé le travail (en gros elle permet de choisir un parseur en fonction de l'extension du fichier). Ils disent clairement que c'est en vue du support du markdown :

This should help with #825, by allowing for a mixture of reST and MD.

Plus interessant encore nous avons cette remarque d'un dev principal :

Markdown support can now be done entirely in an extension until we include it in 1.4.

La 1.4 sera la prochaine version stable de Sphinx. Au vue de leur rythme, ça voudrait dire que ce serait dispo dans 3 mois.

Je vais donc clairement pas me lancer dans un nouveau parseur markdown si ils comptent le faire. On va continuer comme prévu avec Pandoc pour le moment et voir ce qui se passe car si effectivement une version de Sphinx arrive avec le support du markdown, là pour le coup ce sera assez facile, je n'aurais qu'a rajouter nos extensions et virer celles dont on a pas besoin.

En attendant, c'est surtout la compilation Latex qui pose facilement des soucis en ce moment, elle peut être réglé quelque soit le parseur avant.

Pour info, grace à firm1 qui m'a refilé les infos de tous les articles publiés qui ne sont pas dans les archives, j'ai put commencer à lancer un traitement plus ou moins automatique de toutes les articles. J'ai déjà repéré sur les quelques premiers exemples put trouver plusieurs problèmes falgrants que je vais m'efforcer de corriger.

Bref ça avance.

Bon j'ai une bonne et une mauvaise nouvelle. La bonne est que moi qui me plaignait des Monads encapsulé, l'upstream vient d'en virer une couche. La mauvaise nouvelle est que du coup ça change TOUT le code, toutes les signatures de fonctions doivent être changé, les codes doivent être mit a jour, etc. Bref ça compile plus et faut que je passe du temps pour réparer le parseur du coup…

La mauvaise nouvelle est que du coup ça change TOUT le code, toutes les signatures de fonctions doivent être changé, les codes doivent être mit a jour, etc. Bref ça compile plus et faut que je passe du temps pour réparer le parseur du coup…

Heu, ils font ça souvent ? Car s'il faut mettre à jour fortement le code trop souvent, ce n'est pas vraiment une solution pérenne.

Non c'est la première fois que j'ai un merge aussi pénible a faire. Techniquement ça va dans le bon sens (simplification) mais j'avoue que ça me fait chier a cet instant, il faut que je dégage du coup quelques heures pour tout fixer et re vérifier. Je pense que c'est lié a l'implémentation de commonmark dans pandoc qui, meme si dans un module séparé, doit les motiver a factoriser le parseur.

Kje : je pense que tu devrais te fixer sur une release de pandoc le temps de développer la ZEP pour ne pas avoir à gérer les merge upstream trop souvent. Une fois la ZEP sortie on ne ferait plus que des merges de release en release.

C'est en tout cas ce que j'avais fais avec GitPython à l'époque pour éviter de faire rentrer du code non stable dans ZdS.