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

Le principal problème de ReST sur Markdown c'est sa difficulté d'apprentissage et le manque total d'habitude. Il suffit de regarder la doc technique de zds pour se rendre compte des typo que les dev réalisent parce que reST est mal maîtrisé. De plus ReST est hyper sensible à la typographie (rien que le contexte sourcecode…), donc pour un site orienté débutant comme zds, c'est un mur presque infranchissable.

Si demain on a un parseur markdown/Rest qui permette d'utiliser sphinx, je dis OK. Sinon on se calme.

En passant, je voulais passer par là pour que techniquement la tâche vous soit simplifier : avec la v16 qui arrive, changer la manière dont les extra-content sont générés est hyperfacile. AInsi, on pourrait tout à fait avoir d'un côté un code qui gère le PDF/Latex avec autrechosequepandoc alors qu'on garderait (pour un temps du moins) le générateur pandoc pour les epub par exemple.

PS : en plus on pourrait aller plus loin encore en mettant un faux générateur de PDF pour tous les tests unitaires. Devoir installer pandoc+latex à chaque fois ça saoûle.

Les ebup c'est franchement pas le problème. Ce ne sont basiquement que des html zippé.

Je ne suis pas persuadé que le rest soit une solution. Il faudrait faire de toute façon pas mal d'adaptation car il y a certaines choses qu'on ne veut pas (a commencer par le html dans le contenu). Du coup il faudrait toucher au parseur. Je ne sais pas a quel point il est personnalisable mais ça demanderait forcément du travail.

De plus ça ne dit pas si on ne va pas avoir le meme problème avec sphinx que j'ai eu avec pandoc : certaines choses sont pénible à faire en latex, a commencer par les tableaux un minimum complexe. Je vois pas pourquoi ça changerai avec sphinx.

NB: les fonctionnalités a implémenter dans le markdown ce n'est pas spécialement compliqué, le seul problème est qu'on a encore une chaine branlante.

Avant toute chose j'aurais une question : est-ce que le fork de pandoc est nécéssaire ? Car apparemment il est possible de "scripter" avec pandoc, et par conséquent je me demandais si ça ne sera pas possible de s'en passer (en plus, il y a un paquet disponible pour écrire des filtres en python). Donc si le fork est nécéssaire, qu'est-ce que l'on doit modifier précisément ?

A mon avis, c'est un peu regrettable de se passer du LaTeX pour générer un PDF. Est-ce que les problèmes soulevés demandent à faire du cas par cas, ou bien tu penses qu'il est possible de régler ces problèmes de façon générique ?

De plus ReST est hyper sensible à la typographie (rien que le contexte sourcecode…), donc pour un site orienté débutant comme zds, c'est un mur presque infranchissable.

Est-ce que tu pourrais expliciter ce point ? Plus précisément, en quoi est-ce différent avec le zMarkdown, où une ligne blanche oubliée transforme les listes en bouillie infâme et un espace oublié en fin de ligne ruine la mise en forme sur plusieurs lignes, par exemple ?

Là encore, en quoi le zMarkdown ne demande-t-il pas d’apprentissage pour un nouveau (le Markdown, il n’y a que sur ce site que je m’en sers, ce n’est absolument pas un usage courant que j’aurais eu avant de venir), et en quoi les difficultés éventuelles du ReST ne peuvent-elles pas être « lissées » par un bon éditeur de texte, comme celui dont précisément nous disposons pour le zMarkdown ?

De manière générale, je trouve que le ReST est plus logique et cohérent que le Markdown, et donc plus simple à apprendre : là où en ReST tous les blocs (sauf la citation) ont la même forme…

1
2
3
4
5
6
7

.. type_de_bloc::
    option: valeur
    option: valeur

    Contenu du bloc.

On passe à autre chose.

