Modify rjournal_article template to allow more than one affiliation per author

[RLumSK]

Motivation

I realized that the rjournal_article template does not support multiple affiliations per author, which are, however, sometimes needed (and requested by the affiliations you are attached to).
On top of it, I realized that the fields url and orcid were not yet supported.
My contribution enables multi-affiliation support for this template and addresses #287 so that the
the output will be more consistent with the RJournal author's instructions (I am sorry, it accidentally ended up in the same pull request).

The commit includes the following modifications:

Changes

• resources/template.tex now knows how to handle multiple affiliations, while the default behavior of the template did not change. In other words, if the author has only one affiliation and enters the information as before, the PDF output renders as before.
• I added fields for url an orcid
• I updated the skeleton.Rmd to have an example for multiple affiliations
• I updated the DESCRIPTION and added me as a contributor (more is not justified given the minor nature of my contribution)
• I added a line to NEWS.md
• I address issue Differences from rjournal_article() to R Journal Instructions.  #287

Forms

• 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.

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

Not applicable.

• Add the Pandoc LaTeX template inst/rmarkdown/templates/journalname_article/resources/template.tex.

Not applicable, but the original template was updated.

• Add a skeleton article inst/rmarkdown/templates/journalname_article/skeleton/skeleton.Rmd.

Not applicable, but the original skeleton was updated.

• Add a description of the template inst/rmarkdown/templates/journalname_article/template.yaml.

Not applicable.

• Please include the document class file (*.cls) if needed, but please do not include standard LaTeX packages (*.sty) that can be downloaded from CTAN. Please keep the number of new files absolutely minimal, 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 one hundred items in it without using all of them).

Not applicable.

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

Not applicable.

• Update NEWS.

Not applicable.

• Update README with a link to the newly supported journal.

Not applicable.

• Add a test to tests/testit/test-formats.R.

Not applicable, the tests do not change, but I ran all tests to make sure that I did not break something.

• Add your name to the list of authors Authors@R in DESCRIPTION. You don't need to bump the package version in DESCRIPTION.

[cderv]

@RLumSK I have left some comments. Please tell me if it is clear enough. I can take the lead to modify and finish the PR based on your work. You tell me if you have time or not.

[cderv]

I now have revised the implemention to fix a few issues and refactor some code. Here, we only rename R file and tex file and we only document and warn for bibliography naming. Documentation of the format has also been improved. Figures are now kept in the *_files that rmarkdown creates as any other format and I believe pdf file can be generated from tex file.

I like the md documenting for roxygen so I kept that for this one even if it is the first function to be documented this way currently. Thanks for suggesting that !

@yihui You can now have a look at it and I think we have now a new good base to rethink this bib renaming thing.

Let's note that currently (as in master branch) the rticles::rjournal_article() format do not support setting output_dir in rmarkdown::render. I did not correct that yet in this PR.

[RLumSK]

@cderv Very nice work, indeed. Interesting to see how you solved the issues differently. I also played with the post_knit but it did not work out (of course this was because I did this file copying into a separate folder and when the function runs not all files are available).

