marcimat. {{Ma Graine}} .Net

Livre libre «Programmer avec SPIP»

Matthieu Marcillaud — 2010-05-18T17:12:53Z

Tôt ce matin a été proposée officiellement la première version du livre « Programmer avec SPIP » pouvant être achetée en ligne chez un imprimeur « à la demande ». Cette « Édition Troglo2 », sous licence libre (cc-by-sa), est un export complet du site http://programmer.spip.org en date du 16 mai 2010. Il est diffusé chez Lulu dans un format A5 à spirale. Retours sur cette expérience.

L'idée a germé un jour de fin 2008 où l'on m'a rémunéré quelques jours pour écrire des pages d'une documentation technique, peu de temps après la sortie de SPIP 2.0. Il y avait des trous béants sur des absences de documentation de certaines fonctionnalités qu'il était intéressant de combler.

Puisque mon éditeur de texte favori est l'interface privée de SPIP, j'ai commencé une série d'articles en local, sous SPIP. Je les voulais cohérents, se suivant logiquement, courts pour mettre peu d'idées sur une même page et ne pas effrayer le lecteur de la quantité de texte à lire, et actualisés pour la dernière version de SPIP.

Un squelette SPIP pour lire plus agréablement cette suite d'articles et de rubriques a été élaboré dans le même temps, rendant la navigation plus agréable. Puis le tout a été mis en ligne début 2009 (je ne me rappelle plus précisément).

Au fil des jours, sur mon temps libre, je complétais ces premières pages par d'autres, puis par d'autres encore. Un nom de domaine fut alors attribué au projet : programmer.spip.org ... L'idée germait de non seulement avoir en ligne « comme » un livre, mais d'un jour aussi réussir à en proposer une véritable version papier.

Technique autant que rédactionnel

Ce qu'il est difficile d'imaginer en parcourant les 338 pages de l'exemplaire spécial « Troglo SPIP » que j'ai sous les yeux, c'est que sa création a nécessité presque autant de temps pour la technique sur le site et pour générer le livre que pour l'écriture en elle-même. Au fil de la progression du site, de nouvelles contraintes à résoudre apparaissent.

C'est d'abord un niveau de sous-rubriques à prendre en compte en plus, c'est une meilleure lisibilité par là, c'est de l'AJAX à mettre ici pour éviter des pages trop volumineuses, c'est d'installer un système pour que les visiteurs puissent proposer des améliorations, c'est gérer les balises sur 2 langues et quelques dizaines de rubriques lorsque des traducteurs anglais investissent l'espace éditorial... puis il y a trop de rubriques et cela devient invivable alors c'est encore mettre un niveau de sous-rubriques en plus pour gérer les langues, puis c'est permettre de déclarer des traductions entre rubriques via un plugin (tradrub), puis c'est fournir des outils aux traducteurs pour suivre les modifications un rien plus simplement (tradsync), en même temps, c'est ajouter des mots clés pour que le livre puisse générer un glossaire, c'est créer les outils pour exporter le contenu entier du site, et exporter le résultat dans un format PDF convenable (via PrinceXML), et adapter la CSS d'impression pour rendre les textes encore plus contrastés que sur l'écran, et patati... et patata... et j'en passe et des meilleures.

Tout cela aurait certainement été plus facile en écrivant directement dans OpenOffice ou dans un logiciel spécialisé. Mais.

De la relecture aux traductions

Mais l'immense avantage d'une interface de rédaction collaborative en ligne, telle que celle de SPIP, c'est de permettre à tous les visiteurs de participer, tant sur la rédaction d'articles que sur les relectures.

Et heureusement ! Combien de fautes ou de tournures de phrases lourdes, ou d'idées mal exprimées ont pu être corrigées grâce à la vigilance et à la participation des différents lecteurs. Elles furent nombreuses ; nul n'est à l'abri d'un coup de fatigue :). Il y a un regard multiple sur le contenu et c'est en cela que c'est très intéressant : apporter ce que l'on peut, ou même dire « je ne comprends pas » permet d'améliorer au final l'ensemble du livre.

Ma plus grande surprise, peut-être, dans cette histoire, est l'arrivée spontanée de traducteurs. Une envie de faire découvrir la technique de SPIP par delà les frontières. Nous avons volontairement bridé les tentations dans un premier temps, puis autorisé les traductions en une première langue, l'anglais, pour tester le fonctionnement des squelettes (ça a nécessité diverses expérimentations), puis le multilinguisme semblant fonctionner, nous avons ouvert récemment la porte à une seconde langue, l'espagnol.

Passer d'un site monolingue à un site multilingue implique des choix techniques qui ne sont pas évidents à trancher. Je suis encore à l'heure actuelle très sceptique sur certaines difficultés tel que « comment traduire un mot clé ? ». Pour l'instant ça fait des titres avec des balises contenant 3 langues... mais cela va vite être difficile s'il y a 8 langues à gérer... On a évacué très fièrement ce problème avec les rubriques en créant [1] un plugin (tradrub) permettant de créer et gérer des traductions entre rubriques. Mais il reste ces maux, ou mots... Affaire à suivre de ce côté. Mais revenons aux traducteurs...

