Quel outil pour éditer des styles CSL?

We believe using a simple text editor is a good way to learn HTML.

Vous l’aurez compris à la lecture de cet épigraphe, nous abordons aujourd’hui la question des éditeurs, non sans parti-pris.
Nous proposons en effet, à ceux d’entre vous qui ont déjà édité des styles CSL et à ceux qui souhaitent commencer, un aperçu des différentes possibilités pour ce faire.

Qu’est-ce que CSL?

CSL (Citation Style Language) désigne non seulement le langage XML utilisé pour encoder les styles bibliographiques, mais plus encore un projet open source dont l’objectif est de

faciliter l’édition scientifique en automatisant le formatage des citations et des bibliographies.

Soulignons que CSL n’est pas spécifique à Zotero : ce langage est utilisé par de nombreuses applications (Pandoc par exemple), et reçoit un soutien actif de Papers et Mendeley – voir About us sur le site CSL.
Si CSL vous est parfaitement étranger, vous pourrez vous familiariser avec ce langage, son vocabulaire, sa syntaxe et quelques exemples simples de modification d’un fichier, grâce aux ressources suivantes :

• Page du site Zotero Editer des styles CSL – Guide pas à pas
• Trame de l’atelier Zotero Avancé – styles bibliographiques : comprendre et contribuer, organisé par HackYourPhd, le blog Zotero francophone et la Boîte à outils des historiens.

Au menu de notre revue d’outils, nous avons inscrit :

• l’éditeur de style intégré à Zotero,
• l’éditeur en ligne,
• l’éditeur de texte,
• le validateur en ligne.

L’éditeur de style Zotero

Zotero possède un outil intégré pour éditer les styles, accessible depuis les Préférences > Citer.

 

Comme on le voit sur cette copie d’écran, Zotero dispose en fait de deux outils de style, l’Aperçu des styles et l’Éditeur de style.
Commençons par une brève présentation du premier.

L’Aperçu des styles vous permet de comparer rapidement tout ou partie des styles que vous avez installés, en générant des appels de citation et une bibliographie à partir d’éléments sélectionnés dans votre bibliothèque.
Afin que cet aperçu soit significatif et parlant, il importe de s’assurer de deux points.

Tout d’abord, assurez-vous que ces éléments reflètent la diversité de types de documents que vous allez citer (article, chapitre, mais aussi thèse ou encore brevet ou film ) : vous vérifierez ainsi que tous ces types sont bien pris en compte par les styles que vous comparez. Le style Nature, par exemple, ne sera pas le plus adapté si vous citez des documents non publiés comme les thèses. La revue Nature demande aux auteurs de citer un nombre restreint de types de document (voir les instructions aux auteurs, rubrique References), aussi le style CSL Nature encode-t-il uniquement le formatage des références pour ces types de document.

Ensuite, et surtout, assurez-vous que ces éléments sont complets et exacts.

• S’il manque des informations bibliographiques, il est logique que le style ne puisse pas les afficher lorsqu’il génère les citations et la bibliographie.
• Si vous faites un usage inadéquat ou détourné de certains champs, vous générerez également une bibliographie détournée ou inadéquate, ne correspondant pas au résultat que peut produire le style normalement. Prenons un exemple, la date d’édition originale renseignée à tort dans le champ Edition et non dans le champ Extra sous la forme original-date: 1876. L’affichage produit aura toutes les chances d’être incohérent, car CSL attend dans ce champ une information du type “2” ou “2 éd. revue et corrigée” et non une date. Et cet usage détourné peut aussi conduire à d’autres difficultés : que faire lorsque vous devrez renseigner pour un livre à la fois une date d’édition originale et une mention d’édition?

Ces deux points sont tout aussi importants lorsque vous utilisez l’Éditeur de style.
Si l’Aperçu des styles permet de manipuler plusieurs styles à des seules fins de visualisation, l’Éditeur de style se limite à l’affichage d’un seul style en vue de son édition.

L’écran est composé de 3 zones, avec, de bas en haut :

• le panneau de prévisualisation, dans lequel vous voyez évoluer en temps réel le formatage des citations et de la bibliographie au fur et à mesure des modifications que vous apportez au fichier de style,
• le panneau d’édition,
• la barre d’outils.

