5 Références, glossaire et annotations

Ce chapitre présente le système de citations bibliographiques (style IEEE via IEEEtran-francais.bst), le système de glossaire et d’acronymes, les commentaires collaboratifs, et les pages liminaires spéciales.

5.1 Citations bibliographiques

5.1.1 Syntaxe de base

Les citations s’insèrent avec [@clé]. La clé correspond à l’identifiant BibTeX défini dans references.bib :

La composition typographique informatique a été révolutionnée par Knuth [@Knuth1984],
dont le système \TeX{} a été rendu accessible par Lamport avec \LaTeX{} [@Lamport1994].
Quarto [@Allaire2022] unifie ces outils dans un environnement de publication moderne.

Rendu :

La composition typographique informatique a été révolutionnée par Knuth (Knuth 1984), dont le système a été rendu accessible par Lamport avec (Lamport 1994). Quarto (Allaire et al. 2022) unifie ces outils dans un environnement de publication moderne.

5.1.2 Références multiples

Les outils de visualisation Python [@Hunter2007] et les ouvrages de référence
typographiques [@Bringhurst2004; @Mittelbach2023] complètent la palette de l'auteur.

Rendu :

les outils de visualisation Python (Hunter 2007) et les ouvrages de référence typographiques (Bringhurst 2004; Mittelbach et Fischer 2023) complètent la palette de l’auteur.

Toujours utiliser [@clé] avec les crochets

Le style IEEEtran-francais.bst utilise natbib. La syntaxe @clé sans crochets appelle \citet{} qui est cassé avec IEEEtran — elle produit le nom de l’auteur suivi de [?]. Utilisez toujours [@clé] pour obtenir [N] (numérotation IEEE).

5.1.3 Fichier `references.bib`

Le fichier references.bib doit se trouver à la racine du projet. Pandoc en mode natbib génère \bibliography{references} (sans chemin), et BibTeX cherche le fichier dans le répertoire courant. Un fichier dans content_fr/references.bib ne sera pas trouvé.

Gestionnaires bibliographiques

Zotero (avec le connecteur Better BibTeX), JabRef ou Mendeley exportent directement en format .bib. L’entrée @IEEEtranBSTCTL en tête de fichier configure le style IEEEtran (nombre d’auteurs avant « et al. », etc.) — ne la supprimez pas.

5.2 Glossaire et acronymes

5.2.1 Déclarer des entrées dans `glossaire-entries.qmd`

Toutes les entrées sont déclarées dans content_fr/liminaire/glossaire-entries.qmd via deux shortcodes :

{{< acr label SIGLE "Développé complet" >}}
{{< terme label "mot" "Définition complète du terme" >}}

Les shortcodes écrivent automatiquement _glossaire-entries.tex (lu par LaTeX) et alimentent les tables HTML. Les labels doivent être uniques.

5.2.2 Utiliser les acronymes dans le texte

Quatre shortcodes permettent de référencer un acronyme selon la forme souhaitée :

Table 5.1: Shortcodes de référence du glossaire.

Shortcode	Sortie PDF	Sortie HTML
`{{< gls cnam >}}`	forme courte (1re occur. : longue)	forme courte
`{{< acrs cnam >}}`	toujours forme courte	toujours forme courte
`{{< acrl cnam >}}`	toujours forme longue	toujours forme longue
`{{< acrf cnam >}}`	long (court)	long (court)

Exemples en situation :

Le {{< acrs cnam >}} ({{< acrl cnam >}}) a été fondé en 1794.
Le format {{< acrf qmd >}} est le format natif de Quarto.
La numérotation toc est générée automatiquement par Quarto.

Rendu :

le cnam (cnam) a été fondé en 1794. Le format qmd est le format natif de Quarto.

Comportement PDF vs HTML

En PDF, label expanse à la première occurrence (forme longue + sigle entre parenthèses) puis utilise la forme courte. En HTML, cette logique de première occurrence n’est pas gérée par le shortcode — il produit toujours la forme courte. Pour la cohérence, préférez label à la première occurrence dans le texte, et label ensuite.

5.3 Commentaires collaboratifs (`quarto-comments`)

5.3.1 Configuration dans `_quarto.yml`

L’extension quarto-comments (dossier _extensions/comments/) est configurée via la clé extensions.quarto-comments: dans _quarto.yml :

extensions:
  quarto-comments:
    enabled: true
    authors:
      eb:
        name: "Eric Bavu"
      ag:
        name: "Abbé Grégoire"
      # Couleurs auto depuis la palette Bootstrap 5 ; surcharger si besoin :
      # nc:
      #   name: "Nicolas Conté"
      #   color_html: "#198754"
      #   color_latex: "green!30"

5.3.2 Les quatre types de commentaires

{{< comment "Reformuler cette phrase, elle est trop longue." author="ag" >}}
{{< todo "Ajouter une figure illustrant ce point." author="eb" >}}
{{< note "Voir aussi Bringhurst 2004, §2.4." author="ag" >}}
{{< question "Ce résultat est-il reproductible sur un autre jeu de données ?" author="ag" inline=true >}}

Rendu en situation :

Voici une phrase avec un commentaire du directeur de thèse (qui a ajouté directement celui-ci dans le fichier .qmd parce qu’il n’est pas frileux !).

