tutorial on citation in R Markdown needs clarification

[ElsLommelen]

When searching for information on citations on the internet, I arrived at the tutorial on citation in R Markdown by @hansvancalster and @florisvdh (which is nice, I think).

However, when using this tutorial, I immediately got in troubles: it is recommended (or even needed) to enter VME mode, but the button that is shown in the pictures, is not present in my RStudio, despite I have the newest typical INBO installation of R & RStudio (new version since last friday). I moreover have markdown, rmarkdown and bookdown installed. So I suppose for this VME mode, an additional installation should be done? It would be helpful if the tutorial would mention this.

[hansvancalster]

It's just that the new version of RStudio changed the GUI layout a little bit. When you open a Rmd file, you will see on the top left buttons with the words "source" and "visual". Just click "visual" and the document will be shown in VME mode.
But yes, we will need to update the tutorial to reflect this very recent change.

[ElsLommelen]

These buttons with "source" and "visual" also don't appear automatically when opening a Rmd...
I searched a bit, and after choosing for the gear wheel symbol ('settings') centrally above the Rmd and selecting 'Use Visual Editor', these buttons appeared. After doing it once, they seem to stay there, but apparently one has to do this once before these buttons appear. So please add this as well to the tutorial: once these buttons are there, it all seems very intuitive, but the manual is useless if nobody knows how to let these buttons appear.
(And now: how can I let them disappear again? :-p Since all these rows with buttons take a lot of space.)

[hansvancalster]

These buttons with "source" and "visual" also don't appear automatically when opening a Rmd... I searched a bit, and after

Good to know. They were visible to me probably because I have used VME mode in previous version of RStudio and my settings are remembered somehow.

[florisvdh]

You get the same effect by doing Ctrl+Shift+F4 (referred at https://rstudio.github.io/visual-markdown-editing/), it displays the buttons and switches to visual.

How to let the buttons disappear, I'm not sure, it can probably be done by fiddling with (or deleting) config files. It seems to be remembered cross-project, so that should be in the user-specific configuration (or history) of RStudio (not visible in the Global Options GUI).

[ElsLommelen]

How to let the buttons disappear, I'm not sure, it can probably be done by fiddling with (or deleting) config files. It seems to be remembered cross-project, so that should be in the user-specific configuration (or history) of RStudio (not visible in the Global Options GUI).

Indeed, there seem to be no options yet to hide menu bars in RStudio except for config files.

[ElsLommelen]

Another item to check when updating the tutorial: it has been suggested to not make a bibliography file beforehand and let it be created automatically, but as the bibliography yaml heading is added automatically in the Rmd chapter where one adds the first reference, it is getting messy. This should in my opinion better be placed in the general yaml in index.Rmd, as I'm not sure what will happen when rendering the bookdown if references are added in chapters before the one in which the bibliography yaml is added.

[florisvdh]

Good point @ElsLommelen, I agree.

[hansvancalster]

Last time I tried, the visual mode citation tool in combination with bookdown is a bit cumbersome. In bookdown in case you have separate .Rmd files next to index.Rmd, visual mode will not be aware of the bibliography field in index.Rmd if you are working in one of the other *.Rmd files. A workaround is to add a yaml section at the top for each *.Rmd which refers to the same bibliography as in index.Rmd:

---
bibliography: referenties.yaml
---

It would be nice if RStudio visual mode would be aware that these files belong to the same bookdown project, but AFAIK this is not the case and I use the above workaround. I wasn't aware of this issue when I wrote the citation tutorial but we can add this when we update it.
I haven't yet tested if the new RStudio version has improved upon this.

[florisvdh]

@hansvancalster can you have a look whether this is an existing issue in the RStudio repo? If not, I think it's best to raise an issue.

A sidenote for Zotero users preferring the source mode, is to install the rbbt package, which makes use of the BBT plugin for Zotero to import selected bibliographic data. One can use rbbt's RStudio addin for that, see screenshot below. I just use it to manually amend an existing YAML file with bibliographic data, and afterwards insert the citation manually in an Rmd. But it will equally work for JSON & BibTeX files; it just detects the file which you're in. This workflow has the same compatibility with a collaborative environment as does the RStudio VME tool, although it involves an extra step.

[ElsLommelen]

In my case I could finally add references to other chapters without having the bibliography added to each of the chapters. Because I did some testing to get it working, I don't know exactly how I succeeded, but I suppose it should more or less work using the following workflow:

• go to visual mode, add a citation, and fill in your bibliography name (a bibliography name in index.Rmd is simply ignored, so this part of the current tutorial is superfluous)
• return to source mode and move the bibliography yaml to index.Rmd
• build the bookdown
• after that, one can add citations to each chapter of the bookdown, I think. But if you have played around with different bibliographies at that point (like I did), to be sure, one has to check before adding a citation if the right bibliography is mentioned in the reference window.

So to be tested, but somehow it should be possible to work with it in a bookdown, as I'm doing it right now. ;-)

[hansvancalster]

@ElsLommelen I tried your approach and it worked for a while. But when I closed RStudio and reopened the .Rproj, a yaml bibliography field gets inserted again if I inserted a new citation. So the wanted behavior seems not persistent across sessions?

[hansvancalster]

@hansvancalster can you have a look whether this is an existing issue in the RStudio repo? If not, I think it's best to raise an issue.

I didn't find an issue that mentions this. However, I find it logical that each Rmd file should refer to a (possibly shared) bibliography file. It is only after bookdown is built that we know which files belong together and have shared yaml metadata. Adding the bibliography field to each Rmd that has citations is already made as easy as possible given that it is done automatically upon the first @citationkey that you insert (just need to make sure you give it the same name and extension as the one in index.Rmd -or more generally the one you are using- if you want a shared single file containing the references).

[florisvdh]

It is only after bookdown is built that we know which files belong together and have shared yaml metadata.

I think the fact of being a bookdown project is also an RStudio project setting ('build site'), i.e. what triggers the build pane to show the bookdown behaviour? RStudio's citation logic could check this, and perhaps the existence of _bookdown.yml and/or index.Rmd to decide how to deal with the bibliography YAML key (if bookdown, then use index.Rmd or the file enlisted first in _bookdown.yml.

But you're right, it's not a problem when the key is repeated in the Rmd's, so it is a robust however IMHO not very elegant solution for bookdown projects.