Pourquoi recommandons-nous cet outil, qui semble rudimentaire et pourvu de fonctionnalités limitées?

Avantages de l’éditeur de styles Zotero

• Toute erreur de syntaxe XML donne lieu à un message d’erreur immédiat : le panneau de prévisualisation affiche le message suivant, aussi voit-on tout de suite que son fichier n’est pas bien formé.

• On prévisualise en direct les modifications de paramétrage du style, et ce à partir des exemples de document de sa bibliothèque.
• On peut tester en direct les paramétrages liés à des situations de citation particulières : ainsi lorsque l’on précise une mention de page ou de paragraphe (menu déroulant Page), ou que l’on supprime le nom de l’auteur d’un appel de citation dans un style de type auteur-date. Ou encore, dans un style de type note, lorsque l’on cite à plusieurs reprises la même référence (gestion des ibid, op. cit., etc. – menu déroulant Position de la citation).

Limites de l’éditeur de style Zotero

• L’éditeur n’intègre pas d’aide à la saisie comme la coloration syntaxique ou l’indentation du code.
• Il ne contrôle pas la validité CSL : on peut créer un style dont la syntaxe XML est correcte, mais qui ne soit pas conforme aux spécifications CSL et qu’on ne pourra donc pas installer dans Zotero.
• L’écran est partagé en 2 bandeaux horizontaux, ce qui peut occasionner une lisibilité réduite en fonction de la taille et de l’orientation de son écran.

Afin de faciliter la création de styles, les bibliothèques de l’Université de Columbia et Mendeley, grâce à un financement de la fondation Sloan, ont développé en 2012 un éditeur CSL open source en ligne.

Éditeur de style en ligne

Le site http://editor.citationstyles.org propose en plus de l’édition de style CSL la recherche de style à partir d’un exemple, fort utile à chacun quel que soit l’outil d’édition CSL qu’il utilise.

Deux modes d’édition des styles sont disponibles :

• un mode visuel,
• un mode code.

Rechercher un style à partir d’un exemple

Revenons tout d’abord sur cette fonctionnalité, à première vue très tentante. Tient-elle ses promesses?

Pas très convaincant, n’est-ce pas?

Il convient donc de bien vérifier les propositions suggérées par cette fonctionnalité, en affichant notamment les résultats détaillés (bouton View style).

Le mode visuel

Le mode visuel offre plusieurs fonctionnalités facilitant et fiabilisant l’édition du code.

Sélection des éléments au passage de la souris

Dans le volet de prévisualisation comme dans l’arbre de structure, il suffit de sélectionner l’élément que l’on souhaite modifier pour l’afficher dans le formulaire d’édition du code. Il est alors surligné en bleu à la fois dans le volet de prévisualisation et dans l’arbre de structure.

Ajout d’éléments assisté

Le bouton “+” dans l’arbre de structure guide l’ajout d’un nœud élément ou texte en affichant, en fonction du contexte :

• directement le nom du ou des éléments enfant autorisés par CSL (un élément Name a par exemple pour seul élément enfant un élément Name-part),
• le choix d’un type d’élément à insérer : Group, Conditional, Number, Text, Label, Date, Names. On choisit alors dans un deuxième temps, dans le formulaire, l’élément à ajouter. Cette typologie est rendue visuelle par l’association d’une icône spécifique à chaque type d’élément ; ces icônes s’affichent aussi dans l’arbre de structure.

Présélection du vocabulaire et de la syntaxe

Pour chaque élément, le formulaire affiche uniquement les attributs qu’il est autorisé d’utiliser pour le qualifier. Il affiche à la fois ceux qui sont déjà utilisés (et leur valeur) et ceux qui ne le sont pas (la valeur est alors bien sûr vide).

Un menu déroulant affiche les valeurs possibles de l’attribut si applicable (i. e. si les valeurs doivent être choisies dans une liste fermée).

Le mode code

Le mode code, comme son nom l’indique, affiche le code CSL, en facilitant sa lecture et son édition grâce à la coloration syntaxique et l’indentation.

Avantages

• Les deux modes d’édition peuvent être combinés et proposent des aides à la saisie, pour une édition plus ou moins guidée.
• Le mode visuel interdit la création d’un fichier mal formé ou non valide.
• Le mode code affiche un message d’erreur si le fichier est mal formé ou non valide.
• On prévisualise en direct les modifications de paramétrage du style.