Abbé Grégoire

Ceci est un commentaire de type ‘comment’ par le directeur.

Ces commentaires ne sont visible que si l’option quarto-comments est à enabled : true dans le fichier yaml, ce qui est le cas pour cette documentation.

Eric Bavu

Penser à passer l’option à false avant soumission aux rapporteurs!

Il est aussi possible d’ajouter des commentaires en ligne : Une note bibliographique Abbé Grégoire: Voir Knuth 1984, chapitre 12. sans que cela occupe de la place dans la marge.

inline=true occupe toute la ligne en PDF

En HTML, les annotations inline=true apparaissent comme un span coloré compact, exactement à la largeur de leur contenu. En PDF, le package todonotes rend \todo[inline] sous la forme d’un bloc coloré pleine largeur — c’est une contrainte de conception du package, sans contournement possible sans perdre la capacité de couper les annotations longues sur plusieurs lignes. Utilisez inline=true pour de courtes notes qui doivent rester dans le flot du texte ; pour des annotations plus longues, omettez inline pour placer la note en marge.

Désactiver les commentaires avant le dépôt final

Avant de soumettre la thèse à l’école doctorale et de la déposer sur theses.fr, passez extensions.quarto-comments.enabled: false dans _quarto.yml. Les annotations ne doivent pas figurer dans la version officielle archivée.

5.4 Annotations web avec Hypothesis (opt-in)

Pour une relecture à distance, la version HTML peut être enrichie d’annotations web via Hypothesis. Le directeur ou les relecteurs sélectionnent du texte dans le navigateur et ajoutent des commentaires sans toucher aux fichiers source. Les annotations sont stockées sur les serveurs Hypothesis et liées à l’URL de la page — elles persistent d’un rendu à l’autre tant que l’URL reste stable (déploiement GitHub Pages).

Pour activer, décommenter le bloc suivant dans _quarto.yml :

format:
  cnam-thesis-html:
    comments:
      hypothesis:
        theme: clean   # clean = discret ; classic = barre latérale toujours visible

Créer ensuite un groupe privé sur hypothes.is et partager le lien d’invitation aux relecteurs. Hypothesis est désactivé par défaut dans tous les profils.

5.5 Pages liminaires spéciales

5.5.1 Résumé et abstract

Les pages resume.qmd et abstract.qmd utilisent des classes CSS qui ajoutent une bordure gauche en HTML :

::: {.resume-block}
Texte du résumé en français.

**Mots-clés :** mot1, mot2, mot3
:::

Résumé français obligatoire pour toute thèse Cnam

Même pour une thèse rédigée en anglais, un résumé en français est obligatoire selon les règles de l’abes pour le dépôt sur theses.fr. C’est le rôle du fichier content_en/frontmatter/resume.qmd dans le profil anglais.

5.5.2 Le Comité de Suivi Individuel (csi)

Processus doctoral français — le csi

Le csi est obligatoire depuis 2016 pour tous les doctorants en France. Il se réunit au moins une fois par an, indépendamment du directeur de thèse, pour vérifier l’avancement, les conditions de travail et le respect du calendrier. Le compte-rendu du csi doit être joint au dossier de soutenance.

Le template HTML de cette thèse est particulièrement adapté pour les réunions de csi : il permet de partager un lien vers la version en ligne, plus facile à parcourir qu’un PDF de 200 pages.

Allaire, J. J., Charles Teague, Yihui Xie, et Christophe Dervieux. 2022. Quarto. Zenodo, released. https://doi.org/10.5281/zenodo.5960048.

Bringhurst, Robert. 2004. The Elements of Typographic Style. 3ᵉ éd. Hartley & Marks.

Hunter, J. D. 2007. « Matplotlib: A 2D Graphics Environment ». Computing in Science & Engineering 9 (3): 90‑95. https://doi.org/10.1109/MCSE.2007.55.

Knuth, Donald E. 1984. The TeXbook. A. Computers & Typesetting. Addison-Wesley.

Lamport, Leslie. 1994. LaTeX: A Document Preparation System. 2ᵉ éd. Addison-Wesley Professional.

Mittelbach, Frank, et Ulrike Fischer. 2023. The LaTeX Companion. 3ᵉ éd. Addison-Wesley Professional.

5.1 Citations bibliographiques

5.1.1 Syntaxe de base

5.1.2 Références multiples

5.1.3 Fichier references.bib

5.2 Glossaire et acronymes

5.2.1 Déclarer des entrées dans glossaire-entries.qmd

5.2.2 Utiliser les acronymes dans le texte

5.3 Commentaires collaboratifs (quarto-comments)

5.3.1 Configuration dans _quarto.yml

5.3.2 Les quatre types de commentaires

5.4 Annotations web avec Hypothesis (opt-in)

5.5 Pages liminaires spéciales

5.5.1 Résumé et abstract

5.5.2 Le Comité de Suivi Individuel (csi)

5.1.3 Fichier `references.bib`

5.2.1 Déclarer des entrées dans `glossaire-entries.qmd`

5.3 Commentaires collaboratifs (`quarto-comments`)

5.3.1 Configuration dans `_quarto.yml`