Export PDF : (r)évolution et bugs connus

Bonjour à toutes et à tous !

depuis la v27 et ses versions mineures nous avons enfin un système d’export de tuto qui est qualitatif. QU’il permette de créer des ebooks au format pdf ou epub de grande qualité, sans DRM et gratuitement est une chose qui, je pense, est un des grands intérêts d’écrire un tuto ou un article sur zds.

Cependant ce système n’est pas parfait, il a des bugs, et il doit encore évoluer pour être encore et toujours meilleur.

Je vous propose ici de vous décrire les problèmes connus, ce qu’on compte faire contre eux, et ce qui a déjà été fait, évidemment.

Problème 1 : les titres sont parfois mal parsés sur les PDF

Exporter au format PDF signifie deux choses de notre point de vue :

• mettre à plat votre tuto
• le parser et en tirer le PDF

pendant très très très longtemps, c’était la seconde partie qui pêchait. Allant jusqu’à masquer complètement les problèmes de la première partie. Et les titres en sont un.

Il serait vraiment bien que les validateurs et les auteurs lisent ce message car il sera important pour eux.

Le problème n’apparaissant que sur les bigs et moyens tuto, vous comprendrez que je ne parle pas ici du cas particulier des minituto et articles :

ecrire "# Introduction"
ecrire tuto.intro
pour chaque partie du tuto
   ecrire "# " + partie.titre
   ecrire décaler_les_titres_de1(partie.intro)
   pour chaque chapitre
       ecrire "## " + chapitre.titre
       ecrire décaler_les_titres_de2(chapitre.intro)
       pour  chaque section
       ecrire "### " + section.titre
       ecrire décaler_les_titre_de_3(section.texte)
       ecrire "---" // c'est une ligne de séparation
       ecrire décaler_les_titres_de2(chapitre.conclusion)
   ecrire décaler_les_titres_de1(partie.conclusion)
ecrire "---"
ecrire tuto.conclusion // à la demande des auteurs on ne met plus la conclusion sous un titre

Maitenant, imaginez qu’un auteur, pour une raison quelconque ait mis dans une section #### mon titre. Il en a le droit, l’interface le lui dit. Eh bien si vous calculs sont justes, vous êtes arrivés à la conclusion que le titre sera mis dans le fichier "à plat" ####### mon titre.

Et ça, c’est inconnu au bataillon de markdown.

Après quelques pérégrinations, j’ai compris la double cause de tout ça :

• côté UI/UX on autorise les gens à le faire, alors ils le font, il faudrait griser les boutons pour les "niveau 4" à "niveau 6" quand on est dans une section ceci sera intégré obligatoirement en v28.2
• côté historique de zds, on s’était compliqué la vie à une époque et on avait fait un truc "intelligent" qui détectait que si on était dans une section alors un titre de niveau 4 était équivalent à un titre de niveau 1. Avec l’arrivée de zmarkdown, on a arrêté ce genre de choses immaintenables (même si pour cette fonctionnalité en particulier c’était pas prévu à la base car personne ne le savait côté technique) et on a décidé d’avoir un comportement cohérent : quand on demande du html pour les sections, on dit à zmd "considère que tous les titres doivent être rendu comme des titres de rang $n + 2$ et si $n + 1 > 6$ tu mets 6. Pour le latex, comme on envoie un fichier à plat, aucun décalage n’est fait par zmd.

ALors, comment gérer ça?

• pour les validateurs, pourriez-vous regarder, quand vous validez qu’il n’y a pas de titre de niveau 4 dans les sections des big tuto (de niveau 5 dans les moyens, de niveau 6 dans les minitutos)
• pour les auteurs, pourriez-vous corriger cela?

De notre côté, que pouvons-nous faire pour vous?

1. on va éviter de vous donner des boutons qui ne marchent pas, donc on va griser les niveaux inutiles (v28.2)
2. dès aujourd’hui, vous pouvez utiliser un script qui vous explique quel titre corriger et qui vous donne le bon niveau à mettre (voir là suite)
3. dans l’avenir, nous avons un chantier pour ajouter des conseils contextuels à notre éditeur, ça serait ce genre de conseils qui vous permettrait de dire "ah là, c’est pas bon"

Parfois les codes ont des ### en trop

