Premier jet Utilisation avancée de Zotero

Documentation/GUIDE_CSL-Clio.md

@@ -171,22 +171,83 @@ Pour l'instant, le projet *CSL/Clio* est surtout informé par ma pratique de doc
 
 # Gérer ses données bibliographiques avec *Zotero*
 
+Pour pouvoir utiliser les styles de *CSL/Clio*, il est tout d'abord primordial de bien enregistrer sa bibliographie dans son gestionnaire. Dans cette partie, nous allons tout d'abord indiquer quelques fonctionnalités auxquelles nous ferons référence par la suite, puis nous allons indiquer les conventions utilisées par *CSL/Clio* pour l'enregistrement des données bibliographiques. Comme le reste de ce manuel, cette section prend l'exemple de *Zotero* parce que c'est le logiciel que j'utilise. Si vous utilisez un autre logiciel et que vous constatiez des différences, n'hésitez pas à me les signaler : je me ferai un plaisir de les indiquer dans ce guide.
+
 ## Utilisation avancée de *Zotero*
 
 ### Indications de mise en forme dans une valeur de champ
 
-### Intervalles de dates
+Il est possible de mettre certaines parties des valeurs que vous renseignez dans les champs en italiques, gras, petites capitales, indice ou exposant. C'est utile, notamment, lorsqu'un titre cite un autre titre, comme dans la [@fig:titre-dans-titre] (noter que, dans ce cas, si le titre principal était en italiques, *Dialogica polymorpha antiiudaica* serait en caractères droits).
+
+![Utilisations de balises pour mettre en valeur un titre cité dans un autre titre](titre-dans-titre.png){#fig:titre-dans-titre}
+
+Vous trouverez plus d'informations [ici](https://citationstyles.org/authors/#/rich-text-within-fields). <!-- TODO : vérifier le point suivant --> Il s'agit d'une fonctionnalité recommandée par CSL (mais absente des spécifications) et supportée au moins par les processeurs [*citeproc*](https://pandoc.org/MANUAL.html#specifying-bibliographic-data) (utilisé par *Pandoc*) et [*citeproc-js*](https://www.zotero.org/support/fr/kb/rich_text_bibliography) (utilisé par *Zotero* et d'autres gestionnaires de bibliographie).
 
 ### Champ *Extra*
 
+L'interface de *Zotero* contient un champ *Extra* dans lequel l'utilisateur peut renseigner des variables qui ne sont pas prévues dans les champs proposés par défaut pour le type de document sélectionné. La syntaxe utilisée est *variable: valeur*, chaque variable étant séparée de la précédente par un passage à la ligne. Une valeur peut contenir des espaces. Pour citer un individu, il faut séparer son nom de son prénom par deux barres verticales (Altgr+6 sur un clavier AZERTY). *Le nom de la variable est celui prévu dans les [spécifications CSL](https://docs.citationstyles.org/en/1.0.1/specification.html#appendix-iv-variables), pas celui affiché dans l'interface de* Zotero *!*
+
+Exemples :
+
+> annote: Titre de la source
+> editor: Nom || Prénom
+> ~~annote: "Titre de la source"~~
+> ~~Éditeur: Nom || Prénom~~
+
+### Intervalles de dates
+
+Le champ *Date* ne supporte pas les intervalles tels que « 2009–2011 ». Lorsque vous entrez plusieurs nombres séparés par des tirets, *Zotero* les interprète comme des indications de jour, mois et année. Pour indiquer un intervalle de date dans *Zotero*, vous devez laisser le champ *Date* vide et renseigner la date dans le champ *Extra* comme valeur de la variable `issued` en utilisant la syntaxe *année-mois-jour/année-mois-jour*, où *mois* et *jour* sont optionnels et où les deux dates doivent compter le même nombre d'éléments.
+
+Exemples :
+
+> issued: 1999-09/1999-12\
+> issued: 1999-09/2000-01\
+> issued: 1999/2000
+> ~~issued: 1999-09/12~~
+> ~~issued: 1999-09/2000~~
+
 ### Console JavaScript
 
-<!-- Mettre ici le code pour passer de abstract à annote -->
+Une console JavaScript est accessible dans l'interface de *Zotero* via le menu *Outils > Développeur > Run JavaScript*. Elle permet d'automatiser certaines tâches laborieuses dans la gestion de la base de données bibliographique, et peut être utile si vous avez besoin de modifier de manière systématique l'enregistrement de certaines informations pour utiliser les styles de *CSL/Clio*. À titre d'exemple, il fut un temps où j'enregistrais les titres de sources dans le champ *Résumé* ; lorsque j'ai dû les transférer de la variable `abstract` (correspondant au champ *Résumé*) à la variable `annote` (à enregistrer dans *Extra*), j'ai pu le faire en utilisant le code suivant (les lignes commençant par `//` sont des commentaires que j'ai ajoutés pour expliquer le déroulement de l'algorithme) :
+
+~~~ {.javascript}
+// Récupérer la collection sélectionnée dans l'interface.
+var collection = ZoteroPane.getSelectedCollection();
+// Récupérer les notices dans la collection.
+var items = collection.getChildItems();
+// Pour chaque notice...
+for (let item of items) {
+  // Récupérer la valeur du champ Résumé.
+  let sourceName = item.getField('abstractNote')
+  // Passer directement à la notice suivante si cette
+  // valeur est nulle.
+  if (!sourceName) continue
+  // Si cette valeur est renseignée, récupérer la
+  // valeur du champ Extra.
+  let extraField = item.getField('extra')
+  // Ajouter à cette valeur un passage à la ligne (\n),
+  // puis "annote: ", puis la valeur de Résumé.
+  item.setField('extra', extraField + '\nannote: ' + sourceName)
+  // Vider le champ Résumé.
+  item.setField('abstractNote', '')
+  // Sauvegarder le résultat.
+  item.saveTx()
+}
+~~~
+
+On pourra trouver sur [le site de la Mozilla Foundation](https://developer.mozilla.org/en-US/docs/Web/Tutorials<!-- REF plus précise -->) des ressources sur JavaScript (seules les connaissances les plus basiques sont requises). Le [site de *Zotero*](https://www.zotero.org/support/dev/client_coding/javascript_api) contient une introduction et de nombreux exemples. N'hésitez pas à [demander de l'aide](#demander-de-laide-et-signaler-des-bugs) !
+
+Attention : avant d'utiliser la console, faites une sauvegarde de votre répertoire de données, dont l'emplacement peut être trouvé via le menu *Édition > Préférences > Avancées > Fichiers et dossiers*. Les modifications ne sont pas réversibles ! Après avoir appliqué vos modifications, il peut être judicieux de cliquer sur *Vérifier l'intégrité de la base de données* dans le même menu.
 
 ### Export d'une collection en format CSL JSON
 
+*Zotero* permet également, par un simple clic droit, d'exporter une collection dans le format de votre choix. Vous pouvez ainsi exporter une collection dans un fichier texte, opérer des modifications automatiques et réimporter le fichier obtenu dans *Zotero*. Dans ce cas, le format CSL JSON est à préférer car il est facile à comprendre et utilise les variables de CSL. Notez toutefois que vous perdrez vos notes, marqueurs et fichiers attachés si vous procédez ainsi.
+
+<!-- TODO : référence à correct-json si ça peut être utile, mais il n'est plus nécessaire pour Pandoc -->
+
 ### Liste d'abréviations
 
+
 ### Demander de l'aide et signaler des bugs
 
 ## Enregistrement des documents selon les conventions de *CSL/Clio*
@@ -211,10 +272,14 @@ Pour l'instant, le projet *CSL/Clio* est surtout informé par ma pratique de doc
 
 ## Pratiques à éviter
 
-### Abréger les prénoms
-
 ### Faire confiance à l'enregistrement automatique des références à partir du navigateur
 
+### Mettre en forme les informations en fonction d'un style donné
+
+<!-- Prénoms abrégés : empêche de désambiguiser ; si un même auteur a son prénom abrégé dans une notice et plein dans l'autre il ne sera pas reconnu comme le même auteur et le prénom risque d'être affiché en plein pour la deuxième notice -->
+
+<!-- Date : indiquer de préférence les dates complètes, car CSL prévoit des instructions pour déterminer quelles parties de la date doivent être affichées. -->
+
 # Automatiser la mise en forme
 
 ## Installation