Copernicus template update - fixes syntax highlight problem (#391)

* Update template for follow guidelines from Copernicus: no additional packages can be used from those in the cls file. This requires to deactivate Pandoc highlighting for typesetting. algorithms packages can't be loaded in template too
* Adapt the skeleton and document all this. Add command to install packages in the skeleton.

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

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: rticles
 Type: Package
 Title: Article Formats for R Markdown
-Version: 0.19.2
+Version: 0.19.3
 Authors@R: c(
   person("JJ", "Allaire", role = "aut", email = "[email protected]"),
   person("Yihui", "Xie", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0003-0645-5666")),

NEWS.md

@@ -1,6 +1,10 @@
 rticles 0.20
 ---------------------------------------------------------------------
 
+- Update Copernicus Publications template to comply with editor's guidelines following a manuscript bounce back during the typesetting step. Copernicus does not allow to add any `\usepackage` command as they all are included in `copernicus.cls` for supported LaTeX packages. **This is leading to breaking changes with existing template - please follow the advice below**.
+  - `algorithms: true` cannot be used anymore and as no more effect. `\usepackage{algorithmic}` and `\usepackage{algorithm}` has been removed from the template as the command are already done in `copernicus.cls`. Please, make sure `algorithms` and `algorithmcx` are installed.  
+  - Additionally, the template gained support for the `highlight` parameter of `rmarkdown::pdf_document` to enable or disable syntax highlighting with Pandoc. To comply with the above guideline by Copernicus, it is disabled by default (`highlight: NULL`) to prevent Pandoc adding any more packages required for its highlighting. Syntax highlighting can be reactivating by using `highlight: "default"` in the YAML header as this can be desirable before submitting for typesetting. (thanks, @RLumSK, @nuest, #391).
+
 - Fix issue with Pandoc's citation processing by updating all templates with last relevant changes from Pandoc's default template (thanks, @BlackEdder, @dahrens, #390)
 
 - remove warning in `joss_article()` about `citation_package` (thanks, @llrs, #389).
@@ -9,6 +13,7 @@ rticles 0.20
 
 rticles 0.19
 ---------------------------------------------------------------------
+
 - Update Copernicus Publications template to version 6.2 from 2021-01-15 (thanks, @RLumSK, #366).
 
 - Add article template `pihph_article()` for the *Papers in Historical Phonology* (PiHPh) (thanks, @stefanocoretta, #362).

R/copernicus_article.R

@@ -3,7 +3,8 @@
 #' Format for creating submissions to Copernicus journals.
 #'
 #' @inheritParams rmarkdown::pdf_document
-#' @param ... Additional arguments to \code{rmarkdown::pdf_document()}.
+#' @param ... Additional arguments to \code{rmarkdown::pdf_document()}. \bold{Note}: \code{extra_dependencies} are not
+#' allowed as Copernicus does not support additional packages included via \code{\\usepackage{}}.
 #' @param journal_name A regular expression to filter the by the journal name, see \code{pattern} in \code{\link[base]{grep}}; defaults to \code{*}.
 #'
 #' @return An R Markdown output format.
@@ -12,21 +13,23 @@
 #'
 #' An number of required and optional manuscript sections, e.g. \code{acknowledgements}, \code{competinginterests}, or \code{authorcontribution}, must be declared using the respective properties of the R Markdown header - see skeleton file.
 #'
-#' \strong{Version:} Based on copernicus_package.zip in the version 5.3, 18 February 2019, using \code{copernicus.cls} in version 8.82.
+#' \strong{Version:} Based on \code{copernicus_package.zip} in the version 6.2, 15 January 2021, using \code{copernicus.cls} in version 9.25.
 #'
-#' \strong{Copernicus journal abbreviations:} You can use the function \code{copernicus_journal_abbreviations()} to get the journal abbreviation for all journals supported by the copernicus article template.
+#' \strong{Copernicus journal abbreviations:} You can use the function \code{copernicus_journal_abbreviations()} to get the journal abbreviation for all journals supported by the Copernicus article template.
 #'
 #' \strong{Important note:} The online guidelines by Copernicus are the official resource.
 #' Copernicus is not responsible for the community contributions made to support the template in this package.
-#' Copenicus converts all typeset TeX files into XML, the expressions and markups have to be highly standardized.
+#' Copernicus converts all typeset TeX files into XML, the expressions and markups have to be highly standardized.
 #' Therefore, please keep the following in mind:
 #'
 #' \itemize{
 #'   \item Please provide only one figure file for figures with several panels, and please do not use \code{\\subfloat} or similar commands.
 #'   \item Please use only commands in which words, numbers, etc. are within braces (e.g. \code{\\textrm{TEXT}} instead of \code{{\\rm TEXT}}).
 #'   \item For algorithms, please use the syntax given in template.tex or provide your algorithm as a figure.
 #'   \item Please do not define new commands.
-#'   \item The most commonly used packages (\code{\\usepackage{}}) are integrated in the copernicus.cls. Some other packages often used by the community are defined in template.tex. Please do not insert additional ones in your *.tex file.
+#'   \item Supported packages (\code{\\usepackage{}}) are already integrated in the \code{copernicus.cls}.  Please do not insert additional ones in your \code{*.tex} file.
+#'   \item If you opt for syntax highlighting for your preprint or other reasons, please do not forget to use
+#'    \code{highlight = NULL} for your final file upload once your manuscript was accepted for publication.
 #'   \item Spaces in labels (\code{\\label{}}) are not allowed; please make sure that no label name is assigned more than once.
 #'   \item Please do not use \code{\\paragraph{}}; only \code{\\subsubsection{}} is allowed.
 #'   \item It is not possible to add tables in colour.
@@ -48,14 +51,21 @@
 #' }
 #' @export
 copernicus_article <- function(
-  ..., keep_tex = TRUE, citation_package = "natbib", md_extensions = c(
+  ..., keep_tex = TRUE, highlight = NULL, citation_package = "natbib", md_extensions = c(
     "-autolink_bare_uris", # disables automatic links, needed for plain email in \correspondence
     "-auto_identifiers"    # disables \hypertarget commands
   )
 ) {
+  if ("extra_dependencies" %in% names(list(...)))
+    warning(
+      "Copernicus does not support additional LaTeX packages and options!
+          >> Please remove 'extra_dependencies' from your YAML header!",
+      call. = FALSE
+    )
+
   pdf_document_format(
     "copernicus", citation_package = citation_package,
-    keep_tex = keep_tex, md_extensions = md_extensions, ...
+    keep_tex = keep_tex, highlight = highlight, md_extensions = md_extensions, ...
   )
 }
 

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

@@ -62,8 +62,9 @@
 % Web Ecology (we)
 % Wind Energy Science (wes)
 
-
-%% \usepackage commands included in the copernicus.cls:
+%% Please DO NOT add additional packages or LaTeX commands to the template. They
+%% are not supported by Coperncius. LaTeX packages already
+%% included in the copernicus.cls are:
 %\usepackage[german, english]{babel}
 %\usepackage{tabularx}
 %\usepackage{cancel}
@@ -111,11 +112,6 @@
 %$header-includes$
 %$endfor$
 
-$if(algorithms)$
-\usepackage{algorithmic}
-\usepackage{algorithm}
-$endif$
-
 $if(highlighting-macros)$
 $highlighting-macros$
 $endif$

inst/rmarkdown/templates/copernicus/skeleton/skeleton.Rmd

@@ -46,8 +46,6 @@ running:
 # This section is mandatory even if you declare that no competing interests are present.
 competinginterests: |
   The authors declare no competing interests.
-# OPTIONAL:
-algorithms: true
 # See https://publications.copernicus.org/for_authors/licence_and_copyright.html, normally used for transferring the copyright, if needed. 
 # Note: additional copyright statements for affiliated software or data need to be placed in the data availability section. 
 copyrightstatement: |
@@ -87,15 +85,17 @@ appendix: |
   
   Please add `\clearpage` between each table and/or figure. Further guidelines on figures and tables can be found below.
 output:
-  rticles::copernicus_article: default
+  rticles::copernicus_article: 
+    highlight: NULL
+    keep_tex: true
   bookdown::pdf_book:
     base_format: rticles::copernicus_article # for using bookdown features like \@ref()
 ---
 
 \introduction[Introduction]
 
 Introduction text goes here.
-You can change the name of the section if neccessary using `\introduction[modified heading]`.
+You can change the name of the section if necessary using `\introduction[modified heading]`.
 
 The following settings can or must be configured in the header of this file and are bespoke for Copernicus manuscripts:
 
@@ -119,8 +119,23 @@ The following settings can or must be configured in the header of this file and
 
 See the defaults and examples from the skeleton and the official Copernicus documentation for details.
 
-**Important**: Always double-check with the official manuscript preparation guidelines at [https://publications.copernicus.org/for_authors/manuscript_preparation.html](https://publications.copernicus.org/for_authors/manuscript_preparation.html), especially the sections "Technical instructions for LaTeX" and "Manuscript composition".
-Please contact Daniel Nüst, `[email protected]`, with any problems.
+**Please note:** Per [their
+guidelines](https://publications.copernicus.org/for_authors/manuscript_preparation.html),
+Copernicus does not support additional \LaTeX{} packages or new \LaTeX{}
+commands than those defined in their `.cls` file. This means that you cannot add any extra dependencies and a warning will be thrown if so.  
+This extends to syntax highlighting of source code. Therefore this template sets
+the parameter `highlight` in the YAML header to `NULL` to deactivate Pandoc
+syntax highlighter. This prevent addition of external packages for highlighting
+inserted by Pandoc. However, it might be desirable to have syntax highlight
+available in preprints or for others reasons. Please see
+`?rmarkdown::pdf_document` for available options to activate highlighting.
+
+**Important**: Always double-check with the official manuscript preparation
+guidelines at
+[https://publications.copernicus.org/for_authors/manuscript_preparation.html](https://publications.copernicus.org/for_authors/manuscript_preparation.html),
+especially the sections "Technical instructions for LaTeX" and "Manuscript
+composition". Please contact Daniel Nüst, `[email protected]`, with
+any problems.
 
 # Content section one
 
@@ -290,10 +305,15 @@ x & y & z\\
 \end{matrix}
 $$
 
-## ALGORITHM
+## ALGORITHM/PROGRAMMING CODE
 
-If you want to use algorithms, you can either enable the required packages in the header (the default, see `algorithms: true`), or make sure yourself that the \LaTeX packages `algorithms` and `algorithmicx` are installed so that `algorithm.sty` respectively `algorithmic.sty` can be loaded by the Copernicus template.
-Copernicus staff will remove all undesirable packages from your LaTeX source code, so please stick to using the header option, which only adds the two acceptable packages.
+If you want to use algorithms, you need to make sure yourself that the \LaTeX packages `algorithms` and `algorithmicx` are installed so that `algorithm.sty` respectively `algorithmic.sty` can be loaded by the Copernicus template. Both need to be available through your preferred \LaTeX{} distribution. With TinyTeX (or TeX Live), you can do so by running `tinytex::tlmgr_install(c("algorithms", "algorithmicx"))`
+
+```{r, echo = FALSE, eval = tinytex::is_tinytex()}
+tinytex::tlmgr_install(c("algorithms", "algorithmicx"))
+```
+
+Copernicus staff will no accept any additional packages from your LaTeX source code, so please stick to these two acceptable packages. They are needed to use the example below
 
 \begin{algorithm}
 \caption{Algorithm Caption}