En anglais, au début est arrivé Gilles, puis Thomas qui ont tranquillement réalisé plus de 40 traductions. Et un jour Mark Baber a débarqué ! Et... quelques semaines plus tard tout était traduit en anglais. C'est quelque chose de fabuleux. Quelques relecteurs attentifs comme Paolo éliminent les derniers coquilles anglaises et on se retrouve à très prochainement proposer la première, toute première édition d'un livre SPIP dans une autre langue que le français.

C'est là, à ce moment là, qu'on s'aperçoit de la force d'une communauté multilingue et d'un logiciel SPIP parfaitement adapté à presque toutes les problématiques de traduction.

D'un fichier pdf à un livre

Réaliser un livre lorsque l'on a qu'une page HTML à la base semble un rien difficile. Les imprimeurs à la demande, qui sont vraiment très adaptés pour de petites séries de livres, réalisent des impressions numériques à partir de fichiers au format PDF. L'enjeu consiste donc à transformer un contenu au format HTML en un contenu au format PDF mis en page. Cela semble très simple au premier abord.

On peut avoir comme idée de générer une page HTML et de l'importer dans OpenOffice (ou de le générer directement en .odt avec le plugin SPIP adapté), d'insérer table des matières et pieds de page, puis d'enregistrer le tout en PDF. Oui... mais... Voici quelques problèmes rencontrés : comment gérer les renvois et afficher sur les liens internes au document les numéros de pages auxquels ils correspondent ? comment faire prendre en compte la coloration syntaxique des codes HTML sans que cela fasse une liste extrêmement vilaine de morceaux de mots ? comment générer automatiquement des sections (au sens OpenOffice) à partir du HTML pour que le titre des chapitres apparaisse bien dans l'entête de toutes les pages du chapitre concerné ? Au bout du compte on remarque qu'on ne maitrise pas assez OOo pour cela.

Une autre idée, est d'utiliser les compétences de CSS3. Car CSS3 est en outre prévu pour gérer des impressions papiers. On donne le format, on crée des types de pages, indique quel texte placer dans l'entête, on peut aussi ajouter des renvois vers les numéros de page correspondant sur les liens internes... C'est extrêmement puissant.

Mais voilà... Qui gère ces propriétés de CSS3 suffisamment correctement ? aucun navigateur ! Ils en connaissent quelques-unes, comme la prise en compte des sauts de page souvent, mais pas toutes. Peu se débrouillent avec les marges, les formats du papier, les entêtes et pieds de page comme il faut.

Je n'ai croisé à ce jour qu'un seul logiciel capable de prendre en entrée un fichier HTML, de récupérer sa CSS3, et de générer le PDF attendu. C'est PrinceXML, logiciel qui n'est malheureusement pas libre, mais dont l'usage sur une machine locale est autorisée, du moins pour la version 7.0 que j'utilise, mais je vois aujourd'hui qu'ils ont sorti ce mois-ci une version 7.1 et que la licence me semble différente de ce qu'elle était en restreignant bien plus l'usage de la version gratuite... C'est très ennuyant ! Bref, ça serait bien de trouver ou créer une alternative libre ! Ou utiliser d'autres mécaniques, quitte à se passer de la coloration syntaxique...

Des déceptions...

Outre la difficulté de mise en œuvre technique – mais j'aime ces défis – c'est l'organisation et la cohérence des chapitres que je trouve complexe à trouver. J'avais lancé sur la liste de discussion spip-devel un sujet, en demandant « s'il existait un livre sur la programmation avec SPIP, quelle serait sa table des matières idéale ». J'ai été finalement déçu par le peu de réponses apportées ou qui disaient que l'organisation du site était déjà très bien comme ça. J'imaginais qu'à plusieurs on arriverait à trouver un chapitrage qui me/nous conviendrait et ce ne fut pas vraiment le cas. Du coup, je ne suis pas spécialement satisfait de l'ordre des chapitres de cette version 1, de leur enchevêtrement. Cela manque, je trouve, de fil conducteur, de lien.

L'autre élément d'insatisfaction c'est que cette version sort alors que j'ai le sentiment de n'avoir pas tout dit, qu'il reste plein de zones d'ombres, que certaines parties ne sont pas claires ou à réécrire, qu'il y a des absences, des chapitres commencés mais pas finis comme « développer des plugins » où l'on a de quoi rester sur sa faim.

Je suis triste de cela, et en même temps, je pense que je n'arriverai jamais à être 100% satisfait. Ce livre est une photo du site à un instant t et à cet instant là, des parties sont excellentes et d'autres à terminer, mais c'est toujours mieux que s'il n'y avait rien. Il faut savoir à un moment dire (merci BennyB) : « bon, on y va ? »

... aux perspectives

