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

Pandoc possède un tas de reader pour les formats d'entrées et des writer pour les formats de sorties. Les modif actuelles se sont concentrés sur le markdown en entrée et le latex en sortie. Pour l'entrée Pandoc proposait déjà plusieurs variantes. En gros chaque variante est le markdown de base + un certain nombre d'extensions.

De mémoire le premier commit est la pour rajouter la variante zds du markdown qui utilise les extensions qui collent a notre markdown (ex: il active le rayer et la mise en exposant mais il n'autorise pas le HTML dans le markdown).

Ensuite chaque commit est a peu prêt une extension. L'extension est rajouté dans les options, le morceau de passer est rajouté dans le reader et la génération de la sortie est rajouté dans le writer latex.

Il y a globalement 2 types de contenu qui vont être parsé : les blocks (paragraphes, bloc de code, secret, listes, etc.) et les inclinés (gras, italique, touches, etc.).

J'ai fais le choix de ne pas toucher a l'ast (le modèle de donnée représentant le document en mémoire entre le reader et le writer) pour plusieurs raisons :

• il est géré dans un dépôt a part et donc sa modification oblige a mettre a jour les constructions de build, de dépendance, gerer deux depots syncronises, etc.
• chaque modification de l'ast aurait généré des warning a la compilation, dans les writer ne les gérant pas, et des erreurs a l'exécution.

Au lieu de ça, j'utilise l'élément générique de bloc (div) ou inline (span) avec des attributs persos. Par exemple l'extension des touches va générer un span avec un attribut permettant au writer de le reconnaître. Le gros avantage est que un writer qui ne le reconnait pas va le rendre comme si c'était un span inconnu et le fonctionnement de nase est de les ignorer. Ce qui fait que toutes les sorties restent fonctionnelles même si elle n'ont pas été modifié, simplement les touches ne sont pas rendus.

(To be continued)

Juste pour dire que ton message n'est pas passé inaperçu et que j'essaye de me pencher dessus dès que j'ai du temps.

Je vais le compléter et il faut que je pousse les templates modifié aussi.

Je vais aussi essayer de dégager du temps pour t'aider de manière plus direct mais je promet rien actuellement…

Bon, je remonte un peu ce sujet. C'est dommage qu'il n'avance plus

Pour rappel, le fork actuel commencé par Kje apporte les fonctionnalités suivantes sur les rendus de PDFs

• Les blocs spéciaux (Information, Question, Attention, Erreur, Secret)
• Des sources de citations
• Des vidéos (youtube uniquement pour le moment) avec sa légende optionnel
• Des touches
• Des alignements (centré et à droite)
• Commentaires dans le markdown
• Abréviations

Vu le nombre de changements qui ont déjà été apportés, sur ce fork de pandoc , ça serait dommage les laisser moisir dans un coin quand on connait la piètre qualité du rendu PDF actuel.

Est-ce qu'on pourrait envisager de compiler le fork dans une prochaine release et avoir un meilleur rendu que celui actuel ?

De ce que j'ai vu dans le code, ça reviendrait à :

• variabiliser les variables à passer à pandoc (4 lignes de code python à modifier)
• mettre à jour le template LaTex modifié
• mettre à jour le script de MEP qui devra, avant de couper l'accès en ligne, compiler le binaire pandoc depuis les source du dépot. (2 lignes de shell)

Est-ce que ça aurait du sens pour vous ?

Bon, je remonte un peu ce sujet. C'est dommage qu'il n'avance plus

Malheureusement je n'ai vraiment pas le temps en ce moment. Perso je ne pourrait rien faire avancer avant Noël je pense.

variabiliser les variables à passer à pandoc (4 lignes de code python à modifier)

En fait il suffit simplement de mettre a jour la ligne de commande, je peux fournir la nouvelle ligne de commande à utiliser.

mettre à jour le template LaTex modifié

Je peux fournir le nouveau template Latex utilisable avec les nouveaux éléments parsé, il ne doit donc rien avoir a faire à cette étape que de copier/coller les éléments dans le dépot.

Don't panic, je trouve que tu as déjà fait un excellent taf. Et de ce que je vois de ton code ça m'a l'air plutôt pédagogique.

Ouaip, mais si on change la ligne de commande sa signifie qu'il faudra changer tous les binaires pandoc en local, sur travis, bref, partout. L'idée est juste de variabiliser pour ne pas impacter les devs.

Par contre si tu as la ligne de commande entière ça serait cool si tu la copie ici. Idem pour le template, y'a moyen de le mettre à dispo ?

Bon, les paramètres sont variabilisés. Je pense qu'on pourra passer sur la nouvelle version des PDFs pour la 1.4

Rappel le moi lundi que je te passe la ligne de commande et le template.

Plop.

Je remonte un peu le sujet car j'ai touché au fork ce soir :

Nouveauté :

• Les videos de dailymotion
• Les smileys ! (oui ils sont gros mais ça c'est un prob de template/latex)

En gros il reste les légendes de codes et la surbrillance de lignes de codes.

Bonjour tout le monde,

Avant de partir en congé, où je vais essayer de bosser sur cette ZEP sans forcément de connexions, j'aurais aimé avoir vos avis sur quelques points.

Où en sommes nous ?

Actuellement le fork de Pandoc est capable de parser presque toute notre syntaxe. Il ne reste plus vraiment que les légendes de codes et éventuellement la mise en surbrillance de lignes particulières. A partir de là, aux bugs et nettoyage du code pret, la partie "parsing" du markdown sera normalement terminé.

Etapes suivantes

La route est encore longue avant une mise en prod. Ce qu'il va rester a faire, pas forcément dans l'ordre :

• Nettoyer le code de génération de Latex.
• Nettoyer, refactorer et découper en deux le template Latex (un pour les long contenu type big-tuto, un autre pour articles et mini-tuto).
• Gérer proprement la notion de document constitué de multiples extraits (pour gérer les meta et les décalages de titres, voir plus bas).
• Binder tout ça pour faciliter l'utilisation depuis Python.

A partir de là on devrait avoir une version qui puisse être mise en prod pour la génération de pdf. Ensuite viendra (toujours pas forcément dans l'ordre) :

• La mise a jour du créateur d'ebook/epub pour supporter toute notre syntaxe.
• (optionnellement) Le rajout de l'export d'ebooks au format mobi/kindle (parce que moi je trouverai ça pratique (j'ai un kindle) et pourrait permettre aux auteurs ou au site de proposer le contenu sur Amazon; peut être fait proprement (un nouveau writer pandoc, qui partagera beaucoup avec celui epub) ou niveau python avec des convertisseurs epub <-> mobi existants.
• La prise en charge de notre sémantique dans la sortie HTML (ce qui permetra de passer à un full-pandoc sur le site)
• La prise en charge de notre sémantique dans la sortie markdown (avec mise a jour des autres modules d'entrées de Pandoc) pour permettre plus facilement l'import de contenu (utiliser pandoc avec Html en entrée et markdown en sortie nous permet d'importer plus facilement du contenu d'un peu partout par exemple).

Bref encore pas mal de boulots, les 4 premiers points étant les plus important à court-terme.

Voici pour l'état des lieux.

Les questions en suspent

Il y a plusieurs points sur lesquels j'aimerai avoir votre avis!

Coloration de code

La coloration du code est un point assez important de notre rendu de contenu. J'ai retenu 3 solutions :

• highlighting-kate
• listing
• pygment

Il y en a probablement d'autres, mais ces 3 là sont les plus évidents. Et déjà ces 3 là vont forcément demander du dev pour supporter pleinnement notre fonctionnement.

Les solutions

highlighting-kate

• Avantages:

  • Solution intégré à Pandoc, il n'y a rien à faire pour que ça fonctionne.
  • Marche pour html et latex : résultat identique pour les deux. Une configuration pour les deux sorties.
  • Une bonne liste de langages supportés, ajout facile depuis une définition de langage de l'éditeur Kate.
  • Possibilité d'activer la coloration pour le code inline en rajoutant un truc type {python} à la suite de la définition de l'élément inline.
  • Tout le rendu reste entièrement dans le monde Haskell, pas d'appel à d'autres technos.

• Désavantage:

  • Probablement le moins complet (au niveau nombre de langages et fonctionnalités) et connu des 3. Inconvénient à relativiser vu ce qui est déjà disponible.
  • Ne supporte pas actuellement la mise en évidence des lignes de codes. Mais des tickets en font mention, ce serait facilement accepté upstream (et John MacFarlane est assez rapide à releaser)
  • Ne supporte pas le coupure des lignes de codes si elles sortent de la page en Latex. Difficile à régler.

listing

• Avantages:

  • Standart de-facto dans le monde Latex
  • Grosse base de langages supportés, pleins d'options de rendu.
  • Seul a gérer correctement la césure de lignes de codes pour éviter le dépassement.
  • Déjà intégré à Pandoc
  • Possibilité d'activer la coloration pour le code inline mais pas actuellement géré coté Pandoc.
  • Supporte la mise en évidence de lignes de codes

• Désavantage:

  • Latex seulement. On peut donc avoir quelques incompatibilités entre les deux et un rendu différent.

pygment

• Avantages:

  • Probablement le module de coloration le plus connu, le plus utilisé et le plus complet.
  • Peut générer la coloration pour le html et le latex.
  • Solution actuellement utilisé sur zds pour le html.
  • Gestion partiel des cesures de longues lignes dans le latex.
  • Supporte la mise en évidence de lignes de codes

• Désavantage:

  • Pandoc n'est pas prévu pour l'utiliser. Possible mais necessite du dev.
  • Aucune idée si il est possible de colorer de l'inline. Probablement en choissant les bonnes options. Dans tous les cas necessite un peu de tests et dev.
  • Gestion partiel des cesures de longues lignes dans le latex : ne se fait que sur des espaces et il y a donc des cas pathologique qui rendront très mal (ne peut pas couper une adresse web en commentaire, peut couper au milieu d'une string, etc.)
  • Necessite de lancer un process Python supplémentaire dédié à la coloration durant le traitement.

Mon avis

Je reste partagé sur cette question. Actuellement je suis pour une solution pragmatique :

• Ne pas utiliser listing car ça ne résoud le problème que pour le latex, je préfèrerai avoir un seul élément qui gère tout pour m'éviter des bugs foireux ou comportements différents.
• A court terme, utiliser highlighting-kate car intégré nativement. Voir la difficulté que représente la mise en évidence des lignes de codes et la soumettre si facile. Ça liste de langage supporté et sa facilité d'ajout me semble largement suffisant pour nos besoins.
• A moyen terme, envisager Pygment en faisant un POC de son utilisation et voir le résultat obtenu et le coup de mise en place (dev, temps de traitement).

Et votre avis ?

Gestion de documents constitués de multiples extraits

Actuellement nous avons une notion de document représenté par :

• Un dossier contenant les multiples extraits d'un tuto
• Un manifeste qui contient leur agencements, les titres des parties et une parties des meta-informations
• Des données en bases annexe (auteurs, logo, etc.)

Pandoc n'a pas cette notion. Il n'accepte qu'un unique document en entrée. Si plusieurs fichiers lui sont données, il les concatène en entrée.

Pour gérer ça, la solution actuel est sous-optimal :

• Décalage de tous les titres des extraits à coup de regexp (non complète, source de bugs, etc.)
• Assemblage dans un fichier temporaire de ces extraits modifiés en injectant les titres et les meta comme sources markdown
• Passage du tout à Pandoc avec des options permetant de gérer tout ça (en particulier accepter la définition de blocs meta depuis le markdown ce qui pourrait permettre a un auteur de les modifier depuis son code markdown).

La première évidence qui vient ici est le décalage des titres qui peut être faite facilement et proprement au niveau de l'AST de pandoc. Cela demande de changer la gestion de ces multiples extraits.

Solutions possibles

Je vois deux solutions pour gérer ça proprement :

• En Haskell, en créant un nouveau point d'entrée. En gros on rajouterai un executable dans le code de Pandoc qui prendrait en entrée le manifeste et les quelques meta données manquantes et se chargerait de faire l'assemblage propre en manipulant l'AST directement.
• En Python directement. Il prendrait les mêmes types de paramètres et passerait les extraits un à un à Pandoc qui se chargerait aussi du décalage des titres et le module ré-assemblerait tous les extraits latex pour appeler latex et générer le pdf.

Depuis haskell/pandoc

• Avantages:

  • Tout reste dans le monde Haskell qui peut manipuler entièrement et proprement toute l'AST
  • Temps de traitements : il sera possible de générer toutes les sorties (pdf, ebook et html "entier") d'un seul coup depuis une source. On économisera autant de temps de parsage de l'entrée markdown qu'il y a de sorties supplémentaire puisqu'une fois transformé, la même AST peut être utilisé pour générer plusieurs sorties.

• Désavantage:

  • Nécessitera obligatoirement le fork pour fonctionner, plus contraignant pour les contributeurs externes

Depuis python

• Avantages:

  • Ce module est dans la techno la mieux maitrisé par le reste de l'équipe
  • Je peux me débrouiller pour que le décalage de titre ne necessite pas le fork et donc la génération global de pdf pourra rester compatible avec un pandoc de base.
  • Les différents extraits généré devront être assemblés et cela devra être fait avec une techno de template qui du coup pourra être la même que celle utilisé dans le reste du projet. Ainsi tous les templates (html, latex, etc.) utiliseront la même techno de template.

• Désavantage:

  • Necessite de transformer les templates latex et ebook vers la solution du projet.
  • Necessite de piloter Latex/xetex depuis le python (pour compiler le nouveau document).
  • Plus lent quand génération de plusieurs formats puisque Pandoc ne supporte pas plusieurs sorties simulatanément : on reparssera le tout systématiquement.

Mon avis

Instinctivement je partirai sur la solution en Haskell puisque c'est celle qui demande le moins de nouveau dev (celle python demande de refaire le liens avec les template et l'appel des builders comme latex). La necessité du fork peut être fortement diminuer : dans tous les cas il faudrat un mini-binding python (pour appeler pandoc) et celui-ci peut être fournit sous forme d'un package compatible PIP qui embarque le binaire du fork. Le seul vrais inconvénient est que je suis moins à l'aise en Haskell qu'en Python mais ça me semble jouable d'autant que tout est déjà dispo dans Pandoc (Pandoc inclus déjà un package pour lire les json par exemple).

Votre avis ?

Et maintenant ?

J'aimerai bien des avis ! Puisque c'est moi qui coder tout ça et le maintenir, je trancherai probablement à la fin si aucune solution ne fait consensus mais j'aimerai bien des avis externes. J'ai un peu le nez dans le problème, je loupe probablement des trucs.

De plus, à la rentrée, je ne serais pas contre de l'aide pour maintenir le bouzin et avancer ce qui demande des compétences, soit :

• En haskell pour intervenir sur le coeur de Pandoc (Vayel va participer quand il aura le temps, a priori)
• En latex pour améliorer le rendu des pdf (une fois que ce sera stabilisé)
• En html/css pour améliorer le rendu des ebook (parce que les ebook utilisent les technos web)

Et votre avis ?

Sur la coloration syntaxique, highlight-kate me paraît pas mal ! Et il y a un support pour les langages étranges qui m'intéressent, donc je n'ai pas de raison de râler

En latex pour améliorer le rendu des pdf (une fois que ce sera stabilisé)

Là je peut donner un coup de main !

Et il y a un support pour les langages étranges qui m'intéressent, donc je n'ai pas de raison de râler

Genre… Julia ? Note que c'est déjà supporté actuellement…

Là je peut donner un coup de main !

Je note !

Genre… Julia ? Note que c'est déjà supporté actuellement…

Et FORTRAN =)

Et FORTRAN =)

Fortran c'est pas étrange, c'est obsolète

Just don't feed the troll.

En plus dans ton domaine tu dois avoir vu passer du code Fortran, non ?

En plus dans ton domaine tu dois avoir vu passer du code Fortran, non ?

Ils sont déjà compilé quand je les utilise moi. Mon domaine n'existe vraiment que depuis les années 80 et ne c'est vraiment développé que dans les années 90-2000. Doit peut être y avoir du code fortran qui traine sous le tapis mais dieu merci il y a 4 couches de codes qui me sépare de lui.

Au risque de paraître un peu HS, Kate ne supporte pas Fortran correctement. Tout du moins pas Fortran90 et ultérieur (contains considéré comme un commentaire car il y a un "c" en début de ligne par exemple, c'est du Fortran 77… Ou bien l'absence de coloration pour certains mot-clé, comme class (si !), pass, abstract, ou tout les paramètres IEEE_machin). J'avais fait un truc qui répondait à mon besoin (coloration du fortran90/03 dans Kate, en modifiant le fichier xml qui servait au parsage du Fortran77), mais quand j'ai voulu l'envoyer chez Kate, la procédure m'a rebuté (cloner tous le git d'un projet comme ça quand on est en 50 ko/s, c'est dur). Si ça vous intéresse et que vous avez la possibilité de l'ajouter facilement à la main, je peut vous l'envoyer.

N'hésitez pas à me MP.

En soit j'en sais rien. Le fichier qu'utilise le module est ici. Cela ressemble a la version avant ton patch (je viens de le trouver sur leur ML). Une solution moins lourde est de proposer le patch uniquement à highlighting-kate. Dans tous les cas, on a pas encore de contenu fortran, donc on a encore le temps de voir venir, surtout si on sait que quelqu'un a déjà le patch qui traine

Dans tous les cas, on a pas encore de contenu fortran, donc on a encore le temps de voir venir, surtout si on sait que quelqu'un a déjà le patch qui traine

Ben c'est en cours justement =)

Mais la version de highlighting-kate a l'air bien. Je pourrais faire des tests si besoin.

Mais la version de highlighting-kate a l'air bien.

Par expérience, elle a deux gros manques :

• Pour le fortran 90, elle considère que les lignes qui commence par "c" sont des commentaires. Ça arrive dans chaque fichier de module, avec les contains.
• Pour le fortran 2003 et 2008, elle ne gère pas du tout les classes.

Si le tuto ne parle pas de Fortran orienté objet, un contournement simple est possible : ajouter une espace en début de ligne pour le contains.

Je ne sais pas ce qu'on utilise à l'heure actuelle, mais pour le coup, ça marche. Par exemple, dans le code que j'ai mis en dessous (qui ne compile surement pas, c'est des bouts de truc que j'ai trouvé dans mes dossiers - pas de moi, d'ailleurs), la coloration flancherai pour : contains, class, pass, nopass et abstract. Il suffit de faire un ctrl-f dans le fichier mis en lien pas Kje deux messages avant.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

!Ceci est un test.
module m
use ISO_FORTRAN_ENV
CLASS mytype
    private
    real :: x
    integer :: i
    PROCEDURE (set), public, POINTER, PASS :: p
    PROCEDURE (f), public, POINTER, NOPASS :: q
END CLASS mytype

contains
subroutine set (this, r, i)
    CLASS (mytype) , intent (inout) :: this
    real, intent (in) :: r
    integer, intent (in) :: i
    this%x = r ; this%i = i
    write (OUTPUT_UNIT, "(' THIS %X = ', f6 .2 ,/ , ' THIS %I = ', i6 )") this%x , this%i
end subroutine set

end module m

module m2
abstract interface
    SUBROUTINE sub( x, y )
        REAL, intent(out) :: x
        REAL, intent(in) :: y
    END SUBROUTINE sub
end interface
end module m2

Pour le cas de contains, il n'est pas géré en tant que mot clef, mais il a sa propre regex plus loin.

Il faudrait tester pour le reste.