---
title: "Technical Notes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{trackdown-tech-notes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  echo = TRUE,
  eval = FALSE,
  comment = "#>"
)
```

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 {#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 {#Html2Pdf}

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 {#auth}

> 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](https://googledrive.tidyverse.org/)) 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](https://gargle.r-lib.org/index.html)). 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](https://googledrive.tidyverse.org/reference/drive_auth.html)).

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: 

```{r}
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](https://gargle.r-lib.org/reference/gargle_options.html)).

### The `.trackdown` folder {#hidden-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 {#corrupted}

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.