Update section about rmdrive becoming trackdown package

[ClaudioZandonella]

Referring to issue #333

I updated the section referring to the package rmdrive now named trackdown. The package received a complete revision, the workflow follows the same idea as before, but there are several new features and changes.

The chapter now includes updated documentation:

• Introduce the trackdown package for collaborative writing.
• Description of package main features and general workflow.
• Example of workflow
• Added 3 images

TODO missing reference for trackdown package. I could not add the bib entry for the package to the packages.bib file that is automatically created.

@Manual{R-trackdown,
    title = {trackdown: Collaborative Writing and Editing of R Markdown (or Sweave) Documents in Google Drive},
    author = {Emily Kothe and Claudio {Zandonella Callegher} and Filippo Gambarota and Janosch Linkersdörfer and Mathew Ling},
    year = {2021},
    note = {R package version 0.1.0}
    url = {https://github.com/ekothe/trackdown},
  }

[cderv]

Thanks for the PR !

TODO missing reference for trackdown package. I could not add the bib entry for the package to the packages.bib file that is automatically created.

trackdown needs to be installed so that knitr::write_bib() picks it up. You need to add it to DESCRIPTION as it is where we track dependencies. I believe for now, it is not installed. Then you need to add it to the list of package only installed for references
https://github.com/yihui/rmarkdown-cookbook/blob/c2f249e9e7cbac4fc82a044ea7f4a35b1f4ca20f/18-references.Rmd#L11

However, when I install the package on my system and run the citation function I don't get exactly what is expected it seems (urls are not in url part of the citation...)

> toBibtex(utils::citation("trackdown"))
@Manual{,
  title = {trackdown: Collaborative Writing and Editing of R Markdown (or Sweave)
Documents in Google Drive},
  author = {Emily Kothe and Claudio {Zandonella Callegher} and Filippo Gambarota and Janosch Linkersdörfer and Mathew Ling},
  year = {2021},
  note = {https://github.com/ekothe/trackdown/,
https://ekothe.github.io/trackdown/},
}
Warning message:
In utils::citation("trackdown") :

Possibly because it is not from CRAN ?

About CRAN, we could also wait for the package to be on CRAN to update the book section.

About the book chapter on trackdown, it is now quite long. The R Markdown Cookbook does not aim to be the place for documenting how to use the package. We added on this in the book to inform users that such package exist and can suits their specific need.

You already have a great documentation on https://ekothe.github.io/trackdown/ with a specific article on the workflow example already https://ekothe.github.io/trackdown/articles/trackdown-workflow.html. Having such documentation is several places could make it difficult to keep up to date.

So I would probably tend to remove the "workflow example" part and instead point to your documentation or specific part of your documentation.

What do you think ?

[ClaudioZandonella]

Hi @cderv,

thank you for the quick reply.

Regarding packages dependencies, I have added trackdown to the list (see commit be9a76e).

Now if I run toBibtex(utils::citation("trackdown")) information are displayed correctly, because I added the CITATION file in the trackdown repo.

> toBibtex(utils::citation("trackdown"))
@Manual{,
  title = {trackdown: Collaborative Writing and Editing of R Markdown (or Sweave) Documents in Google Drive},
  author = {Emily Kothe and Claudio {Zandonella Callegher} and Filippo Gambarota and Janosch Linkersdörfer and Mathew Ling},
  year = {2021},
  note = {R package version 0.1.0},
  url = {https://github.com/ekothe/trackdown},
}

The only remaining issue is that in the rendered book I do not get the same output. Looking at the source code of knitr::write_bib() function, I noted that the function utils::citation() is used specifying the argument auto. In short, this leads to the citation being generated from the information included in the DESCRIPTION file rather than the CITATION file.

In the URL field of the DESCRIPTION file, I have two URLs one linking to the Github repo and the other linking to the documentation:

URL: https://github.com/ekothe/trackdown/, https://ekothe.github.io/trackdown/

In the function utils::citation() if more than one URL is specified, the URLs are listed in the bib note field. Thus the actual bib entry I get in the packages.bib file is:

@Manual{R-trackdown,
  title = {trackdown: Collaborative Writing and Editing of R Markdown (or Sweave)
Documents in Google Drive},
  author = {Emily Kothe and Claudio {Zandonella Callegher} and Filippo Gambarota and Janosch Linkersdörfer and Mathew Ling},
  year = {2021},
  note = {https://github.com/ekothe/trackdown/,
https://ekothe.github.io/trackdown/},
}

I have noted that this happens also for other packages (e.g., reactable, gifski, ggplot2). Basically, all packages with more than one URL have the same problem.

I would like to keep both URLs in the DESCRIPTION file as it helps to point out the documentation available online. Is it ok if I leave the citation like that?

About the book chapter on trackdown, it is now quite long. The R Markdown Cookbook does not aim to be the place for documenting how to use the package. We added on this in the book to inform users that such package exist and can suits their specific need.
You already have a great documentation on https://ekothe.github.io/trackdown/ with a specific article on the workflow example already https://ekothe.github.io/trackdown/articles/trackdown-workflow.html. Having such documentation is several places could make it difficult to keep up to date.
So I would probably tend to remove the "workflow example" part and instead point to your documentation or specific part of your documentation.
What do you think ?

I agree with you! In commit 4cddb18 I have removed the workflow example pointing out interested readers to the package documentation. Now the chapter is much shorter.

About CRAN, we could also wait for the package to be on CRAN to update the book section.

The JOSS is considering whether or not to review the package (openjournals/joss-reviews#3427). If they accept to review (fingers crossed) I guess that it would require around 3 months or more before the package is on CRAN. In this case, I would prefer to update the chapter section now as the current chapter is still referring to the old version of the package.

Instead, if the JOSS refuse to review it, I will submit it to CRAN immediately. In this case, I guess it would take only a couple of weeks so we can wait for the package to be on CRAN before update the chapter.

What do you think about this?

PS. thanks for pointing out I was missing the Remotes: specification

[cderv]

In the URL field of the DESCRIPTION file, I have two URLs one linking to the Github repo and the other linking to the documentation:

This is how we handle the multiple URL in DESCRIPTION for our package and their citations

https://github.com/rstudio/bookdown/blob/0699af4bc8d4900312945b726bd8896783a9b522/inst/CITATION#L12

You can see we have a special handling for the URL.

However, you are right that write_bib does not seems to take into account the CITATION file. It uses the autogenerated version from Package's DESCRIPTION. However, Multiple urls in URL field is handled only for CRAN package.

Maybe write_bib could behave differently, and / or handle this case specifically. For now, we'll need to have the url in notes for your package.

This is something for knitr. I'll probably open an issue there.

When will you have the JOSS answer ?

I think we could still publish like this before CRAN release anyway

[ClaudioZandonella]

https://github.com/rstudio/bookdown/blob/0699af4bc8d4900312945b726bd8896783a9b522/inst/CITATION#L12

Thanks for your tip! Really interesting method. I love to learn new tricks every day!

When will you have the JOSS answer?

I guess JOSS would require a couple of days ~ one week to answer.

I agree with you that if it is possible we can just publish and update when the package will be available on CRAN.

Thanks for your time!

[cderv]

@ClaudioZandonella see yihui/knitr#2028

there was a change in write_bib() to use the first URL if found and so that it is not included in note. Using the CITATION file could be trickier.

[cderv]

I don't where we are on the CRAN release or not. I'll merge this PR and you can do one more to update when the package is on CRAN.

Thanks !