Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify caveats of book-project bibliographies #1076

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

jfy133
Copy link

@jfy133 jfy133 commented Apr 12, 2024

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
Copy link
Collaborator

cscheid commented Apr 12, 2024

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
Copy link
Author

jfy133 commented Apr 15, 2024

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
Copy link
Author

jfy133 commented Apr 15, 2024

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
Copy link
Contributor

mcanouil commented Apr 15, 2024

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

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:

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

@@ -81,7 +81,7 @@ You can find CSL files or learn more about using styles at the [CSL Project](htt

### Bibliography Generation

By default, Pandoc will automatically generate a list of works cited and place it in the document if the style calls for it. It will be placed in a div with the id `refs` if one exists:
By default, Pandoc will automatically generate a list of works cited if the style calls for it. If it exists, the bibliography will be explicitly placed where a div with the id `refs` is specified:
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Author

jfy133 commented Apr 15, 2024

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 :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants