Add template for ICES JMS

dmkaplan2000 commented 3 years ago

This pull request creates a new format for the ICES Journal of Marine Science. This format is essentially the same as the OUP format currently in rstudio/rticles, but I have also created a pull request to update that format to the new OUP CTAN template that is currently not supported by ICES JMS. So that I (and others) can continue to submit to ICES JMS using rticles, I am creating a format specifically for that journal.

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 commented 3 years ago

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 commented 3 years ago

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.

cderv commented 3 years ago

And now looking at #418, I understand better

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.

Would it be better (as a user) to have a way to use old and new format from within oup_article(), with an argument ?

Having a new format function for a specific article also make sense, so it could stay that way and I understand the need of this PR then.

dmkaplan2000 commented 3 years ago

And now looking at #418, I understand better

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.

Would it be better (as a user) to have a way to use old and new format from within oup_article(), with an argument ?

Having a new format function for a specific article also make sense, so it could stay that way and I understand the need of this PR then.

These are all good questions. I thought initially about using an argument to switch between the two formats, but the problem is that the new format is sufficiently distinct in how it functions and the options it permits that it would be hard to create an understandable skeleton that was usable for both. It could probably be done, but it would be something of a mess of options and formats that are only usable if oup_version = "new" and others that are only usable if oup_version="old". I think the result would not be particularly satisfying and would be confusing for the user.

We would also probably need to have two different template.tex as merging the two would be an awful mess in my view - the underlying CLS files are completely different so the LaTeX templates are quite distinct. For maintenance, the old OUP template.tex is already something of a mess (because I initially made some less than ideal choices on how it works, but have tried to maintain backwards compatibility as I improved it), so I think a clean start with the new format is best. I imagine it is technically possible to have two different template.tex that are chosen via a parameter, but I would need some pointers from you on how to go about this.

In my opinion, the best solution would be to replace the current oup_article with oup_old_format_article and oup_new_format_article (or some other names that seem appropriate). This would make a clear distinction between the different options, both of which are currently in use (I have no idea if or when OUP will convert all journals over to the new format). I created a ICESJMS format for that specific journal because I personally need it and I saw one or two other OUP journals that have their own rticles format, but I think it is much better to include formats that adapt to multiple journals than single journal formats.

Cheers, David

cderv commented 3 years ago

I was thinking of two skeleton and two templates but only one function for the user instead of two. would it be too odd ? Like a version argument. We have that for Bootstrap in bslib package now where dependency is versionned, and this is leaking in other tools like pkgdown which will use different template depending on a version variables.

Aim is to avoid functions duplications which needs thinking of new names, when the only differences is major version update.

I guess something like this would work

oup_article <- function(
  ..., oup_version = "new", keep_tex = TRUE,
  md_extensions = c("-autolink_bare_uris")
) {
  if (oup_version == "new") {
    pdf_document_format(
      "oup",
      keep_tex = keep_tex, md_extensions = md_extensions, ...
    )
  else if (oup_version == "old") {
    pdf_document_format(
      "oup_old",
      keep_tex = keep_tex, md_extensions = md_extensions, ...
    )
  }
  }
}

but it would change the underlying way all of the folder structure is working and this may not be a good idea. It only helps to use the new name.

Maybe a new format is better, but a name would be needed. This is simpler for the codebase surely, but harder job to find good names. We should brainstorm.

oup2_article() ?
oup_new_article() ?

I need to think about it.

I saw one or two other OUP journals that have their own rticles format, but I think it is much better to include formats that adapt to multiple journals than single journal formats.

Maybe oup_article() was not a good idea in the first place and we should have one function per journal as it mainly the case for other function we have (I think) ? but it does feel right if you can use the same formats for multiple journals. 🤔 I need to think about this. thanks for bringing that up.

dmkaplan2000 commented 3 years ago

I now understand your suggestion better and agree that having two templates and skeletons with an argument in the function in the function is the best approach. The only thing I would do differently is to keep the current "oup" folder as is, but create a new "oup_new" folder for the new format. I would also make "old" the default oup_version for now. This will assure backward compatibility and avoid having to change directory structures.

dmkaplan2000 commented 3 years ago

