Experts LaTeX, Zeste de Savoir à besoin de vous

Bonjour à tous,

Ce message s’adresse principalement aux bon connaisseurs de $\LaTeX$ : l’équipe de développement a besoin de vous !

Contexte

Nous travaillons actuellement sur la refonte de l’outils qui gère la partie MarkDown -> autres formats et nous souhaitons refaire le template actuel LaTeX. Nous utilisons celui de base de Pandoc or cet outil sera remplacé dans le futur. Nous cherchons donc quelques personnes pour nous aider dans la réalisation de macros pour chaque élément spécifique à ZdS.

Si vous avez des questions et/ou si vous êtes intéressés, n’hésitez pas à passer sur IRC ou à laisser un message par ici

Les éléments à faire

Ensemble des éléments classiques

• Gras
• Italique
• Barré
• Abbréviation
• Indice_X
• Exposant²
• Emojis
• liens

Texte aligné à gauche

• Listes
• Liste numérotées

Titres

de

toutes

tailles

Touche

Touche a

Code

aaa

1
2

def foo(bar):
    return 42

Citation

Bloc information

Bloc question

Bloc attention

Bloc erreur

Bloc secret

Tableaux

Images / Vidéos

Plus d’informations : https://zestedesavoir.com/tutoriels/249/rediger-sur-zds/

Qui dit PDF dit (peut-être ?) impression. Quelques éléments à prendre en compte :

• Pour les liens, faire un truc où on voit l’URL (note de bas de page, ou mon lien (http://perdu.com))
• pour le spoiler, faire un bloc déplié par défaut (on peut pas déplié sur papier :/) ;
• pour la vidéo, mettre l’adresse de la vidéo ;

Je pense que, à part les blocs et la vidéo, la plupart est en natif. Après, pour les blocs, on peut créer des commandes spécifiques.

Quelques tutoriels sur LaTeX.

L’important c’est que tous les éléments du zmarkdown aient une correspondance latex, et qu’un rendu PDF de ce latex soit agréable à lire et visuellement potable.

Merci d’avance !

Mes quelques remarques:

• MathJax part avec une liste surprenante de packages qu’il ne faut pas oublier de charger. Peu importe le gestionnaire d’équation, cette remarque est générale.
• Faut pas oublier d’échapper certains caractères, par exemple le backslash, les dollars et ainsi de suite, mais aussi penser à gérer l’unicode proprement (non, le support UTF-8 de LaTeX ne suffit pas)
• Le placement des tableaux et image en HTML est à l’encontre de la philosphie LaTeX du "mettre le flottant là ou il y a de la place". Comme on utilise pas d’appels de flottants ("voir table XYZ"), faut pas qu’on utilise les flottants, mais faut être gentil avec LaTeX quand on lui explique
• Les tableaux vont pas être marrant à gérer (y’a la solution du minipage, mais on est loin des tableaux dont la taille s’ajuste au contenu). Probablement le plus gros chantier. Ce sans parler de la gestion des multicolonnes et mulilignes dans les tableaux, tant que j’y pense.
• Les maths seront aussi un peu surprenante parce que en "vrai" LaTeX, $$\begin{align}...\end{align}$$ n’est pas permis (align est déjà un environnement mathématique en lui-même). À ce sujet, MathJaX (ou autre) laisse passer les erreurs (en n’interprétant rien du tout), alors que LaTeX ne se laisse pas faire.
• UN gros +1 pour les remarques de qwerty sur les liens
• Le générateur actuel pour passer à un fichier markdown unique à la publication est relativement mauvais comme base pour générer du LaTex. Il faudrait faire un minimum de différence entre un article/mini-tuto (pour lequel c’est la classe de document article qui colle, avec des \section{}) et les autres (pour lesquels on peut utiliser \chapter{} et \part{}).

On ne se sert pas de mathjax donc ne vous souciez pas de ça.

La remarque vaut pour n’importe quel gestionnaire d’équation. Je parle de MathJaX parce que c’est l’actuel, mais ça vaut pour KaTeX (sauf que la liste des trucs supportés est moindre, donc la liste des packages réduit, mais c’est pas non plus du LaTeX vanilla, si vous me passez l’expression). Pareil, KaTeX ne va pas bloquer l’affichage de la page si le code mathématique est mauvais, alors que c’est typiquement le genre de chose que LaTeX aime faire

EDIT: bon, je vais pas trop râler parce que je suis probablement le seul à l’utiliser, mais on va perdre le support de mhchem (rajoutée ici et probablement la fonctionnalité dont je me sert le plus), si on change d’interpréteur. Oubliez ça, y’a un possible support <3

Ça me semble quand même pas l’endroit pour en discuter. Oui la compilation du latex peut planter plus aisément que notre compilation de l’ast markdown.

Le sujet, ici, c’est qu’on a besoin d’un template latex pour nos contenus, agréable à la lecture PDF, et avec le support de toutes les fantasies zmarkdown actuelles.

Juste pour être sûr, ce que vous voulez, c’est une table de correspondance du genre

avec, bien évidemment, les cas complexes ?

Bien entendu, mais pas besoin de me répondre un "ce n’est pas le sujet". Je serais heureux de reposter mes différentes remarques à l’endroit nécessaire (sur GH, j’imagine), parce que je pense qu’elles sont pertinentes: en gros, ce que je dis, c’est qu’un template LaTeX ne suffira sûrement pas, et qu’il faudra un minimum de traitement de l’AST. Ce traitement conditionne les macros qui doivent être écrites et comment elle doivent être écrites (et permet d’ailleurs de se débarrasser de situations pour lesquelles les macros ne peuvent rien, comme le align dans $$, et autres).

Au delà de ça, je suis tout à fait disponible pour écrire ces macros en question, count me in !

Non.

On a besoin d’un template contenant tous les éléments du zmarkdown, qu’on pourra ensuite utiliser pour générer des documents.

Par exemple, un document class "tuto" et un exemple (un kitchensink) utilisant les éléments de syntaxe exposés par le document class.

Il faut que ce soit–comme je le disais–lisible. Le but est de faire des PDFs pour la lecture des contenus offline, et éventuellement pour l’impression.

Par exemple, un document class "tuto" et un exemple (un kitchensink) utilisant les éléments de syntaxe exposés par le document class.

Ça prendrais quelle forme, en pratique ? Parce que Gabbro n’as pas tord, en fait, la plupart des conversions sont assez évidentes. On peut toujours faire des \newcommand{\zMTextInBold}{\textbf}, mais c’est un peu idiot, non ?

(et au risque d’être pénible, je répète que cette astuce ne fonctionne pas pour les tableaux)

C’est la partie qui m’inquiète le moins: LaTeX peut faire des trucs très lisibles, c’est même pour ça qu’il a été conçu. Et il existe des packages très bien pour faire des rendus relativement propres et "pour l’impression" (loin de cet aspect "par défaut" qu’offre LaTeX). L’idéal, ce sera de s’inspirer dont la manière dont Sphinx s’en sort, en fait

Par exemple, un document class "tuto" et un exemple (un kitchensink) utilisant les éléments de syntaxe exposés par le document class.

Ça prendrais quelle forme, en pratique ?

La forme d’un document latex normal.

Parce que Gabbro n’as pas tord, en fait, la plupart des conversions sont assez évidentes. On peut toujours faire des \newcommand{\zMTextInBold}{\textbf}, mais c’est un peu idiot, non ?

Je ne propose pas de redéfinir les trucs de base, non non. Je ne dis pas que Gabbro a tort dans les équivalences qu’il propose. Gabbro a demandé si ce dont on avait besoin était ce tableau d’équivalence, et la réponse est non. On a besoin d’un genre de feuille de style (genre un document class), et on a besoin de document latex utilisant cette feuille de style et utilisant tous les éléments du zmarkdown.

(et au risque d’être pénible, je répète que cette astuce ne fonctionne pas pour les tableaux)

D’accord, pas grave. C’est pas tout ou rien, de mon point de vue. Ça peut être un travail collaboratif tendant vers une solution complète pas à pas. Si les tableaux bloquent, pas grave, attaquez le reste. Quand il ne manquera plus que les tableaux, on avisera.

Volontiers !

Je créé un repo sur zestedesavoir pour ce projet ?

J’ai quelques questions (j’ai déjà une classe que j’utilise pour faire les PDF de mes tutoriels et que je peux adapter pour avoir le résultat voulu, pour le moment elle donne ça.

Pour les images, tableaux et blocs de code qu’est-ce qui est attendu comme rendu, des flottants que LaTeX place comme il veut où des images fixes, placées exactement à la place demandée ?

Pour les tableaux et les blocs de code, on accepte qu’ils soient coupés au milieu d’une page et continuent sur la suivante ou pas ?

Ce sont en gros les points qui posent le plus de soucis avec les bloc attention, spoiler, etc. Sinon, la majorité des éléments à faire se gèrent bien.

J’ai eu beau lire ta réponse plusieurs fois, je ne vois vraiment pas ce que tu veux faire, victor. Si tu as italique(texte) dans ton AST, tu fera *texte* en markdown, \textit{texte} en latex et je-ne-sais-pas-quoi en HTML. Je ne vois pas en quoi tu as besoin de plus.

Pour les cas complexe, OK, on peut définir un truc du genre newcommand{\info}[1]{\parbox{etc}}, mais ça reste une simple correspondance AST (bloc info) <-> [[information]] <-> \parbox{etc} <-> idem HTML. Ce n’est même pas obligé, puisque le Latex n’a pas vocation à priori à être lu (rien n’empêche de générer des doublon dans le fichier latex).

Soit je passe à côté d’un truc, soit il suffit de donner la correspondance AST - Latex au parseur, pas besoin d’une classe ou d’un fichier latex.

J’ai quelques questions (j’ai déjà une classe que j’utilise pour faire les PDF de mes tutoriels et que je peux adapter pour avoir le résultat voulu, pour le moment elle donne ça.

Oooh c’est super ça Karnaj ! La classe ! Tu peux montrer à quoi ressemble la classe, et comment tu l’utilises ? Idéalement avec un doc utilisant la classe, et démontrant vite fait les principaux éléments du zmarkdown ?

Pour les images, tableaux et blocs de code qu’est-ce qui est attendu comme rendu, des flottants que LaTeX place comme il veut où des images fixes, placées exactement à la place demandée ?

Pour les tableaux et les blocs de code, on accepte qu’ils soient coupés au milieu d’une page et continuent sur la suivante ou pas ?

J’ai pas d’avis sur ces questions. Il faudra tôt ou tard que quelqu’un tranche, mais c’est pas des décisions qui m’appartiennent ni un débat auquel j’aimerais participer.

Je l’ai dit plusieurs fois : une classe et un document montrant tous les éléments utilisés, et le PDF qui en résulte.

Et moi je t’ai dit plusieurs fois que je ne comprenais pas. Ce n’est pas en répétant la même chose que je vais mieux comprendre.

J’ai quelques questions (j’ai déjà une classe que j’utilise pour faire les PDF de mes tutoriels et que je peux adapter pour avoir le résultat voulu, pour le moment elle donne ça.

J’aime BEAUCOUP ce que ça donne, en particulier le rendu de tes blocs questions/…

Pour les images, tableaux et blocs de code qu’est-ce qui est attendu comme rendu, des flottants que LaTeX place comme il veut où des images fixes, placées exactement à la place demandée ?

Deuxième version. Parce que justement, il arrive souvent qu’on écrive dans un tuto "comme vous pouvez le voir dans le tableau ci-dessous:", ce qui ne fonctionne pas si on utilise des flottants.

Pour les tableaux et les blocs de code, on accepte qu’ils soient coupés au milieu d’une page et continuent sur la suivante ou pas ?

Vu le point précédent, pas trop le choix. T’utilise quoi pour le rendu de code, btw ?

Je suis d’accord avec toi. Éventuellement, je pense que quand victor d’un fichier LaTeX, il veut que dans ce template de base, il y aie les \newcommand et les différents packages. Comme ça, plus qu’à faire

1
2
3
4

\documentclass[big]{zMTuto}
\begin{document}
%% la suite
\end{document}

Mais j’avoue que c’est pas hyper-clair ce qu’il entend par "style" (bon, ça vient probablement du fait que j’ai pas été lire le code du parseur avant)

Volontier !

Je vais tenter à nouveau. Quand je parle d’un document class, et je présume quand Karnaj parle d’une classe, ou quand je parle de feuille de style, c’est comme vient de le dire pierre : \documentclass[big]{zMTuto}. Dedans sont définies les macros et commandes et autres. Ça expose des choses comme toutes classes latex : des chapitres si ce format permet d’avoir des chapitres, etc.

Ensuite, il faut comprendre que ce document class n’est pas un document latex, il ne contient pas le texte d’un tuto par exemple. Du coup il nous faut un document latex utilisant cette classe. Ce document latex devrait utiliser tous les éléments du zmarkdown, comme ça on peut se rendre compte de ce que ça donne.

Est-ce que c’est plus clair Gabbro ? Quelle partie ne comprends-tu pas ?

Si vous voulez voir l’AST actuel (et pas définitif), vous pouvez le générer ici : https://zestedesavoir.github.io/zmarkdown/public/ (Cadrant en haut à gauche : entrez du zmarkdown, cadrant en bas à gauche : l’AST.)

@pierre : https://github.com/zestedesavoir/latex-template Tu es l’admin du repo, hésite pas à donner write access à qui peut contribuer.

Oooh c’est super ça Karnaj ! La classe ! Tu peux montrer à quoi ressemble la classe, et comment tu l’utilises ? Idéalement avec un doc utilisant la classe, et démontrant vite fait les principaux éléments du zmarkdown ?

Je montre tout ça demain, avec un fichier de test qui utilise tous les éléments du zmarkdown. Mais mis à part les chargements de package, voici en gros les éléments qui font le travail.

 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
31
32
33
34
35
36
37
38
39
40
41
42
43

\newcommand{\newZdSbox}[3]{{
\theoremprework{~\\ \textcolor{#3}{\rule{0.6\linewidth}{1pt}}}
\theorempostwork{\hfill \textcolor{#3}{\rule{0.6\linewidth}{1pt}} \\}
\theoremheaderfont{\scshape}
\theoremseparator{ ---}
\theoremstyle{break}
\theorembodyfont{\normalfont}
\newtheorem*{#1}{\textcolor{#3}{#2}}
}}

\newZdSbox{Info}{Information}{SkyBlue}
\newZdSbox{Ques}{Question}{Orchid}
\newZdSbox{Err}{Erreur}{RedOrange}
\newZdSbox{Atten}{Attention}{Apricot}

\newenvironment{Attention}{\begin{minipage}{\linewidth}\begin{Atten}}{\end{Atten}\end{minipage}}
\newenvironment{Question}{\begin{minipage}{\linewidth}\begin{Ques}}{\end{Ques}\end{minipage}}
\newenvironment{Information}{\begin{minipage}{\linewidth}\begin{Info}}{\end{Info}\end{minipage}}
\newenvironment{Erreur}{\begin{minipage}{\linewidth}\begin{Err}}{\end{Err}\end{minipage}}


\definecolor{sectionfontcolor}{HTML}{EA9408}

\addtokomafont{chapter}{\color{sectionfontcolor}}
\addtokomafont{section}{\color{sectionfontcolor}}
\addtokomafont{subsection}{\color{sectionfontcolor}}
\addtokomafont{subsubsection}{\color{sectionfontcolor}}

\newcommand{\licence}[1]{\def\@licence{#1}}
\newcommand{\logo}[1]{\def\@logo{#1}}


\renewcommand{\maketitle}{%
    {\centering
    \vspace*{0.5 cm}
    \ifcsdef{@logo}{\includegraphics[width=0.6\linewidth]{\@logo}}{Pas de logo}\\[1.0 cm]
    \LARGE \href{https://zestedesavoir.com/membres/voir/@author/}{\bsc{\@author}}\\[2.0 cm]
    \Large \href{https://zestedesavoir.com}{Zeste de Savoir}\\[0.5 cm] 
    \rule{\linewidth}{0.2 mm} \\[0.4 cm]
    \huge\textbf{\@title}\\
    \rule{\linewidth}{0.2 mm} \\[1.5 cm]  
   \large\textbf{Ce tutoriel est sous licence \@licence}\\[2 cm]}
}

Deuxième version. Parce que justement, il arrive souvent qu’on écrive dans un tuto "comme vous pouvez le voir dans le tableau ci-dessous:", ce qui ne fonctionne pas si on utilise des flottants.

C’est ce que je fais (avec le package caption s’il y a des légendes). Ça pose problème pour certaines images, mais sinon ça passe bien.

T’utilise quoi pour le rendu de code, btw ?

J’utilisais listings, je suis passé à minted. Ça fait un module Pyhton de plus (Pygments) à utiliser, mais le résultat en vaut la peine.

Sinon, je comprends pas trop le débat pour la classe, en avoir une serait un un gros plus selon moi (et peut-être plusieurs, s’il doit y avoir des différences entre article, Big tuto, mini tuto, …).

Merci victor, je vais regarder ce soir ce qu’on peut faire pour vous simplifier la vie, probablement sur base de ce que Karnaj a déjà fait et dont je suis assez fan. Faut aussi que je vois deux minutes comment fonctionne exactement le parseur actuel sur le principe (pasque si, la table de correspondance peut aider pour les gens qui ont jamais fait de LaTeX).

C’est ce que je fais (avec le package caption s’il y a des légendes). Ça pose problème pour certaines images, mais sinon ça passe bien.

Ben c’est ce qu’il faudra probablement faire: créer un environnement zMdImage qui fait le taff à ce niveau là

J’utilisais listings, je suis passé à minted. Ça fait un module Pyhton de plus (Pygments) à utiliser, mais le résultat en vaut la peine.

M’en doutais. Je ne peux que grandement saluer ce choix, et d’ailleurs on utilisais déjà pygments jusqu’ici. Le problème, c’est que je ne sais pas encore quelle solution va être reprise par le nouveau parseur, et je les vois déjà grimacer d’ici si on leur propose une dépendance python

Sinon, je comprends pas trop le débat pour la classe, en avoir une serait un un gros plus selon moi (et peut-être plusieurs, s’il doit y avoir des différences entre article, Big tuto, mini tuto, …).

Comme je disais plus haut, pour moi un article/mini-tuto correspond à la classe de document article alors qu’on serait plus sur report (ou book) dans le cas d’un moyen/grand tuto. Donc idéalement, faudrait un truc du genre:

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

%% if mini
\newcommand{\zMdTitleLevel1}{\section}
\newcommand{\zMdTitleLevel2}{\subsection}
% ...

%% if middle
\newcommand{\zMdTitleLevel1}{\chapter}
\newcommand{\zMdTitleLevel2}{\section}
% ...

%% if big
\newcommand{\zMdTitleLevel1}{\part}
\newcommand{\zMdTitleLevel2}{\chapter}
% ...

Je le mettrais plutôt genre en fin de chapitre ou un truc comme ça. Les blocs spoilers pourraient être utilisés pour donner les réponses à un exercice, ou insérer du contenu sans surcharger visuellement la page.

Et sinon, une réflexion en l’air comme ça : est-ce que ça serait pas utile de pouvoir définir quelques options lors de l’export du tuto en PDF, comme par exemple :

• format A4 ou A5;
• définir si c’est pour impression (style avec moins de couleurs, fond blanc, etc) ou juste pour lire hors ligne (la plus agréable à lire);
• etc.

Edit : Et je trouve la démo zMarkdown vraiment ultra chouette.