Updates AMS to V6.1 (#444)

* Cherry-pick @eliocamp

* Uses xelatex in the AMS skeleton

* Update for v6.1

* Default to twocol=FALSE

* check for old argument unsupported and warn

* Set pandoc requirement and add warning about new tempalte

* Check various metadata

* rewrite the new for loop for author

* rewrite affiliation as YAML

* Move article function to its own file and document

* set bibliography in the right place

* Add missing part in template for Pandoc

* Use markdown in the template for most part

* Update bibliography file

* Add a lua filter to help write expected AMS syntax

* fix affiliation

* Adapt test and fix citation package to natbib

* Trigger warning immediately

* Bump version

---------

Co-authored-by: Elio Campitelli <[email protected]>
Co-authored-by: Christophe Dervieux <[email protected]>

.gitignore

@@ -6,3 +6,5 @@
 reference
 inst/doc
 .vscode
+
+/.luarc.json

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: rticles
 Title: Article Formats for R Markdown
-Version: 0.27.6
+Version: 0.27.7
 Authors@R: c(
     person("JJ", "Allaire", , "[email protected]", role = "aut"),
     person("Yihui", "Xie", , "[email protected]", role = "aut",

NEWS.md

@@ -8,6 +8,15 @@
 
 - Update `mdpi_article()` to latest version of September 2024 (thanks, @nielsbock, #573, #580).
 
+- Update `ams_article()` to latest version 6.1 with some breaking changes:
+  - Pandoc v2.10 is required with the template now
+  - Removed metadata no more used : 
+    - `journal`, `layout`, `exauthors`, `author1`, `author2`, `currentaddress`, `affiliation`)
+  - Authors related variable are now `authors` and `affiliations` fields which accept multi authors. See the new skeleton by creating new template with `rmarkdown::draft("Untiltle.Rmd", "ams", "rticles")`.
+  - Only `natbib` is supported now in `citation_package`
+  - Some knitr options are made default in the format: `fig.path = ""`, `out.extra = ""`, `echo = FALSE`. They can be overriden in the document. 
+  - Specific markdown syntax are available in template for `acknowledgments`, `datastatement`, `appendix`. See the new skeleton by creating new template with `rmarkdown::draft("Untiltle.Rmd", "ams", "rticles")`.
+
 # rticles 0.27
 
 - `joss_article()` now correctly works as `base_format` for `bookdown::pdf_book()` (thanks, @mlysy, #564).

R/ams_article.R

@@ -0,0 +1,61 @@
+#' American Meteorological Society journals format.
+#'
+#' Format for creating submissions to American Meteorological Society journals.
+#'
+#' @inheritParams rmarkdown::pdf_document
+#' @param citation_package only natbib is supported with this template.
+#' @param ... Additional arguments to [rmarkdown::pdf_document()]. **Note**: `extra_dependencies` are not
+#' allowed as Copernicus does not support additional packages included via \code{\\usepackage{}}.
+#'
+#' @return An R Markdown output format.
+#' @details This was adapted from
+#' <https://www.ametsoc.org/index.cfm/ams/publications/author-information/latex-author-info/>.
+#'
+#' The template require some default knitr option to be change:
+#'
+#' * `echo = FALSE` as no R code should be shown
+#' * `fig.path = ""` as all directory paths need to be removed from figure names
+#' * `out.extra = ""` to force figure labels with knitr
+#'
+#' @examples
+#' \dontrun{
+#' library("rmarkdown")
+#' draft("MyArticle.Rmd", template = "ams", package = "rticles")
+#' render("MyArticle/MyArticle.Rmd")
+#' }
+#' @export
+ams_article <- function(..., keep_tex = TRUE, citation_package = "natbib", md_extensions = c("-autolink_bare_uris", "-auto_identifiers"), pandoc_args = NULL) {
+
+  rmarkdown::pandoc_available('2.10', TRUE)
+
+  if (citation_package != "natbib") {
+    stop("AMS template supports only `natbib` for citation processing.")
+  }
+
+  pandoc_args <- c(
+    pandoc_args,
+    "--lua-filter", find_resource("ams", "ams.lua")
+  )
+
+  base <- pdf_document_format(
+    "ams", keep_tex = keep_tex, md_extensions = md_extensions, citation_package = 'natbib',
+    pandoc_args = pandoc_args, ...
+  )
+  pre_knit <- base$pre_knit
+  base$pre_knit <- function(input, metadata, ...) {
+    if (is.function(pre_knit)) pre_knit(input, metadata, ...)
+    old_meta <- c("journal", "layout", "exauthors", "author1", "author2", "currentaddress", "affiliation")
+    # check old arg
+    metadata_used <- old_meta %in% names(metadata)
+    if (any(metadata_used)) {
+      warning("You are probably using an old version of the template - please update to new skeleton or keep using rticles 0.27.", immediate. = TRUE, call. = FALSE)
+      warning("Some metadata are no more used in new AMS template: ", knitr::combine_words(old_meta[metadata_used]), ". They will be ignored.", immediate. = TRUE, call. = FALSE)
+    }
+  }
+  base$knitr$opts_chunk <- merge_list(base$knitr$opts_chunk, list(
+    fig.path = "",     # AMS required
+    out.extra = "",    # To force figure labels
+    echo = FALSE       # Don't show R code
+  ))
+  return(base)
+}

R/article.R

@@ -86,19 +86,6 @@ amq_article <- function(..., latex_engine = "xelatex", keep_tex = TRUE,
   )
 }
 
-#' @section `ams_article`: Format for creating an American Meteorological
-#'   Society (AMS) Journal articles. Adapted from
-#'   <https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/author-resources/latex-author-info/>.
-#' @export
-#' @rdname article
-ams_article <- function(..., keep_tex = TRUE,
-                        md_extensions = c("-autolink_bare_uris")) {
-  pdf_document_format(
-    "ams",
-    keep_tex = keep_tex, md_extensions = md_extensions, ...
-  )
-}
-
 #' @section `asa_article`: This format was adapted from The American
 #'   Statistician (TAS) format, but it should be fairly consistent across
 #'   American Statistical Association (ASA) journals.

inst/rmarkdown/templates/ams/resources/ams.lua

@@ -0,0 +1,70 @@
+local function getLetter(counter)
+    if counter < 1 or counter > 26 then
+        return nil  -- Return nil for invalid input
+    end
+    local letter = string.char(counter + 64)  -- 64 is used because ASCII value of 'A' is 65
+    return letter
+end
+
+local function process_div(div)
+  if div.classes:includes("acknowledgments") then
+    if #div.content and #div.content[1].content then
+      div.content[1].content:insert(1, pandoc.RawInline("latex", "\\acknowledgments\n"))
+    elseif #div.content then
+      div.content:insert(1, pandoc.RawInline("latex", "\\acknowledgments\n"))
+    end
+    return div.content
+  end
+  if div.classes:includes("datastatement") then
+    if #div.content and #div.content[1].content then
+      div.content[1].content:insert(1, pandoc.RawInline("latex", "\\datastatement\n"))
+    elseif #div.content then
+      div.content:insert(1, pandoc.RawInline("latex", "\\datastatement\n"))
+    end
+    return div.content
+  end
+  if div.classes:includes("appendix") then
+    nb_appendix = 0
+    div.content:walk({
+      Header = function(h)
+        if h.level == 1 then
+          nb_appendix = nb_appendix + 1
+        end
+      end
+    })
+    if nb_appendix > 0 then
+      local counter = 0
+      return div.content:walk({
+        traverse = 'topdown',
+        Header = function(h)
+          if h.level == 1 then
+            counter = counter + 1
+            local appendix
+            if nb_appendix == 1 then
+              appendix = pandoc.RawInline("latex", "\\appendix\n")
+            else
+              appendix = pandoc.RawInline("latex", string.format("\\appendix[%s]\n", getLetter(counter)))
+            end
+            h.content:insert(1, pandoc.RawInline("latex", "\\appendixtitle{"))
+            h.content:insert(pandoc.RawInline("latex", "}"))
+            h.content:insert(1, appendix)
+            return { h.content }
+          elseif h.level == 2 then
+            local star = ""
+            if h.classes:includes("unnumbered") then
+              star = "*"
+            end
+            h.content:insert(1, pandoc.RawInline("latex", string.format("\\subsection%s{", star)))
+            h.content:insert(pandoc.RawInline("latex", "}"))
+            return { h.content}
+          end
+        end
+      })
+    end
+  end
+  return div.content
+end
+
+return {
+  Div = process_div,
+}