Je vous disais au dessus que notre ancienne technologie masquait les défauts de l’étape "mise à plat", eh bien vous venez d’en trouver un autre. Heureusement grâce à la réactivité d'@Eskimon sur le tuto arduino, cette erreur est déjà corrigée dans la v28.1 (elle sera déployée quand django 2.1 sera proprement mis et que les retours des auteurs quant aux statistiques auront été implémentés)

Il y a des parties non publiées dans le pdf

Oui, ça sera corrigé quand j’aurai réussi à comprendre pourquoi, je fais le ticket dès que possible.

Il n’y a pas de couverture dans l’epub

Oui, on a besoin d’un graphiste pour nous aider à styler la couverture de l’epub, j’irai poster une demande dans le forum graphiste dès que j’ai un peu de temps.

Parfois j’ai pas de PDF

Il y a deux causes possibles à ça :

• le publicateur a encore planté, et là il faudra attendre que côté technique on change de méthode de fonctionnement ou bien que je me connecte à la prod et que je le relance, après, ça marche du feu de dieu

• votre tuto possède des cas particuliers mal traité par notre parser markdown -> latex ou bien qui n’ont pas d’équivalent en latex, voici la liste des cas connus à ce jour :

  • une image a retourné 404 ET une page html : https://github.com/zestedesavoir/zmarkdown/issues/294
  • vous avez mis un bloc de code dans une footnote : https://github.com/zestedesavoir/zmarkdown/issues/299

pour les validateurs, pourriez-vous regarder, quand vous validez qu’il n’y a pas de titre de niveau 4 dans les sections des big tuto (de niveau 5 dans les moyens, de niveau 6 dans les minitutos)

Ce n’est pas le genre de choses qu’il est facile d’identifier en regardant comme ça. Ça concerne combien de tutos ? Je ne crois pas avoir validé quoi que ce soit d’excessivement imbriqué.

pour les auteurs, pourriez-vous corriger cela?

Si on me dit automatiquement où cela se trouve, éventuellement. L’idéal étant d’interdire complètement de le faire, comme une erreur de parsage (ou un avertissement).

Si on me dit automatiquement où cela se trouve, éventuellement. L’idéal étant d’interdire complètement de le faire, comme une erreur de parsage (ou un avertissement).

On va trouver un moyen d’en arriver là.

Pour le nombre de tutos, je saurais pas te dire. Là on a le tuto sur les réseaux de @Vince. On avait déjà bien isolé le problème sur le tuto Arduino de @Eskimon.

Un autre truc m’a interpellé quand j’ai testé l’export PDF de mon tuto : c’est la numérotation qui commence à 1 pour l’introduction. Si je parle de la "partie 2" dans mon tuto, la référence est pétée dans le PDF, car elle sera numérotée 3. C’est pas un souci technique, c’est qu’un lecteur qui lit le tuto juste en PDF pourrait ne pas avoir la bonne numérotation par rapport à la version site.

@pierre_24 y’aurait pas moyen, dans le template latex de dire que si on a \addLevelOneTitle{Introduction} ça n’incrémente pas la numérotation? je sais que ne pas incrémenter la numérotation est possible en latex, mais est-ce que ce genre de cas précis est possible?

En LaTeX "standard", on a \section*{} (par exemple) qui fait ce genre de chose, donc c’est tout à fait envisageable de vous offrir quelque chose de ce goût là. Note ceci dit que la template offre déjà des titres custom pour les intros et conclusions, et c’est vrai que j’ai jamais pensé à vérifier que vous les employiez. Donc si vous utilisiez ça, on pourrait s’adapter

(le problème, c’est qu’il faudrait que tout les sous titres n’aie pas de numéro non plus, sinon ça génère des 0.1 machin :/ )

EDIT: J’ai créé un ticket, faut que vous me disiez ce que vous voulez exactement

On peut tenter d’utiliser la commande \introduction côté zmd, en effet mais après de toute façon on ne trouvera rien de parfait.

Salut,

Pour le cas des tutos sans export PDF disponible, comment sait-on dans quel cas on se trouve ?

Parce que je viens de regarder, sur l’ensemble de mes contenus, je n’ai que 3 billets qui proposent le PDF. Alors je veux bien corriger des choses si besoin (je ne pense pas avoir de problème sur les titres cela dit), mais comment les connaître ?

Pour les billets, j’ai du retard à rattraper 99% de chances que ça soit dans le cas n°1

Pour mes tutoriels voici les problèmes que j’ai :

