Document `translator` argument and change default

[bwiernik]

Users should be encouraged to use CSL-JSON and not BibLaTex when using CSL styles to format their references.

Closes https://github.com/paleolimbot/rbbt/issues/4

[paleolimbot]

This would only work if people are generating Word docs or HTML...LaTeX folks would be out of luck (I think?). You could put something in your .RProfile if you'd like a custom function, or just type translator = "csljson" once per doc.

[bwiernik]

No, that's not true. By default pandoc formats the citations itself, then generates the TeX. It doesn't use BibLaTeX to do any of the referencing unless you specifically tell it to.

[paleolimbot]

In the bbt_write_bib() case, it seems like you could guess the translator pretty effectively from path. Would you be interested in using this PR to make a bbt_guess_translator(path = NULL) function? If path is NULL you could use getOption("rbbt.default.translator") and set this option in your .RProfile.

[bwiernik]

To use TeX to format the citations, users have to add pandoc_arguments: --natbib or pandoc_arguments: --biblatex to their YAML header. See https://pandoc.org/MANUAL.html#citation-rendering

If a user doesn't specify that, then it uses CSL to format the citations and bibliographies. pandoc formats the citations in Markdown, then converts to TeX, then to PDF. That always requires CSL-JSON, even if going to PDF.

Most people don't realize that they shouldn't use .bib format if they are using Markdown, so I really think you should make that the default.

[bwiernik]

(Wrote that before I saw your above post.)

I can add a guess translator function. rbbt.default.translator should still be csljson to avoid misunderstandings and incorrect bibliographies.

[paleolimbot]

It's still pretty uncommon to use CSL-JSON, and the defaults reflect that. Changing the defaults here will just annoy people (mostly me)...there are more effective ways to communicate that CSLJSON is a better choice.

[bwiernik]

That it's uncommon is a pretty big problem. I've seen quite a lot of documents generated with RMarkdown with incorrectly formatted bibliographies because of the BibTeX conversion. Unless RMarkdown is being converted to raw TeX (not PDF) for later processing by biber or bibtex, there isn't much reason to use .bib over .json.

If you really prefer that the order of the translator vector be kept, I still recommend leaving the default path to be "bibliography.json".

[bwiernik]

Sorry if I'm being annoying here, just in my experience, most users know very little about citation formatting engines or intend to do any manual configuring of their bibliography files. So, I think the default should give them the best hands-off result. Most people using RMarkdown aren't going to raw TeX, so the best default is a CSL-native format (json or yaml).

[paleolimbot]

I think it's best to leave the default path blank...this should always be specified by the user. I agree that the json thing is a problem, but it's one that needs to be solved by good writing and outreach (as you've done in the documentation), not by imposing behaviour on people that they don't expect.

For the other functions, could you set the default arguments such that translator = getOption("rbbt.default.translator", "biblatex"). This makes it transparent that the user can update the default (realistically these functions never get used on their own, so keeping the default won't make it more likely that people will or will not use CSLJSON). The default arg for ".bib" should probably do this too (.bib = getOption("rbbt.default.bib", "biblatex")).

If you're up for it, you could also update the addins to use bbt_guess_translator() based on the filename in the editor!

[bwiernik]

I can add those things, but I think users would expect their citations to be correctly formatted much more than they would expect a specific arcane file format to be generated. I guess our point of disagreement is that I don't think that 99% of users are thinking about their bibliography file at all and just want this magic stuff to work. Getting a .bib file for users who want it is as simple as specifying a path ending with .bib.

[paleolimbot]

Even if .json were the norm the user should still specify the filename (for any file write operation). You should definitely write a blog post about this though (with examples of where this matters). Like I said, the other functions only ever get used by the addin or bbt_write_bib(), so the default translator isn't that important.

[bwiernik]

I can do that. Could you also help out on that front by updating your example in your blog post to use json and/or copy the documentation paragraph explaining the choice to folks? 😜

[bwiernik]

Should write_bib() error or give a warning if the file extension doesn't match the translator requested?

[paleolimbot]

I think that's not necessary (as long as the default arg is translator = bbt_guess_translator(path))

[paleolimbot]

I'll update the readme and the post after this PR with notes about CSL JSON (and link to your post when you've written it)

[bwiernik]

What does your comment about the CAYW tool not working well on some platforms mean?

[paleolimbot]

It doesn't work on my machine (mac OS)...I think it's OK on linux (never tried on windows).

[bwiernik]

Hmm, I'll check it out.

[paleolimbot]

Also don't forget to add yourself as an author in DESCRIPTION!

[bwiernik]

Oh, thank you!

[bwiernik]

Okay, I did everything except integrating guess_translator() into the addin. I'm not sure what you mean there. Do you mean replacing the individual bbt_biblatex_zotero_addin(), etc. functions with a single one that looks in the current context for a "bibliography:" YAML field, then parses it for a final extension? That seems rather fragile.

[paleolimbot]

I'll add it in, thanks for the addition!

[bwiernik]

Thank you for making this addin! It's made my life so much easier.