claudiozandonella / trackdown Goto Github PK

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!

Just found trackdown and it looks like a great package to solve some issues I'm facing for collaborating with non-programmers. I went to get started by following the OAuth config guidelines but noticed something new at step 8 when I went to push to produciton:

Do I worry about this message? I am not interested in sharing all of that info with Google just to make collaboration with others more easy.
Further, during step 5, there was no pop-up window. I wonder if these issues are connected and something going on at google?

Thanks for any help.

When using trackdown for a distill site that has many pages, there are situations (more frequent than I would like) where a more than dozen pages need to be updated. If I've checked that there have been no updates since the previous trackdown update, it would be nice to be able just upload all of them without having the verify that, "yes, I do want to overwrite the Google Doc contents." I'm wondering about a "don't ask" parameter.

And thanks for a wonderful package! It's extremely useful.

Hi Team-Trackdown,
first of all thank you for this great tool! It is exactly what I was looking for and what I need to collaborate with my co-authors who don't want to work with RMarkdown!
Unfortunatelly, I have a bug with the document header. After uploading the file, there is a 1 in the google drive document instead of the flac [[document-header]] and accordingly the header could not be restored in RStudio. It works perfectly fine for the code chunks, though.
Does anyone have any idea what is going wrong here and how to fix it? Thanks a lot in advance!

With #52 one cannot use [experimental] as it indicates a link in Markdown syntax. I replaced it with (experimental).

Alternative: https://lifecycle.r-lib.org/reference/badge.html

Thanks so much for writing this package, @ekothe! I was very happy to find it when I started thinking about how to implement a workflow that allows collaborative editing of .Rmd files on Google Drive. I have since modified a fork of @benmarwick's fork of this repository: https://github.com/januz/rmdrive.

I rewrote the package with a specific workflow in mind that I describe in the Readme. As this approach is relatively specific, I was wondering whether you would still want me to prepare a pull request here or just have the two packages evolve independently. Some of my changes might be of general interest though like allowing for the use of Team Drives and (sub)folders on Google Drive. Please let me know whether you'd be interested in me preparing a PR for a subset of my changes. Thanks!

Is there a way to automate some or all of the steps outlined in the vignette?

https://claudiozandonella.github.io/trackdown/articles/oauth-app-configuration.html

If there are three dashes somewhere in the document, then the option to hide the code will not work when syncing the file to Google Drive.

Reprex:

Test.Rmd (adapted the code chunks so they can be rendered as code):

---
title: "Test"
output: html_document
---

``{r setup, include=FALSE}
 knitr::opts_chunk$set(echo = TRUE)
``

## R Markdown

---

``{r cars}
summary(cars)
``

Command that fails:

trackdown::upload_file("test.Rmd", hide_code = TRUE)

As far as I can tell the error happens in trackdown:::extract_header(). The following lines produce an error when there are three dashes in the text:

header_index <- which(grepl(info_patterns$file_header_start, text_lines))
    if (length(header_index) != 2) 
        stop("There are some issues in the identification of YAML start/end line indexes", call. = FALSE)

If this is expected, maybe adding a hint to the error messages might be a good idea.

Thanks a lot!

> session_info()$platform
 setting  value                       
 version  R version 4.1.1 (2021-08-10)
 os       Manjaro Linux               
 system   x86_64, linux-gnu           
 ui       RStudio                     
 language (EN)                        
 collate  en_US.UTF-8                 
 ctype    en_US.UTF-8                 
 tz       Europe/Berlin               
 date     2021-10-11  

Dear @ekothe,

I have created a branch gh-pages with the rendered documentation of the package obtained with pkgdown package documentation-link.

Could you please publish the GitHub pages following these instructions?

Configuring a publishing source for your GitHub Pages site

In particular select:

• gh-pages as branch
• /(root) as folder

The website should be automatically published at https://ekothe.github.io/trackdown/

Thanks!

Hello,

I have a problem trying to upload my .Rnw document to Google drive. When I do it with hide_code= FALSE it works fine but, when I change it to hide_code=TRUE it does not work and an error message appears.

• Removing code...
  Parameter format not correct -
  Error: There are some issues in the identification of the document header start/end line indexes

