Update to elsevier template #467
Conversation
|
As per #396 |
There was a problem hiding this comment.
Thanks a lot for tackling this. Here is a first review.
My main point of concerns is how I should handle potential breaking change for this format. Either the pandoc requirement, or the template change.
we don't have a good way to handle this currently. But maybe there is not so much user, and publishing to elservier would require the new template.
@cboettig do you have a thought on this as the first contributor to this template ?
@robjhyndman you can also add you on the README table. https://github.com/rstudio/rticles#templates
| @@ -157,13 +157,23 @@ ctex <- ctex_article | |||
| #' @section `elsevier_article`: Format for creating submissions to Elsevier | |||
| #' journals. Adapted from | |||
| #' <https://www.elsevier.com/authors/policies-and-guidelines/latex-instructions>. | |||
| #' | |||
| #' It requires a minimum version of 2.10 for Pandoc. | |||
There was a problem hiding this comment.
I need to think about this. I don't mind doing that for new articles formats, but elsevier_article() is not a new function. Adding this requirement will make this a breaking change. They would need to have a newer Pandoc. Version 2.10 is not that old "2020-06-29" and even if RStudio is shipping with recent version, there could be some users still using an older Pandoc.
| $if(keywords)$ \begin{keyword} $for(keywords)$$keywords$$sep$ $endfor$\end{keyword}$endif$ | ||
| $if(keywords)$ | ||
| \begin{keyword} | ||
| $for(keywords/allbutlast)$$keywords$ \sep $endfor$ | ||
| $for(keywords/last)$$keywords$$endfor$ | ||
| \end{keyword} | ||
| $endif$ |
There was a problem hiding this comment.
This is the part where Pandoc 2.10 is required right ?
So that we have keyword1 \sep keyword2 and not keyword1 \sep keyword2 \sep ?
There was a problem hiding this comment.
Yes, that's the only place that requires pandoc 2.10. I can't think of another way to do it without the user explicitly adding the \sep separators which is a bit ugly.
There was a problem hiding this comment.
yes this is cleaner, but it brings a pretty recent version of Pandoc as a requirement for this template.
You have concerns about elsarticle.cls being outdated on some Linux distribution and that user won't update. Shouldn't we have the same concerns regarding Pandoc ?
If we consider that rticles users are mainly RStudio users, a pandoc version > 2.10 is available since last release. And next release with upgraded version should be soon. So we can set the minimum requirement and see if someone complain.
Other option would be indeed to have a comment in YAML header to ask user to add \sep at the end of the last keyword, or do that ourself in the format by modifying the metadata before doing conversion with Pandoc.
|
@cderv I don't have any deep insights here (been too long since I was up-to-date on changes to pandoc etc), but perhaps it is worth introducing a version number to the template rather than creating a breaking change? Personally I don't have too many reservations though about requiring the newer version of pandoc going forward without that (particularly if RStudio is shipping with a recent enough version of pandoc). I have plenty of old papers/drafts using the old template, but those usually need to run in version-locked environments anyway as changes to packages or even LaTeX style files can break those builds. |
|
Thanks for the feedback.
That is one option. We did that for
I like this - Maybe I should add a vignette or other documentation to recommend using renv with rticles project so that one can rerun an article with a fixed rticles version. This would allow us to be less conservative about changes in the template. Considering this, I would go with the breaking change here. |
Co-authored-by: Christophe Dervieux <[email protected]>
|
Thanks @robjhyndman ! |
How to contribute a new output format ?
To contribute a new article template to this package, please make sure you have done the following things (note that
journalname_articlebelow is only an example name):This project uses a Contributor Licence Agreement (CLA) that you'll be asked to sign when opening a PR. This is required for a significant pull request (it is fine not to sign it if a PR is only intended to fix a few typos). We use a tool called CLA assistant for that.
You could also, unless you have done it in any other RStudio's projects before, sign the individual or corporate contributor agreement. You can send the signed copy to [email protected].
Add the
journalname_article()function toR/article.Rif the output format is simple enough, otherwise create a separateR/journalname_article.R.Document your function using roxygen2. Markdown syntax is supported. Refer to https://roxygen2.r-lib.org/articles/rd-formatting.html for formatting references.
Add the Pandoc LaTeX template
inst/rmarkdown/templates/journalname/resources/template.tex.Add a skeleton article
inst/rmarkdown/templates/journalname/skeleton/skeleton.Rmd.Add a description of the template
inst/rmarkdown/templates/journalname/template.yaml.Please include the document class file (
*.cls) if needed, but please do not include standard LaTeX packages (*.sty) that can be downloaded from CTAN. If you are using TinyTeX or TeX Live, you can verify if a package is available on CTAN viatinytex::parse_packages(files = "FILENAME"")(e.g., whenFILENAMEisplain.bst, it should return"bibtex", which means this file is from a standard CTAN package). Please keep the number of new files absolutely minimal (e.g., do not include PDF output files), and also make examples minimal (e.g., if you need a.bibexample, try to only leave one or two bibliography entries in it, and don't include too many items in it without using all of them).Update Rd and namespace (could be done by
devtools::document()).Update NEWS.
Update README with a link to the newly supported journal. Please add your Github username and the full name of the journal (follow other examples in the list).
Add a test to
tests/testit/test-formats.Rby adding a linetest_format("journalname"). We try to keep them in alphabetical order.Add your name to the list of authors
Authors@Rin DESCRIPTION. You don't need to bump the package version in DESCRIPTION.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!