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.

R/tf_article.R

@@ -10,21 +10,21 @@
 #' * <https://www.tandf.co.uk/journals/authors/InteractTFSLaTeX.zip>
 #'
 #' @inheritParams rmarkdown::pdf_document
-#' @param biblio_style should be set according to the specific Taylor & Francis
+#' @param reference_style should be set according to the specific Taylor & Francis
 #'   journal. Possibles values: "APA" (American Psychological Association
 #'   reference style), "CAD" (Chicago Author-Date reference style), "NLM"
 #'   (National Library of Medicine reference style), "TFP" (Reference
 #'   Style-P), "TFQ" (Reference Style-Q), and "TFS" (Reference Style-S).
 #' @param ... Additional arguments to [rmarkdown::pdf_document()]
 #'
 #' @examples \dontrun{
-#' rmarkdown::draft("MyArticle.Rmd", template = "tf", package = "rticles", biblio_style = "APA")
+#' rmarkdown::draft("MyArticle.Rmd", template = "tf", package = "rticles", reference_style = "APA")
 #' rmarkdown::render("MyArticle.Rmd")
 #' }
 #' @importFrom rmarkdown pandoc_variable_arg
 #' @export
 tf_article <- function(..., keep_tex = TRUE, citation_package = "natbib",
-                       biblio_style = c("CAD", "APA", "NLM", "TFP", "TFQ", "TFS"),
+                       reference_style = c("CAD", "APA", "NLM", "TFP", "TFQ", "TFS"),
                        pandoc_args = NULL) {
   styles <- list(
     APA = list(
@@ -80,29 +80,41 @@ tf_article <- function(..., keep_tex = TRUE, citation_package = "natbib",
       )
     )
   )
-  biblio_style <- match.arg(biblio_style)
-  if (! biblio_style %in% names(styles))
+  reference_style <- match.arg(reference_style)
+  if (! reference_style %in% names(styles))
     stop(
       paste(
-        "Invalid biblio_style in Taylor and Francis article. Allowed values are:",
+        "Invalid reference_style in Taylor and Francis article. Allowed values are:",
         paste(names(styles), collapse = ", ")
       )
     )
-  sty <- styles[[biblio_style]]
+  sty <- styles[[reference_style]]
   pandoc_args <- c(
     pandoc_args,
-    rmarkdown::pandoc_variable_arg("bst-name", sty$bst),
+    rmarkdown::pandoc_variable_arg("biblio-style", sty$bst),
     rmarkdown::pandoc_variable_arg(
       "biblio-commands",
       paste(sty$cmd, collapse = "\n")
     )
   )
-  pdf_document_format(
+
+  base <- pdf_document_format(
     "tf",
     keep_tex = keep_tex,
     citation_package = citation_package,
     pandoc_args = pandoc_args,
     ...
   )
-}
+  pre_knit <- base$pre_knit
 
+  # Alert the user about deprecation of the biblio_style field in the YAML header
+  base$pre_knit <- function(input, metadata, ...) {
+    if (is.function(pre_knit)) pre_knit(input, metadata, ...)
+    if (!is.null(metadata$biblio_style))
+      warning("`tf_article()` now ignores the 'biblio_style' field in YAML header. ",
+              " Use the 'reference_style' option of 'output:tf_article', instead.",
+              call. = FALSE)
+  }
+
+  base
+}

inst/rmarkdown/templates/tf/resources/template.tex

@@ -197,7 +197,7 @@
 $body$
 
 $if(bibliography)$
-\bibliographystyle{$bst-name$}
+\bibliographystyle{$biblio-style$}
 \bibliography{$bibliography$}
 $endif$
 

inst/rmarkdown/templates/tf/skeleton/skeleton.Rmd

@@ -44,7 +44,7 @@ header-includes: |
   \def\tightlist{}
 output:
   rticles::tf_article:
-    biblio_style: CAD
+    reference_style: CAD
 ---
 
 # Introduction
@@ -398,12 +398,12 @@ Authors must specify the required reference style in the YAML header of this fil
 ```
 output:
   rticles::tf_article:
-    biblio_style: CAD
+    reference_style: CAD
 ```
 
 ## References cited in the text
 
-[CAVEAT: The only subsection below that will be correctly typeset is the one corresponding to the  value specified in the `biblio_style` field of the YAML header.]
+[CAVEAT: The only subsection below that will be correctly typeset is the one corresponding to the value specified in the `reference_style` field of the YAML header.]
 
 ### American Psychological Association reference style (APA)