Update to oup_article for new CTAN template

[dmkaplan2000]

I have updated the OUP format to use the latest template available on CTAN. I do, however, have a number of comments regarding the update:

1) I didn't include the .csl file as they are on CTAN. However, as what is on CTAN doesn't include a .sty file, I am not 100% sure that the style is easily installable with tlmgr. I don't use tinytex, so it is hard for me to check if that is the case or not. 2) This new template is largely backward compatible with the old template, but there was no simple way to maintain full backward compatibility. In particular, multi-paragraph abstracts in the old format won't work in the new. 3) I discovered that not all OUP Journals currently accept this new format. In particular, one that I submit to, ICES Journal of Marine Science, does not use this format. As such, I will submit a separate pull request creating a format for this specific journal that is still based on the old OUP style.

---

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):

• [X ] 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 jj@rstudio.com.

• [X ] Add the journalname_article() function to R/article.R if the output format is simple enough, otherwise create a separate R/journalname_article.R.

• [ X] Add the Pandoc LaTeX template inst/rmarkdown/templates/journalname/resources/template.tex.

• [X ] Add a skeleton article inst/rmarkdown/templates/journalname/skeleton/skeleton.Rmd.

• [X ] Add a description of the template inst/rmarkdown/templates/journalname/template.yaml.

• [ X] 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 via tinytex::parse_packages(files = "FILENAME"") (e.g., when FILENAME is plain.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 .bib example, 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).

• [ X] Update Rd and namespace (could be done by devtools::document()).

• [ X] Update NEWS.

• [ X] 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).

• [ X] Add a test to tests/testit/test-formats.R by adding a line test_format("journalname"). We try to keep them in alphabetical order.

• [X ] Add your name to the list of authors Authors@R in 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!

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

:white_check_mark: yihui
:x: David M. Kaplan

---

David M. Kaplan seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[dmkaplan2000]

x David M. Kaplan

David M. Kaplan" is from some old commits I did predating this branch where I used my name as the git commit email address. All commits since branching that are relevant to this pull request have been done with my github email address, for which the CLA has been signed. I haven't found a convenient way to fix the commit address on the old commits predating this branch.

[dmkaplan2000]

I looked into the R-CMD-check errors and they appear to be due to older versions of pandoc not understanding certain elements of my template.tex (specifically, pandoc 2.7.3 does not understand $elseif()$ and pandoc 2.9.2.1 does not seem to know about the pipe "first"). The development version of pandoc also produces an error, but that is not related to the OUP template. The strange thing is that on my system running Ubuntu 20.04 with pandoc 2.5, everything works fine.

In any case, should I be trying to fix these issues? $elseif$ could be fixed if need be (it would be messy, but presumably it could be done), but replacing the pipe first would be a bit more complicated I think.

[cderv]

I looked into the R-CMD-check errors and they appear to be due to older versions of pandoc not understanding certain elements of my template.tex (specifically, pandoc 2.7.3 does not understand $elseif()$ and pandoc 2.9.2.1 does not seem to know about the pipe "first"). The development version of pandoc also produces an error, but that is not related to the OUP template. The strange thing is that on my system running Ubuntu 20.04 with pandoc 2.5, everything works fine.

For the CI error, it would require that master should be merged. There are some fixes already for some error in other template. As of now, all templates are tested in a PR and not just the one you change.

About the pandoc requirement, yes template syntax is dependant of Pandoc version.

• Pipes where introduces in Pandoc 2.10 https://pandoc.org/releases.html#pandoc-2.10-2020-06-29
• elseif in Pandoc 2.8: https://pandoc.org/releases.html#pandoc-2.8-2019-11-22

It should not work in Pandoc 2.5 for you.

We could make a minimal requirement on Pandoc for a format. I am open to that. However, it would justify a new format or an opt-in way to not impact user of current oup_article

[dmkaplan2000]

Thanks for this important update.

My main concerns is with breaking change.

The update seems important and maybe this could cause issue to user still using the old cls file. All the more if some journal does not accept yet the new style.

Yes, I agree with this, but haven't figured out the best solution. I talk about some of the issues involved in this here, but I am open to other suggestions.

So I am hesitant on what to do exactly:

* Create a new function

* Have a switch is this function to use the old or new template ? We would have both and copy / use the correct one depending on what is asked. We could still have the old as default maybe but this could allow us to deprecate the function and inform of changes before changing the default.

I think creating a new function (e.g., oup_new_format_article) until such time as almost all OUP journals use the new format is probably the best option. For reasons I explain here, a switch seems hard to me. A new function would preserve backward compatibility and make it clearer what the options are.

