Evaluating Citation and Footnotes

[ClaudioZandonella]

Using this issue to discuss and keep track of the proposed feature: Evaluating Citation and Footnotes

Proposed on twitter by

Thanks for your great work! I recently introduced your package in a workshop on working collaboratively with reproducible tools such as Rmarkdown. Do you plan to implement that certain aspects of the document are already knitted when being uploaded to GoogleDoc (e.g. citations)?

— Caroline Zygar-Hoffmann (@psycaroly) December 20, 2021

During the package development, we considered the possibility to evaluate documents parts before uploading (e.g., inline code, figures, or tables). However, we found two major problems:

• Assuming the right environment to render the document. In most cases, everything is defined within the document but there could be many conditions that require specific settings depending on the user preferred workflow.
• trackdown works on plain text files (.txt) so adding special elements such as figures or tables would require extra complex elaboration during the upload and the download.

These aspects would increase the chances of introducing errors and unexpected problems. Therefore, we chose to not evaluate the document to keep the workflow as simple as possible and to enhance stability. Instead, we introduced the possibility to upload the rendered output (pdf or HTML already compiled by the user) together with the main file. Our ideal workflow is to keep both files open side by side. Users should edit the main file using the rendered output (pdf or HTML ) to evaluate figures and tables or to understand the meaning of the markdown syntax when this is not clear from the main file.

In this way, we also try to remind users that the main file should always be considered as a markdown (or LaTeX) file and proper formatting syntax comands have to be used (google docs text formatting is lost at download). Markdown syntax is pretty easy to understand, thus this is also an opportunity for non-programmer users to become more familiar with it. In fact, the other idea behind trackdown is to find a middle ground between Rusers and MS Word users to facilitate collaboration but this also requires both to get outside their comfort zone.

Considering the particular issue of citations and footnotes. Surely, it is possible to hide them, placing a tag instead (as for the code chunks), but I guess this is not the desired result (or may this still be helpful?).

I will look at knitr code to understand how it manages citations as some other solution may be possible!

[psycaroly]

Hi and thank you for taking the time to consider this feature! :) As it is mainly an issue of readability, I do not think that placing a tag instead of showing the rmarkdown-syntax would help.

In my particular use case, my collaborator is familiar with rmarkdown, so they would have no problem understanding the citations / footnote syntax. Instead, it really is a case of not having a smooth reading experience with non-evaluated citations / footnotes and thus providing feedback becomes more burdensome if you have to have two files open simultaneously, one to read and one to comment.

Maybe this is a style-thing, but although I write all my papers in rmarkdown, I always perform the "check of how does it read" in an evaluated/knitted version (e.g., pdf or word), and not in the rmarkdown file itself.

So, if it wouldn't make too much trouble to evaluate citations and footnotes, that would surely improve the experience I personally have with trackdown and the chances that I get collaborators to cooperate ;-)

[ClaudioZandonella]

Hi @CaroZygar,

Sorry for the late reply.

I have tried to figure out how Rmarkdown manages citations and footnotes. I was hoping for some kind of already available functions to evaluate citations and footnotes separately from the whole document. Actually, everything is managed by Pandoc.

To my understanding (that I admit is pretty limited, as each time I dig into rmarkdown/knitr source code I end up with little more than a huge headache😅; I really admire the complexity of these packages), there is no shortcut for evaluating citations and footnotes other than using Pandoc. Now, Pandoc is a little bit too far for me. I have very limited experience using Pandoc directly. Moreover, managing citations is quite complex (many options, settings and possible scenarios). On top of this, there would still be the problem of how to manage backward evaluation to restore the original document.

At the moment, I do not see any easy solutions to evaluate citations and footnotes without evaluating the whole document. For the reasons discussed in the previous comment (link), the idea beyond trackdown is to not evaluate the document to keep the workflow as simple as possible. Instead, to enhance readability, we can hide/restore code chunks and other parts. As you pointed out, however, placing a tag instead of showing the rmarkdown-syntax would not help in the case of citations and footnotes (apart from avoiding other collaborators inadvertently editing the code).

Unfortunately, I can't think of other solutions. I will leave the issue open. Maybe, someone will find a possible solution in the future.