Add support to all bibliography styles required by Taylor & Francis journals

[rlaboiss]

• R/article.R: Check whether the biblio-style field in the YAML header contains one of the allowed values
• inst/rmarkdown/templates/tf/skeleton/interact.cls: Update to version v1.05
• inst/rmarkdown/templates/tf/resources/template.tex: Choose the bibliography-related code according to biblio-style
• inst/rmarkdown/templates/tf/skeleton/tf{nlm,p,q,s}.bst: Add lacking bibliography style files from T&F
• man/article.Rd: Document the changes

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_article below 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). Unless you have done it in any other RStudio / Posit projects before, sign the individual or corporate contributor agreement as appropriate. You can send the signed copy to [email protected].

• Add the journalname_article() function to R/article.R if the output format is simple enough, otherwise create a separate R/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 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).

• 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.R by adding a line test_format("journalname"). We try to keep them in alphabetical order.

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

All committers have signed the CLA.

[cderv]

Thanks a lot for this PR. Really good to see how the template can be improved.

For the biblio-style logic, you could have also be processing depending on the value of the biblio-style

Let's take this example

output: tf_article
biblio_style: tfcad.bst

This following usual syntax.

As a pre_processor in the format, you could check for biblio-style value, and check that xfun::sans_ext(metadata$biblio-style) a known value. If not you would error, if this is you would then define the appropriate pandoc_variable_arg("biblio-commands") associated with this style.

This is an idea to keep the same YAML metadata as other format, while adding a specific processing to it.

I am using pre_processor here, because this function returns new args to be used with Pandoc.

guess that, in case my PR get merged, my name will appear in the DESCRIPTION file. Please, tell me which role should I indicated for myself.

Please add yourself in DESCRIPTION as other contributor.

Should I add my name and affiliation in the YAML header of inst/rmarkdown/templates/tf/skeleton/skeleton.Rmd?

The skeleton is an example so no need to add you to it, unless you want to be the example.

There is only an annoying point: all tf*.bst are installed by

I don't think that is a big issue. A user will have to remove the undesired one. Otherwise, we need to think about this dynamically and only copy at render time the right file from resources if not already there. It could be tricky but this is the only way without modifying general draft logic.

Otherwise maybe I need to do a rticles::create_article() that would wrap the default draft, but do some postprocessing too depending on some specific rules 🤷

I also triggered the test and they are failing. This is because documentation needs to be updated in Roxygen command. By creating a new file for this function it will solve it I thhink.

Thanks again.

[rlaboiss]

For the biblio-style logic, you could have also be processing depending on the value of the biblio-style

Let's take this example

output: tf_article
biblio_style: tfcad.bst

This following usual syntax.

As a pre_processor in the format, you could check for biblio-style value, and check that xfun::sans_ext(metadata$biblio-style) a known value. If not you would error, if this is you would then define the appropriate pandoc_variable_arg("biblio-commands") associated with this style.

This is an idea to keep the same YAML metadata as other format, while adding a specific processing to it.

I am using pre_processor here, because this function returns new args to be used with Pandoc.

I need a clarification here. Are you proposing that we should only have the biblio_style metadata variable (containing the name of the .bst file), like this:

output: rticles::tf_article
biblio_style: tfcad.bst

instead of the scheme that I implemented, like this:

output:
  rticles::tf_article:
    biblio_style: CAD

or are you proposing to keep both possibilities?

[cderv]

Are you proposing that we should only have the biblio_style metadata variable (containing the name of the .bst file)

Yes I am suggesting we could use the existing biblio-style metadata. it is usually how biblio style is set for articles with Pandoc and R markdwn.

It could be biblio_style: tfcad.bst or biblio_style: tfcad

Do you think this is not great user experience ?

[rlaboiss]

Are you proposing that we should only have the biblio_style metadata variable (containing the name of the .bst file)

Yes I am suggesting we could use the existing biblio-style metadata. it is usually how biblio style is set for articles with Pandoc and R markdwn.

It could be biblio_style: tfcad.bst or biblio_style: tfcad

Do you think this is not great user experience ?

Oh, this would change completely my design!

The existing biblio_style metadata is currently used for specifying the .bst file that is set as argument of the\bibliography{} command in the template.tex file.

The bilbio_style argument of my new tf_article() function, which can have values "APA", "CAD", "NLM", "TFP", "TFQ", and "TFS", serves another purpose. It is used for determining both the name of the .bst file and the necessary LaTeX commands, which will substitute the Pandoc construct $biblio-commands$.

