Using JSS article in vignettes

[cderv]

@cderv Thanks for getting back to me. Also, if you feel SO would be a better place for me to ask questions like this, I'm happy to be redirected.

I tried isolating my issue in a standalone package: nbenn/rticles329, created as

usethis::create_package("rticles329")
usethis::use_mit_license()
rmarkdown::draft("vignettes.Rmd", template = "jss", package = "rticles",
                 edit = FALSE)

rmd <- readLines("vignettes/vignettes.Rmd")
ind <- grep("---", rmd)[2L]
rmd <- c(
   rmd[seq_len(ind - 1L)],
   "vignette: >",
   "  %\\VignetteIndexEntry{A Capitalized Title}",
   "  %\\VignetteEngine{knitr::rmarkdown}",
   "  %\\VignetteEncoding{UTF-8}",
   rmd[seq.int(ind, length(rmd))]
)
write(rmd, file = "vignettes/vignettes.Rmd")

usethis:::use_dependency("knitr", "Suggests")
usethis:::use_dependency("rmarkdown", "Suggests")
usethis:::use_dependency("rticles", "Suggests")
usethis:::use_description_field("VignetteBuilder", "knitr", overwrite = TRUE)
usethis:::use_git_ignore("inst/doc")

usethis::use_github_action("build",
   url = paste("https://raw.githubusercontent.com/eth-mds/ricu",
               "f7558ed99017dcd3a36ef2a5c92a9c8043621472/.github/workflows",
               "build.yaml", sep = "/")
)

One thing I don't fully understand, is which file is used in the end. From what I have observed so far, it seems that if available (i.e. not build-ignored), the package-local is used and if build-ignored, this defaults to the file that comes with R.

This leaves me with the choice of either having a note as

❯ checking files in ‘vignettes’ ... NOTE
  The following files are already in R: ‘jss.bst’, ‘jss.cls’
  Please remove them from your package.

on all R versions during checking (see this run) or build-ignoring the files as

usethis::use_build_ignore("^vignettes/jss\\.(cls|bst)$", escape = FALSE)

and then all is fine with R-release, but R-oldrel fails (see this run). Is there any way out of this conundrum?

Originally posted by @nbenn in #329 (comment)

[cderv]

@nbenn I moved your comment in a new issue

Thanks for getting back to me. Also, if you feel SO would be a better place for me to ask questions like this, I'm happy to be redirected.

When in doubt, follow the issue guide: https://yihui.org/issue/

• It is better to open a new issue and reference an old closed issue than replying and the end of an old thread - most of the time, months later it is not directly related.
• For general questions, https://community.rstudio.com is a good place to ask.

I tried isolating my issue in a standalone package

Thanks, that will help to have a look. And it clarify for me that you are using this in a R package for vignettes. Sorry I did not get that earlier.

And I think you got to the bottom of the issue. JSS files are special because they are included with R as you said. The file included with oldrel of R is not compatible with the new version of latex - it has been updated only for R 4.0 here wch/r-source@50e0332#diff-40d315f66f364ab42b39fbf99b30ddebea15425296b4c844827d478059fe061b

So it is very specific to R package and old version of R and not with rticles directly. You may seek advice on twitter or in R package devel mainling list maybe.

Unfortunately, I am not sure how to solve this with a third way after the two you tried already.
However, R 4.1 will be out on 2021-05-18, so oldrel will because 4.0.5 which will contain the correct jss.cls
file. So maybe you can wait for it to be solved ?

[nbenn]

Unfortunately, I am not sure how to solve this with a third way after the two you tried already.

Thanks. I guess this answers the original question I had for you.

The way forward would consequently be to either depend on R >= 4.0.4 or not build-ignore jss.cls and explain the note to CRAN for any R package that includes a JSS article as vignette. @cderv do you agree?

So it is very specific to R package and old version of R and not with rticles directly.

I do understand that this is not an issue that is created by rticles, but nevertheless, any R package that uses the JSS portion of rticles and does not depend on R >= 4.0.4 is affected by this.

However, R 4.1 will be out on 2021-05-18, so oldrel will because 4.0.5 which will contain the correct jss.cls
file. So maybe you can wait for it to be solved ?

This of course does not solve anything really (near-term at least). Sure oldrel will be bumped but the R >= 4.0.4 dependency remains.

[nbenn]

@cderv Thanks to your tip of writing to r-pkg-devel, I got an excellent suggestion from @zeileis, who provided a workaround that essentially puts this issue to rest (at least as far as I am concerned):

1. add classoption: notitle to the YAML header
2. add \maketitle somewhere between the YAML header and the first section heading

Personally I feel this warrants consideration for being added to the template (or at least for being mentioned somewhere), but this of course is your call.

[cderv]

Thanks for sharing back this solution. I feel this is rather specific making vignettes with jss_article() format and this Github issue will serve as documentation. If anyone else encounter this same issue, your solution will be found, and one can give a 👍.

If this is really something people are struggling with, we could add a mention in the help page of the function. However, I feel users will more easily look on the web and find this thread than open the help page of the function - I may be wrong, we'll see.

If you want to suggest a PR for documenting this, please feel free to do so as you may explain it better than me. I'll be happy to review.

Thanks!

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.