rjournal: Add "\pkg" to title

phargarten2 commented 3 years ago

Thank you for allowing me to compose an article for the R Journal without leaving the Markdown environment. I wanted to bring a matter to your attention as I was going over the journal's formatting instructions.

Frequently, the title of an article in the R Journal includes the name of the package. According to [the journal's instructions] (https://journal.r-project.org/share/proofreading-checklist.pdf),

Other than the above, names of R packages should be marked up with \pkg, including in the title (This ensures that the package name is correctly formatted in the table of contents). Thus, I need to add '\pkg{}' to the journal's title. However, I run into an error in Rmarkdown.

For instance, I am writing an article in the R Journal about the package foo. I created a new R Journal Template with the filename foo and the title "Foo: A Package About Foo." Below is the header from the sample Rmarkdown document.

---
title: Foo: A Package About Foo
author:
  - name: Author One
    affiliation: Affiliation
    address:
    - line 1
    - line 2
    url: https://journal.r-project.org
    orcid: 0000-0002-9079-593X
    email:  author1@work
  - name: Author Two
    url: https://journal.r-project.org
    email: author2@work
    orcid: 0000-0002-9079-593X
    affiliation: Affiliation 1
    address:
    - line 1 affiliation 1
    - line 2 affiliation 1
    affiliation2: Affiliation 2
    address2:
    - line 1 affiliation 2
    - line 2 affiliation 2
  - name: Author Three
    url: https://journal.r-project.org
    email: author3@work
    affiliation: Affiliation
    address:
    - line 1 affiliation
    - line 2 affiliation
abstract: >
  An abstract of less than 150 words.
preamble: |
  % Any extra LaTeX you need in the preamble

# per R journal requirement, the bib filename should be the same as the output 
# tex file. Don't forget to rename the bib file and change this example value.
bibliography: RJreferences.bib

output: rticles::rjournal_article
---

Per the journal requirements, I need to change the text-style of foo in the title. So, if I add the tag "\pkg{}" in the title field of the YAML header such that the title now reads \pkg{Foo}: A Package About Foo, I get the error

Error in yaml::yaml.load(..., eval.expr = TRUE) : 
  Scanner error: mapping values are not allowed in this context at line 1, column 17
Calls: <Anonymous> ... parse_yaml_front_matter -> yaml_load -> <Anonymous>
Execution halted

A simple solution is to add \pkg{} in the generated LaTex file, but such an approach is against the spirit of this package.

More details can be found here: foo.zip

Thanks for your help!

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.

Package Information:

R version 4.0.2 (2020-06-22)
Platform: x86_64-apple-darwin17.0 (64-bit)
Running under: macOS High Sierra 10.13.6, RStudio 1.2.1335

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

Package version:
  base64enc_0.1.3    digest_0.6.25      evaluate_0.14     
  glue_1.4.2         graphics_4.0.2     grDevices_4.0.2   
  highr_0.8          htmltools_0.5.0    jsonlite_1.7.1    
  knitr_1.30         magrittr_1.5       markdown_1.1      
  methods_4.0.2      mime_0.9           rlang_0.4.7       
  rmarkdown_2.3      rticles_0.16.1     stats_4.0.2       
  stringi_1.5.3      stringr_1.4.0.9000 tinytex_0.26      
  tools_4.0.2        utils_4.0.2        xfun_0.17         
  yaml_2.2.1

phargarten2 commented 3 years ago

I also cited this issue in the YAML package as the error is from a yaml function.

spgarbet commented 3 years ago

If it's in quotes and properly escaped it works fine.

---
title: "\\pkg{Foo}: A Package About Foo"
author: "Someone"
date: "1/4/2021"
output: html_document
---

phargarten2 commented 3 years ago

Thank you. It sure does (though the output suggested is using rmarkdown::html_document() rather than rticles::rjournal_article()`). The same sort of logic though works in this case (see below).

 ---
title: "\\pkg{foo}: A Package About Foo"   #Adding \pkg{Foo} throws an error in yaml.
author:
  # see ?rjournal_article for more information
  - name: Author One
    affiliation: Affiliation
    address:
    - line 1
    - line 2
    url: https://journal.r-project.org
    orcid: 0000-0002-9079-593X
    email:  author1@work
  - name: Author Two
    url: https://journal.r-project.org
    email: author2@work
    orcid: 0000-0002-9079-593X
    affiliation: Affiliation 1
    address:
    - line 1 affiliation 1
    - line 2 affiliation 1
    affiliation2: Affiliation 2
    address2:
    - line 1 affiliation 2
    - line 2 affiliation 2
  - name: Author Three
    url: https://journal.r-project.org
    email: author3@work
    affiliation: Affiliation
    address:
    - line 1 affiliation
    - line 2 affiliation
abstract: >
  An abstract of less than 150 words.
preamble: |
  % Any extra LaTeX you need in the preamble

# per R journal requirement, the bib filename should be the same as the output 
# tex file. Don't forget to rename the bib file and change this example value.
bibliography: RJreferences.bib

output: rticles::rjournal_article

When using a special command like '\pkg{}' in the title, what language are you thinking of? Is the syntax (the quotes and escape character "\") as if you are in LaTex, @spgarbet? It is interesting as the title in the YAML header is usually not quoted.

spgarbet commented 3 years ago

Once you get into special characters, like the colon in YAML, it needs to be escaped or quoted.

yihui commented 3 years ago

From this page: https://bookdown.org/yihui/rmarkdown/output-formats.html

If you are not sure if a string should be quoted or not, test it with the yaml package

and you can try:

> cat(yaml::as.yaml(list(title = "\\pkg{Foo}: A Package About Foo")))
title: '\pkg{Foo}: A Package About Foo'

Special characters lose their special meanings inside single quotes. You can also use double quotes, but backslashes need to be escaped (hence \\).

github-actions[bot] commented 3 years ago

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.

rstudio / rticles

rjournal: Add "\pkg" to title #363