Improving the experience of adding references to a document

[njtierney]

I recently taught an intro to rmarkdown course. It was great to expose people to the world of rmarkdown, but one thing that seemed rather annoying and manual process was that of adding references to a document.

It would be awesome to have some tooling in R to improve how we cite packages and papers.

I wrote about this at the rOpenSci unconf in the USA in 2017 (issue here), but decided to work on a different project.

So, here is an adapted summary of that issue

---

Citing packages in R can be tricky.

One path for improving this at the unconf could be to create a set of functions to assist the process of making citations for software and using citations for software

These might either be wrapped up in their own package, or perhaps even as a pull request to devtools, usethis, or goodpractice.

• cite_pkgs:
  • makes a .bib file that contains citations from the R packages that are called or used. This could perhaps build off of knitr::write_bib(c(.packages(), 'bookdown','knitr', 'rmarkdown'), 'packages.bib')
• use_citation (for use in R package development)
  • A get_zenodo_doi option talks to https://github.com/ropensci/zenodo.
  • adds information to the inst/CITATION file.
• project_citations()
  • Grabs citations for packages used in a project/repo.
  • The user could then choose from and then export appropriately.
• get_doi()
  • auto-generates citations to be the same or compatible citation that would be extracted by citation()
  • It also encourages authors to be explicit in what they want.
• cleanup_bib()
  • This code would go through and clean up the .bib file, arranging all of the .bib entries in alphabetical order, and deleting exact duplicates. Some of this has been implemented in @HughParsonage 's TeXCheckR