Also, there are a number of generic formats, such as elsevier, frontiers, tf, springer, etc. I think this should be the preferred approach as maintaining formats for every journal under the sun just seems impossible, particularly as the number of journals has just exploded. OUP should be this way except that they have completely changed their format along the way without preparing all of their journals for the change. I presume in time they will centralize on the new format, but only they know for sure...

cderv commented 3 years ago

Let's try this way then.

We may need to adjust some other function in the package that could rely on having one folder = one function. I don't remember exactly but that is possible. I'll watch out for this.

We could also have one oup folder which would contain the two version in two separate folder. I think that would also work. This would have the benefit of keeping one folder = one function.

dmkaplan2000 commented 3 years ago

OK. I suppose that the best way to go about this is to create a new clean branch on my repository with the combination of the two formats as we have described and then create a new pull request?

I can try a single oup directory with two subdirectories, old and new, but I wonder if the two templates will be recognized in this case (e.g., available in RStudio). I also wonder how this will work with the test functions, but I suppose you can have two test lines for that.

cderv commented 3 years ago

but I wonder if the two templates will be recognized in this case (e.g., available in RStudio)

Good thinking ! That won't work indeed... https://rstudio.github.io/rstudio-extensions/rmarkdown_templates.html

rmarkdown::draft() does not support subdirectory out of the box. but using oup/new in template= argument would do the trick, but the IDE won't allow.

We would definitely need to have two folders so that we have two different templates on RStudio IDE side. We could have those two template use the same format function with different argument though. If we do that, we need to tweak a bit rticles internals that rely on 1 format function = 1 folder. We can see that when working on it, nothing

dmkaplan2000 commented 3 years ago

OK. Let me know what part of this you want me to tackle. I don't feel like messing with rticles internals, but creating the two folders and adjusting the format function seem to be within my scope of knowledge. I would probably create a completely new branch and pull request to...

I have also been thinking that oup_version="old" and "new" isn't the most forward thinking approach as I can imagine that there will some day be a new new version of the template. The old CLS file has no version number associated with it, but the new CLS file on CTAN has a version number 1.0. Perhaps "old" and "1.0" are better names (or "0" and "1" presuming "1.1" would be backward compatible with "1.0")?

cderv commented 3 years ago

OK. Let me know what part of this you want me to tackle. I don't feel like messing with rticles internals, but creating the two folders and adjusting the format function seem to be within my scope of knowledge. I would probably create a completely new branch and pull request to...

You can do what you are confortable with. I'll help with the rest. Let's hope that this idea will work ! I would have another PR indeed so that we can have both implementation in case we need to switch back.

I have also been thinking that oup_version="old" and "new" isn't the most forward thinking approach as I can imagine that there will some day be a new new version of the template. The old CLS file has no version number associated with it, but the new CLS file on CTAN has a version number 1.0. Perhaps "old" and "1.0" are better names (or "0" and "1" presuming "1.1" would be backward compatible with "1.0")?

Yes I agree. I like the simple version = 0 or version = 1. I think that makes it clear.

dmkaplan2000 commented 3 years ago

Ok. I will try to work that up quickly. I just noticed that the old ouparticle.cls file has the following line at the top:

\ProvidesClass{ouparticle}[2009/12/09 v1.0]

So it does have a version. But unfortunately, that version is identical to the version indicated in the current oup-authoring-template.cls file:

\newcommand\classname{oup-authoring-template}
\newcommand\lastmodifieddate{2020/02/18}
\newcommand\versionnumber{1.0}

\NeedsTeXFormat{LaTeX2e}[2001/06/01]
\ProvidesClass{\classname}[\lastmodifieddate\space\versionnumber]

I could use oup_version="2009" and "2020", but that still seems confusing and ad hoc. I think 0 and 1 remain the cleanest solution.

cderv commented 2 years ago

Should be superseded by #431 right ?

cderv commented 1 year ago

Should be superseded by https://github.com/rstudio/rticles/pull/431 right ?

@dmkaplan2000 can you confirm that our work on OUP to keep the old and new format working make this PR outdated ?

Thank you

dmkaplan2000 commented 1 year ago

I believe so, but I must admit that it has been long enough that I have forgotten the details.

cderv commented 1 year ago

Considering the description of this PR I think oup_article() with its version 1 can be used for ICES JMS submission.

I'll close this. Thanks again for the work on OUP

rstudio / rticles

Add template for ICES JMS #419