Format du document : notes et références

#Notes de bas de page

Une note de bas de page a deux parties : l’appel [^id] là où la note est citée, et la définition, un paragraphe à part qui commence par [^id]: n’importe où dans le chapitre.

The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.
 
[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.

• Appel. [^id] imprime le numéro de la note en exposant, collé au mot qui le précède (écrivez-le après la ponctuation, comme ci-dessus). L’identifiant accepte les lettres, les chiffres, -, _, . et :. L’appel fonctionne dans les paragraphes, les éléments de liste, les citations et les encadrés ; dans les titres, les légendes et les cellules de tableau, il s’imprime tel qu’il est écrit.
• Définition. Un paragraphe qui commence par [^id]: ; son texte court jusqu’à la ligne vide suivante et accepte les marques en ligne habituelles (gras, italique, liens, :ref, formules, pastilles). Les définitions sortent du flux où qu’elles soient écrites : elles peuvent donc se trouver sous le paragraphe qui les cite ou toutes ensemble à la fin du chapitre. La première définition d’un identifiant l’emporte.
• Numéros. Les notes sont numérotées dans l’ordre de leur première citation, en recommençant à chaque chapitre (un titre de niveau 1, et chaque document d’un livre) ; une note citée deux fois garde son premier numéro et n’est composée qu’une fois. footnotes.numbering: 'document' continue la numérotation dans tout le livre, et 'page' la recommence à chaque page, comme le font les livres chinois ; footnotes.numberFormat: 'circled-decimal' écrit ① ② ③ sur la ligne de base. footnotes.numberFormat: 'symbols' les marque *, †, ‡, §, ‖, ¶, puis doublés, en recommençant à chaque page, comme le font les revues.
• Texte japonais. Écrivez l’appel avant un 。 de fin de phrase (先生[^1]。) : il reste avec le caractère qui le précède, et 。 n’ouvre jamais une ligne. Un livre japonais vertical compose par défaut ses appels （1） à droite de la ligne et ses notes après le chapitre ; footnotes.markerPosition: 'side' place un petit appel à côté du mot, sans prendre de place dans la ligne, et footnotes.placement: 'spread' compose les notes à côté du texte de chaque double page (voir Configuration › Notes de bas de page).
• Où va la note. Par défaut, au pied de la colonne qui contient la ligne qui la cite, sous un court filet : la ligne et sa note partagent toujours une colonne, et une ligne dont la note ne tient pas passe plus loin avec elle. Dans une mise en page à une colonne, c’est le pied de la page. footnotes.placement: 'chapterEnd' compose plutôt toutes les notes d’un chapitre après son dernier bloc, par défaut au pied de la colonne qu’elles terminent. Voir Notes de bas de page dans la référence de configuration pour les tailles, le filet et l’espacement.
• Vérifications. Un appel sans définition (undefinedFootnote) imprime son numéro au-dessus d’une note vide ; une définition qu’aucun appel ne cite (unusedFootnote) n’est pas composée. Le Sandbox liste les deux dans le panneau Vérifications.

#Renvois et ancres

Un renvoi désigne un endroit du livre et imprime son numéro, son titre ou sa page : voir la section 3.2, comme l’explique le chapitre 4, à la p. 112. Les mots et les numéros suivent le texte : déplacer une section, renuméroter les chapitres ou recomposer le livre met à jour tous les renvois. Dans le PDF, le HTML et les aperçus du Sandbox, chaque renvoi est un lien : un clic mène le lecteur à sa cible, y compris dans un autre chapitre.

Ancres. Un renvoi a besoin d’une cible :

• Un titre avec un identifiant : ## Method {#sec-method} (la forme de Pandoc ; id="sec-method" fonctionne aussi).
• Un encadré ou un autre conteneur ouvert avec un identifiant : :::callout{#box-safety title="Safety"}. Un encadré d’un style numéroté (un théorème) est désigné par son libellé et son numéro : Théorème 2.
• Une formule en display avec un \label{eq:x} (voir Formules mathématiques) : un renvoi imprime son numéro comme le fait la formule, (3).
• Un point du texte : :anchor{#key-idea} pose une ancre invisible ; [the key idea]{#key-idea} garde ses mots et leur donne un nom.

Un identifiant accepte les lettres, les chiffres, -, _, . et :. Il doit être unique dans le livre : le panneau Vérifications liste un identifiant défini deux fois (duplicateAnchor), et les renvois mènent à sa première définition.

Renvois. :ref{id="…"} désigne une ancre de la même façon qu’il désigne une figure ou un tableau :

## Method {#sec-method}
 
The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}.

Les commandes LaTeX \eqref{x} et \ref{x} fonctionnent aussi dans le texte : \eqref comme un renvoi sans style, \ref comme style=number, si bien que \ref{thm:main} imprime 2 et \ref{fig:map} le numéro d’une figure. Un ~ placé juste avant est une espace insécable (Theorem~\ref{thm:main}). À l’intérieur de $…$, elles appartiennent à la formule.

text="…" imprime vos propres mots et reste un lien ; case=capitalize commence le libellé par une capitale (Section 3.2 en début de phrase). Les mots suivent la langue du document (sección 3.2, 第3.2节, S. 112) et peuvent être modifiés dans Renvois dans la configuration ; un numéro de titre que son modèle écrit déjà en toutes lettres (Chapitre 4, 第四章) s’imprime tel quel.

Sauts de ligne. Un renvoi qui imprime des mots est coupé à ses espaces comme le texte qui l’entoure : le texte d’une ancre ([close the lever so that it points backwards]{#step}), un titre, votre propre text="…". Ses espaces sont des espaces de la ligne : sur une ligne justifiée, elles s’étirent avec les autres, et le renvoi reste un seul lien, en deux morceaux quand il court sur deux lignes. Ses mots ne reçoivent jamais de césure. Dans un tel libellé, un nombre, un chiffre romain ou une lettre seule reste avec le mot qui le précède, si bien que text="Fig. 1a" ou text="plate IV" n’est jamais séparé. Un libellé qui porte un numéro ou une page (section 3.2, p. 112, Fig. 1.7, Théorème 2) n’est jamais coupé, quelle que soit l’espace que contient son modèle, et une espace insécable dans un libellé lie comme partout ailleurs. crossRefs.breakLabels: false garde chaque libellé entier, comme jusqu’à postext 1.27, quand un libellé était un seul mot qui ne pouvait pas remonter sur la ligne précédente ; voir Renvois.

Les renvois de page ne sont connus qu’une fois le livre mis en page. Le moteur remet le document en page avec les pages de la passe précédente jusqu’à ce qu’elles se stabilisent, comme il le fait pour la table des matières ; d’ici là, une page s’imprime ?.

pandoc-crossref. Un texte écrit pour pandoc-crossref se lit de la même façon : @sec:method, [@fig:map], et [-@tbl:data] pour le numéro seul. Le préfixe (sec, fig, tbl, eq, lst) peut faire partie de l’identifiant ({#sec:method}) ou en être omis ({#method}). Un @ collé à un mot, comme dans une adresse électronique, reste du texte.

Un renvoi vers un identifiant que rien ne définit imprime ? et le panneau Vérifications le liste (unknownResourceId). Dans l’éditeur du Sandbox, @ propose les figures, les tableaux, les titres munis d’un identifiant et les ancres du livre.

#Citations et bibliographie

Écrivez les citations comme Pandoc les lit, gardez les références dans le document et choisissez le style de citation dans les réglages : passer d’APA à IEEE, ou aux notes Chicago, change le réglage de style, pas le texte. Chaque citation renvoie par un lien à son entrée dans la bibliographie.

#Citer

As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004].
@garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees.

• [@key] cite entre parenthèses ; plusieurs ouvrages se placent dans une même paire de crochets, séparés par ;.
• Localisateur : après une virgule, p. 33, pp. 4–6, chap. 2, sec. IV, fig. 3, vol. 2, n. 12, l. 4, § 4.2 ; un nombre seul est une page. Les termes espagnols (pág., cap.) et chinois (页, 章) fonctionnent aussi. Un intervalle prend un tiret demi-cadratin ou les deux traits d’union de TeX : pp. 4--6 imprime 4–6.
• Préfixe et suffixe : du texte avant le @ (see) et après la clé ou le localisateur (, emphasis added). Le suffixe garde la virgule écrite devant lui, avec ou sans localisateur : [@brown2020, inter alia] imprime (Brown et al., 2020, inter alia), comme le fait Pandoc ; écrit sans virgule ([@brown2020 inter alia]), il n’en a pas. L’emphase dans un préfixe ou un suffixe est composée en emphase dans tous les styles : [*e.g.*, @brown2020, *inter alia*].
• [-@key] omet l’auteur, pour une phrase qui le nomme déjà.
• @key cite dans la phrase (García (2020)) ; @key [p. 4] ajoute un localisateur.
• Dans les légendes : la légende d’une figure ou d’un tableau, et sa note, citent comme le fait le texte (Prior best from [@cobbe2021].). Leurs ouvrages entrent dans la bibliographie sans nocite, et un style numéroté les numérote là où la ressource est placée : après les citations du paragraphe qui y fait référence en premier (son bloc ::resource ou son premier :ref). Une citation dans une cellule de tableau reste du texte.
• Un @ collé à une lettre ou à un chiffre (une adresse électronique), un @ dans du code en ligne et \@ sont du texte. Une citation pour laquelle le livre n’a pas de référence s’imprime telle qu’elle est écrite, si bien qu’un document sans références se lit comme avant. Dans une citation de plusieurs ouvrages, une clé qu’aucune référence ne définit est imprimée en gras après les autres ((Glen, 1955) **@nye1953**), pour que l’ouvrage manquant apparaisse sur la page autant que parmi les avertissements. Un deux-points après une citation est du texte : [@french2018]: the land….
• Dans un texte chinois, japonais ou coréen, une citation suit le dernier caractère sans espace (周明远@zhou2019认为), et une citation auteur-date prend les signes pleine chasse du texte qui l’entoure : （施雅风等，1988；刘时银等，2015）.

#Références

Les références s’écrivent dans le document, au format CSL (le modèle de données de Zotero et de Pandoc) :

---
references:
  - id: garcia2020
    type: book
    author: [{family: García, given: Ana}]
    title: Tipografía y lectura
    issued: 2020
    publisher: Trea
nocite: "@lopez2019"
---

ou dans un bloc :::references, en BibTeX (un export de Zotero, JabRef ou Google Scholar), en CSL-JSON ou en CSL-YAML :

:::references{format=bibtex}
@article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla},
  journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}}
:::

Le bloc n’imprime rien. nocite liste des ouvrages sans les citer (@* : tous). Dans un livre, les références écrites dans n’importe quel chapitre valent pour tout le livre.

Dans une liste de noms BibTeX, and others représente les noms omis (author = {Tan, Wei and others}) : tous les styles impriment et al. à leur place. En YAML, écrivez others comme dernier nom de la liste.

#La bibliographie

:::bibliography compose la liste des ouvrages cités là où il se trouve ; en son absence, la liste suit le dernier chapitre, avec un titre dans la langue du document (References, Referencias, 参考文献). :::bibliography{title="Works cited"} change le titre et title="" le supprime ; scope=chapter liste les ouvrages que cite le chapitre (un ouvrage collectif). Chaque entrée est une ancre (ref-<key>) : un lien Markdown vers #ref-garcia2020 y mène, et le PDF la balise comme BibEntry.

scope=new liste les ouvrages cités jusque-là dans le document qu’aucune liste précédente n’a imprimés, dans l’ordre du style et avec ses numéros : un :::bibliography{scope=new} après le texte principal et un autre après les Methods donnent les deux listes d’un article de Nature, la seconde numérotée à la suite de la première. Un style numéroté compte ses citations sur tout le livre ; avec citations.numbering: 'chapter', chaque chapitre (chaque document, et chaque titre de niveau 1 placé après une citation) numérote les siennes à partir de 1, et sa liste de chapitre reprend ces numéros, comme le font les rapports d’un bulletin ou les communications d’actes de colloque.

#Styles

Le style décide de ce que disent une citation et une entrée. Les styles fournis sont listés ci-dessous ; tout autre style CSL (il y en a plus de dix mille dans le dépôt de styles de Zotero) peut être chargé depuis son fichier .csl dans Réglages → Citations.

Avec un style à notes, chaque citation devient une note de bas de page, placée et numérotée selon les réglages des notes de bas de page ; les citations ultérieures du même ouvrage prennent une forme abrégée. Dans un texte chinois, citations.notes: 'warichu' les compose comme des notes sur deux rangées à l’intérieur de la ligne (夹注) ; une note suivie d’un signe chinois (，, 。) perd son propre point final.

Chinois. Les styles GB/T 7714-2015 écrivent les codes de type de document ([M], [J], [D], [EB/OL]), gardent les noms chinois entiers et écrivent 等 après trois auteurs d’un ouvrage chinois et et al. après ceux d’un ouvrage occidental, en choisissant selon la language de chaque ouvrage. Dans le texte vertical, un numéro en exposant se place à droite de son caractère ; citations.marker: 'corner' écrit 〔1〕, qui reste debout.

Moteur. Les citations sont mises en forme par le paquet postext-citeproc (citeproc-js et les styles CSL). Le Sandbox le charge pour les documents qui citent ; dans votre propre code, enregistrez-le avant la mise en page :

import 'postext-citeproc/register';

Le panneau Vérifications liste une clé qu’aucune référence ne définit (unknownCitationKey) et un bloc de références illisible (referencesUnreadable).

#Index

Un index liste les termes d’un livre avec les pages où ils apparaissent. Marquez chaque terme là où le texte en traite et imprimez l’index avec :::index là où il doit se trouver, en général dans un chapitre à part à la fin. Le moteur trouve la page de chaque marque après la mise en page, si bien que les numéros suivent le texte : ajoutez un paragraphe, déplacez un chapitre ou changez le format, et l’index imprime les nouvelles pages.

Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}
 
# Index {style="index"}
 
:::index

#Marques d’index

• :index[text] imprime text et le classe sous ses propres mots. Les marques en ligne qu’il contient s’impriment et sont retirées de l’entrée. Des attributs après le crochet le classent ailleurs : :index[iron deficiency]{term="Anaemia!iron-deficiency"}.
• :index{term="…"} n’imprime rien. La marque prend la page du mot écrit juste avant elle sur sa ligne ou, quand elle ouvre une ligne, celle du mot qui la suit. Une ligne qui ne contient que des marques est supprimée : une marque sur une ligne à part ne scinde donc jamais un paragraphe et n’ajoute pas d’espace.
• Où. Paragraphes, titres, éléments de liste, citations, encadrés et définitions de notes de bas de page. Dans les légendes, les cellules de tableau et les éléments de maquette, une marque s’imprime telle qu’elle est écrite. Dans du code en ligne, et après une barre oblique inverse (\:index), c’est du texte.

Une marque sans terme (:index{} ou :index{see="…"} seul) n’indexe rien et déclenche indexMarkInvalid.

#Imprimer l’index

:::index imprime l’index principal là où il se trouve, et :::index{index="names"} un index nommé. La directive se développe en blocs ordinaires, un par entrée, qui suivent le flux des colonnes et des pages comme du texte : sous un titre dont le style de titre définit un layout à deux colonnes, elle donne l’index habituel sur deux colonnes. Un clic sur une entrée mène à la ligne de la directive.

# Index of names {style="index"}
 
:::index{index="names"}
 
# Index of subjects {style="index"}
 
:::index

• Ordre. Les entrées se trient dans l’ordre alphabétique de la langue du document (locale, ou index.locale) : une lettre accentuée se classe avec sa lettre de base (Árbol sous A), et en espagnol ñ vient après n, sous une lettrine de groupe à part. Les entrées qui commencent par un symbole viennent en premier, puis celles qui commencent par un chiffre, puis les lettres. Les sous-entrées se trient de la même façon sous leur entrée, en retrait d’un cran par niveau. Un index japonais trie selon la lecture dans l’ordre de JIS X 4061 et regroupe par rangée du gojūon (あ行, か行…), ses entrées latines avant les kana (voir Mise en page japonaise › Index dans l’ordre du gojūon).
• Groupes. Chaque nouvelle initiale ouvre un groupe : une lettre d’en-tête (index.groups) et une ligne d’espace au-dessus (aucune au-dessus du premier groupe). La lettre d’en-tête est composée en un seul bloc avec la première entrée du groupe, si bien qu’elle ne termine jamais seule une colonne ; une entrée sans page propre (qui ne sert que de tête à ses sous-entrées) est composée avec sa première sous-entrée pour la même raison.
• Numéros de page. Les libellés qu’impriment les pages, y compris les chiffres romains des pages liminaires. Les pages d’une entrée sont triées et chacune n’est listée qu’une fois ; les pages consécutives se regroupent en un intervalle (12–14, index.mergeRanges), une page qui tombe dans un intervalle de la même entrée s’y fond (une page principale à cet endroit met l’intervalle en gras), et index.rangeFormat: 'chicago' abrège le second nombre (234–37). Les pages en gras (principales) restent séparées. Dans le PDF, chaque numéro renvoie par un lien à sa page.
• Les renvois terminent l’entrée : Terme. Voir Cible quand l’entrée n’a pas de pages, Terme, 12. Voir aussi Cible quand elle en a. Les libellés suivent la langue du document (See, Véase…) et peuvent être définis dans index.see.
• Livres. Dans un livre mis en page chapitre par chapitre (le Sandbox, buildBundle), le chapitre qui imprime l’index reçoit les marques de tous les chapitres avec leurs pages, et il n’est remis en page que lorsque l’une d’elles se déplace. Un document qui contient à la fois ses marques et son index est remis en page jusqu’à ce que les numéros se stabilisent, comme avec :::toc.

Voir Index dans la référence de configuration pour la typographie, les retraits et les séparateurs.