Specify caveats of book-project bibliographies

[jfy133]

As per this discussion and it appears in multiple places, there is confusion on what is possible in Book project types when it comes to bibliographies.

It appears many people (including myself) assume if a dedicated bibliography file is specified in the header of a page, it should be possible that only the cited works on the page will be rendered in a bibliography of that page. This is because many acadmic 'edited volume' books indeed has a standalone reference section per chapter.

However @mcanouil stated this is not possible with Quarto., and that there can only be single bibliography in a Book project - and even if there is HTML on the page with what was expected, it is hidden using css with no (apparent?) way to make this visible (see original discussion).

I've made a (likely overly wordy) attempt to clarify single-bibliography behaviour of books, as I found it is not clear from the current documentation, and can be easily misinterpreted (the current phrasing is rather implicit).

I have not made reference to @mcanouil 's section-biblography extension as I'm not sure if that is allowed on the 'main' Quarto documenation - but I would think it would be useful.

[cscheid]

Thanks for the PR.

I do want to be careful with our documentation. For example, using words like "page" in the context of books might make things more confusing to the readers. (Is it a "single book page", or a quarto file, in which case it's a chapter? etc).

I'm not going to merge this right away, but I understand the need to improve the situation.

(cc @cderv @mcanouil @cwickham, just to keep everyone in the loop about the request here. We should have a bit of a discussion)

[jfy133]

Thanks for the PR.

I do want to be careful with our documentation. For example, using words like "page" in the context of books might make things more confusing to the readers. (Is it a "single book page", or a quarto file, in which case it's a chapter? etc).

I'm not going to merge this right away, but I understand the need to improve the situation.

(cc @cderv @mcanouil @cwickham, just to keep everyone in the loop about the request here. We should have a bit of a discussion)

Completely fine with me! I'm not super familiar with Quarto, so feel free to reword/phrase with me to make it more precise/clear :)

[jfy133]

Actually to clarify, @mcanouil showed me you can have 'per-page' (although maybe 'per-file' is better terminology) specific bibliographies - this is actually done by default - if you don't reference a ::: {refs} block. This is something I did not understand from the existing documentation. I discovered this now when trying to work out in the discussion referenced in my opening comment, why I couldn't 'replicate' my error - which I've now discovered was because I had a 'hidden' ::: {ref} reference.

If I understand the behaviour correctly, I think what tripped me up is, and is not clear from the documentation:

• ::: {refs} forces a single bibliography in the place you place it (you cannot have any other bibliographies elsewhere)
• the ::: {refs} does not refer to just the single references included in the bibliography: specification in the markdown header, but refers to all references in all .bib files(?)
• what a refs div is - I don't think the div is actually described - I guess it's a HTML thing but I'm thinking in markdown when I see something like ::: {ref}
  • This last one could be on me as maybe it's described in intro pages, but I think few people will read entire documentation nowadays as much of this is too easy to 'install and go'...

[mcanouil]

It's not ::: {refs} it's ::: {#refs}.
Fenced div is a Pandoc syntax used in Quarto and described:

• https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans
• https://pandoc.org/chunkedhtml-demo/8.18-divs-and-spans.html

what a refs div is - I don't think the div is actually described

In addition to "Markdown Basics", it's described in the book guide:

• https://quarto.org/docs/books/book-structure.html#references

The behaviour of the "ref div" is also described in:

• https://quarto.org/docs/authoring/footnotes-and-citations.html#bibliography-generation

[jfy133]

I actually find the original ordering here was confusing, I sort of feel the 'default' behaviour should be described first: i.e., if no div was specified.

[jfy133]

It's not ::: {refs} it's ::: {#refs}. Fenced div is a Pandoc syntax used in Quarto and described:

* https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans

* https://pandoc.org/chunkedhtml-demo/8.18-divs-and-spans.html

what a refs div is - I don't think the div is actually described

In addition to "Markdown Basics", it's described in the book guide:

* https://quarto.org/docs/books/book-structure.html#references

The behaviour of the "ref div" is also described in:

* https://quarto.org/docs/authoring/footnotes-and-citations.html#bibliography-generation

Fair enough, then understanding what is a div is indeed on me :)