Tutoriel : produire sa propre structure de livre (nouvelle version)

Les différent élèments de l’API

-  Le plugin latexwheel propose des règles de transformation des raccourcis SPIP en code LaTeX. Il se base sur TextWheel.
-  Le plugin Zippeur et ses fonctionnalité de la version 2.

Cet article se veut un tutoriel visant à montrer comment se servir de ces deux plugins pour créer sa propre structure de liste avec SPIP.

Deux articles plus détaillés donnent les détails de l’API.

Exemple de la structure prise

La structure sera simple : il s’agira dans un livre de regrouper tout les articles d’une rubrique. Par exemple, la rubrique éditoriale, en les classant par ordre chronologique, en mettant à chaque fois le titre, suivi de la date, du chapo, du corps du texte, puis de la signature des auteurs.

Organisation finale de notre Zip

Il est possible en LaTeX de diviser un projet en plusieurs fichiers .tex, un peu comme on ferait en SPIP avec des squelettes inclus, via <INCLURE> ou #INCLURE.

Dans cette logique, le but est que SPIP produise un fichier livre.tex, qui appelle lui-même des des fichiers inclure/articlexxx.html correspondant à chaque article. L’ensemble de ces fichiers étant regroupés dans un fichier .zip.

Pour les besoins de l’exercice, nous nous servirons de la base de donnée sqlite jointe [1]. L’identifiant pour se connecter est auteur et le mot de passe est demodemo.

Nous supposerons qu’il n’y a ni images dans nos articles, ni code informatique, ni liens. L’article détaillé sur l’API fournit les outils pour les intégrer le cas échéant.

Pour éviter tout ennui de cache, désactivez le en mettant la ligne suivante dans le fichier mes_options.php :

define('_NO_CACHE',-1);

Étape 1 : le fichier parent

Créons un squelette livre.tex.html, en y mettant le contenu suivant :

#HTTP_HEADER{content-type:application/x-latex}
\documentclass[a4paper,12pt]{book}
\begin{document}
<BOUCLE_articles(ARTICLES){id_rubrique}{!par date}>
\input{inclus/article#ID_ARTICLE}
</BOUCLE_articles>
\end{document}

Analysons le code :

• ligne 1, la balise #HTTP_HEADER permet, dans notre cas, deux choses :
  1. de dire au navigateur qu’on produit du latex et pas du html.
  2. d’empêcher SPIP d’insérer les boutons d’administrations.
• ligne 2, nous déclarons la classe de notre fichier .tex. Pour rappel, un fichier latex doit toujours commencer par une déclaration de classe. Ici nous disons que nous produisons un livre, sur du papier A4, avec une police de base de 12 pt.
• ligne 3, nous commençons le corps du document.
• ligne 4, une Boucle classique de SPIP : on demande les articles de la rubrique passée en argument lors de l’appel au squelette, classés par ordre antéchronologique.
• ligne 5, pour chaque article, nous insérons le code \input{inclus/articlexxx} qui permettra à LaTeX d’appeler le fichier inclus/articlexxx.tex.
• ligne 6, fin de la boucle.
• ligne 7, fin du corps du document LaTeX.
• Maintenant, rendons-nous sur http://votresite.dev/?page=livre.tex&id_rubrique=1. Notre navigateur va nous télécharger un fichier contenant les lignes suivantes :

\documentclass[a4paper,12pt]{book}
\begin{document}
 
\input{inclus/article1}
 
\input{inclus/article2}
 
\end{document}

C’est bien, mais il serait bon d’avoir un préambule appelant les packages nécéssaires. Ces packages peuvent varier en fonction du contenu des articles, si par exemple on a des images, du code, des tableaux. Mais tout cela est sera détaillé dans l’article sur l’API LaTeXWheels.

Pour le moment, contentons nous des packages minimums.

Il nous faut :
-  fontspec et xunicode pour gérer correctement l’UTF-8.
-  polyglossia, pour gérer les langues.

Insérons donc entre le \documentclass[a4paper,12pt]{book} et le \begin{document} l’appel à ces packages :

\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}

Et puis, précisons quand même la langue, avec le code suivant :