• use_cls()
  • Provides a way to add .cls files, from the repo: citation language styles.
  • This function would allow you to:
    • Search for a CLS
    • add a cls (adding it to the .RProj/current directory, and
• use_badge()
  • Create a DOI or other citation badges ("please cite me!", or something).

Existing work

There is already some work on this in the papaja package, which has a really nice description in this chapter on citation, and the package citr by @crsh

Although, looking at these packages now, they are quite well developed!

Perhaps one outcome of this project could be to create a lightweight citation package that incorporates features missing from citr, and might end up being incorporated into a pull request, or perhaps into a blog post to discuss this topic.

[mrjoh3]

Is this more of a workflow issue than a technical one? Earlier today I was adding refs to an rmarkdown and was thinking of how ready it was. I organised my refs in zotero, exported a .bib file then rendered using radix.

It just worked,I was very happy.

Of course there is always room for improvement or imagining a better way

On Mon., 19 Nov. 2018, 16:07 Nicholas Tierney <notifications@github.com wrote:

I recently taught an intro to rmarkdown course. It was great to expose people to the world of rmarkdown, but one thing that seemed rather annoying and manual process was that of adding references to a document.

It would be awesome to have some tooling in R to improve how we cite packages and papers.

I wrote about this at the rOpenSci unconf in the USA in 2017 (issue here https://github.com/ropensci/unconf17/issues/24), but decided to work on a different project.

So, here is an adapted summary of that issue

Citing packages in R can be tricky.

One path for improving this at the unconf could be to create a set of functions to assist the process of making citations for software and using citations for software

These might either be wrapped up in their own package, or perhaps even as a pull request to devtools, usethis, or goodpractice.

• cite_pkgs:
  • makes a .bib file that contains citations from the R packages that are called or used. This could perhaps build off of knitr::write_bib(c(.packages(), 'bookdown','knitr', 'rmarkdown'), 'packages.bib')
• use_citation (for use in R package development)
  • A get_zenodo_doi option talks to https://github.com/ropensci/zenodo.
  • adds information to the inst/CITATION file.
• project_citations()
  • Grabs citations for packages used in a project/repo.
  • The user could then choose from and then export appropriately.
• get_doi()
  • auto-generates citations to be the same or compatible citation that would be extracted by citation()
  • It also encourages authors to be explicit in what they want.
• cleanup_bib()
  • This code would go through and clean up the .bib file, arranging all of the .bib entries in alphabetical order, and deleting exact duplicates. Some of this has been implemented in @HughParsonage https://github.com/HughParsonage 's TeXCheckR https://hughparsonage.github.io/TeXCheckR/reference/lint_bib.html
• use_cls()
  • Provides a way to add .cls files, from the repo: citation language styles https://github.com/citation-style-language/styles.
  • This function would allow you to:
    • Search for a CLS
    • add a cls (adding it to the .RProj/current directory, and
  • use_badge()
  • Create a DOI or other citation badges ("please cite me!", or something).

Existing work

There is already some work on this in the papaja package, which has a really nice description in this chapter on citation https://crsh.github.io/papaja_man/writing.html#citations, and the package citr https://github.com/crsh/citr by @crsh https://github.com/crsh

Although, looking at these packages now, they are quite well developed!

Perhaps one outcome of this project could be to create a lightweight citation package that incorporates features missing from citr, and might end up being incorporated into a pull request, or perhaps into a blog post to discuss this topic.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/ropensci/ozunconf18/issues/26, or mute the thread https://github.com/notifications/unsubscribe-auth/AB1TAacI6tnc_JwfAK73h0GdaWWndDMPks5uwjyBgaJpZM4YoaaM .

[ekothe]

@mrjoh3 If you're using Zotero you might be interested in Better BibTeX since it removes the requirement for you to actually export to .bib.

[markdly]

+1 @ekothe! I only recently discovered I could use Better BibTeX so Zotero could auto sync with citr to build the .bib file on-the-fly. It's been very handy for me especially if I'm round tripping between writing and continually adding new references to Zotero.

[njtierney]

@mrjoh3 - absolutely, if you organise your references in a reference management software like zotero, it is a fine experience, although one thing that always bothered me was fixing up the handles - I usually like mine to be "authorYYYY" - so "smith1999", but the handles generated aren't always that. But the citraddin extension can help with this.

@ekothe and @markdly can you tell me about using Better BibTex with Zotero? This sounds super neat! I often find the round - tripping really annoying and this would help with that.

[ekothe]

@njtierney basically BBT is a Zotero plugin, you can use it with citr to mean that you don't actually have to manually export your reference list to .bib (it will do that and keep it everything updated between your .rmd and your .bib in the background).

If you are using Zotero or Juris-M citr can access your reference database directly. For this to work, you need to install the Better Bib(La)TeX extension, which I would recommend anyway. Once the extension is installed and your reference manager is running, citr will automatically access all your references and keep your Bib(La)Tex-file updated by adding missing references. If you dislike this behavior, you can disable it by setting options(citr.use_betterbiblatex = FALSE).

I think BBT will also fix your reference key issue as well (see https://retorque.re/zotero-better-bibtex/citation-keys/)

[mrjoh3]

thanks @ekothe @markdly and @njtierney citr and BBT looks really promising. It looks like BBT alows you to set your own key bibtex: [your citekey] using zoteros extra field.

I am probably being a pain now, but does this get us back to @njtierney original issue: getting package citations into the bibliography. I wonder if we can merge refs from multiple sources? Like zotero BBT with ones only created in to document?

[njtierney]

Wow, so BBT looks amazing, @ekothe !

But it sounds like it is a zotero specific thing? I currently use paperpile for my references, so I wonder how I could set up somethign like this.

Fair point @mrjoh3 - it sounds like you'd need to push the R package citations up into the zotero cloud or something for better bib tex to work? I'm not familiar with them though, so I could be missing something obvious!

I'm unsure if I'll work on this project (hard to choose!) but happy to discuss tomorrow :)

[markdly]

I think there may be a way to dynamically build the citations for packages and citations for external docs using existing tools (for Zotero at least, not sure about paperpile). Keen to discuss this morning :)

[ekothe]

@mrjoh3 I think we talked about this in person but I thought it would be useful to flag here for people reading the issue.

You can use multiple .bib files within a single rmarkdown document. If you have a .bib that includes references for your substantive research area (e.g. for an introduction section) called refs.bib and then a second .bib that includes citations for the packages you're using that you created yourself or generated using citr r-references.bib you'd use both within a single document like specifying both in the YAML.

bibliography : ["refs.bib", "r-references.bib"]

[crsh]

Thanks @ekothe, you have repeatedly given the answers I was about to type up. ;)

citr currently only integrates with Better BibLaTeX. However, I'd be more than happy to add support for other reference managers. I'm currently accessing automatic exports of the references in Bib(La)TeX format. If other reference managers offer a similar interface, it should be straight forward to extend this approach. Other interfaces could also be added but would require more work. In the case of paperpile, there doesn't seem to be a good way access the references.

Some thoughts on some of the other suggestions:

• cleanup_bib(): Take a look at citr::tidy_bib(), maybe this does some of what you are looking for. It scans one or more R Markdown files for inserted citations and removes all unneeded references from the bibliography and removes duplicates. I'm not sure what you mean by alphabetical ordering. Do you mean order by reference handles? If so, this should be fairly easy to add.

• cite_pkgs()/project_citations(): I have implemented something like this in papaja, another in-the-works package of mine. See the documentations for an example.

• use_cls(): This sounds interesting and would probably be best implemented in an RStudio addin. I do feel like this would be somewhat special purpose and I'm not sure it's worth the time since it's easy to search the CLS repositories in the browser and download the CSL files.