I am not quite sure of the difference however and it seems this could be minimum.

I didn't include the .csl file as they are on CTAN. However, as what is on CTAN doesn't include a .sty file, I am not 100% sure that the style is easily installable with tlmgr. I don't use tinytex, so it is hard for me to check if that is the case or not.

Do you mean cls file ? The new file will be found so we are ok

> tinytex::parse_packages(files = "oup-authoring-template.cls")
tlmgr search --file --global "/oup-authoring-template.cls"
[1] "oup-authoring-template"

Yes, I meant CLS (I always mix up those two). I tried what you did a couple of weeks ago and it didn't work, but I most likely used .csl instead of .cls...

If you meant CSL, where is it available ,

This new template is largely backward compatible with the old template, but there was no simple way to maintain full backward compatibility. In particular, multi-paragraph abstracts in the old format won't work in the new.

I understand that my concerns are to be minimized because you are saying this is backward compatible, is that right ? Do you know the list of changes that we could document / inform ?

The new template is "largely" backward compatible. The main breaking issue I see is multi-paragraph abstracts. The old format used \begin{abstract}...\end{abstract}, so multi-paragraph abstracts was easy, whereas the new format used a command \abstract{paragraph 1\\paragraph 2}, so the only solution was to make the abstract element of the YAML header a list/vector, each element of which is treated as a paragraph.

The other major change is that now citation_package is by default "natbib", whereas before it was "default".

I discovered that not all OUP Journals currently accept this new format. In particular, one that I submit to, ICES Journal of Marine Science, does not use this format. As such, I will submit a separate pull request creating a format for this specific journal that is still based on the old OUP style.

This could mean also that ICES JMS may not be the only one. is icesjms_article required if you were able to still use somehow the current oup_rticles() function ?

Yes, there are undoubtedly other journals that still use the old format, but I do not have an exhaustive list. If we want to keep backward compatibility, I think that the easiest solution is to keep the old oup_article format as is and create a new function for this new format.

Thanks again for you valuable contribution !

[dmkaplan2000]

I looked into the R-CMD-check errors and they appear to be due to older versions of pandoc not understanding certain elements of my template.tex (specifically, pandoc 2.7.3 does not understand $elseif()$ and pandoc 2.9.2.1 does not seem to know about the pipe "first"). The development version of pandoc also produces an error, but that is not related to the OUP template. The strange thing is that on my system running Ubuntu 20.04 with pandoc 2.5, everything works fine.

For the CI error, it would require that master should be merged. There are some fixes already for some error in other template. As of now, all templates are tested in a PR and not just the one you change.

About the pandoc requirement, yes template syntax is dependant of Pandoc version.

* Pipes where introduces in Pandoc 2.10 https://pandoc.org/releases.html#pandoc-2.10-2020-06-29

* `elseif` in Pandoc 2.8: https://pandoc.org/releases.html#pandoc-2.8-2019-11-22

It should not work in Pandoc 2.5 for you.

And yet it does...

> system("pandoc -v")
pandoc 2.5
Compiled with pandoc-types 1.17.5.4, texmath 0.11.2.2, skylighting 0.7.7
Default user data directory: /home/dmk/.pandoc
Copyright (C) 2006-2018 John MacFarlane
Web:  http://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.

But I just noticed that RStudio isn't running the default pandoc version, but rather a custom installation that is newer:

> system("/usr/lib/rstudio/bin/pandoc/pandoc -v")
pandoc 2.11.4
Compiled with pandoc-types 1.22, texmath 0.12.1, skylighting 0.10.2,
citeproc 0.3.0.5, ipynb 0.1.0.1
User data directory: /home/dmk/.local/share/pandoc or /home/dmk/.pandoc
Copyright (C) 2006-2021 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

We could make a minimal requirement on Pandoc for a format. I am open to that. However, it would justify a new format or an opt-in way to not impact user of current oup_article

Pipes and ifelse are really pretty useful. I would say that we make a new function with a minimum pandoc version (I am not sure technically how to impose this...).

[dmkaplan2000]

I have also imposed a minimum pandoc version for oup_version>0 in the branch associated with PR #431.

[cderv]

Should be superseded by #431 right ?

[dmkaplan2000]

Should be superseded by #431 right ?

I believe this is the case, but it has been a while since I thought about it.

[cderv]

From the content of the PR, the updated is now available in oup_article(oup_version = 1). So I believe this should cover what this issue was about.

I'll close this, and if some newer update are needed, we'll do it in the new version. Thanks!

[dmkaplan2000]

No problem, thanks...