\setmainlanguage{[(#LANG|lang_polyglossia)]}

Alors là, on a un mélange de LaTeX, la commande \setmainlanguage qui permet de dire à polyglossia qu’elle est la langue principale, et donc de gérer correctement les césures et la ponctuation, et le code [(#LANG|lang_polyglossia)], qui prend le code de la langue courante, en l’occurence fr et le transforme en code compréhensible par polyglossia, à savoir french, par le biais du filtre |lang_polyglossia.

Tout ceci donne donc :

#HTTP_HEADER{content-type:application/x-latex}
\documentclass[a4paper,12pt]{book}
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}
\setmainlanguage{[(#LANG|lang_polyglossia)]}
\begin{document}
<BOUCLE_articles(ARTICLES){id_rubrique}{!par date}>
\input{inclus/article#ID_ARTICLE}
</BOUCLE_articles>
\end{document}

Ce qui une fois interprété par SPIP, produit :

\documentclass[a4paper,12pt]{book}
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}
\setmainlanguage{french}
\begin{document}
 
\input{inclus/article2}
 
\input{inclus/article1}
 
\end{document}

Et puis soyions fous, ajoutons une table des matières, à la fin, avec la commande \tableofcontents :

#HTTP_HEADER{content-type:application/x-latex}
\documentclass[a4paper,12pt]{book}
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}
\setmainlanguage{[(#LANG|lang_polyglossia)]}
\begin{document}

<BOUCLE_articles(ARTICLES){id_rubrique}{!par date}>
\input{inclus/article#ID_ARTICLE}
</BOUCLE_articles>

\tableofcontents
\end{document}

Étape 2, les fichiers fils

Préparons le squelette qui va engendrer les fichiers inclus/articlexxx.tex. Appelons ce squelette article.tex.

#HTTP_HEADER{content-type:application/x-latex}
<BOUCLE_article(ARTICLES){id_article}>
\chapter{[(#TITRE*|propre_latex)]}
 
[(#DATE|affdate|propre_latex)]
 
[(#CHAPO*|propre_latex)]
 
[(#TEXTE*|propre_latex)]
 
<B_auteurs><BOUCLE_auteurs(AUTEURS){id_article}{","}>[(#NOM*|propre_latex)</BOUCLE_auteurs></B_auteurs>
</BOUCLE_article>

Analysons :

• Ligne 1, le même #HTTP_HEADER que précédemment, vu que je veux à nouveau produire un fichier .tex
• Ligne 2 et 12, boucle ARTICLES classique.
• Ligne 3, mettre le titre dans la commande LaTeX \chapter{}.
• Ligne 5, mettre la date.
• Ligne 7, mettre le chapeau.
• Ligne 9, mettre le texte.
• Ligne 11, mettre les auteurs.

On remarque les lignes vides : rappelons qu’en LaTeX, les lignes vides produisent des changements de paragraphes.

Toutes les balises SPIP qui retournent du texte sont présentés de la manière suivante :
[(#BALISE*|propre_latex)]

Rappelons une règle de fonctionnement de SPIP : le contenu de chaque champ de type texte est filtré automatiquement par le filtre |propre, qui transforme les raccourcis SPIP en code HTML.

En revanche, si on écrit #BALISE*, |propre n’est pas appelé : on obtient alors le contenu du champ, de manière brute [2].

C’est ce contenu brut qui est passé dans le filtre |propre_latex du plugin latexwheel. Ce filtre transforme les raccourcis SPIP en code LaTeX.

Au final, si je me rend sur la page http://site/?page=article.tex&id_article=1, j’obtiens :

\chapter{De l'influence de LaTeX sur la sexualité humaine}

28 décembre 2011

Si selon le mot, peut-être apocryphe, de Freud, « tout est sexe », alors LaTeX a une influence sur la sexualité humaine. Qu'en est-il ?




On pourrait montrer trois influences de LaTeX en matière de sexualité humaine :

\begin{enumerate}
\item  En tant que le LaTeX est généralement le principal composant des préservatifs.
\item  Dans certaines pratiques sexuelles avec certains vêtements.
\item  Dans la constitution de groupes d'utilisateurs de LaTeX, pouvant constituer des lieux de rencontres.
\end{enumerate}



Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

auteur

Étape 3 : générer automatiquement les fichiers .tex fils

L’étape suivante consiste à dire au squelette livre.tex.html de générer automatiquement, lorsqu’il est appelé, les fichiers .tex fils, comme article1.tex et article2.tex.

Pour ce faire, on utilise le filtre |zippeur_creer_fichier du plugin zippeur.

Ce filtre s’applique sur le nom du squelette à interpréter, sans le .html final. Il reçoit comme premier argument le chemin du fichier à produire, à l’intérieur du dossier local, et comme second argument un tableau d’arguments à passer lors de l’appel au squelette.

Dans notre cas, nous souhaitons interpréter le squelette article.tex.html, pour produire un fichier inclus/articlexxx.tex, en passant à chaque fois au squelette l’id_article nous intéressant.

Nous allons donc insérer dans le fichier livre.tex.html, après \input{inclus/article#ID_ARTICLE} la ligne suivante :

[(#VAL{article.tex}|zippeur_creer_fichier{ziptex/inclus/article#ID_ARTICLE.tex,#ARRAY{id_article,#ID_ARTICLE}})]

Au final, :

#HTTP_HEADER{content-type:application/x-latex}
\documentclass[a4paper,12pt]{book}
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{polyglossia}
\setmainlanguage{[(#LANG|lang_polyglossia)]}
\begin{document}
<BOUCLE_articles(ARTICLES){id_rubrique}{!par date}>
\input{inclus/article#ID_ARTICLE}
[(#VAL{article.tex}|zippeur_creer_fichier{ziptex/inclus/article#ID_ARTICLE.tex,#ARRAY{id_article,#ID_ARTICLE}})]
</BOUCLE_articles>
\tableofcontents
\end{document}

Désormais, en allant sur http://site.com/?page=livre&id_rubrique=1, non seulement SPIP nous retourne un fichier LaTeX, mais en plus il produit les fichiers inclus/article1.tex et inclus/article2.tex dans le dossier local/ziptex.

Étape 4 Fabriquer un zip contenant tout les fichiers .tex

Il va maintenant falloir produire un zip contenant tout les .tex nécéssaires à la production du livre.

Pour ce faire, nous allons créer un squelette livre.html, qui nous retournera l’adresse du Zip.

Pour que ce zip soit généré, on va appeler le filtre zippeur_dynamique.

Ce filtre zippe s’applique sur le nom du zip à produire, sans l’extension .zip.

Il reçoit comme premier argument une date, qui est utilisée pour éviter de calculer plusieurs fois un zip (cf. la documentation de base de Zippeur.). Si cet argument est vide, comme ici, la date de calcul du squelette est utilisée.

Le second argument correspond à la méthode de zippage. S’il est vide, la méthode définie par la configuration du plugin est utilisée.

Le troisième argument est un tableau contenant la liste des squelettes à interpréter, ici nous n’en avons qu’un seul. Chaque squelette est défini par un tableau à trois entrées :

• chemin du squelette au sens SPIP, sans l’extension html. Ici squelette
• chemin du fichier calculé, à l’intérieur du Zip, avec l’extension. Ici squelette1.
• paramètres d’environnement passés au squelette, sous forme de tableau. Ici un seul paramètre : id_article, égale à 1.

Dans notre cas, ce troisième argument contiendra un tableau à une entrée, correspondant à la transformation du squelette livre.tex.html en fichier livre.tex. On passera la rubrique courante comme argument.

On pourrait avoir un quatrième argument, pour d’éventuelle fichiers à inclure sans les calculer à partir d’un squelette. Ce n’est pas le cas ici.

Au final, on obtient on obtient dans livre.html :

<a href="[(#VAL{ziptex}|zippeur_dynamique{'','',#ARRAY{0,#ARRAY{0,livre.tex,1,livre.tex,2,#ARRAY{id_rubrique,#ID_RUBRIQUE}}}})]">Le zip</a>

Si je me rend sur http://site.com/?page=livre&id_rubrique=1, j’obtiens un liens vers le zip contenant les fichiers .tex.

Si on compile deux fois ce fichier, avec XeLaTeX, on obtient alors le PDF joint.

Conclusion

Cet article vous présente les base pour transformer du SPIP en LaTeX. Vous pouvez trouver ci joint le squelette complet de ce tutoriel.

Il faut ensuite évidemment connaître LaTeX pour gérer la présentation. En outre, si nos textes sont plus complexes (liens, code, etc.) il faut appeler d’autres packages, ajouter des codes.

On se reportera aux deux articles de références :

• Référence de LaTeXWheel
• Zipper des fichiers produits par des squelettes