csl-clio/Documentation/GUIDE_CSL-Clio.md

112 lines
18 KiB
Markdown
Raw Normal View History

2020-12-21 22:26:14 +00:00
---
title: "CSL/Clio"
2020-12-21 22:26:14 +00:00
subtitle: "Guide d'utilisation et de création de styles CSL supportant un formatage complexe des sources primaires"
author: Bastien Dumont
2020-12-29 10:52:28 +00:00
date: 29/12/2020
2020-12-21 22:26:14 +00:00
lang: fr-FR
2020-12-28 14:28:14 +00:00
colorlinks: true
2020-12-21 22:26:14 +00:00
---
2020-12-29 10:52:28 +00:00
<!-- TODO :
— REF
— Mécanisme pour modifier la date à chaque fois que l'on fusionne dans master
-->
2020-12-21 22:26:14 +00:00
# Introduction
Le but du projet *CSL/Clio* est de fournir une solution clé en main aux historiens pour utiliser des gestionnaires bibliographiques basés sur CSL, tels que [*Zotero*](https://www.zotero.org/), et mettre en forme automatiquement les citations et les bibliographies grâce aux processeurs CSL existants. Il comprend trois aspects :
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
* Proposer des stratégies claires pour encoder des références bibliographiques dans le format CSL en contournant ses limitations plutôt qu'en l'étendant ;
* Fournir des feuilles de style CSL qui poussent le plus loin possible l'automatisation de la mise en forme des citations et de la bibliographie en s'appuyant sur ces stratégies d'encodage ;
* Fournir des outils de post-traitement (macros LibreOffice, filtres Pandoc) pour automatiser la plus grande partie des modifications qui doivent être effectuées sur le résultat produit par les processeurs CSL.
Cette introduction développe les principes et les objectifs du projet. Les sections suivantes donneront des indications pratiques pour utiliser son gestionnaire de références bibliographiques selon les principes de *CSL/Clio*, utiliser les outils fournis et étendre le nombre de styles proposés.
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
## Présentation de CSL
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
*Citation Style Language* (CSL) est un format de fichier basé sur [XML](https://www.w3.org/standards/xml/core) qui décrit la manière dont doivent être mises en forme des références bibliographiques au sein d'un document. Il permet de mettre en forme différemment une référence selon qu'elle se trouve dans une citation ou dans la bibliographie, et de distinguer entre la première mention d'une référence et ses mentions ultérieures. Pour ce faire, il spécifie :
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
* Les différentes variables qui peuvent être utilisées pour décrire une référence dans un gestionnaire de bibliographie : `title`, `author`, `editor`, `issued`, `page`,...
* La manière dont doivent être rédigées les instructions de mise en forme dans une feuille de style ;
* La manière dont ces instructions doivent être interprétées par les logiciels qui traitent ces feuilles de style pour procéder à la mise en forme, CSL n'étant pas lui-même un programme mais un format.
Ainsi, l'utilisation de CSL pour la mise en forme des citations met en œuvre quatre outils :
* Un gestionnaire de bibliographie qui se base sur les règles spécifiées par CSL pour décrire les références. Dans la suite de ce document, nous prendrons l'exemple de [*Zotero*](https://www.zotero.org/), mais [d'autres logiciels supportent CSL](https://en.wikipedia.org/wiki/Comparison_of_reference_management_software) ;
* Une feuille de style conforme aux directives de la revue, de la collection ou de la maison d'édition qui doit publier le travail en train d'être rédigé (les deux principaux dépôts étant [celui du projet CSL](https://github.com/citation-style-language/styles) et [celui de Zotero](https://www.zotero.org/styles)) ;
* Un processeur CSL, c'est-à-dire un programme qui traite les données enregistrées dans le gestionnaire de bibliographie selon les instructions données dans la feuille de style spécifiée pour produire une référence mise en forme dans un format qui lui est propre ;
* Un programme qui convertit les données renvoyées par le processeur CSL dans le format du fichier où la référence doit être insérée.
De nombreux gestionnaires de bibliographie intègrent un processeur CSL, le plus souvent [*citeproc-js*](https://citeproc-js.readthedocs.io/en/latest/), et proposent des extensions pour les principaux logiciels de traitement de texte. Grâce à ceux-ci, lorsque l'auteur souhaite insérer une citation, il lui suffit de cliquer sur un bouton et d'indiquer dans la fenêtre qui s'ouvre à quels items il veut faire référence et quelles précisions supplémentaires il souhaite apporter ; le plugin appelle le processeur intégré en lui indiquant la feuille de style choisie par l'utilisateur et les informations relatives à la citation et intègre la citation produite par le processeur dans le document courant sous la forme d'une note de bas de page ou d'une référence dans le corps du texte. On en trouvera un exemple [sur le site de *Zotero*](https://www.zotero.org/support/word_processor_integration). [D'autres processeurs existent](https://citationstyles.org/developers/#/csl-processors), notamment celui utilisé par [Pandoc](https://pandoc.org/).
La mise en œuvre de cette chaîne opératoire pour la mise en forme des citations comporte de nombreux avantages sur un travail purement manuel. En automatisant la mise en forme des citations, elle réduit les risques d'incohérences et d'erreurs : on gagne ainsi du temps à la fois lors de la saisie des citations et à la relecture. Elle évite d'avoir à vérifier si une référence a déjà été citée ou non et dans quelle note. La séparation entre le stockage des références bibliographiques et leur mise en forme facilite également l'utilisation des mêmes références dans plusieurs publications soumises à des normes différentes. Elle permet même de changer les règles de mise en forme en cours de rédaction sans perdre de temps à modifier toutes les citations existantes, ce qui peut s'avérer précieux lorsque l'éditeur met à jour ses instructions ou lorsque l'on décide de soumettre à une autre revue que celle envisagée initialement. Certes, il est nécessaire de prendre un peu de temps pour apprendre à utiliser ces outils et pour enregistrer sa bibliographie dans le gestionnaire ; mais cet investissement est faible si l'on se contente d'utiliser ou de modifier légèrement des feuilles de styles existantes, et il est très rapidement rentabilisé.
Enfin, CSL présente toutes les garanties de durabilité. Les spécifications sont publiées sous license [Creative Commons Attribution-ShareAlike](https://creativecommons.org/licenses/by-sa/3.0/), une license [libre](https://www.gnu.org/philosophy/free-sw.html) qui leur garantit une large diffusion. Les processeurs existants, ainsi que plusieurs logiciels de gestion de bibliographie (dont *Zotero*), sont relativement nombreux, dotés pour certains d'une importante communauté d'utilisateurs, en partie dépendants les uns des autres, et libres, ce qui rend très peu probable l'arrêt de leur développement. La large [batterie de tests](https://github.com/citation-style-language/test-suite) maintenue sur le dépôt en ligne de CSL permet aux développeurs de vérifier si le comportement de leur programme est conforme aux spécifications : ainsi, dans la plupart des cas, un style CSL donné produira bien les mêmes résultats quel que soit le processeur utilisé — et si tel n'est pas le cas, il est possible de signaler le problème sur le dépôt du code source du projet. Le principal risque pour l'utilisateur est qu'une modification des spécifications CSL impose de modifier les styles ou l'enregistrement des données dans le gestionnaire de bibliographie ; cependant, dans ce cas, des outils seront très probablement mis à disposition pour rendre la migration automatique, [comme cela a été le cas](https://github.com/citation-style-language/utilities/blob/master/update-styles-0.8.1-to-1.0.sh) lors du passage de la version 0.8 à la version 1.0 des spécifications.
> **Pour aller plus loin :**
>
> * [Site de CSL](https://citationstyles.org/)
> * [Introduction à CSL](https://docs.citationstyles.org/en/1.0.1/primer.html)
2020-12-21 22:26:14 +00:00
## Limites actuelles de CSL pour les publications en Histoire
Si CSL a été développé principalement par des chercheurs pour les besoins de la publication scientifique, le fait qu'il soit pensé pour couvrir les besoins de l'ensemble des sciences humaines le rend peu adapté, au premier abord, à certains besoins particuliers.
Pour les historiens, son point faible le plus évident est le manque de support pour la gestion des sources primaires. En effet, CSL prévoit principalement une variable `title`^[
`Titre` dans *Zotero*.
] pour le titre d'une référence et une variable `container-title`^[
Dans *Zotero*, `Titre du livre` si l'item enregistré est un chapitre ou `Publication` s'il s'agit d'un article.
], pour l'ensemble dans lequel elle est insérée (livre pour un chapitre d'ouvrage, revue pour un article), mais rien pour le titre d'une source. Or, on ne peut pas renseigner le titre de la source comme `title` et celui de l'ouvrage dans lequel elle est publiée dans `container-title` car certaines sont publiées dans des articles ou des chapitres d'ouvrages. En outre, selon les éditeurs, il faut indiquer soit le titre de la source, soit celui de la publication, soit les deux : si l'on veut que les enregistrements dans la base de données bibliographique soient complets et indépendants des styles utilisés, une variable *ad hoc* est donc nécessaire. Or, le fait que l'utilisation d'une telle variable soit limitée aux historiens empêche qu'elle soit ajoutée dans les spécifications^[
Pour plus de détails, voir [cette discussion](https://github.com/citation-style-language/schema/issues/388) sur le dépôt officiel du schéma CSL.
].
2020-12-21 22:26:14 +00:00
Bien que ce point ne soit pas explicité, les spécifications actuelles de CSL (v. 1.0.1) semblent supposer que la localisation d'un passage dans une publication se fait en fonction d'un critère unique, tel que la page, le chapitre ou la ligne. Les processeurs, en accord avec les tests officiels, ne prévoient en tout cas que ce cas de figure. Or, le plus souvent, lorsque l'on précise la ligne, on indique aussi la page, le folio ou la colonne. De même, on peut avoir besoin de citer une source à la fois selon les divisions internes de la source (p. ex. VI, 5) et selon la page dans l'édition. De ce fait, dans les boîtes de dialogue d'ajout de citation, on ne peut renseigner qu'un des deux critères de localisation dans le champ approprié, l'autre étant à ajouter en suffixe (voir [@fig:double-locator-zotero]). Cela pose problème à double titre : d'abord parce que certains localisateurs, dans certains styles, sont rendus différemment selon qu'ils sont seuls ou combinés à d'autres^[
Comparer p. ex. « La Fontaine, *À Fouquet*, l. 7 » (ligne seule) et « La Fontaine, *Le Songe de Vaux*, p. 26^5^ » (page et ligne en exposant). Voir aussi [cette discussion](https://github.com/citation-style-language/schema/issues/342).
] ; ensuite parce que cette lacune oblige à mettre en forme une partie des localisateurs directement dans le champ *Suffixe*, ce qui peut poser problème en cas de modification des normes suivies. Par ailleurs, CSL prévoit une grande variété de critères de localisation dans les *citations*, mais pas dans les *références bilbiographiques* : ainsi, on peut se référerer à un folio précis d'un manuscrit dans une citation, mais non indiquer la localisation d'une œuvre dans un manuscrit dans la bibliographie.
2020-12-28 14:28:14 +00:00
![Localisation selon la page et la ligne dans la fenêtre classique d'ajout de citation de *Zotero*](double-locator-zotero.png){#fig:double-locator-zotero}
Concernant les titres de revues, les spécifications CSL prévoient une variable `container-title-short` qui permet d'indiquer une forme abrégée. *Zotero* [propose en outre une option](https://www.zotero.org/support/kb/journal_abbreviations) pour ignorer cette variable et utiliser à la place la liste d'abréviations de l'*Index Medicus*. Toutefois, ces deux approches ne sont pas satisfaisantes, d'une part parce qu'elles ne prévoient pas un mécanisme semblable pour les titres de collections, d'autre part parce que les listes d'abréviations varient selon les éditeurs et les revues. Pour l'instant, seul *Pandoc* permet de fournir une liste d'abréviations en plus du fichier CSL [en utilisant un mécanisme généralisable à toutes les variables](https://pandoc.org/MANUAL.html#specifying-a-citation-style) (dont `collection-title`). Cependant, il faut acquérir des connaissances de bases sur le format JSON et CSL pour constituer une telle liste, et les utilisateurs de logiciels de traitement de texte tels que *Word* ou *LibreOffice* ne peuvent pas en bénéficier. *Zotero* devrait aussi acquérir cette fonctionnalité dans le futur^[
2020-12-29 10:52:28 +00:00
En réalité, [une solution existe déjà](https://forums.zotero.org/discussion/comment/155854/#Comment_155854) mais elle n'est pas officiellement documentée et est assez délicate à metre en œuvre. Nous l'expliquons néanmoins plus loin<!-- REF -->.
].
2020-12-28 14:28:14 +00:00
Enfin, il manque des solutions claires pour l'encodage de certains éléments. Il n'existe pas, dans CSL, de types de documents tels que « actes de colloque », « répertoire », « blog » ou « site Web ». Il n'est pas prévu non plus de rôle pour les collaborateurs^[
Il existe bien un champ *Collaborateur* dans *Zotero*, mais il n'est relié à aucune variable dans CSL.
]. Comme nous l'avons évoqué plus haut, il n'est pas possible de localiser autrement une partie d'ouvrage dans la bibliographie que par pages, volume ou partie : il n'est donc pas possible d'indiquer à quels folios ou dans quelles colonnes de la *Patrologie grecque* se trouve une source (bien que ce soit possible dans les citations).
2020-12-28 14:28:14 +00:00
Heureusement, les membres du projet CSL sont parfaitement conscients de ces limites que les nombreux retours d'utilisateurs mettent en évidence, et ils travaillent à faire évoluer les spécifications pour y apporter des réponses. À l'heure à laquelle ce guide est rédigé, les spécifications officielles, qui sont implémentées par les processeurs, portent le numéro de version 1.0.1. Elles devraient bientôt évoluer vers la version 1.0.2, qui introduira quelques nouveautés sans véritablement résoudre les problèmes que nous avons identifiés. À plus long terme, CSL sera plus profondément remanié dans la version 1.1. Les discussions en cours sont très prometteuses, mais nul ne sait quand elles aboutiront, et il faudra encore un délai supplémentaire pour que les processeurs soient mis à jour. En attendant, il nous faut trouver des moyens de surmonter les limites actuelles de CSL en faisant avec l'existant.
> **En savoir plus sur l'évolution de CSL :**
>
> * Le blog de CSL contient un [article très synthétique sur les évolutions envisagées](https://citationstyles.org/2020/07/11/seeking-public-comment-on-CSL-1-0-2/) ;
> * Sur la version 1.0.2, en gardant à l'esprit qu'il s'agit encore d'un travail en cours, quoique très avancé, on peut prendre connaissance des [spécifications](https://github.com/citation-style-language/documentation/blob/master/specification.rst). Un document synthétique listant les évolutions par rapport à la version 1.0.1 est disponible [ici](https://docs.google.com/document/d/1wY1cOOamDYYh8VNW7h_uleqieBDGOa_LYsRiVdQy1RI/) ;
> * Sur la version 1.1, on peut consulter la [liste des problèmes identifiés ou en cours de traitement](https://github.com/citation-style-language/schema/milestone/1) ;
> * À plus long terme encore, [quelques objectifs ont été identifiés pour une version 1.2](https://github.com/citation-style-language/schema/labels/1.2) ;
> * Voir aussi la [liste des propositions pour de futures versions de CSL](https://github.com/orgs/citation-style-language/projects/3) (toutes versions confondues).
2020-12-21 22:26:14 +00:00
## Objectifs de *CSL/Clio*
2020-12-21 22:26:14 +00:00
Actuellement, pour bénéficier malgré tout des avantages de CSL, chacun doit définir des stratégies d'encodage *ad hoc* et créer des styles qui reposent sur elles en fonction de ses besoins. Cela requiert beaucoup de recherches et de temps pour comprendre comment fonctionne CSL, découvrir des fonctionnalités peu connues de *Zotero*, programmer des outils et corriger ensuite ses erreurs. Pour des raisons fort compréhensibles, peu de chercheurs ont le temps ou l'envie de se consacrer à ces tâches. Le but du projet *CSL/Clio* est de réduire le plus possible l'investissement requis en fournissant des solutions clés en main pour utiliser CSL et automatiser le plus possible le travail de post-traitement qui reste nécessaire. Ainsi, le temps d'apprentissage nécessaire pour maîtriser les principes et les outils présentés dans ce guide sera largement compensé par le temps et l'énergie gagnés lors du processus de rédaction. Les lignes directrices du projet sont exposées maintenant, avant de passer à la pratique.
2020-12-21 22:26:14 +00:00
### Créer un ensemble de styles cohérent et interopérables
### Fournir des stratégies d'encodage claires
### Poser des principes pour l'encodage des sources primaires
### Coupler CSL avec des outils de post-traitement
<!-- À terme, mon souhait est que le langage CSL soit étendu de sorte que ces styles ne reposent plus sur des détournements et puissent être intégrés au dépôt officiel. -->
### Un projet évolutif et ouvert aux retours des utilisateurs
Pour l'instant, le projet *CSL/Clio* est surtout informé par ma pratique de doctorant en histoire byzantine. Il est possible que je n'aie pas rencontré les mêmes problèmes que vous, que je n'aie pas eu les mêmes besoins. Si, par exemple, vous trouvez un bug dans les outils proposés, si le présent guide n'est pas clair, si vous avez besoin d'un style de revue qui n'est pas fourni, si les outils de post-traitement n'effectuent pas une tâche dont vous avez besoin, ou si vous souhaitez participer, n'hésitez pas à me contacter en utilisant [le dépôt du projet](<!-- REF -->).
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
# Gérer ses données bibliographiques avec Zotero
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
# Automatiser la mise en forme
2020-12-21 22:26:14 +00:00
2020-12-28 14:28:14 +00:00
# Programmer de nouveaux styles