L'avenir est soumis à bien des incertitudes. Déjà : ce livre va-t-il plaire ? était-il attendu ? sera-t-il utilisé ? Nous verrons les retours dans quelques temps... Mais déjà nous avons réussi un beau défi : oui, on peut réaliser un livre libre, rédigé partiellement de manière collaborative, proposer à tous le pdf, le faire imprimer et le commercialiser. Cela marche. Même pour les traductions. On peut donc imaginer de nouveaux défis, d'autres perspectives :

sortir une version anglaise (99,9% est déjà traduit)
sortir une version espagnole (13% traduit) : souhaitons courage aux hispanophones et à Sylvano qui a démarré sur les chapeaux de roues !
ajouter pour la prochaine version des divertissements, par des illustrations ou strips horizontaux, pour alléger le côté très formel du texte
créer une trilogie « Publier | Personnaliser | Programmer » ou encore « Utiliser | Créer son site | Programmer », bref, quelque chose par type d'utilisateurs : du rédacteur/administrateur/traducteur, puis le bidouilleur/installateur/webmestre , et enfin pour les webmestres qui triturent les codes et autres développeurs...

À vous aussi, lecteurs, de proposer des améliorations. Ne pas oublier qu'il y a des tas de manières de participer à son échelle sur la galaxie SPIP, entre l'organisation d'évènements locaux, les traductions, les retours d'expérience, les rapports de bugs, les contributions sur les forums, les encouragements verbaux, de l'écriture de documentation, de contributions. Partage et ouverture. Ah, et si possible avec un peu de tendresse :)


Couverture du livre «Programmer avec SPIP»: Première version officiellement en vente, l' « Édition Troglo2 » de mai 2010.

[1] enfin en le mettant à jour « from scratch »

J'en profite pour dire un GRAND MERCI à tous ceux qui de près ou de loin ont apporté leur pierre, leur regard, leur savoir, leur temps pour le site Programmer.spip.org ou pour le livre. Il y a de beaux et braves gens derrière tous ces textes et codes informatiques. Les Troglos2 pour ceux qui ont pu s'y déplacer, est un excellent évènement qui soude, motive, donne du soleil, et je suis heureux d'avoir croisé certains d'entre vous à cette occasion.

Créer un nouvel objet éditorial

Matthieu Marcillaud — 2009-10-20T19:47:38Z

Nous allons étudier comment créer un nouvel objet éditorial très simple et sans relation, pour SPIP 2.0. De ces explications vont naître un petit plugin d'exemple. Mais le tout fait appel à un grand nombre de fonctions de SPIP et n'est pas évident à mettre en œuvre. Nous en profitons pour relever un défi : aucun affichage géré en PHP, mais tout en squelette SPIP.

Nous allons définir un nouvel objet SPIP. Cet objet sera un « chat » ! Pourquoi pas ? Nous allons voir dans un premier temps comment créer la table SQL correspondante et donner un exemple de mise à jour. Nous décrirons ensuite la création d'une page de visualisation des chats, celle pour éditer un chat existant, et le formulaire CVT qui correspond. Enfin, nous ajouterons une action pour pouvoir supprimer un chat ! Et que la SPA ne m'en veuille pas trop, ce n'est qu'un exemple ! Et pour terminer, nous verrons comment interfacer le plugin « Champs Extras 2 » sur le nouvel objet !

Création du plugin

On commence par un fichier plugin.xml rudimentaire. On déclare dedans cependant une information qui peut être utile : 1 dépendance, à SPIP 2.

>
>Chats (plugin d'exemple)>
>Matthieu Marcillaud>
>1.0>
>stable>
>
Ce plugin est un exemple de création
d'un nouvel objet éditorial dans SPIP
>
>http://marcimat.magraine.net/?article344>
>images/chat-128.png>
>chats>
id="SPIP" version="[2.0.9;]" />
>

marcimat. {{Ma Graine}} .Net

Livre libre «Programmer avec SPIP»

Technique autant que rédactionnel

De la relecture aux traductions

D'un fichier pdf à un livre

Des déceptions...

... aux perspectives

Créer un nouvel objet éditorial

Création du plugin

Déclaration de la table spip_chats

Installation/désinstallation de la table spip_chats

Mise à jour de la table

Création du bouton pour accéder à la liste des chats

Création d'une page privée pour lister les chats

<:chats:liste_des_chats:>

Création d'une page privée pour voir un chat

#NOM

Création d'une page privée pour ajouter ou modifier un chat

(#ENV{titre,<:chats:texte_nouveau_chat:>})

Création du formulaire CVT d'édition

Création de l'action de suppression

Interface avec « Champs Extras 2 »

Conclusions

Squelettes SPIP à layout unique

Historique

Le critère ENV

Un gabarit de page définit une seule fois (layout unique)

Quelques détails du fichier de structure

Organisation des dossiers (squelette Zesty)

Cas particuliers des objets et des 404

De la simplicité des thèmes

Les formulaires CVT de SPIP

Introduction

Projet exemple : traduire via google

Charger

Vérifier

Traiter

URLs en minuscules

Pipeline creer_chaine_url

Mettre à jour ses URLs