Utiliser le squelette « Documentation » pour rédiger un livre

La manière la plus simple pour se lancer dans le projet « un livre avec SPIP » est d’utiliser le squelette documentation pour SPIP 3.

Ce squelette est celui utilisé par le site de Marcimat Programmer avec SPIP, mais porté sur SPIP 3.

Dans cet article, j’explique comment installer et l’utiliser de manière à optimiser l’export en .tex.

Installation

Le squelette est distribué sous forme de plugin. Il s’installe comme n’importe quel plugin.

Toutefois il nécessite au minimum SPIP 3.

En outre il a besoin des plugins :
-  ZPIP 1.7.x
-  Critères precedent et suivant
-  Saisie
-  Champ extra 3

Utilisation

Arborescence

Puisque le but est d’utiliser le squelette pour ensuite fabriquer un .tex pour l’impression, il est bon de savoir comment est organisé la hiérachie des titres dans un fichier LaTeX.
Par défaut, tout les titres sont numérotés automatiquement. Voici les différents niveaux de titre, du plus important au plus faible.

Nom de titreCode LaTeXSpécificité lors de la conversion en PDF
Partie \part Le titre est sur une page de droite dédiée.
Chapitre \chapter Un chapitre commence en haut de page, sur une page de droite.
Section \section Une section provoque un changement de paragraphe.
Sous-section \subsection Une sous-section provoque un changement de paragraphe

Il existe également les niveaux \subsubsection, \paragraph et \subparagraph, mais ces nivaux ne sont pas utilisés lors de la génération des fichiers .tex par SPIP.

À ces niveaux de titre LaTeX correspondent des nivaux dans la hiérachie des rubriques.

-  Le premier niveau (secteur) correspond à un livre entier. Un secteur correspondant à une langue.
-  Le second niveau correspond à un partie au sens LaTeX (\part). Exemple de rubrique de niveau \part : http://programmer.spip.org/-Ecriture-des-squelettes-.
-  Le troisième niveau correspond à un chapitre au sens LaTeX (\chapter) http://programmer.spip.org/-Les-boucles-.
-  Un article correspond à une section au sens LaTeX (\section) http://programmer.spip.org/Syntaxe-des-boucles.
-  Les raccourcis {{{…}}} provoquent des sous-sections. (\subsection).

Contenu des articles
En plus du classique champs titre et texte, chaque article peut avoir un exemple, un exercice et une réponse à l’exercice. Le champ PS est également utilisé.

Lors de l’export en .tex, les trois champs supplémentaires (exemple, exercice, réponse) seront encadrés d’un code signalant qu’il faudra les mettre dans un cadre gris dans le PDF final.

Les champs exemple, exercice, réponse et PS seront précédés d’intertitres.

Ordre des rubriques / articles

Il est possible de ne pas écrire les rubriques / articles dans leur ordre logiques. Pour déterminer l’ordre des rubriques / articles, il suffit de faire précéder les titres d’un nombre, suivi d’un point, suivi d’un espace :

1. Rubrique qui apparaîtra en premier

Raccourcis typographique

On peut utiliser l’ensemble des raccourcis typographique de SPIP. Si on cite du code, il faut utiliser le plugin coloration code.

Un code entre <cadre> aura ses lignes numérotées, pas un code entre <code>.

Par ailleurs, le module LaTeX de gestion du code sources colorés n’est pas capable de couper automatiquement les lignes trop longues : il faut donc les limiter directement au sein des balises <cadre> ou <code> (60 caractères approximativement, si vous gardez les réglage de format de papier et de marge standard).

Production du PDF

La production du PDF est détaillé dans un autre article.

updated on 2 March 2019

Discussion

