Références croisées

Introduction

Les références croisées dans Quarto permettent une navigation transparente entre différentes entités telles que les figures, les tableaux, les sections et les équations, ce qui améliore significativement la lisibilité et l’accessibilité des documents.

Les références croisées nécessitent des étiquettes uniques pour chaque entité. Par exemple, #fig-element désigne une figure et #tbl-element désigne un tableau. Cela permet un référencement facile ailleurs dans le document.

Vous apprendrez à:

Référencement croisé des figures, des tableaux et des listes de codes.
Créer des références croisées personnalisées.
Utiliser des sous-références pour les éléments imbriqués.
Inclure les valeurs computationnelles dans les légendes.
Personnaliser l’apparence des références croisées.
Liste de toutes les figures, de tous les tableaux et de toutes les listes de codes dans un document.
Renvoi aux notifications, théorèmes et preuves.
Renvoi aux sections, diagrammes et vidéos.
Renvoi à des figures supplémentaires.

Exemple de figures:

![Un éléphant](elephant.png){#fig-elephant}

Pour faire référence à cette figure ailleurs, utilisez le préfixe @:

Voir @fig-elephant pour une illustration.

Note

Évitez les underscores pour éviter les problèmes de rendu LaTeX.

Entités pouvant faire l’objet de références croisées

Figures, Tableaux et Liste de codes
Prend en charge les figures et les tableaux générés à partir de cellules de code exécutables en utilisant Knitr ou Jupyter.
Les listes de figures, de tableaux, etc. peuvent être utilisées dans les documents suivants : Notifications, Théorèmes et preuves et Equations
Sections

Personnaliser l’apparence :

Type de vidéo	Syntaxe	Sortie
Défaut	`@fig-elephant`	Figure 1
Préfixe personnalisé	`[Fig @fig-elephant]`	Fig 1
Pas de préfixe	`[-@fig-elephant]`	1

Regroupez les références croisées en utilisant la syntaxe suivante:

Comme illustré dans [@fig-elephant; @fig-panther; @fig-rabbit].

Listes

Pour les PDF:

Use \listoffigures, \listoftables and \listoflistings to produce listings of all figure, table, etc.
Personnaliser les titres avec les options lof-title, lot-title, et lol-title.

Exemple:

---
title: "Mon document"
crossref:
  lof-title: "List of Figures"
format: pdf
---

\listoffigures

Note

Les titres par défaut des listes utilisent la forme affichée ci-dessus (c.-à-d. ‘Liste des <Type de vidéo>’).

Figures

Pour en savoir plus sur le référencement des figures et des sous-figures, voir Figures.

Tableaux

Pour en savoir plus sur le référencement des tableaux et sous-tableaux, voir Tableaux.

Liste des codes

Pour rendre un bloc de code référençable, utilisez un préfixe #lst- et lst-cap pour la légende:

```{#lst-customers .sql lst-cap="Requête clients"}
SELECT * FROM Customers
```
Y faire référence avec (@lst-customers).

Pour une référence croisée utilisant la syntaxe div, enveloppez le code et la légende dans une div ::: {#lst-} div:

::: {#lst-customers}

```{.sql}
SELECT * FROM Customers
```

Requête clients
:::

Pour le référencement des blocs de code exécutables, utilisez lst-label pour l’identifiant avec un préfixe lst- et lst-cap pour la légende. La valeur de lst-cap fournit la légende de la liste de codes:

```{python}
#| lst-label : lst-import
#| lst-cap : Importer pyplot

import matplotlib.pyplot as plt
```

@lst-import...

Résultats du rendu:

Listing 1: Importer pyplot

import matplotlib.pyplot as plt

Listing 1…

Pour les cellules de code générant des figures ou des tableaux, utilisez lst-, label et fig-cap/tbl-cap pour le référencement croisé du code et de sa sortie:

```{python}
#| label: fig-plot
#| fig-cap: Légende de la figure
#| lst-label : lst-plot
#| lst-cap : Légende de la liste

plt.plot([1,23,2,4])
plt.show()
```

Le code dans @lst-plot produit la figure dans @fig-plot.

Sortie:

Listing 2: Légende de la liste

plt.plot([1,23,2,4])
plt.show()

Le code dans Listing 2 produit le graphique dans Figure 1.

Notifications

Pour référencer une notification, utilisez un ID avec un préfixe de notification (voir Table 1) et faites-y référence avec @. Exemple : ajouter #tip-exemple à la notification et y faire référence:

::: {#tip-exemple .callout-tip}
## Référencement croisé d'un conseil

Ajouter un ID commençant par `#tip-` pour référencer un conseil.
:::

Voir @tip-exemple...

Sortie:

Tip 1: Référencement croisé d’un conseil

Ajouter un ID commençant par #tip- pour référencer un conseil.

Voir Tip 1…

Les préfixes de chaque type de notification sont les suivants:

Table 1: Préfixes pour les références croisées des notifications

Type de vidéo de notification	Préfixe
`note`	`#nte-`
`tip`	`#tip-`
`warning`	`#wrn-`
`important`	`#imp-`
`caution`	`#cau-`

Théorèmes et preuves

Pour inclure un théorème référençable, utilisez une div avec une étiquette #thm- et indiquez le nom du théorème dans le premier titre. Vous pouvez ajouter n’importe quel contenu à l’intérieur de la div:

::: {#thm-line}

## Équation de la ligne

L'équation d'une droite quelconque peut s'écrire comme suit:

$$
y = mx + b
$$
:::

Voir @thm-line.

Sortie:

Théorème 1 (Équation de la ligne) L’équation d’une droite quelconque peut s’écrire comme suit:

\[ y = mx + b \]

Voir Théorème 1.

Variantes de théorèmes supportées et leur préfixe d’étiquette:

Préfixe d’étiquette	Nom affiché	Environnement LaTeX
`#thm-`	Théorème	théorème
`#lem-`	lemme	lemme
`#cor-`	Corollaire	corollaire
`#prp-`	Proposition	proposition
`#cnj-`	Conjecture	conjecture
`#def-`	Définition	définition
`#exm-`	Exemple	exemple
`#exr-`	Exercice	exercice
`#sol-`	Solution	solution
`#rem-`	Remarque	remarque

Créez une preuve en ajoutant la classe .proof à une div:

::: {.proof}
Par induction.
:::

Note

proof n’est pas numérotée (et ne peut donc pas faire l’objet de référencements croisés). Comme pour les théorèmes, vous pouvez inclure un titre comme premier élément de la division.

Equations

Étiqueter les équations avec #eq- immédiatement après pour les rendre référençables:

Les équations linéaires (@eq-linear) sont de la forme:
 
$$
y = mx + b
$$ {#eq-linear}

Sortie:

Les équations linéaires (Équation 1) sont de la forme:

\[ y = mx + b \tag{1}\]

Sections

Ajouter #sec- aux titres pour les références de section:

## Introduction {#introduction}

Se référer à @sec-introduction pour plus de détails.

Activez l’option number-sections dans les métadonnées du document pour une numérotation visible:

---
title: "Mon document"
number-sections: true
---

Diagrammes

Ajouter le préfixe fig- à l’ID d’une div pour les référencements croisés.
Pour y faire référence en tant que figure, utilisez le préfixe @. Par exemple, Figure 2 est créé en utilisant:

::: {#fig-simple}

```{dot}
graph {
  A -- B
}
```

Graphique simple de graphviz
:::

Figure 2: Il s’agit d’un simple graphique graphviz

Vidéos

Utilisez la syntaxe div pour ajouter une vidéo et une légende, puis la référencer en tant que figure:

::: {#fig-cern}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

La vidéo 'CERN : le voyage de la découverte'

:::

Dans @fig-cern...

Ce qui donne:

Capture d'écran d'une vidéo YouTube

Si vous préférez donner aux vidéos une étiquette et un compteur distincts des figures, envisagez de définir des Type de vidéos de références croisées personnalisés.

Sous-références

Note

Lorsque votre sous-contenu ne comporte que des figures ou que des tableaux, il existe une syntaxe abrégée, voir la page Références croisées pour Sous-figures et Sous-tables pour plus de détails.

Utiliser des divs imbriqués pour créer des éléments avec des sous-références:

Div extérieure : Référence principale (fig-subrefs) avec une légende générale.
Divs internes : Références spécifiques (fig-first, fig-second) avec légendes individuelles.

:::: {#fig-subrefs}

::: {#fig-first}
CONTENU 1

Première légende
:::

::: {#fig-second}
CONTENU 2

Deuxième légende
:::

Légende principale
::::

Ce qui donne:

CONTENU 1

(a) Première légende

CONTENU 2

(b) Deuxième légende

Figure 3: Légende principale

L’élément principal et les sous-éléments peuvent être référencés directement dans le texte, par ex.

@fig-subrefs, @fig-first, @fig-second

Cela se traduit par : Figure 3, Figure 3 (a), Figure 3 (b).

Combinés aux attributs de mise en page, vous pouvez créer des mises en page complexes de contenus mixtes où chaque élément peut être référencé. Par exemple:

:::: {#fig-complex layout="[[1, 1], [1]]"}

::: {#fig-elephant}

![](images/elephant.jpg)

Un fichier image
:::

::: {#fig-scatterplot}

```{r}
#| echo: false
plot(1:10)
```

Une figure computationnelle
:::

::: {#fig-diagram}

```{dot}
//| fig-height: 2
digraph {
  rankdir = "LR";
  Transform -> Visualize
}
```

Un diagramme
:::

Exemple de figure combinant différents types de contenu
::::

Ce qui donne:

Disposition complexe des figures avec une image, un graphique et un diagramme

Légendes computationnelles

Si vous souhaitez inclure des valeurs computationnelles dans une légende, utilisez la syntaxe div de référence croisée, ainsi qu’une expression de code en ligne:

Python
R

::: {#fig-box}

```{python}
#| echo: false
import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5, 10]
p = plt.boxplot(x)
plt.show()
```

Cette donnée contient des observations `{python} len(x)`.

:::

::: {#fig-box}

```{r}
#| echo: false


x <- c(1, 2, 3, 4, 5, 10)
boxplot(x)

```

Cette donnée comporte `{r} length(x)` observations.

:::

Référence croisée personnalisée

Les références croisées Float comme les figures, les tableaux et les listes de codes peuvent flotter dans le document avec des légendes.
Définir des flottants personnalisés dans YAML avec:
- kind: Must be float.
- key: Abbreviation for reference ID (e.g., vid pour la vidéo).
- reference-prefix: Texte pour la référence de sortie (par exemple, ‘Dans la Figure 1, …’).
- caption-prefix: Texte pour la légende (par exemple, ‘Figure 1 : …’). La valeur par défaut est reference-prefix si elle n’est pas spécifiée.

Vidéo

Exemple:

crossref:
  custom:
    - kind: float
      reference-prefix: Vidéo
      key: vid

Référence avec:

::: {#vid-cern}



'CERN : le voyage de la découverte'
:::

Dans @vid-cern.

Sortie:

Vidéo 1: ‘CERN : le voyage de la découverte’

Dans Vidéo 1…

Sortie PDF

Ajouter latex-env dans YAML pour nommer l’environnement float dans TeX pour les références personnalisées, comme video pour les vidéos:

format: pdf
crossref:
  custom:
    - kind: float
      reference-prefix: Vidéo
      key: vid
      latex-env: video

\listofvideos{}

Use \listof command in LaTeX for listing custom references, appending s to latex-env, like \listofvideos{} for videos.
Le titre de la Liste est par défaut le titre de l’article reference-prefix, but you can customize it with latex-list-of-description.

Figures supplémentaires

Pour les figures supplémentaires dans un document:

Ils doivent faire l’objet d’un compteur distinct de celui des figures ordinaires.
Les étiquettes doivent être ‘Figure S1’, ‘Figure S2’, etc.
Inclure une section ‘Liste des figures supplémentaires’.

Définissez ce type comme suit:

crossref:
  custom:
    - kind: float
      key: suppfig
      latex-env: suppfig
      reference-prefix: Figure S
      space-before-numbering: false
      latex-list-of-description: Supplementary Figure

Note

Notez l’utilisation de space-before-numbering : false, qui empêche l’insertion d’un espace entre le reference-prefix ou le caption-prefix et le compteur, de sorte que les étiquettes apparaissent sous la forme de ‘Figure S1’, ‘Figure S2’, etc.