Limites

• La prévisualisation n’est pas effectuée à partir des documents de sa bibliothèque, elle porte sur des exemples par défaut d’un nombre restreint de types de document : livre, chapitre, article de revue, article de journal, rapport, brevet et page web.

Il est possible de personnaliser ces exemples, mais de façon moins directe et aisée qu’avec l’Editeur de styles de Zotero. Il faut en effet exporter les exemples de sa bibliothèque Zotero au format CSL-JSON, puis les importer dans l’interface de l’éditeur depuis le menu Example citations > Citation n > Advanced. Cet export/import n’est pas dynamique et devra être renouvelé à chaque nouvelle connexion à l’interface, et après chaque modification apportée aux références dans votre bibliothèque Zotero

• L’utilisation de cet outil suppose, par définition, une connexion Internet – ce qui peut être embêtant lorsque vous êtes en déplacement sans accès wifi fiable ;).

Au final, l’éditeur en ligne nous semble particulièrement recommandable, outre pour la recherche par exemple, dans les cas suivants.

• Le style cible nécessite seulement des modifications mineures du style source.
• Les types de document à prendre en compte sont limitées et correspondent aux exemples de l’interface.
• Il s’agit de se familiariser visuellement avec le langage CSL.

L’éditeur de texte

Une dernière option reste bien sûr le traditionnel éditeur de texte, dont les fonctionnalités varient en fonction de l’application choisie. Vous retrouverez toujours toutefois au moins :

• la possibilité de rechercher-remplacer du code,
• la possibilité de visualiser votre fichier sur la totalité de l’espace de votre écran,
• la possibilité de travailler hors ligne.

Citons quelques exemples d’éditeur gratuits utilisés par la rédaction, que viendront compléter nous l’espérons vos suggestions et compléments en commentaire au présent billet.

• Atom : disponible sur Linux, Mac, Windows (logiciel libre, licence MIT)
• NotePad++ : disponible sur Windows et Linux (logiciel libre, licence GNU GPL)
• TextWrangler : disponible uniquement sur Mac (logiciel propriétaire)

Avantages

• La plupart des éditeurs intègrent des aides à la saisie comme la coloration syntaxique, l’indentation du code, ou encore l’ajout automatique du guillemet fermant lorsque l’on insère un guillemet ouvrant.
• Un éditeur XML permettra un contrôle tant du caractère bien formé que de la validité de votre fichier.

Limites

• La prévisualisation des modifications n’est possible qu’indirectement, en utilisant conjointement l’éditeur de style de Zotero.
• Les erreurs de syntaxe ne sont pas forcément signalées ni immédiatement ni à l’enregistrement du fichier, ce qui peut occasionner de longs et déprimants rapports d’erreur lorsque l’on valide ensuite le fichier.

En résumé, l’éditeur de texte nous semble plus particulièrement recommandable :

• pour un travail d’édition conséquent,
• lorsqu’on est familier de CSL.

Validateur en ligne

Comme nous l’avons vu, tous les outils n’assurent pas la validation CSL, indispensable pour installer et utiliser votre style, et bien sûr pour le soumettre au dépôt CSL si son champ d’application dépasse un usage personnel ou local.
Pendant de l’éditeur en ligne, le validateur en ligne http://validator.citationstyles.org/ vérifie la validité de votre fichier, et surtout affiche le cas échéant de façon détaillée les erreurs à corriger.

Chacun peut donc se constituer sa boîte à outils CSL en fonction de son contexte de travail, de l’ampleur du travail d’édition à effectuer, de la variété des types de document cités et à prendre en compte dans le paramétrage, ou encore bien sûr de ses habitudes et préférences personnelles.
Qu’avez-vous mis dans la vôtre?

Mise à jour du 2018-01-18 : Nous ajoutons à notre boîte à outils l’outil de formatage du code en ligne http://formatter.citationstyles.org/, pour notamment réindenter facilement et rapidement le code. Merci à Rintze Zelle pour cet ajout signalé sur Twitter !

And you could briefly mention https://t.co/GloV4OutfS, which makes it very easy to reindent the XML style code.

— Rintze Zelle (@rintzezelle) 18 janvier 2018

---

---