5  References, glossary, and annotations

This chapter presents the bibliographic citation system (IEEE style via IEEEtran-francais.bst), the glossary and acronym system, collaborative comments, and special front matter pages.

5.1 Bibliographic citations

5.1.1 Basic syntax

Citations are inserted with [@key]. The key corresponds to the BibTeX identifier defined in references.bib:

Computer typesetting was revolutionised by Knuth [@Knuth1984],
whose \TeX{} system was made accessible by Lamport with \LaTeX{} [@Lamport1994].
Quarto [@Allaire2022] unifies these tools in a modern publishing environment.

Output:

Computer typesetting was revolutionised by Knuth (Knuth 1984), whose system was made accessible by Lamport with (Lamport 1994). Quarto (Allaire et al. 2022) unifies these tools in a modern publishing environment.

5.1.2 Multiple references

Python visualisation tools [@Hunter2007] and typographic reference works
[@Bringhurst2004; @Mittelbach2023] complement the author's toolkit.

Output:

Python visualisation tools (Hunter 2007) and typographic reference works (Bringhurst 2004; Mittelbach et Fischer 2023) complement the author’s toolkit.

AvertissementAlways use [@key] with brackets

The IEEEtran-francais.bst style uses natbib. The @key syntax without brackets calls \citet{} which is broken with IEEEtran — it produces the author name followed by [?]. Always use [@key] to obtain [N] (IEEE numbering).

5.1.3 The references.bib file

The references.bib file must be located at the project root. Pandoc in natbib mode generates \bibliography{references} (without a path), and BibTeX looks for the file in the current directory. A file in content_en/references.bib will not be found.

AstuceBibliography managers

Zotero (with the Better BibTeX connector), JabRef, or Mendeley export directly to .bib format. The @IEEEtranBSTCTL entry at the top of the file configures the IEEEtran style (number of authors before “et al.”, etc.) — do not remove it.

5.2 Glossary and acronyms

5.2.1 Declaring entries in glossaire-entries.qmd

All entries are declared in content_en/frontmatter/glossaire-entries.qmd via two shortcodes:

{{< acr label ABBREV "Full expansion" >}}
{{< terme label "word" "Complete definition of the term" >}}

The shortcodes automatically write _glossaire-entries.tex (read by LaTeX) and populate the HTML tables. Labels must be unique.

5.2.2 Using acronyms in the text

Four shortcodes allow referencing an acronym in the desired form:

Table 5.1: Glossary reference shortcodes.

Shortcode	PDF output	HTML output
{{< gls cnam >}}	short form (1st use: long)	short form
{{< acrs cnam >}}	always short form	always short form
{{< acrl cnam >}}	always long form	always long form
{{< acrf cnam >}}	long (short)	long (short)

Examples in context:

The {{< acrs cnam >}} ({{< acrl cnam >}}) was founded in 1794.
The {{< acrf qmd >}} format is Quarto's native format.
The toc is generated automatically by Quarto.

Output:

The cnam (cnam) was founded in 1794. The qmd format is Quarto’s native format.

NotePDF vs HTML behaviour

In PDF, label expands on the first occurrence (long form + abbreviation in parentheses) then uses the short form. In HTML, this first-occurrence logic is not handled by the shortcode — it always produces the short form. For consistency, prefer label on the first occurrence in the text, and label thereafter.

5.3 Collaborative comments (quarto-comments)

5.3.1 Configuration in _quarto.yml

The quarto-comments extension (folder _extensions/comments/) is configured via the extensions.quarto-comments: key in _quarto.yml:

extensions:
  quarto-comments:
    enabled: true
    authors:
      eb:
        name: "Eric Bavu"
      ag:
        name: "Abbé Grégoire"
      # Colors auto-assigned from Bootstrap 5 palette; override if needed:
      # nc:
      #   name: "Nicolas Conté"
      #   color_html: "#198754"
      #   color_latex: "green!30"

5.3.2 The four comment types

{{< comment "Rephrase this sentence, it is too long." author="ag" >}}
{{< todo "Add a figure illustrating this point." author="eb" >}}
{{< note "See also Bringhurst 2004, §2.4." author="ag" >}}
{{< question "Is this result reproducible on another dataset?" author="ag" inline=true >}}

Rendered in context:

Here is a sentence with a comment from the thesis supervisor (who added it directly in the .qmd file, because that is how it works!).

Abbé Grégoire

This is a ‘comment’ type annotation by the supervisor.

These annotations are only visible when enabled: true is set under extensions.quarto-comments in _quarto.yml — which is the case for this documentation.

Eric Bavu

Remember to set this option to false before submitting to the reviewers!

An inline note can be added without pushing the surrounding text to the margin: a bibliographic reference Abbé Grégoire: See Knuth 1984, chapter 12. stays in the text flow.

Noteinline=true occupies the full line in PDF

In HTML, inline=true annotations appear as a compact coloured span, exactly as wide as their content. In PDF, the todonotes package renders \todo[inline] as a full-width coloured block — this is a design constraint of the package that cannot be worked around without losing the ability to wrap long annotations across lines. Use inline=true for short notes that must stay in the text flow; for longer annotations, omit inline to place the note in the margin instead.

ImportantDisable comments before final submission

Before submitting the thesis to the doctoral school and depositing it on theses.fr, set extensions.quarto-comments.enabled: false in _quarto.yml. Annotations must not appear in the official archived version.

5.4 Web annotations with Hypothesis (opt-in)

For remote proofreading, the HTML output can be enhanced with web annotations via Hypothesis. Supervisors and reviewers select text in the browser and add comments without touching the source files. Annotations are stored on Hypothesis servers and tied to the page URL — they persist across renders as long as the URL stays stable (GitHub Pages deployment recommended).

To enable, uncomment the following block in _quarto.yml:

format:
  cnam-thesis-html:
    comments:
      hypothesis:
        theme: clean   # clean = discreet ; classic = sidebar always visible

Then create a private group on hypothes.is and share the invite link with your reviewers. Hypothesis is disabled by default in all profiles.

5.5 Special front matter pages

5.5.1 Résumé and abstract

The resume.qmd and abstract.qmd pages use CSS classes that add a left border in HTML:

::: {.resume-block}
Text of the résumé in French.

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

ImportantFrench résumé mandatory for all Cnam theses

Even for a thesis written in English, a French résumé is mandatory according to the abes rules for deposit on theses.fr. This is the role of the file content_en/frontmatter/resume.qmd in the English profile.

5.5.2 The Individual Monitoring Committee (csi)

NoteFrench doctoral process — the csi

The csi has been mandatory since 2016 for all doctoral students in France. It meets at least once a year, independently of the thesis supervisor, to verify progress, working conditions, and adherence to the schedule. The minutes of the csi meeting must be included in the defence dossier.

The HTML version of this thesis template is particularly well suited for csi meetings: it allows sharing a link to the online version, which is easier to navigate than a 200-page PDF.

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.