• Galalithe : ça sort un pdf mais les images sont cassés et les tableaux marchent pas
• Nombre d’oxydation : problème d’image cassé et bloc cassé
• Coefficient de partage : impossible de tirer un pdf

EDIT : Mais en l’état Galalithe et nombre d’oxydation ne sont pas exportables, problème de taille d’image, GIF qu’il faudrait changer. On en a discuté avec Pierre je pense qu’il saura vous retransmettre mon idée pour les gif dans un PDF.

Disons que les deux premiers PDFs sont legacy (et devraient être régénérés). Cette couverture en bleu plus clair, ça ne trompe pas

Et pour ce qui est des articles / tutos ?

En fait je fais au fur et à mesure (j’ai 300 contenus de retard, 90% sont des billets, puisque dès que je repère un article/tuto, je le mets de suite).

Si tu as des tutos non exportés, donne-moi la liste, je fais ça ce soir.

Comme je disais c’est le cas de l’ensemble de mes contenus publiés.

• Donc en tutoriels : La POO en Python, Le guide du contributeur et Notions de Python avancées.
• En articles : T-shirts pour ZdS, Les secrets d’un code pythonique, Retour sur la PyConFR 2017 et Sortie de Python 3.6.

Est-ce que, dans un big tuto, on peut faire un lien vers un chapitre ou une section spécifique, et que ça se traduise par un lien vers une ancre (pas sûr du terme) du PDF lors de l’export ?

Même question pour faire un lien interne au tuto quand un chapitre n’est pas encore publié.

Pour les introductions et conclusions on a aussi des problèmes du côté latex-template ; pour le moment, on n’en a qu’un seul niveau. @pierre_24 a ouvert une issue, pour proposer l’ajout d’un environnement dédié aux introductions.

PS : en fait, non, on a bien ce qu’il faut, j’avais zappé qu’on avait bien les différents niveaux d’introduction et de conclusion.

(le problème, c’est qu’il faudrait que tout les sous titres n’aie pas de numéro non plus, sinon ça génère des 0.1 machin :/ )

Un \setcounter{secnumdepth}{0} avant l’introduction et ensuite un \setcounter{secnumdepth}{8} à la fin pour remettre la numérotation comme on veut devrait suffire ?

\documentclass[fontisze=12, french]{scrartcl}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}

\begin{document}
   \tableofcontents
   \setcounter{secnumdepth}{0}
   \section{Introduction}
      \subsection{Sous-intro}
      \subsection{Autre sous-intro}
   
   \setcounter{secnumdepth}{7}
   \section{Section}
      \subsection{Sous-section}
      \subsection{Autre sous-section}
\end{document}

Je me permet de signaler les bugs que j’ai trouvé sur mes articles qui ont des pdfs (côté tuto, 0 pdf sur 4 tutos ) :

• les gif affichent une image noir là. À défaut de gérer l’animation, mettre la première image serait un plus ;
• les abréviations ne sont pas gérées là, page 7 ;
• certaines images débordent en hauteur là, page 8 ou en largeur ;
• certaines images mangent le texte là, page 13 ;
• les petites figures ont leur légende à côté plutôt que en dessous là, page 17 ;
• les blocs secrets sont très mal gérés là, page 25.

Je crois que votre parseur n’apprécie pas les contenus trop pleins d’images…

Merci beaucoup pour ça ; l’export pdf est un gros plus qui manquait !

pour @entwanne

• guide du contributeur OK
• notions avancées de python OK
• tshirts pour zds ok

tout le reste ce sont des contenus qui sont trop vieux pour avoir connu la v27 et trop récent pour avoir eu la génération cassé en mode pandoc. Je ferai une passe ce soir car tu n’es pas le seul à demander ce genre de contenus

@blackline j’ai tenté de régénérer "les coeficients de partage". Pour les autres c’est la même chose qu’avec entwanne. Pour "les coeficients de partage, on passe en MP pour que les consultant en latex (@pierre_24 et @karnaj, la casse est choisie à dessein) puissent dire ce qui ne va pas.

Ok, merci beaucoup !

Pour @gabbro

• embryogénèse : pour une raison inexpliquée je ne peux régénérer ni l’epub ni le pdf, le pdf était trop vieux
• philae : pdf de l’époque de pandoc, régénéré, epub généré, je te laisse jeter un nouveau coup d’oeil.

@artragis : philae ii est tout bon, philae iii a les mêmes problèmes, je suppose que tu n’as régénéré que le 2.

Encore merci, c’est du super boulot !