I read in the bug report (#21 ) that using code headers --- inline can be producing the problem however, I use <<>>= as chunk headers and begin document and end document as document headers due to I work with a .Rnw file. Even so, I already checked my document, and the headers <<>>= are not repeated in any other part (just code chunks) as well as begin and end document code. I also have installed the 1.3.4 trackdown version but nothing the error is still appearing. Do you have an idea of how to solve this issue?
Thanks in advance!

In a personal email, an enthusiastic trackdown user suggested a very interesting idea:

Highlighting/colouring text that should not be changed in google docs (e.g. inline code, code chunks etc.).

In this way, we can minimize the risk that other users unintentionally modify these parts while editing the narrative text.

Great idea! I have started working on it, it is a little bit tricky but it is doable. I open this thread to document the development of this new feature.

Good news: Google provides API for document editing:

• google API format text https://developers.google.com/docs/api/how-tos/format-text
• batchUpdate https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
• updateTextStyleRequest https://developers.google.com/docs/api/reference/rest/v1/documents/request#UpdateTextStyleRequest
• TextStyle https://developers.google.com/docs/api/reference/rest/v1/documents#TextStyle

Bad news: r package googledrive (on which trackdown is based to manage google API) does not support Google Docs specific API (i.e., "https://docs.googleapis.com").

I have created a project for trackdown in the Google cloud platform enabling the required API. trackdown works as usual plus I was able to edit document text using the API. During the download, the formatting is automatically removed so we do not have to care about it.

However, the project on the Google cloud platform is currently in testing status (only invited users can use it). Before to published it, we need to follow best practices to deal with authentication.

• googledrive functions for authorization https://googledrive.tidyverse.org/reference/index.html#authorization
• gargle functions to create API request https://gargle.r-lib.org/reference/request_develop.html
• gargle manage API authentication for own service https://gargle.r-lib.org/articles/get-api-credentials.html
• gargle other functions https://gargle.r-lib.org/reference/oauth_app_from_json.html

To summarize, this feature is possible but requires creating a separate profile on the Google cloud platform with the required API. Plus we need to be sure that the whole authentication process is correctly managed. Plus understanding quotas and the number of operations allowed.

I will try first to ask at googledrive r package maintainers if they can introduce support for Google Docs specific API.

Finally, here is an example of an API request.

# build request text style

body <- list(requests = list(
  updateTextStyle = list(
    range = list(
      startIndex = 1,
      endIndex = 50
    ),
    textStyle = list(
      backgroundColor = list(
        color = list(
          rgbColor = list(
            blue = .99,
            green = .57,
            red = .62
          )
        )
      )
    ),
    fields = "*"
  )
),
writeControl = NULL)

req <- gargle::request_build(
  method = "POST",
  path = "v1/documents/{fileId}:batchUpdate",
  params = list(fileId = "<file-Id>"),
  body = body,
  base_url = "https://docs.googleapis.com",
  token = googledrive::drive_token()
)

resp <- gargle::request_make(req)
out <- gargle::response_process(resp)

I finally got around to testing the Team Drive (now renamed to Google Drive shared drive, see the other issue I opened) functionality.

It almost worked but there was one problem: get_root_dribble() always returned the root folder of "My Drive", even if a team_drive was specified. Furthermore, even after fixing this issue, the current implementation defaulted to data.frame(id = "root") if there were no files found which again resulted in "My Drive" being used if a team_drive was specified but it did not contain any files.

I rewrote and simplified the function (see the feature branch shared-drive) by directly getting a dribble for the root folder using drive_get() and team_drive_get(), respectively. Were there any specific reasons why you used drive_find that will make my solution fail in specific situations?

I created a new shared drive trackdown-shared-drive and shared it with the [email protected] user you created to test trackdown. So you should now all be able to test trackdown with shared drives. Please let me know whether you run into problems. Relatedly, I wanted to log into the trackdown.rpackage Google account but dual authentification is set up, so I would need either the account holders recovery email address or phone number.

Creating an issue thread to discuss testing of forks from @januz and @ClaudioZandonella on Windows

In the vignette about OAuth setup, at the moment only the non sensitive scopes are shown because the Google Drive and Google Docs APIs are enabled after that step. Could there be a screenshot of the sensitive scopes as well? Thank you!

Could there be an argument for opening the file that has been created/updated in a browser?

Possibly related to #13

On Google Docs one can name versions to "tag" them https://www.techrepublic.com/article/version-history-essentials-for-google-docs-sheets-and-slides/

Maybe trackdown could name a version (for instance the first characters of the hash of the local file) when creating/updating a doc?

Thank you for these useful package!,

I've found this error and a possible workaround

Error in seq.default(2, length(index), 2) : wrong sign in 'by' argument

Workaround:

• In addition to the setup chunk you need to have another chunk before the markdown, if it doesn't exist you get this error.

I attach two files for reproduce this error.

bug_trackdown_.zip

Dear all (@ekothe, @januz, @filippogambarota, @Lingtax )

I created a folder in Google Drive with a single file Abstract-submission to review the submission at the UseR2021 conference. Here is the link to contribute https://drive.google.com/drive/folders/1goMOIiGZ7y-N3Fokrq65kAUpVKSxis94?usp=sharing. In the first part of the document I copied relevant info for the submission, then I prepared a first draft of the abstract and other required info.

You can change, add, review and comment.

Important missing info:

• package-name
• github-repo
• authors info and order (at the moment I just used alphabetical order)

Moreover, is there anyone talented in video presentations who would like to be the presenting and first author?

Submission deadline 15th March

So it would be great to submit everything in the next few days, say by Friday 12th March.

I'll make a PR in a sec.

Please report here any issue regarding authentication or google access.

Hi, is it possible to integrate the feature like redoc https://noamross.github.io/redoc/, which allows collaborative editing on a formatted word (hence google doc) file?

This would be more 'friendly' when interacting with your non-nerd collaborators...

Running remotes::install_github("claudiozandonella/trackdown", build_vignettes = TRUE) results in:

** testing if installed package can be loaded from temporary location
Warning: The `app` argument of `drive_auth_configure()` is deprecated as of googledrive
2.1.0.
ℹ Please use the `client` argument instead.
ℹ The deprecated feature was likely used in the trackdown package.
  Please report the issue at
  <https://github.com/claudiozandonella/trackdown/issues>.
Error: package or namespace load failed for 'trackdown':
 .onLoad failed in loadNamespace() for 'trackdown', details:
  call: drive_auth_configure(client = app, path = path, api_key = api_key)
  error: missing(client) || is.null(client) || inherits(client, "gargle_oauth_client") is not TRUE
Error: loading failed
Execution halted
ERROR: loading failed
* removing 'C:/Users/socce/AppData/Local/R/win-library/4.3/trackdown'
Warning message:
In i.p(...) :
  installation of package ‘C:/Users/socce/AppData/Local/Temp/Rtmpsxm0e2/file17745baa135e/trackdown_1.5.0.tar.gz’ had non-zero exit status

R.version
               _                                
platform       x86_64-w64-mingw32               
arch           x86_64                           
os             mingw32                          
crt            ucrt                             
system         x86_64, mingw32                  
status                                          
major          4                                
minor          3.0                              
year           2023                             
month          04                               
day            21                               
svn rev        84292                            
language       R                                
version.string R version 4.3.0 (2023-04-21 ucrt)
nickname       Already Tomorrow         

https://claudiozandonella.r-universe.dev/ui#package:trackdown

Since it does not necessitate remotes/pak.

See https://ropensci.org/blog/2021/06/22/setup-runiverse/ for more context

Google Team Drives have been rebranded as Google Drive shared drives. Accordingly, all functions in the googledrive package will use that terminology from 2.0.0 on: https://googledrive.tidyverse.org/news/index.html

While the team_drive function arguments and the team_drive_get() function I used to fix the team drive functionality should still work (at least for a while), we should plan for adapting our package once googledrive 2.0.0 is on CRAN. This will involve renaming all function arguments in our package and where we use googledrive functions.

I actually started implementing these changes in the feature branch but then
stopped myself as I didn't want to make trackdown depend on a Github version of googledrive. As an intermediate strategy, we could already rename all function arguments (and related documentation) in our package but keep them in the calls to googledrive functions. Maybe this would make it easier for users as we wouldn't have to rename an argument relatively soon after releasing trackdown. What do you think?

Hello,

Thank you for this amazing package!

Nevertheless, when I try to upload my .Rmd file to my Google Drive with the upload_file() function, I keep having this error:

Error in `gargle_abort_request_failed()`:
! Client error: (403) Forbidden
Insufficient Permission: Request had insufficient authentication scopes.
• domain: global
• reason: insufficientPermissions
• message: Insufficient Permission: Request had insufficient authentication scopes.```

It seems to me to be a google drive authorization issue but I could not find a way to resolve this issue.

Do you know how to manage this issue?

Thank you in advance

When I download my document from google docs all my YAML header is missing!

This is the message I receive:

Warning message:
Failed retrieving [[document-header]] placeholder, code added at first line

Find a zip file with the initial file and the result after downloading the file.

Thanks!

Hi,

I have a problem uploading a child Rmd file that does not contain YAML header. Specifically upload_file() returns error "Error: There are some issues in the identification of YAML start/end line indexes" when hide_code = TRUE. Upload works just fine if hide_code = FALSE or with empty YAML header.

I'm not sure whether it is a really bug or it's kinda "safety feature" that you need to preserve.

Hi,
Thanks for developing this package.
I'm trying to upload a document for the first time, however tracdown seems to get stuck in the authentication stage: all what I get in the console after selecting my account is: "Auto-refreshing stale OAuth token".

Am I missing any dependencies. I'm running R 4.1.0 on Macos. The command I'm using is quite standard, I.e.::
upload_file(filename,
gpath=google_path,
hide_code=TRUE)

Thanks!
Carlos

Congratulations on this package that makes the RMardown collaboration a reality!

Here is a small typo:

Hi @ekothe!

@filippogambarota and I stumbled across your package. We found it very interesting, and we believe that it would be a handy tool in enhancing the use of R markdown in research. Many PhD students and young researchers already recognise the utility of using literate programming to write reproducible documents as well as research papers. However, the reviewing process with colleagues often becomes a bottleneck as not everyone knows R and, even using shared repositories and git, the workflow is still far from ideal. Your package, instead, allows a smooth workflow that integrates the powerful and well-known google document interface to carry a review.

We would like to collaborate on your package to improve its functions and to publish it on CRAN. Would you be interested in?

We started from the forked repository by Januz and we have already added a few improvements:

• add the possibility to remove code chuck from the uploaded document. This will allow to not scare colleagues not familiar with R code and instead focusing only on the actual text. Chunks are restored when the document is download.
• add the possibility to upload also a pdf report including the actual chunks output (e.g., figures and tables). Colleagues can use this to evaluate figures and tables and eventually comment on the pdf directly on google drive to require changes.
• upload the final document in a pdf/HTML for the final check of the desired paper
• faster google API call to identify dribble objects

We are still working on it on the develop branch (link our repo). Most of the documentation is missing and we are keen to add a few more features as well (e.g., support for .Rnw files). We plan to complete the last few things and then prepare the submission to CRAN. Would you be interested in?

Or alternatively could you please add a License to your repository in order to us to understand if we can build on from it.

In the workflow vignette

You create the initial document, for example My-Report.Rmd, and upload the file to Google Drive using the function upload_file():

trackdown::update_file(file = "Path-to-file/My-Report.Rmd", hide_code = TRUE)

I think you mean upload_file here?

If there is no file on the Google Drive, I would find it useful if trackdown performed a no-op roundtrip: reimport the unchanged document so that any bogus changes are weeded out right in the beginning.

Example: any extra newlines before headings are removed by trackdown::download_file() . Ideally, when starting work on trackdown, I would commit those changes first, before importing any real edits.

Dear @ekothe,

All unit tests are ready and the package has a ~96% of coverage.

There is only one thing that does not work properly. Github action evaluating test coverage runs correctly. However, it is not able to upload the report to codecov, so we miss the badge with the percentage.

I do not understand why. Maybe is something related to the rename of the repository as it says "Could not find a repository, try using upload token" GitHub-action-link. Could you please try to follow these instructions at https://docs.codecov.io/docs/quick-start#basic-usage?

In particular, check please if the repo ekothe/trackdown is available and in case send me by email ([email protected]) the secret token as shown in the figure

It is strange as for public repo token is not required, but something is not working properly.

Thanks

I get the following error message when I upload then download a file with no code chunks at all.

Error in seq_len(nrow(chunk_info)) : argument must be coercible to non-negative integer

I attached a simple R Markdown example as a .txt file.
trackdown.txt
Even just adding a completely empty chunk without a label seems to solve the problem.

This doesn't seem to be a problem if you upload a .rmd file that has code chunks then delete the chunk labels in the Google Doc.

When using trackdown::upload_file() for a file that already exists on Google Drive, could trackdown ask the user whether they want to overwrite it?

I tried the CRAN version and everything works as expected. (Its a wonderful package sofar, thanks!!!)
But when I upgrade to your current master version on GitHub, using:

remotes::install_github("claudiozandonella/trackdown", build_vignettes = TRUE)

I cannot use trackdown functions anymore like:

 path <- "1_paper/1_paper.Rmd"
upload_file(file = path, hide_code = TRUE)
update_file(file = path, hide_code = TRUE)
download_file(file = path)

I get in R the following error:

Error in curl::curl_fetch_memory(url, handle = handle) :
Could not resolve host: metadata.google.internal

and from Goofle I get this message:

This app is blocked
This app has attempted to access sensitive data in your Google Account. To protect your account, we have blocked access.

Could you give more details how to solve this problem (maybe even add it to the vignette)? Because the changes on the master branch are really great and I would love to use them!!! ♥

For reference https://axesslab.com/alt-texts/ and https://www.w3.org/WAI/tutorials/images/informative/

We wish to use Quarto over Rmarkdown because we want to use a journal template (PLoS ONE). Abandoned hope of collaborative development in Posit Cloud because of cost. Trackdown: “Create globally. Render locally.” seems perfect.
Tried to follow instructions re issue #57 for Quarto and Trackdown.

remove.packages("googledrive")
install.packages("~/Downloads/googledrive_2.0.0.tar.gz", repos = NULL, type = "source")
remotes::install_github("claudiozandonella/trackdown", build_vignettes = TRUE);
─ building ‘trackdown_1.5.0.tar.gz’
library(trackdown)
upload_file('OSO_Smolt_L_W.qmd', gpath='OSO SOX Primaries/1. Missing Ages/Paper and Parts/Smolts')
── Uploading files to Google Drive ──────────────────────────────
Error: OSO_Smolt_L_W.qmd not supported file type (only .Rmd or .Rnw)
😢

In the README could there be a diagram like the one in https://claudiozandonella.github.io/trackdown/articles/trackdown-workflow.html but where it is clearer that trackdown does not store the rendered version on Google Docs?

Or will trackdown eventually store the rendered version (from reading issues I have the impression no decision has been made yet)?

Hi,

I just got the following error when trying to install trackdown from GitHub :

* installing *source* package 'trackdown' ...
** using staged installation
** R
** inst
** byte-compile and prepare package for lazy loading
** help
*** installing help indices
*** copying figures
** building package indices
** installing vignettes
** testing if installed package can be loaded from temporary location
Warning: The `app` argument of `drive_auth_configure()` is deprecated as of googledrive
2.1.0.
ℹ Please use the `client` argument instead.
ℹ The deprecated feature was likely used in the trackdown package.
  Please report the issue at
  <https://github.com/claudiozandonella/trackdown/issues>.
Error: package or namespace load failed for 'trackdown':
 .onLoad failed in loadNamespace() for 'trackdown', details:
  call: drive_auth_configure(client = app, path = path, api_key = api_key)
  error: missing(client) || is.null(client) || inherits(client, "gargle_oauth_client") is not TRUE
Error: loading failed
Execution halted
ERROR: loading failed

Thank you for your work!

A current limit of the trackdown workflow is that two copies of the same file exist: one local and the other online in Google Drive. The workflow implies sequential steps where the file is uploaded to Google Drive for changes to the prose and downloaded locally for changes on the code. Changes can not be made simultaneously on the code locally and on the prose on Google Drive as the two document versions can not be merged together but only overwritten, losing one of the two versions.

In this issue, we can discuss solutions to overcome this limit. Here are three possible directions:

• @filippogambarota suggested the following procedure.

  • Currently, code chunks of the local file are extracted from the document and saved locally in the hidden folder .trackdown only if argument hide_code = TRUE. We could extract and save code chunks every time the file is uploaded/updated to Google Drive. This allows us to have a saved version of the original code.
  • After editing on Google Docs, when the document is downloaded locally we could first check if the code in the local version of the document has been modified (changes in the old chunks or new chunks been added) compared to the original code previously saved in .trackdown.
  • If the code has been modified we can ask the user whether to restore the code chunks using the original code saved at the time of upload/update or using the new code present in the current local version.

• @januz suggested having build-in versioning that saves the local file (with date-time stamp) to a hidden folder so that one could at least manually recover local changes that weren’t represented in the online version. One could also save a version of the file every time it is uploaded to GoogleDrive and use that to see whether there have been local changes. Moreover, the option to diff and merge changes should not be restricted to code chunks but also use for the prose parts as well.

• For versioning of the file and saving copies of the document, I would encourage users to rely on Git this is probably the best solution. Ideally, the user would follow the following workflow:

  • make a commit before uploading/updating the document to Google Drive that can be used as a reference point if anything goes wrong
  • create a new branch (e..g, revision) and upload/updat the document to Google Drive
  • than she/he can keep working locally on the master brach to the code or also to the prose and commit when changes are made
  • once editing/revision in Google Docs is terminated user have to switch to the branch revision and download the document
  • now there are two versions of the document, the local copy in the masterbrach with some changes and the online edited version in the review branch.
  • using git merge review -m "..." from the master branch it is possible to merge the two version using the power of git
  • I realize that this process requires some programming skill to do everything. Moreover, there are really high chances of merging conflicts so the user has to solve conflicts by hand. Git does not show differences in an intuitive way (this is one of the advantages of trackdown) but Git is very robust. Probably this workflow works better for the code chuncks. Making changes to the prose will create inevitably many conflicts if changes are done also online.

Overall I would summarize that git is highly recommended (if not mandatory) for versioning but we could still include some processes to facilitate for example the margin of code chunks as suggested by @filippogambarota

I document here an "experimental" feature introduced.

Background

When collaborating online on a document, from time to time, you may need to download and compile the document for a quick check without losing suggested edits and tracked changes. Before downloading, however, you have to accept all suggested edits. Taking advantage of the “Undo” option available in Google Docs, it is possible to download the current document version at any time during the workflow without the need to accept all suggested edits permanently :

“Tools > Review suggested edits > Accept all” and, after the download, press “Undo” to restore the document to its previous state

However, this can not be done with the comments. You can not remove and restore the comments in google docs.

Issue

When downloading the document for a quick check you will download all google comments in the document as well. Therefore, before compiling the document, comments have to be removed manually. This is a repetitive, time-consuming, process.

Solution

To overcome this issue, we introduced an optional (experimental) argument to trackdown::download_file(). By specifying rm_gcomments = TRUE (default is FALSE), google comments will be automatically removed from the document.

Technical Info

Google comments are listed at the bottom of the file. Comments are of type "[a]my comment". Alphabetic indexes between square brackets (i.e., [a], [b], ... , [aa], [ab], etc.) are used as tags to identify the comment and indicate comments' position in the text.

The internal function remove_google_comments() removes comments and comments' tags. The process is conservative. If there are any issues in the comments' identification, the specific comment is not removed.

For example, it the tag "[a]" appears multiple times in the document as actual user's text (and not only as a comment tag) tags "[a]" and relative comment are not removed

Reference commit with introduced changes: 28b5224

out of curiosity 🙂

No Hex-Logo no Package

Here we can collect our ideas and discuss about the package hex logo.

Below the proposed logo by @januz. I really like the idea of using Google Docs changes tracking style in the logo

I also added a version with only lowercase letters (consistent with the actual name of the package)

The core functionality in googledocs relies on the fact that google docs converts to raw .txt files to a google doc when uploaded. We should investigate how other online editors convert similarly formatted files to determine the feasibility of implementation in other editors. This would also be useful for the ongoing package rename discussion.

Using update_rmd() marks the entire document as a change in the google docs version history (i.e. the entire document is a diff rather than just those lines that have changes).

This is an underlying issue with googledrive:: so if diffs are required, git is a much better implementation (either as an alternative or as an additional tool).

This is a great package with lots of potential, so thanks for making it. I'm using this package is to write a scientific manuscript with non-R users, and at present, inline code is printed in the Google Doc file. In my workflow, and I suspect in many others, I use inline code to print numbers within the text (often in the methods and results sections) to avoid errors from manually calculating and transcribing them. The results of this inline code is therefore very important to surrounding inferences and text, so it would be very helpful if {trackdown} was able to evaluate inline R code, and perhaps highlight the output to indicate that it should not be edited. Whilst a workaround is to create the output document at the same time, it would be a far smoother experience to not have to switch between documents.

Thanks again for this package!

I'd like to use trackdown with quarto documents (quarto is the successor to R markdown developed by RStudio, https://quarto.org/). The file extension in qmd rather than rmd, so check-suported_documents() throws an error.

It might be as simple as editing check_supported_documents() to

check_supported_documents <- function(file_info){
  if(!(file_info$extension %in% c("rmd", "rnw", "qmd"))) # check supported files
    stop(paste(file_info$file_name, "not supported file type (only .Rmd, .Rnw, or qmd)"), 
         call. = FALSE)
}

(I tried this but then had problems with google drive authentication that I was not able to fix)

I open this issue following a personal email, as I am sure it could be helpful for others as well.

The Problem

When I download a file from Google Docs where code chunks have been hidden, what versions of code chunks are restored in the local Rmd file. From the current file or old chunks from when the file was uploaded/updated to Google Drive?

Put another way, can we, after uploading/updating the file to Google Drive, make changes to code chunks only in our local Rmd file?

Currently, trackdown restores the old chunks from when the file was uploaded/updated to Google Drive. This means that any new change to the local copy of the file (code chunks or text) made after the document is uploaded to Google Drive will be lost when downloading that file from Google Drive.

This is one of the main limits of the package. We can not change simultaneously the code in the local file and the text in the
Google Drive version of the file. The workflow has to be iterative:

• Upload the file to Google Drive to change the narrative text
• Accept changes and download locally to make changes to the code
• Upload again to Google Drive if new changes to the narrative text are required

This is a big limit.

Solutions

There is a possible solution but is a little bit laborious. The solution involves integrating the trackdown workflow into the git workflow.

Suppose we have our file and we want to use trackdown to collaborate with other colleagues on Google Drive. The workflow is:

1. We need to use git for version control. Suppose we are on the main branch
2. We Create a new branch (e.g., trackdown) and, from the new branch, we upload the file to Google Drive with trackdown.
3. Now we can go back to the main branch and keep working on the code (as well as text but is deprecated; see below). At the same time, colleagues can edit the document on Google Drive.
4. When the revision on Google Drive is finished, first we commit all the new changes on the local file in the main branch.
5. Next we checkout to the trackdown branch and we download the file from Google Drive. We commit the changes.
6. Summarizing, now in the main branch we have the local file with the new code (as well as text but is deprecated; see below) that we added locally. In the trackdown branch, instead, we have the file with the changes to the text from Google Drive and the OLD code.
7. We checkout to the main branch and we merge the trackdown branch into the main branch. In this way, the new narrative text is merged with the new code created locally.

Following this workflow, we can simultaneously on the code locally while collaborators are working on Google Drive. Actually, we can also modify the narrative text locally. However, in this case, it is likely we end up in some merge conflict (note that they can always occur).

This process is laborious. Note that if we need to upload again to Google Drive, first we need to merge the main branch into thetrackdown branch and then upload.

However, using git we are sure we will never lose parts accidentally. Moreover, git merge is very powerful in combining changes to different versions of the file (e.g., code and text). In this git is the best.

Alternative Solution

We can implement a possible alternative solution:

• trackdown checks current code chunks compared to those saved in the .trackdown/ directory before downloading the file from Google Drive.
• If the chunks are identical, restore the old chunks
• if the chunks are different, we can ask the user whether to restore old or new chunks

This process is much simpler but less secure. As long as we only change already existing files there are no problems.

However, if we add now code chunks they could brake the correspondence between tag names of placeholders and actual chunks. Restoring code, in this case, would be very difficult. Moreover, local changes to the narrative text will be always lost.

For these reasons, I would prefer to not implement this "easier" but not safe solution.

Conclusion

Instead of trying to achieve the same power of git, is better to use git. I much prefer the safer git solution, although it is quite complex for git beginners.

I leave the issue open because it could be useful to add the trackdown + git workflow to the documentation.