Interaction between pkdown and `\AND` in JSS articles

nbenn commented 3 years ago

By filing an issue to this repo, I promise that

[x] I have fully read the issue guide at https://yihui.name/issue/.
[x] I have provided the necessary information about my issue.
- If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
- If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('rticles'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('rstudio/rticles').
- If I have posted the same issue elsewhere, I have also mentioned it in this issue.
[x] I have learned the Github Markdown syntax, and formatted my issue correctly.

I understand that my issue may be closed if I don't fulfill my promises.

When creating a package website using pkgdown for a package that contains a JSS vignette which has authors arranged using \AND, the following issue comes up:

First a minimal package where everything works as expected:

usethis::create_package("rticles398")
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)],
   "pkgdown:",
   "  as_is: true",
   "  extension: pdf",
   "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")

devtools::build_vignettes()
# --> all fine
pkgdown::build_site()
# --> all fine

If, however the affiliation containing the \AND also contains an address, as

rmd <- readLines("vignettes/vignettes.Rmd")
ind <- grep("\\AND", rmd)[1L]
rmd <- c(
   rmd[seq_len(ind + 1L)],
   "    address: |",
   "      | First line",
   "      | Second line",
   rmd[seq.int(ind + 2L, length(rmd))]
)
write(rmd, file = "vignettes/vignettes.Rmd")

devtools::build_vignettes()
# --> all fine
pkgdown::build_site()
#> Error : Failed to render RMarkdown
#> * ! Undefined control sequence.
#> * \@Address ...~\\ Second Author\\ Affiliation \AND
#> *                                                   \\ First line\\ Second lin...
#> * l.124 \end{document}
#> *
#> * Error : LaTeX failed to compile /some/dir/rticles398/docs/articles/vignettes.tex. See https://yihui.org/tinytex/r/#debugging for debugging tips. See vignettes.log for more info.

There is a fix for this: If an affilliation2 is added in addition to the offending affiliation, which does not contain the the \AND, the problem goes away.

Is this intentional?
If so, I feel adding a remark somewhere, outlining the fix above, would be helpful, as it took me quite some time to get there.

R version 4.0.4 (2021-02-15)
Platform: x86_64-apple-darwin17.0 (64-bit)
Running under: macOS Big Sur 10.16

Locale: en_US.UTF-8 / en_US.UTF-8 / en_US.UTF-8 / C / en_US.UTF-8 / en_US.UTF-8

Package version:
  digest_0.6.27   evaluate_0.14   glue_1.4.2      graphics_4.0.4
  grDevices_4.0.4 highr_0.9       htmltools_0.4.0 jsonlite_1.7.2
  knitr_1.33      magrittr_2.0.1  markdown_1.1    methods_4.0.4
  mime_0.10       Rcpp_1.0.6      rlang_0.4.11    rmarkdown_2.6
  rticles_0.19    stats_4.0.4     stringi_1.5.3   stringr_1.4.0
  tinytex_0.31    tools_4.0.4     utils_4.0.4     xfun_0.22
  yaml_2.2.1

cderv commented 3 years ago

Is this happening only with pkgdown or can you make a reproducible example with rmarkdown and rticles only with an Rmd file built using rmarkdown::render() ?

If so, that would be easier for me to understand and see the underlying issue.

Thanks.

nbenn commented 3 years ago

I'm sorry, but I don't see how to make the above reproducible example more reproducible. I do say that devtools::build_vignettes() succeeds where pkgdown::build_articles() fails, so the problem is not with rmarkdown::render() (which can be verified with the above example) but is somehow an interaction between pkgdown::build_articles() and specifics of this type of vignette. If you feel that this is more an issue with pkdgown than with rticles, I apologize and you can go ahead and close again.

cderv commented 3 years ago

Thanks for you precision. I missed the fact that this works fine with rmarkdown::render() but fail with the package bundling usage. It feels like this may be an issue with how pkgdown is rendering the vignette.

With an issue like this one, it requires digging and making the reproducible example a minimal reproducible example which is always difficult. For now, this could be in one of the layer involved. (pkgdown, rmarkdown, rticles, the LaTeX template inside rticles, ...)

As this works with rmarkdown::render() or devtools::build_vignettes() and fails only with pkgdown, I would say the issue is there but I don't have a clue why.

As I said, this requires digging but it does not feel like a rticles issue directly. If we need to make some adaptation for pkgdown to work, then we'll happily do it.

If not already, it could be interesting to have this reported in pkgdown also to have more help from them to solve this.

I'll leave that open, but we'll need some help looking into this.

rstudio / rticles

Interaction between pkdown and `\AND` in JSS articles #398