Add JOSS and JOSE format #229

noamross · 2019-06-02T20:34:21Z

While JOSS and JOSE take markdown submissions, this seemed the best place to put the pipeline so that R authors could locally preview the rendered PDF.

@karthik @arfon @eveskew

To contribute a new article template to this package, please make sure you have done the following things (note that journalname_article below is only an example name):

Unless you have done it in any other RStudio's projects before, please sign the individual or corporate contributor agreement for a significant pull request (it is fine not to sign it if a PR is only intended to fix a few typos). You can send the signed copy to jj@rstudio.com.

Previously signed

Lastly, please try your best to do only one thing per pull request (e.g., if you want to add two output formats, do them in two separate pull requests), and refrain from making cosmetic changes in the code base: https://yihui.name/en/2018/02/bite-sized-pull-requests/

Thank you!

yihui

BTW, have you run optipng on PNG images?

Thank you!

yihui · 2019-06-03T16:02:35Z

R/joss_article.R

+                        "Journal of Open Source Software",
+                        "Journal of Open Source Education")
+
+  template_variables <- c(


How about setting these variables in the YAML frontmatter of the Rmd document? That way, you won't have to worry about escaping certain special characters in the values of these variables (although I guess it would be unlikely that these values could contain characters like double quotes). It will also make the R function much simpler.

I wanted to avoid needing these variables in the YAML so that a standard paper.md would compile without setting them, but now I realized that the document will compile without most of them. The logo and journal name still make sense to define here, but I can drop the rest.

yihui · 2019-06-03T16:04:59Z

R/joss_article.R

+  base$knitr$opts_chunk$fig.width <- 6
+  base$knitr$opts_chunk$fig.height <- 4.15
+  base$keep_md <- keep_md
+  base$clean_supporting <- !keep_md


All above options can be passed to pdf_document_format() so you don't need to hack the base object.

Will do, except keep_md, which is not supported in pdf_document() (rstudio/rmarkdown#1001)

I just added support for keep_md in rmarkdown, so you can get rid of this hack, too.

yihui · 2019-06-03T16:05:29Z

R/joss_article.R

+
+  pandoc_args <- c(
+    template_variables,
+    "--csl", find_resource("joss_article", "apa.csl")


I hope the csl option could be set in the YAML metadata of the Rmd document, too.

I wanted to avoid doing this because I wanted the format to compile correctly on a standard paper.md without modifying the YAML.

All other templates in this package include csl under the skeleton/ directory (instead of resources/) so the csl file will be copied over when creating a new article using rticles::draft(), e.g. https://github.com/rstudio/rticles/tree/master/inst/rmarkdown/templates/acm_article/skeleton Then in Rmd: https://github.com/rstudio/rticles/blob/master/inst/rmarkdown/templates/acm_article/skeleton/skeleton.Rmd#L15

I'm aware of the potential disadvantages of this approach (e.g. the csl file may change in the upstream), but I'd like this template to be consistent with other templates. Similarly, I hope logo_path, journal_name, and graphics variables could all be set in the YAML frontmatter of skeleton.Rmd (the png logos need to be moved to skeleton/ accordingly).

noamross · 2019-06-03T22:05:34Z

OK, optimized the images, and simplified the function now that I realize that the article will compile without all those variable set. I have left the csl coded into the function. I think that the most common workflow will be for authors with already-created paper.md files to want to compile them to check references, so want to keep the need to change the YAML minimal.

noamross · 2019-06-17T10:39:40Z

Just checking in. Is this version mergable?

yihui · 2019-06-17T21:12:35Z

Sorry, I haven't had a chance to look at the revision yet.

yihui

I think there is a good chance that this format can be simplified and moved to https://github.com/rstudio/rticles/blob/master/R/article.R. Thanks!

yihui · 2019-06-26T18:59:26Z

R/joss_article.R

+    pandoc_args = pandoc_args,
+    citation_package = "none",
+    fig_width = 6, fig_height = 4.15,
+    dev = "png"


Since you hard-coded these options, are users not supposed to customize fig_width, fig_height, or dev?

BTW, it seems you forgot to pass the ... argument here.

yihui · 2019-06-26T19:07:00Z

R/joss_article.R

+
+  pandoc_args <- c(
+    template_variables,
+    "--csl", find_resource("joss_article", "apa.csl")


All other templates in this package include csl under the skeleton/ directory (instead of resources/) so the csl file will be copied over when creating a new article using rticles::draft(), e.g. https://github.com/rstudio/rticles/tree/master/inst/rmarkdown/templates/acm_article/skeleton Then in Rmd: https://github.com/rstudio/rticles/blob/master/inst/rmarkdown/templates/acm_article/skeleton/skeleton.Rmd#L15

I'm aware of the potential disadvantages of this approach (e.g. the csl file may change in the upstream), but I'd like this template to be consistent with other templates. Similarly, I hope logo_path, journal_name, and graphics variables could all be set in the YAML frontmatter of skeleton.Rmd (the png logos need to be moved to skeleton/ accordingly).

yihui · 2019-06-26T19:35:01Z

R/joss_article.R

+  base$knitr$opts_chunk$fig.width <- 6
+  base$knitr$opts_chunk$fig.height <- 4.15
+  base$keep_md <- keep_md
+  base$clean_supporting <- !keep_md


I just added support for keep_md in rmarkdown, so you can get rid of this hack, too.

yihui · 2019-06-26T19:36:59Z

R/joss_article.R

+        paste(metadata$authors[[1]]$name, "et. al."),
+        metadata$authors[[1]]$name
+      )
+      return(c("-V", paste0("citation_author=", citation_author)))


Again, I wish this variable could be set in YAML. I'm definitely being selfish here: I want the R source code of this package to be as simple as possible, and I guess the price for users to pay is not that high (typing out a name).

noamross · 2019-06-26T22:15:39Z

It's not the upstream that I'm concerned with here as the downstream. With JOSS, the .md file will be submitted, not the LaTeX or PDF, and then the file goes through their automated build system. So I'm concerned that user settings in the YAML will clash with that. Perhaps @arfon can comment here - if users set additional fields such as csl: in their YAML, will that break the JOSS/JOSE build in any way?

karthik · 2019-06-26T22:23:23Z

Arfon will have to weigh in but yes setting csl in the yaml will not be used in the automated build system. It's hard coded here

yihui · 2019-06-28T21:15:50Z

Since csl is hard-coded in the build system, user's setting in YAML will be ignored. See https://pandoc.org/MANUAL.html#citation-rendering:

Set the csl field in the document’s metadata to FILE, overriding any value set in the metadata.

arfon · 2019-07-03T07:10:13Z

Arfon will have to weigh in but yes setting csl in the yaml will not be used in the automated build system. It's hard coded here

Yep, we don't support custom CSL definitions for JOSS papers.

noamross · 2019-09-03T00:53:55Z

I've moved csl and other variables to the YAML rather than the function. I have kept the logic in the function to switch between JOSE and JOSS articles. This is slightly more complex than the simplest article functions but it's DRYer than having two formats for JOSS and JOSE.

yihui

Thank you!

yihui reviewed Jun 3, 2019

View reviewed changes

yihui requested changes Jun 26, 2019

View reviewed changes

yihui force-pushed the master branch 3 times, most recently from 033a19f to d98786f Compare August 20, 2019 20:57

noamross added 5 commits September 2, 2019 19:42

Add JOSS and JOSE format

74c253d

Optimize JOSS logo (JOSE already optimized)

cc7a2f8

Simplify joss_article function

456a566

Fix typo in DESCRIPTION

ae57c1a

Move more logic to skeleton

76376ab

noamross force-pushed the joss branch from ba203de to 76376ab Compare September 3, 2019 00:50

yihui added 3 commits September 13, 2019 10:38

move news to v0.11

7dc6db4

unnecessary assignment

a4c02fc

Merge branch 'master' into joss

454b35c

yihui approved these changes Sep 13, 2019

View reviewed changes

yihui merged commit 4f2ded0 into rstudio:master Sep 13, 2019

github-actions bot locked as resolved and limited conversation to collaborators Nov 2, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add JOSS and JOSE format #229

Add JOSS and JOSE format #229

noamross commented Jun 2, 2019

yihui left a comment

yihui Jun 3, 2019

noamross Jun 3, 2019

yihui Jun 3, 2019

noamross Jun 3, 2019

yihui Jun 26, 2019

yihui Jun 3, 2019

noamross Jun 3, 2019

yihui Jun 26, 2019

noamross commented Jun 3, 2019

noamross commented Jun 17, 2019

yihui commented Jun 17, 2019

yihui left a comment

yihui Jun 26, 2019

yihui Jun 26, 2019

yihui Jun 26, 2019

yihui Jun 26, 2019

noamross commented Jun 26, 2019

karthik commented Jun 26, 2019

yihui commented Jun 28, 2019

arfon commented Jul 3, 2019

noamross commented Sep 3, 2019

yihui left a comment

Add JOSS and JOSE format #229

Add JOSS and JOSE format #229

Conversation

noamross commented Jun 2, 2019

yihui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noamross commented Jun 3, 2019

noamross commented Jun 17, 2019

yihui commented Jun 17, 2019

yihui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noamross commented Jun 26, 2019

karthik commented Jun 26, 2019

yihui commented Jun 28, 2019

arfon commented Jul 3, 2019

noamross commented Sep 3, 2019

yihui left a comment

Choose a reason for hiding this comment