The only thing we may want to keep in mind: I am not sure (nothing is written in the author's guidelines) whether they allow subfolders for the submission or prefer a flat-file structure (i.e. no subfolder like, e.g., Elsevier usually requests).

[cderv]

The only thing we may want to keep in mind: I am not sure (nothing is written in the author's guidelines) whether they allow subfolders for the submission or prefer a flat-file structure (i.e. no subfolder like, e.g., Elsevier usually requests).

You are talking about the figures ? I asked myself the same question and found nothing in the author's guidelines either.

[cderv]

Another question I had: can the \author{} in Tex file be on several line or not ?
If so, the post processing of authors should be modified accordingly. Currently it handles only if on one line in the tex file.

[RLumSK]

The only thing we may want to keep in mind: I am not sure (nothing is written in the author's guidelines) whether they allow subfolders for the submission or prefer a flat-file structure (i.e. no subfolder like, e.g., Elsevier usually requests).

You are talking about the figures ? I asked myself the same question and found nothing in the author's guidelines either.

Yes, I meant the figures. I suggest to leave it as it is for the moment. If no one raises that issue again, it was ok.

[RLumSK]

Another question I had: can the \author{} in Tex file be on several line or not ?
If so, the post processing of authors should be modified accordingly. Currently it handles only if on one line in the tex file.

I was inclined to write no because the template uses

\author{by $for(author)$$author.name$$sep$, $endfor$}

However, I just tried to create a document with six authors and "voilà", there was a linebreak and the replacement did not work anymore the way it should. Means, you are right, we have to consider a linebreak.

Update

@cderv I suggest modifying your helper function post_process_authors() in utils.R as follows (new code):

post_process_authors <- function(text) {
  # correct authors field to have pattern Author 1, Author 2 and Author 3
  ## (1) function to identify author lines
  authors_line <- function(text, 
      range = rep(grep(pattern = "\\author{", x = text, fixed = TRUE),2)) { 
      if(any(is.na(range)) || length(grep(pattern = "}", x = text[range[2]], fixed = TRUE)))
        return(range)
    
       authors_line(text, c(range[1], range[2] + 1))
  }
  
  ## (2) rewrite lines
  if (!any(is.na(line_range <- authors_line(text)))) {
    new_authors <- knitr::combine_words(
      unlist(strsplit(text[seq(line_range[1],line_range[2])], split = ","))
    )
    
    ##write new authors line
    text[line_range[1]] <- new_authors
    
    ##remove no-needed lines
    if(line_range[2] > line_range[1])
      text <- text[-c(seq(line_range[1] + 1, line_range[2]))]    
      
  }
  
  text
}

I have tested this little piece of refactored code using various examples:

• No author tag
• One author (one line)
• Many authors (one line)
• Many authors (many lines)

However, I did not add it as a commit tough. However, if you are happy with it, I could make a commit of it.

[RLumSK]

@cderv One last comment for today. Now where the warning is shown for the bibliography, there is one problem, at least when I use RStudio: If the markdown process does not show an error the panel window (in RStudio) switches immediately back from the R Markdown Panel to the Console. This happens all so fast that it is impossible to notice a warning message. If I back and check, of course, the warning is there. But imagine the user never does something really wrong, never causes an error message, there would be no reason to look into the r markdown terminal feedback. So maybe the warning should become a stop() instead?

[cderv]

@RLumSK Thank you for your input code. I prefered to handled it differently while testing more edge cases. Hope you don't mind!

About the warning, it appears in the R Markdown pane indeed as any other warnings for the R code. So if there is a warning in the R code, and it is not captured in the Rmd output, it will also be printed inside this Rmarkdown pane.
The user has already a comment in the skeleton to remind to change the name

rticles/inst/rmarkdown/templates/rjournal_article/skeleton/skeleton.Rmd

Lines 36 to 38 in 51d27bf

	# 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

This and the warning in addition should be enough - I think adding a stop() is too much.

If we wan't to improve that, we still have the solution of (copying+) renaming the bib file and modifying the file accordingly. As @yihui said, he will look into this and maybe reconsider the current choices.

[RLumSK]

@RLumSK Thank you for your input code. I prefered to handled it differently while testing more edge cases. Hope you don't mind!

Sure, no problem, it was just a suggestion. Looks nice the way you did it.

[yihui]

Looks good overall! I only have one question in the comment.

For the filename of bibliography, I also feel stop() is a little too aggressive.

Thank you!

[cderv]

Thanks a lot @RLumSK for this PR ! Great work and discussions !

[RLumSK]

@cderv Likewise! I also carefully locked into your changes and I hope next time I can meet your expectations from the start. Anyway, it was nice and sincerely exciting work.