Document that references are only inserted if there is a section header called 'References'

[ulyngs]

Unless the references are explicitly inserted with

::: {#refs}
:::

Then they don't appear. If this is by design, then I suggest this is documented in the readme? (This took me hours to realise -- I didn't understand why references were correctly used in the example template.qmd, but not if I instead just installed the extension with quarto install extension quarto-journals/acm, and put in the minimum YAML required to avoid errors in a qmd).

update: this was wrong, see below

[ulyngs]

I did a bit of further testing, and realised that the above was wrong. At the moment, there must be a heading called 'References' for the references to be inserted?

I.e., this works:

---
format: acm-pdf

bibliography: bibliography.bib

title: The Name of the Title Is Hope

author:
  - name: Ben Trovato
    email: [email protected]
    orcid: 1234-5678-9012

# acm-specific metadata
acm-metadata:
  # acm preamble information
  copyright-year: 2018
  acm-year: 2018
  copyright: acmcopyright
  doi: XXXXXXX.XXXXXXX
  conference-acronym: "Conference acronym 'XX"
  conference-name: |
    Make sure to enter the correct
    conference title from your rights confirmation emai
  conference-date: June 03--05, 2018
  conference-location: Woodstock, NY
  price: "15.00"
  isbn: 978-1-4503-XXXX-X/18/06

---

# Introduction

This is a test: [@koNUGUGroupbasedIntervention2015].

# References {-}

::: {#refs}
:::

@Article{koNUGUGroupbasedIntervention2015,
  title = {{{NUGU}}: {{A Group}}-Based {{Intervention App}} for {{Improving Self}}-{{Regulation}} of {{Limiting Smartphone Use}}},
  author = {Minsam Ko and Kyong-Mee Chung and Subin Yang and Joonwon Lee and Christian Heizmann and Jinyoung Jeong and Uichin Lee and Daehee Shin and Koji Yatani and Junehwa Song},
  date = {2015},
  journaltitle = {Proceedings of the 18th ACM Conference on Computer Supported Cooperative Work \& Social Computing - CSCW '15},
  pages = {1235--1245},
  doi = {10.1145/2675133.2675244}
}

and produces this

If you keep the heading (but remove the explicit insertion of the references), it still works:

# Introduction

This is a test: [@koNUGUGroupbasedIntervention2015].

# References {-}

But, if there isn't a heading exactly called 'References', it breaks:

# Introduction

This is a test: [@koNUGUGroupbasedIntervention2015].

# ReferencesBOOOOOOOHH {-}

[ulyngs]

I see now that this is by design (https://github.com/quarto-journals/acm/blob/main/_extensions/quarto-journals/acm/add-bibliography.lua), but it really confused me!

The behaviour I was expecting was that the references were automatically inserted at the end, unless explicitly placed elsewhere with

::: {#refs}
:::

@cscheid If the current design is intended to be final, can we maybe add a note to the readme that says that the references will be inserted wherever there is a 'References' section header in the document (and only if there is such a header)?

[cscheid]

Yes, we should absolutely document this better. Ideally, the filter that inserts the references in the right place should error out if it doesn't find a div with id refs.