5 discussions

  • 4

    Juste pour signaler une petite erreur

    • SPIP 3.2.5 [24404]
    • Squelette Documentation 3.0.11
    • Champs Extras 3.12.1
    • Saisies pour formulaires 3.25.1
    • Z-core 2.8.1
    • Zpip-dist 2.0.11-dev
    • Critères Suivant Précédant 1.4.4
    • Coloration Code 0.9.17
    • pas Forum installé

    Après vidage du cache ou lorsque le cache est désactivé (je précise parce-que j’ai l’impression que ça le fait pas tout le temps, ou alors ça dépend d’autres réglages ?) et lors de la prévisualisation, j’ai les deux erreurs suivantes :

    Numéro Message squelette boucle Ligne
    1 Filtre me non défini plugins/auto/documentation/inclure/forum.html _comments-fils-1 69
    2 Filtre me non défini plugins/auto/documentation/inclure/forum.html _comments-list-1 63
    • Je ne me suis jamais occupé du squelette documentation en tant que tel. Il faudrait corriger directement sur la version svn.

    • Pas de souci ; je regarde ça dès que j’ai un moment (mais je préfère reporter d’abord car j’y pige rien à la structure Z qui multiplie des fichiers dans tous les sens) Je suppose que cette erreur est liée soit à un oubli soit au fait que le filtre est déclaré dans un autre plugin (j’ai pensé à «Forums» qui est utilisé et que je n’ai pas installé)

    • il faut utiliser un ?var_mode=inclure pour retrouver les fichiers.

      Au début c’est un peu complexe, mais à long terme une structure Z permet d’avoir des grosses cohérences.

    • Je viens de pouvoir envoyer la coorection (en attente depuis deux semaines) et d’autres. Faudrait que quelqu’un teste avant qu’on augmente le numéro de version je pense.

    Reply to this message

  • 2

    Il faudrait adapter la règle “wheel” pour prendre en compte cela. C’est le fichier latex.yaml de latexwheel.

    Cf le fichier actuel.

    https://zone.spip.net/trac/spip-zone/browser/spip-zone/_plugins_/latexwheel/trunk/wheels/latex/latex.yaml?rev=115963

    • Arf, je viens de voir la réponse ! Merci beaucoup ; je jetterai un œil.

    • En gros, il me faudra une déclaration similaire à celle des “intertitres-compliquees” (lignes 86 à 92)
      ...mais en indiquant plutôt \subsubsection et non \subsection comme dans la déclaration “intertitres” tout court (lignes 70 à 77)
      Je vais tester ça en fin de mois.

    Reply to this message

  • 1

    Installation fraiche de SPIP 3.2.4 [24285] ; ajout du plugin « Squelette Documentation » 3.0.11 et des compères mentionnés (en prenant « Saisies pour formulaires » 3.25.1 car « Champs Extras » 3.12.1 exigeait une version plus élevée...) Mais impossible de trouver le zip de « Zpip-dist » en version 2.x ! N’ayant pas accès à Subversion, j’ai rapparier un à un, depuis le Trac, les fichiers du « trunk » qui est en version 2.0.11-dev : fallait le trouver... Du coup, je me demande si je suis le seul et si ça ne va pas perturber un utilisateur normal, cette dépendance à un plugin en dev qui n’est pas zippé

    • Il faudrait voir avec Marcimat, c’est lui qui avait concu le squelette documentation, Je ne sais pas pourquoi il a fait augmenter la dépendance. Moi je me suis contenter de faire la partie LaTeX.

    Reply to this message

  • 3

    Bonsoir,

    j’ai voulu activer sur un site.
    SPIP 3.2.4 [24285] + écran de sécurité 1.3.11

    les plugins

    • Squelette Documentation - stable
    • Documentation vers LaTeX - stable

    Résultat Négatif , car j’ai les messages d’erreur suivant
    • Le plugin SVP dépend du plugin ARCHIVISTE ≥ 0.2.2.
    • Le plugin Medias dépend du plugin ARCHIVISTE ≥ 0.2.2.

    • heu... tu dois avoir un problème ailleurs, parce que les deux plugins en question sont des plugins livrés avec SPIP (SVP + medias). DOnc ton install doit être foireuse.

      APrès le squelette “documentation” n’est plus maintenu....

    • ok pour l’info .........

      si plus maintenu , je ne me lance pas a ecrire une doc avec.
      je vais regarder si je trouve un équivalent pour ecrire la doc en ligne et sortir un pdf

      et verifié que mon install spip est bonne

    • je parle du squelette documentation qui est plus maintenu, mais c’est juste un squelette :). LateXwheel2spip est bien maintenu.

      Tout dépend la qualité du pdf que tu veux obtenir.

    Reply to this message

  • Bonsoir,

    J’envisage de mettre en ligne des documents de formation épars de mon disque dur en ligne, avec le squelette documentation et de pouvoir générer mes pdf à partir de là.

    Problème : j’ai parfois quatre (i.e. h3 et h4) ou cinq niveaux (i.e. h3 à h5) que je ne peux pas éclater virtuellement (i.e. transformer un article en sous-rubrique pour y mettre des articles ; ça va juste casser la cohérence d’ensemble en plus du boulot inutile...) Je peux éventuellement réorganiser certains articles pour réduire les niveaux, mais je vois quelques uns où il m’en faudrait quand même quatre !

    Je compte donc travailler avec intertitres hiérarchisés (j’aurai besoin aussi de renvois) et l’utiliser peut-être avec intertitres dans Porte-Plume.

    Ma question du coup, par rapport à ce squelette et le flux de travail lié : est-il possible de prendre en compte le niveau quatre (i.e. h4) y compris dans le LaTeX (i.e. \subsubsection) ?

    Merci.

    Reply to this message

Comment on this article

Who are you?
  • [Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom