rstudio / rstudio/rticles

Interaction between pkdown and `\AND` in JSS articles

Open
#398 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted :heart:
Dominant language
TeX
Stars
1.5k
Forks
517
Avg merge
1d 8h
Merged PRs (30d)
5

Description


By filing an issue to this repo, I promise that

  • I have fully read the issue guide at https://yihui.name/issue/.
  • 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.
  • 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.

  1. Is this intentional?
  2. 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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the example in vignettes/vignettes.Rmd, running devtools::build_vignettes() and pkgdown::build_site(), then inspect the generated docs/articles/vignettes.tex and its LaTeX error. Determine whether an affiliation containing \AND and a multiline address should build successfully; done means the failing case is fixed or the intentional workaround is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, r
Domain
build-system, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.