… le zMarkdown possède pas moins de 5 syntaxes différentes, entre les blocs spéciaux ([[qqch]] puis | à chaque ligne), le code (```), les citations (>), les maths ($$), les images et vidéos (![]()) et j’en oublie peut-être.

Note : je dois partir, je répondrai plus tard à Kje.

La complexité de ReST me fait peur aussi. Quand on voit que les utilisateurs (en particulier non-geek) ont du mal à se faire à un système relativement simple comme les bases de Markdown¹, je ne vois pas comment un langage plus complexe comme ReST peut passer.

On pourrait imagines autoriser les deux syntaxes (mais ça fait du boulot en double), utiliser ReST dans les contenus et Markdown dans les forums et commentaires (mais ça fait du boulot en double et ce n'est pas très cohérent), ou imaginer une double conversion Markdown –(outil X)–> ReST –(Sphinx)–> Formats de sortie (mais ça me paraît casse-gueule).

Dans tous les cas, ça nécessite une soigneuse étude d'impact en particulier au niveau de l'expérience utilisateur des membre non contributeurs, et de la stabilité et de la fiabilité de la pile logicielle.

Oui il faut passer par un fork. La forme de script que propose Pandoc est d'écrire des filtres sur l'ast généré. Malheureusement plusieurs de nos modifs nécessitent de modifier le parseur et ça il faut forker.

En gros ce que j'avais fais sur le fork :

• rajouter des morceaux au parseur pour qu'il comprenne notre syntaxe
• rajouter dans les générateurs de sorties (ici latex) le rendu correspondant.

J'avais réussi a faire cela sans toucher à l'AST (qui est dans un module séparé) en jouant avec les éléments génériques.

Entre temps ils ont modifié le code, entre autre en virant un des 3 niveau de monad présent. Faudrait probablement tout reprendre (ce qui ne serait tout de fois pas un mal).

Le problème du latex pour les pdf sont nombreux mais de mémoire le plus pénible que j'ai eu et pas réussi à résoudre c'est les tableaux. Presque systématiquement quand il y avait quelque chose dans les tableaux autre que du texte simple (code inline ou non, bloc d'infos ou autre) ça voulait pas compiler ou ça déconnait totalement. Et le problème c'est que c'est en parsant des articles publiés que j'ai eu ces problèmes. Donc du contenu qui existe, pas que j'ai inventé.

Pour le ReST, pour moi c'est hors-scope. C'est une possibilité envisageable (même si je ne las trouve pas génial) mais ne devrait pas être discutée ici car l'impact est très important sur le site.

Je ne pense pas que ça suffise. Il y'a des syntaxes qui n'existent pas encore dans les ReadMarkdown pandoc pour passer dans l'AST. Donc faire un filtre au milieu sur quelque chose que pandoc n'a pas encore identifié (je pense ici à la syntaxe des bloc, la syntaxe de la source de citation, … ) n'est pas vraiment possible.

Donc on n'est pas obligé de modifier l'AST directement, mais il faut à minima faire les ReadValue dans un fork de pandoc et leur équivalent coté WriteValue pour supporter la syntaxe zMarkdown

EDIT: grillé par Kje, m'en fou je poste quand même

Comme mes VDD, le ReST, je ne suis pas favorable, parce que :

• Un peu plus lourd à écrire (plus lourd que le markdown je veux dire)
• On a aussi du boulot d'adaptation à faire
• Il faut toucher à tout les contenus existants

Oui il faut passer par un fork. La forme de script que propose Pandoc est d'écrire des filtres sur l'ast généré. Malheureusement plusieurs de nos modifs nécessitent de modifier le parseur et ça il faut forker.

En gros ce que j'avais fais sur le fork :

• rajouter des morceaux au parseur pour qu'il comprenne notre syntaxe
• rajouter dans les générateurs de sorties (ici latex) le rendu correspondant.

Au lieu de se trimbaler un fork, on ne peut pas juste écrire notre propre reader et notre propre writer ? Et les utiliser ensuite avec pandoc ?

Faudrait y réfléchir mais ce n'est pas un problème qui me semble insurmontable à première vue. Il faudrait seulement modifier le writer LaTeX non ?

Faudrait y réfléchir mais ce n'est pas un problème qui me semble insurmontable à première vue. Il faudrait seulement modifier le writer LaTeX non ?

Kje l'a peut être mal expliqué, mais ce qui parait à première vue simple devient compliqué dès lors que l'on considère coté LaTex la gestion des tableaux, du code multiligne, des balises vidéos et tout le tintouin. Après je pense que toute PR est la bienvenue aussi.

Au lieu de se trimbaler un fork, on ne peut pas juste écrire notre propre reader et notre propre writer ? Et les utiliser ensuite avec pandoc ?

J'avais opté pour compléter celui de pandoc en mettant nos ajouts comme des extensions activable (comme toutes les extensions de markdown proposé par pandoc). On pourrait aussi simplement copier l'ensemble et le faire à coté mais ça change pas fondamentalement le problème. Dans tous les cas faut compiler avec.

Faudrait y réfléchir mais ce n'est pas un problème qui me semble insurmontable à première vue. Il faudrait seulement modifier le writer LaTeX non ?

Le problème que j'avais n'étais pas dans la génération en fait, c'etait dans le template latex. Ce sont tous les problèmes que pose latex, entre autre sur les tableaux. Car latex a du mal avec certaines constructions.

Dans ma tête (très naïve certes), il suffit de trouver et regarder ces cas là dans l'AST de pandoc pour les générer correctement en LaTeX.

Au lieu de se trimbaler un fork, on ne peut pas juste écrire notre propre reader et notre propre writer ? Et les utiliser ensuite avec pandoc ?

J'avais opté pour compléter celui de pandoc en mettant nos ajouts comme des extensions activable (comme toutes les extensions de markdown proposé par pandoc). On pourrait aussi simplement copier l'ensemble et le faire à coté mais ça change pas fondamentalement le problème. Dans tous les cas faut compiler avec.

Bien sûr, je pensais faire un copier/coller au début. Mais il n'y a pas d'avantage à juste avoir ces deux fichiers au lieu de se trimbaler tout un fork ?

Ok. Je pensais que cela pouvait se régler à la génération sinon…

Bien sûr, je pensais faire un copier/coller au début. Mais il n'y a pas d'avantage à juste avoir ces deux fichiers au lieu de se trimbaler tout un fork ?

En fait le seul avantage que je vois est que ça permettrait de se rebaser avec pandoc sans que ça affecte notre parser pour des modifs. Mais bon ça nous oblige aussi à les merger à la main. De la façon que je le faisait l'avantage est que tu pouvais utiliser notre fork a la place de pandoc, il changeait pas de fonctionnement par defaut et on profitait directement des améliorations qu'ils ont faites.

Mais fondamentalement c'est du détail. C'est loin d'etre ça le problème le plus important.

Pour le latex on peut changer la génération, je l'ai fait pour certains trucs, mais quand j'étais dessus il y a des passages que j'ai n'ai pas réussi à convertir convenablement. J'arrivai pas à les rendre en latex. Ce sont des problèmes pur latex.

Je pense au contraire qu’avant de forker Pandoc / forker une nouvelle version incompatible de Python-Markdown / forker sphinx pour lui apprendre à gérer le Markdown / forker je ne sais quel autre outil (rayer les mentions inutiles), il pourrait être sage de se demander si ce n’est pas la partie « Markdown » de l’équation qu’il faudrait changer.

Sinon, pour tous ceux qui affirment que ReSt serait trop compliqué, voici un petit comparatif des syntaxes entre zMarkdown et ReST sphinx pour les fonctionnalités les plus utilisées sur les forums (donc par des nouveaux venus devant s’adapter à notre système).

Gras et italique.

1

**Gras** et *italique*.

1

**Gras** et *italique*.

Titres et sous-titres.

1
2
3

# Titre

## Sous-titre

1
2
3
4
5

Titre
=====

Sous-titre
----------

Citations (avec auteur).

1
2

> Voilà une citation qu’elle est belle.
: Auteur

1
2

  Voilà une citation qu’elle est belle.
  -- Auteur

Listes à puces.

1
2
3
4
5

- Point 1
- Point 2
    - Sous-point 1
    - Sous-point 2
- Point 3

1
2
3
4
5
6
7

- Point 1
- Point 2

  - Sous-point 1
  - Sous-point 2

- Point 3

Listes numérotées.

1
2
3
4
5

1. Point 1
2. Point 2
    1. Sous-point 1
    2. Sous-point 2
3. Point 3

1
2
3
4
5
6
7

# Point 1
# Point 2

  # Sous-point 1
  # Sous-point 2

# Point 3

Notez que la syntaxe de zMarkdown fonctionne aussi en ReST, mais sans l’effet « numérotation automatique » du zMarkdown.

Code inline.

1

La fonction `trucmuche` de Python.

1

La fonction ``trucmuche`` de Python.

Bloc de code, avec spécification du langage.

```python
pass
```

1
2
3

.. code-block:: python

  pass

Maths.

1

$$\latex$$

1
2
3

.. math::

  \latex

Liens.

1

Texte avec [un lien](http://monsite.fr/) dedans.

1

Texte avec `un lien <http://monsite.fr>`_ dedans.

Ligne horizontale.

1

------

1

------

Note de bas de page.

1
2
3

Texte, avec une note[^note] au milieu.

[^note]: Texte de la note.

1
2
3

Texte, avec une note [#note]_ au milieu.

.. [#note] Texte de la note.

Bloc « Attention » (ou autre, ils fonctionnent tous pareil).

1
2

[[attention]]
| Texte du bloc.

1
2
3

.. attention::

  Texte du bloc.

Image avec légende.

1
2

![Texte alternatif.](http://monsite.fr/image.png)
: Légende propre.

1
2
3
4

.. figure:: http://monsite.fr/image.png
   :alt: Texte alternatif.

   Légende propre.

Voilà, je pense avoir fait le tour de 95 % de ce qu’utilise le visiteur lambda sur les forums, smileys exceptés, puisqu’ils ne sont pas disponibles de base dans ReST. Du coup, au vu du comparatif, je suis d’accord que ReST est un peu plus lourd car il utilise des mots-clés entiers avec une syntaxe usuelle plutôt qu’une syntaxe nouvelle.

En revanche, désolé, mais l’idée que ReST serait nettement plus difficile que le zMarkdown, ça, ça ne passe pas…

En revanche, désolé, mais l’idée que ReST serait nettement plus difficile que le zMarkdown, ça, ça ne passe pas…

Merci d'avoir prouvé par les syntaxe équivalentes que si, ça passe carrément.

Pas de maths inline. Ça fait mal, quand même. Quid des citations sans auteurs et des citations multilignes, qui sont extrêmement utilisées ?

Perso, je m'en fiche de la solution choisie, le truc qui me gène, c'est que la syntaxe soit bloquée par cette ZEP (bloc définition, sources, maths¹, etc.). Je préfèrerai une solution facile à étendre, car il y a beaucoup de besoin spécifique, et pouvoir faire ça sans demander à un dev serait pas mal.

Ben, quand je vois déjà le bordel qu'on peut avoir par exemple ici pour deux malheureux caractères en plus ou en moins dans une syntaxe, je me dis que le « un peu plus lourd » risque d'avoir beaucoup, beaucoup de mal à passer.

A noter que quand je dis "il faudrait tenter un POC avec WeasyPrint" ça sous-entend "si ça rend bien on peut se passer de forker pandoc, d'avoir latex en dépendance et ne plus maintenir qu'un convertisseur markdown -> html" ce qu'on a déjà et nous rend, potentiellement, indépendant dudit parser (si on veut supporter un deuxième langage d'entrée il suffit qu'il produise du html).

C'est bien pour éviter les forks et minimiser le travail de maintenance que je propose de regarder ça. Car un CSS sera toujours beaucoup moins pénible à maintenir qu'un fork de pandoc + un template de latex + de la glue par dessus tout ça.

@artragis : à ce stade, c’est plus de la mauvaise foi, c’est de l’art.

@Gabbro : j’ai édité mon message de la page précédente pour rajouter quelques infos. Entre autres, j’insiste plus sur le fait qu’il est possible d’étendre assez facilement la syntaxe par de nouveaux blocs ou de nouvelles balises inline, ce qui pourrait entre autres être utilisé pour les maths inline.

Pour les citations sans auteur, tu enlèves simplement la partie -- Auteur. Pour une citation multiligne, ça donne ça.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Phrase d’introduction :

  Première ligne de citation, voilà.

  Deuxième ligne de citation, avec même :

  - une liste ;
  - à puces ;
  - imbriquée.

  C’est trop la classe !

On n’est plus dans la citation.

@SpaceFox : c’est sûr… Après, faudrait voir ce qu’en dit la majorité silencieuse : sur le vote en question, il y a autant de votes blancs que de votes pour les deux choix réunis.

EDIT (21h46) : en fait, si, on peut bien faire des maths inline, avec :math:, j’avais juste mal lu.

@Gabbro : j’ai édité mon message de la page précédente pour rajouter quelques infos. Entre autres, j’insiste plus sur le fait qu’il est possible d’étendre assez facilement la syntaxe par de nouveaux blocs ou de nouvelles balises inline, ce qui pourrait entre autres être utilisé pour les maths inline.

Techniquement c'est cet ZEP qui bloque ça sur le markdown. Rajouter des blocs génériques, c'est techniquement pas compliqué en markdown.

Je rappel a tout hasard que le problème à la fin n'était pas de générer le latex, mais d'avoir un rendu correct depuis ce latex. Je me battais avec latex pour qu'il fasse un rendu correct des structure complexe, pas avec Pandoc.

Refaire le fork de Pandoc ne me ferait pas spécialement peur mais ça ne réglera pas le fait que latex a du mal avec les structures complexes, entre autre les tableaux.

Et ça, pandoc ou sphinx, même combat.

OK, j'avais mal compris. Autant pour une doc python, les blocs délimités par des espaces ne me choquent pas, autant pour du web… On n'a ni les tabulations, ni la sélection par bloc, ni la possibilité d'indenter 15 lignes d'un coup facilement.

Remplacer la traitrise des sauts de lignes markdown par la traitrise de l'indentation… Y gagne-t-on vraiment ? S'il y a de solides arguments autres, pourquoi pas, mais je ne suis pas spontanément enthousiaste.

J'ai le même ressenti que Dominus sur ce thread, il y a de la mauvaise foi dans l'air…

Perso je suis pro markdown et vu que notre éditeur supporte pas les tabulations le rest risque d'etre pénible, mais sortis de ça c'est pas la mer a boire non plus (bon leur syntaxe est pourri des qu'il y a des liens par contre…)

Après sorti de ça le problème dit et répété par Kje n'est pas la syntaxe d'entrée mais tout les cas alakon galère a sortir proprement (tableau …)