The main idea behind the
trackdown workflow is simple: Upload the
.Rnw) document to Google Drive to collaboratively write/edit the narrative text in Google Docs; download the document locally to continue working on the code while harnessing the power of Git for version control and collaboration.
To manage this workflow,
trackdown offers different functions:
upload_file()uploads a file for the first time to Google Drive.
update_file()updates the content of an existing file in Google Drive with the contents of a local file.
download_file()- downloads the edited version of a file from Google Drive and updates the local version.
render_file()- downloads a file from Google Drive and renders it locally.
trackdown offers additional features to facilitate the collaborative writing and editing of documents in Google Docs. In particular, it is possible to:
.Rnw) document. This helps collaborators to evaluate the overall layout including figures and tables and it allows them to add comments to suggest and discuss changes.
For a general overview of the package, see the
trackdown-package help page or
vignette("trackdown-workflow") to know more about the workflow and
vignette("trackdown-tech-notes") for an overview of technical details.
trackdown functions share some common arguments that are used to manage the workflow:
*_file(file, gfile = NULL, gpath = "trackdown", shared_drive = NULL)
Moreover, when uploading or updating a file in Google Drive with
update_file() respectively, two extra arguments are available:
hide_codeto hide the header code and code chunks from the document.
path_outputto upload the rendered output document to Google Drive in conjunction with the .Rmd (or .Rnw) document.
In this section, all arguments of
trackdown functions are introduced, describing default settings and highlighting main features.
A string indicating the path of the local
trackdown functions take as reference the local file to manage the workflow. Thus, the
file argument is mandatory, both when uploading (or updating) a file to Google Drive or when downloading the edited version from Google Drive.
A string indicating the name of the file in Google Drive.
By default (
NULL), the name of the local file (without extension) is used as the name of the file in Google Drive. By specifying the
gfile argument one can personalize the name of the file in Google Drive. In this case, one has to remember to point to the correct file in Google Drive every time one updates or downloads the file during the collaborative writing process.
A string indicating a directory in My Drive or in a shared drive (optional).
By default, files are uploaded to the folder
"trackdown/" on Google Drive. To specify another folder, the full path is required (e.g.,
"trackdown/my_folder/"). If the indicated folder is not already available on Google Drive, the user is asked for permission to create it. One can use
NULL to upload the file directly at the root level, although this is not recommended.
A logical value indicating whether code in the header of the document (YAML header or LaTeX preamble) and code chunks should be removed from the document when it is uploaded (or updated).
This argument is available only for the
update_file() functions. By default, the value is set to
FALSE. If set to
TRUE, the code in the document header and code chunks will be removed from the document and automatically restored when downloaded. Placeholders of type “[[document-header]]” and “[[chunk-<name>]]” are displayed instead.
This feature is intended to prevent collaborators from inadvertently making changes to the code in Google Docs that might corrupt the file and allows them to focus on the narrative text. Note that to guarantee correct code restoration, placeholders must not be modified or removed.
A string indicating the output path (i.e., the resulting rendered document).
This argument is available only for the
update_file() functions. By default (
NULL), no output is uploaded to Google Drive. If specified, the output file (i.e., the rendered HTML or PDF file) is uploaded in conjunction with the main file. The output is named in Google Drive like the main file plus “-output” at the end (e.g., given a main file with the name “My-Report”, the output would be named “My-Report-output”).
This feature is intended to help collaborators to evaluate the overall layout, including figures and tables, and allows them to add comments to propose and discuss changes (See Figure below). Note that, in the case of PDF files, it is possible to add comments directly to the file in Google Drive. However, this is not possible with HTML files.
In the case of HTML 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 an HTML into a PDF. Note that Google Chrome has to be installed on the user’s system for this conversion operation.