Skip to contents

Technical Notes

Source: vignettes/trackdown-tech-notes.Rmd
trackdown-tech-notes.Rmd

In this vignette, some technical details of the trackdown workflow are discussed.

For a general overview of the package, see the trackdown-package help page or vignette("trackdown-workflow") to learn more about the workflow and vignette("trackdown-features") for a detailed description of function arguments and features.

Trackdown Instructions

When uploading (or updating) a file to Google Drive, trackdown adds some simple instructions and reminders on top of the document. For example, in the case of a file named My-Report.Rmd the following instructions are added:

#----Trackdown Instructions----#
This is not a common Document. The Document includes properly formatted Markdown syntax and R code. Please be aware and responsible in making corrections as you could break the code. Limit changes to narrative text and avoid modifying R code.
Please do not remove placeholders of type "[[chunk-<name>]]" or "[[document-header]]"
Once the review is over accept all changes: Tools -> Review suggested edits -> Accept all.
You must not modify or remove these lines, we will do it for you ;)
FILE-NAME: My-Report.Rmd
HIDE-CODE: TRUE
#----End Instructions----#

In particular, the menu option for accepting all changes is pointed out and information about the name of the local file and the selected option for hiding the code is displayed. All these instructions are automatically removed when the document is downloaded so they must not be modified.

Html 2 Pdf

The trackdown package allows uploading the rendered output file (i.e., an HTML or PDF file) together with the main file. This allows collaborators to evaluate the overall layout, including figures and tables, and to add comments to propose and discuss changes. However, only in the case of PDF files, collaborators can add comments directly on the file in Google Drive. This is not possible with HTML files.

When working with HTML output files, trackdown can automatically convert them into PDFs before uploading them to Google Drive. This feature requires that the pagedown package is available. As the pagedown package is not installed as a dependency of trackdown, it has to be installed manually by the user if it is not already available. The function pagedown::chrome_print() is used to convert HTML into a PDF. Note that Google Chrome has to be installed on the user’s system for this conversion operation.

Authentication

From trackdown v1.3.0 [currently only available on GitHub], the trackdown package uses its own API credentials (OAuth client ID and secret; see vignette("trackdown-privacy-policy")).

[IMPORTANT] We currently reached the maximum number of users for the API credentails. Installing the development trackdown from GitHub will require to create your own API credentials. Please, see instructions at https://claudiozandonella.github.io/trackdown/articles/oauth-client-configuration.html

Under the hood, the trackdown package uses functions from the googledrive R package (Official Documentation) to manage files transfers to and from Google Drive. These operations requires authorization to view and manage a user’s Google Drive files. The first time one uses trackdown, one will be directed to a web browser and asked to sign in to one’s Google account to grant googledrive permission to communicate with Google Drive.

Authentication is managed by the gargle R package (Official Documentation). By default, user credentials are cached in a folder in the user’s home directory, ~/.R/gargle/gargle-oauth, from where they can be automatically refreshed, as necessary. Storage at the user level means that the same token can be used across multiple projects and tokens are less likely to be synced to the cloud by accident. Note that if one is using R from a web-based platform like RStudio Server or Cloud, there will be a variant of this user authentification flow, known as out-of-band auth (“oob”). See help page of googledrive::drive_auth() for further information (link).

It is possible to personalize gargle’s default settings by adding options in the .Rprofile startup file. For example, the preferred Google account and cache folder can be set:

options(
  gargle_oauth_email = "my_email@gmail.com",
  gargle_oauth_cache = "/path/to/folder/that/does/not/sync/to/cloud"
)

See the gargle documentation for further information (link).

The .trackdown folder

When uploading or updating an .Rmd (or Quarto / .Rnw) file to Google Drive, it is possible to remove the code in the header of the document (YAML header or LaTeX preamble) and code chunks by specifying the argument hide_code = TRUE.

The header code and the code chunks are saved in a hidden folder named .trackdown that will be created in the same location as the uploaded .Rmd (or Quarto / .Rnw) file. For example, when uploading a file named My-Report.Rmd, two files will be created:

  • My-Report.Rmd-header_info.rds - containing the header code
  • My-Report.Rmd-chunk_info.rds - containing all code chunks

These files are required to automatically restore the header code and all code chunks when the document is downloaded from Google Drive. Consequently, it is important to not delete or move the hidden .trackdown folder. This folder should always be in the same location as the .Rmd (or Quarto / .Rnw) file.

It is recommended to track the hidden .trackdown folder using Git. This provides an extra layer of safety and a chance to restore the code automatically if the folder was deleted or modified by accident.

Corrupted Files

When editing an .Rmd (or Quarto / .Rnw) file in Google Docs, it is possible to introduce some syntax errors and break the code so that it is no longer possible to render the document locally after downloading it. This applies to both Markdown (or LaTeX) syntax and R code.

  • Markdown (or LaTeX) syntax - Less expert collaborators are likely to introduce errors while editing the document in Google Docs. Remember that any editing of the narrative text should be done using proper Markdown (or LaTeX) syntax. Any other formatting done in Google Docs (e.g., bold, italic, titles, font size, etc.) will be lost at download. Collaborators with no experience in these markup languages might find this too demanding. In this case, collaborators might prefer to modify the text format using the standard formatting commands, leaving it to their more experienced collaborators to translate the formatting into the corresponding Markdown (or LaTeX) syntax.

  • R code - Any changes to the R code should be avoided when editing files in Google Docs. Collaborative code writing is better done in an appropriate IDE (e.g., RStudio) using version control systems like Git. To prevent collaborators from inadvertently making changes to the code in Google Docs, it is possible to remove code in the header of the document (YAML header or LaTeX preamble) and code chunks by specifying the argument hide_code = TRUE. This allows collaborators to focus solely on the narrative text. To allow for correct code restoration after download, however, the placeholders of type “[[document-header]]” and “[[chunk-<name>]]” must not be modified or removed when editing the file in Google Docs. If they are inadvertently removed, the trackdown package will try to restore the missing chunks by placing them after the last available placeholder. Unfortunately, this process does not guarantee that chucks are placed in the correct position. Experienced collaborators can, however, easily fix possible issues allowing the document to compile.

In all cases, using Git to track the .Rmd (or Quarto / .Rnw) files (or better the whole project) is highly recommended. Git allows restoring previous versions of the document in case of any issues. In the worst-case scenario where trackdown is not able to restore the code chunks, experienced collaborators can still use Git or the information saved in the hidden .trackdown folder to manually restore all corrupted or missing parts.