I did this on purpose, such that the user does not need to know which specific .bst file they are required to use, according to the journal they are submitting to.

BTW, this is the reason why I used $bst-name$ in the template, instead of the usual $biblio-style$.

Now, if I follow your suggestion, I would have to set $biblio-commands$ inside tf_article() according to the value of the biblio_style in the metadata. Is that possible to do? If yes, I can change the code, even though I really prefer my design, which seems cleaner and less error-prone, in my humble opinion.

If you accept that my design is maintained, I could add a note in the documentation of tf_article() telling the user that the use of the biblio_style metadata is deprecated.

We might also change the name of the argument from biblio_style to reference_style, in order to avoid confusion (BTW, “Reference style” is the terminology used by Taylor & Francis). In this case, the user would use, in the YAML header, something like this:

output:
  rticles::tf_article:
    reference_style: APA

What do you think?

[rlaboiss]

We might also change the name of the argument from biblio_style to reference_style, in order to avoid confusion (BTW, “Reference style” is the terminology used by Taylor & Francis). In this case, the user would use, in the YAML header, something like this:

output:
  rticles::tf_article:
    reference_style: APA

In order to make things more concrete, I went ahead and pushed commit bbf9123 containing changes along the lines above. Here is the commit's log message:

Deprecate the biblio_style option and rename the reference_style option

This commit is intended to eliminate an ambiguity linked to the use of biblio_style as the name of the tf_article function option. In fact, biblio_style is traditionally used in the rticles package to indicate the name of the .bst file that will be used as an argument to the \bibliographystyle command in the LaTeX template.

The new version of tf_article accepts an option that determines the Taylor & Francis reference style to be used. Until now, the name biblio_style was used as the name of this option. In this commit, this name is changed to reference_style. This not only aligns with the terminology used by Francis & Taylor (“Reference Style”), but also avoids any confusion on the part of the user.

The tf_article function has also been modified to include a pre_knit function, in which the presence of the biblio_style in the YAML header is checked. If present, a warning message is issued concerning the depreciation of the biblio_style field.

[cderv]

Now, if I follow your suggestion, I would have to set $biblio-commands$ inside tf_article() according to the value of the biblio_style in the metadata. Is that possible to do? If yes, I can change the code, even though I really prefer my design, which seems cleaner and less error-prone, in my humble opinion.

Yes this is possible. In post processor, you check the metadata$biblio-style name, and you act accordingly if a known one to add the associated biblio command.

This is quite similar to your current design except:

• the name of the bst file needs indeed to be known instead of just reference style name. If you say the reference style name are more known by the authors, then that is good to have it like that even if it add a processing layer.
• the bibliocommand insertion is done in post processor instead of the function.

The only drawback I see for your current design is that no custom biblio-style can now be used with tf_article(). So no custom tweak for a possibly unsupported journal and someone needing to make adjustment.

I don't think that is common, but hiding behind reference_style will lead to that. I am ok with your last change though so we'll see if there are feedback on this.

[rlaboiss]

The only drawback I see for your current design is that no custom biblio-style can now be used with tf_article(). So no custom tweak for a possibly unsupported journal and someone needing to make adjustment.

I don't think that is common, but hiding behind reference_style will lead to that. I am ok with your last change though so we'll see if there are feedback on this.

Yes, I think that this situation (need to use another .bst file) will not arise in the normal case when submiting a manuscript to a T&F journal. Besides that, I really prefer the biblo_style deprecation instead of having to cope with conflicting cases, like this:

biblio_style: tfcad
output:
  rticles::tf_article:
    reference_style: NLM

Such a setup is almost guaranteed to produce broken results.

At any rate, I think that the PR is now ready for merging. I did extensive tests and the skeleton.Rmd file seems to produce correct PDF files for all the six reference styles.

[cderv]

Besides that, I really prefer the biblo_style deprecation instead of having to cope with conflicting cases, like this:

To be clear on my thinking, this would not happen as you wouldn't need reference_style

It is either

biblio_style: tfcad
output: rticles::tf_article

and this would trigger CAD style command addition. No reference_style needed

Or

output:
  rticles::tf_article:
    reference_style: CAD

without needing biblio_style

This

biblio_style: tfcad
output:
  rticles::tf_article:
    reference_style: NLM

would be handled by biblio_style being ignored with reference_style taking precedence.

At any rate, I think that the PR is now ready for merging. I did extensive tests and the skeleton.Rmd file seems to produce correct PDF files for all the six reference styles.

This is awesome ! Thanks a lot for the work on this - greatly appreciated!