diff --git a/DESCRIPTION b/DESCRIPTION index 306532cd9..8a1ceafc4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: rticles Type: Package Title: Article Formats for R Markdown -Version: 0.21.3 +Version: 0.21.4 Authors@R: c( person("JJ", "Allaire", role = "aut", email = "jj@rstudio.com"), person("Yihui", "Xie", role = c("aut", "cre"), email = "xie@yihui.name", comment = c(ORCID = "0000-0003-0645-5666")), @@ -49,7 +49,8 @@ Authors@R: c( person("Greg", "Macfarlane", role = c("ctb"), email = "gregmacfarlane@gmail.com", comment = c(github = "gregmacfarlane")), person("Matthias", "Templ", role = c("ctb"), email = "matthias.templ@gmail.com", comment = c(ORCID = "0000-0002-8638-5276", github = "matthias-da")), person("Alvaro", "Uzaheta", role = c("ctb"), email = "alvaro.uzaheta@gess.ethz.ch", comment = c(github = "auzaheta")), - person("JooYoung", "Seo", role=c("ctb"), email="jseo1005@illinois.edu", comment = c(ORCID = "0000-0002-4064-6012")) + person("JooYoung", "Seo", role=c("ctb"), email="jseo1005@illinois.edu", comment = c(ORCID = "0000-0002-4064-6012")), + person("Karel", "Kroeze", role = c("ctb"), email = "karel.kroeze@gmail.com", comment = c(ORCID = "0000-0002-7000-7377", github = "karel-kroeze")) ) Description: A suite of custom R Markdown formats and templates for authoring journal articles and conference submissions. diff --git a/NEWS.md b/NEWS.md index 3e7fd9a04..6bebd39b3 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,6 +6,8 @@ - Add `trb_article()` for annual meeting submissions to the Transportation Research Board Annual Meeting (thanks, @gregmacfarlane, #427). +- `ieee_article()` now supports journal articles with different defaults, using `journal` classoption for `IEEEtran` document class. This brings a pandoc minimum requirement of 2.8 for conference paper and 2.10 for journal article. A new demo Rmd file has been added in the bundle when creating the template for `ieee_article()` - see this file and help page for new argument and syntax (thanks, @Karel-Kroeze, #375). + # rticles 0.21 ## NEW FEATURES diff --git a/R/ieee_article.R b/R/ieee_article.R index 367190eed..13458d097 100644 --- a/R/ieee_article.R +++ b/R/ieee_article.R @@ -4,7 +4,12 @@ #' . #' #' Presently, only the `"conference"` paper mode offered by the -#' `IEEEtran.cls` is supported. +#' `IEEEtran.cls` is supported, with experimental support for the +#' `"journal"` mode. +#' +#' # Pandoc requirement +#' +#' This format requires at least Pandoc 2.8 and 2.10 when `journal` is used. #' #' @inheritParams rmarkdown::pdf_document #' @param draftmode Specify the draft mode to control spacing and whether images @@ -12,6 +17,9 @@ #' `"draftcls"`, or `"draftclsnofoot"`. #' @param hyphenfixes A `character` value that provides the correct #' hyphenations for ambiguous words. Separate new words with spaces. +#' @param journal Running Header to use for a journal paper. When set, +#' classoption `journal` will be used instead of `conference`. +#' `number_sections` will also default to `TRUE` in this case. #' @param IEEEspecialpaper A `character` value containing the publication's #' special paper designation. #' @param with_ifpdf A `logical` value turning on (`TRUE`) or off @@ -39,6 +47,7 @@ ieee_article <- function( draftmode = c("final", "draft", "draftcls", "draftclsnofoot"), hyphenfixes = "op-tical net-works semi-conduc-tor", + journal = NULL, IEEEspecialpaper = "", with_ifpdf = FALSE, with_cite = FALSE, @@ -49,10 +58,14 @@ ieee_article <- function( with_dblfloatfix = FALSE, keep_tex = TRUE, pandoc_args = NULL, + citation_package = "default", md_extensions = c("-autolink_bare_uris"), + number_sections = FALSE, ... ) { + rmarkdown::pandoc_available("2.8", error = TRUE) + args <- c() draftmode <- match.arg(draftmode) @@ -60,6 +73,19 @@ ieee_article <- function( args <- c(args, "hyphenfixes" = hyphenfixes) + + # Some check when journal mode is set + if (!is.null(journal)) { + # Add as Pandoc's variable + args <- c(args, "journal" = journal) + # activate number_section by default + if(missing(number_sections)) number_sections <- TRUE + # New author syntax needs to be used which requires a recent pandoc + if (!rmarkdown::pandoc_available("2.10")) { + stop("Using `journal` mode for `ieee_article()` requires Pandoc >= 2.10", call. = FALSE) + } + } + # Avoid declaration of pandoc variable if field is empty if (nchar(IEEEspecialpaper) > 1) { args <- c(args, "IEEEspecialpaper" = IEEEspecialpaper) @@ -83,6 +109,7 @@ ieee_article <- function( pdf_document_format( "ieee", pandoc_args = c(pandoc_arg_list, pandoc_args), keep_tex = keep_tex, md_extensions = md_extensions, + number_sections = number_sections, citation_package = citation_package, ... ) } diff --git a/inst/rmarkdown/templates/ieee/resources/template.tex b/inst/rmarkdown/templates/ieee/resources/template.tex index 0e94f6c04..a52008bc6 100644 --- a/inst/rmarkdown/templates/ieee/resources/template.tex +++ b/inst/rmarkdown/templates/ieee/resources/template.tex @@ -50,7 +50,11 @@ % The testflow support page is at: % http://www.michaelshell.org/tex/testflow/ -\documentclass[conference,$if(fontsize)$$fontsize$,$endif$$if(draftmode)$$draftmode$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{IEEEtran} +% *** rticle changes for journal/conference mode. +% adding journal as an override for conference mode to maintain backwards +% compatibility. Any future expansions to further modes will have to come up with +% a cleverer solution, or introduce breaking changes. +\documentclass[$if(journal)$journal$else$conference$endif$,$if(fontsize)$$fontsize$,$endif$$if(draftmode)$$draftmode$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{IEEEtran} % Some Computer Society conferences also require the compsoc mode option, % but others use the standard conference format. % @@ -335,7 +339,7 @@ \bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} $endif$ $if(biblatex)$ -\usepackage[backend=bibtex,citestyle=ieee,style=numeric$if(citation_sorting)$,sorting=$citation_sorting$$endif$]{biblatex} +\usepackage[backend=bibtex,citestyle=ieee,style=$if(biblio-style)$$biblio-style$$else$numeric$endif$,$if(citation_sorting)$sorting=$citation_sorting$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} $if(bibliography)$ $for(bibliography)$ \addbibresource{$bibliography$} @@ -382,7 +386,7 @@ breaklinks=true} \urlstyle{same} % don't use monospace font for urls -% Pandoc toggle for numbering sections (defaults to be off) +% Pandoc toggle for numbering sections $if(numbersections)$ \setcounter{secnumdepth}{$if(secnumdepth)$$secnumdepth$$else$5$endif$} $else$ @@ -406,15 +410,18 @@ \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces$endif$}% {\par} % For Pandoc 2.11+ +\newlength{\cslentryspacingunit} % times entry-spacing +\setlength{\cslentryspacingunit}{\parskip} \newenvironment{CSLReferences}[2] % #1 hanging-ident, #2 entry spacing {% don't indent paragraphs \setlength{\parindent}{0pt} % turn on hanging indent if param 1 is 1 - \ifodd #1 \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces\fi - % set entry spacing - \ifnum #2 > 0 - \setlength{\parskip}{#2\baselineskip} + \ifodd #1 + \let\oldpar\par + \def\par{\hangindent=\cslhangindent\oldpar} \fi + % set entry spacing + \setlength{\parskip}{#2\cslentryspacingunit} }% {} \usepackage{calc} % for calculating minipage widths @@ -447,6 +454,24 @@ % Do not put math or special symbols in the title. \title{$title$} + +% split author affiliations for journal and conference layouts +$if(journal)$ + +$if(affiliation.author)$ +\author{ + $for(affiliation.author)$$if(it.last)$and $endif$$it.name$$if(it.member)$, \IEEEmembership{$it.member$}$endif$$sep$, $endfor$ + $if(affiliation.thanks)$$for(affiliation.thanks)$\thanks{$affiliation.thanks$}$endfor$$endif$ +} +$else$ +$~$!!! Only 'affiliation.author' syntax is supported for the journal mode. Modify you YAML header accordingly.$~$ +$endif$ + +\markboth{$journal$$~$, Vol. XX, No. X, XXXXXX 20XX$~$}% +{$title$} + +$else$ % -- end if/journal + % author names and affiliations % use a multiple column layout for up to three different % affiliations @@ -563,6 +588,8 @@ $endif$ } +$endif$ %% -- end else/journal + % conference papers do not typically use \thanks and this command % is locked out in conference mode. If really needed, such as for % the acknowledgment of grants, issue a \IEEEoverridecommandlockouts @@ -586,14 +613,6 @@ %\IEEEauthorblockA{\IEEEauthorrefmark{4}Tyrell Inc., 123 Replicant Street, Los Angeles, California 90210--4321}} - - -% use for special paper notices -%\IEEEspecialpapernotice{(Invited Paper)} - - - - % make the title area \maketitle @@ -606,7 +625,7 @@ % keywords $if(keywords)$ \begin{IEEEkeywords} -$for(keywords)$$keywords$$sep$; $endfor$ +$for(keywords)$$keywords$$sep$$if(journal)$, $else$; $endif$$endfor$ \end{IEEEkeywords} $endif$ @@ -661,5 +680,3 @@ $endfor$ \end{document} - - diff --git a/inst/rmarkdown/templates/ieee/skeleton/IEEE-journal-example.Rmd b/inst/rmarkdown/templates/ieee/skeleton/IEEE-journal-example.Rmd new file mode 100644 index 000000000..8bfa51101 --- /dev/null +++ b/inst/rmarkdown/templates/ieee/skeleton/IEEE-journal-example.Rmd @@ -0,0 +1,181 @@ +--- +title: Bare Demo of IEEEtran.cls for IEEE Conferences & Journals +affiliation: + ## A custom author ordering field that breaks institution grouping. + ## This is the only supported format for the journal mode. + author: + - name: Eldon Tyrell + member: Member, IEEE ## only used for journal mode + mark: 4 ## ignored for journal mode + email: eldon@starfleet-academy.star + - name: Michael Shell + member: Fellow, OSA + mark: 1 + - name: Roy Batty + member: Life Fellow, IEEE + mark: 4 + email: roy@replicant.offworld + last: true ## mark the last author so that we can insert `and` + ## at the appropriate place. + ## used only in journal mode for author affiliations and other acknowledgements + thanks: + - "E. Tyrell and R. Batty are with Starfleet Academy." + - "M. Shell was with the Department of Electrical and Computer Engineering, Georgia Institute of Technology, Atlanta, GA, 30332 USA e-mail: (see http://www.michaelshell.org/contact.html)." + - "Manuscript received February 17, 2021; revised June 6, 2021." +keywords: ["keyword 1", "keyword 2"] +abstract: | + The abstract goes here. + On multiple lines eventually. +## Example of option for biblatex +# biblatexoptions: sorting=none +## When using pandoc for citation processing (the default), these options set the correct +## citation style, and add links to citations. +csl: https://www.zotero.org/styles/ieee # download locally if needed. +link-citations: true +## bibliography file(s) +bibliography: mybibfile.bib +output: + rticles::ieee_article: + ## Activate journal mode and specify journal for page headers + journal: IEEE Transactions on Learning Technology + # use some specific Tex packages if needed. (see ?rticles::ieee_article()) + # with_ifpdf: true + # with_cite: true + with_amsmath: true # amsmath need to be true to use with bookdown for referencing equations. + # with_algorithmic: true + # with_subfig: true + # with_array: true + # with_dblfloatfix: true +--- + +Introduction +============= + +\IEEEPARstart{T}{his} demo file is intended to serve as a ``starter file'' +for IEEE conference papers produced under \LaTeX\ using +IEEEtran.cls version 1.8b and later. + +I wish you the best of success. + + +## Subsection Heading Here +Subsection text here. + +### Subsubsection Heading Here +Subsubsection text here. + + + + +Conclusion +============ +The conclusion goes here. + + + +Acknowledgment {#acknowledgment} +============== + +The authors would like to thank... + +Bibliography styles +=================== + +Here are two sample references: @Feynman1963118 [@Dirac1953888]. + +\newpage +References {#references .numbered} +========== diff --git a/inst/rmarkdown/templates/ieee/skeleton/skeleton.Rmd b/inst/rmarkdown/templates/ieee/skeleton/skeleton.Rmd index fc1067571..6541a1a98 100644 --- a/inst/rmarkdown/templates/ieee/skeleton/skeleton.Rmd +++ b/inst/rmarkdown/templates/ieee/skeleton/skeleton.Rmd @@ -1,23 +1,33 @@ --- -title: Bare Demo of IEEEtran.cls for IEEE Conferences -affiliation: - ## use one only of the following +title: Bare Demo of IEEEtran.cls for IEEE Conferences & Journals + +affiliation: + ## use one only of the following - only relevant in conference mode and ignored in journal mode # author-columnar: true ## one column per author - institution-columnar: true ## one column per institution (multiple autors eventually) - # wide: true ## one column wide author/affiliation fields - - #author: ## A custom author ordering field that breaks institution grouping. - # - name: Eldon Tyrell - # mark: 4 - # email: eldon@starfleet-academy.star - # - name: Michael Shell - # mark: 1 - # - name: Roy Batty - # mark: 4 - # email: roy@replicant.offworld - ## Authors cited in institution field are ignored when author field exists - - #author_multiline: ## Put authors in a given order, with multiline possibility. Authors cited in institution are ignored if exists + institution-columnar: true ## one column per institution (multiple authors eventually) + # wide: true ## one column wide author/affiliation fields + + ## A custom author ordering field that breaks institution grouping. + ## This is the only supported format for the journal mode. + author: + - name: Eldon Tyrell + member: Member, IEEE ## only used for journal mode + mark: 4 ## ignored for journal mode + email: eldon@starfleet-academy.star + - name: Michael Shell + member: Fellow, OSA + mark: 1 + - name: Roy Batty + member: Life Fellow, IEEE + mark: 4 + email: roy@replicant.offworld + last: true ## mark the last author so that we can insert `and` + ## at the appropriate place. + + ## Put authors in a given order, with multiline possibility. + ## Authors cited in institution are ignored if exists. + ## Only relevant in conference mode. + #author_multiline: # - line: ## Create a new author line # - name: Michael Shell # mark: 1 @@ -32,7 +42,8 @@ affiliation: # mark: 3 # - name: Eldon Tyrell # mark: 4 - + + ## institution information is ignored in journal mode institution: - name: Georgia Institute of Technology department: School of Electrical and Computer Engineering @@ -61,23 +72,41 @@ affiliation: email: eldon@starfleet-academy.star - name: Roy Batty email: roy@replicant.offworld + + ## used only in journal mode for author affiliations and other acknowledgements + # thanks: + # - "E. Tyrell and R. Batty are with Starfleet Academy." + # - "M. Shell was with the Department of Electrical and Computer Engineering, Georgia Institute of Technology, Atlanta, GA, 30332 USA e-mail: (see http://www.michaelshell.org/contact.html)." + # - "Manuscript received February 17, 2021; revised June 6, 2021." + keywords: ["keyword 1", "keyword 2"] abstract: | The abstract goes here. On multiple lines eventually. -# use some specific Tex packages if needed. -# with_ifpdf: true -# with_cite: true -# amsmath need to be true to use with bookdown for referencing equations. -with_amsmath: true -# with_algorithmic: true -# with_array: true -# with_dblfloatfix: true +## Example of option for biblatex +# biblatexoptions: sorting=none + +## When using pandoc for citation processing (the default), these options set the correct +## citation style, and add links to citations. +csl: https://www.zotero.org/styles/ieee # download locally if needed. +link-citations: true +## bibliography file(s) bibliography: mybibfile.bib -output: rticles::ieee_article -#citation_sorting: none ## used as sorting option of the biblatex package (if selected) + +output: + rticles::ieee_article: + ## Activate journal mode and specify journal for page headers + # journal: IEEE Transactions on Learning Technology + # use some specific Tex packages if needed. (see ?rticles::ieee_article()) + # with_ifpdf: true + # with_cite: true + with_amsmath: true # amsmath need to be true to use with bookdown for referencing equations. + # with_algorithmic: true + # with_subfig: true + # with_array: true + # with_dblfloatfix: true --- Introduction diff --git a/man/ieee_article.Rd b/man/ieee_article.Rd index 142420c85..79ad5a95f 100644 --- a/man/ieee_article.Rd +++ b/man/ieee_article.Rd @@ -7,6 +7,7 @@ ieee_article( draftmode = c("final", "draft", "draftcls", "draftclsnofoot"), hyphenfixes = "op-tical net-works semi-conduc-tor", + journal = NULL, IEEEspecialpaper = "", with_ifpdf = FALSE, with_cite = FALSE, @@ -17,7 +18,9 @@ ieee_article( with_dblfloatfix = FALSE, keep_tex = TRUE, pandoc_args = NULL, + citation_package = "default", md_extensions = c("-autolink_bare_uris"), + number_sections = FALSE, ... ) } @@ -29,6 +32,10 @@ should be rendered. Valid options are: \code{"final"} (default), \code{"draft"}, \item{hyphenfixes}{A \code{character} value that provides the correct hyphenations for ambiguous words. Separate new words with spaces.} +\item{journal}{Running Header to use for a journal paper. When set, +classoption \code{journal} will be used instead of \code{conference}. +\code{number_sections} will also default to \code{TRUE} in this case.} + \item{IEEEspecialpaper}{A \code{character} value containing the publication's special paper designation.} @@ -57,10 +64,17 @@ off (\code{FALSE}) the \code{dblfloatfix} LaTeX package.} \item{pandoc_args}{Additional command line options to pass to pandoc} +\item{citation_package}{The LaTeX package to process citations, \code{natbib} +or \code{biblatex}. Use \code{default} if neither package is to be used, +which means citations will be processed via the command +\command{pandoc-citeproc}.} + \item{md_extensions}{Markdown extensions to be added or removed from the default definition or R Markdown. See the \code{\link[rmarkdown]{rmarkdown_format}} for additional details.} +\item{number_sections}{\code{TRUE} to number section headings} + \item{...}{Additional arguments to \code{\link[rmarkdown:pdf_document]{rmarkdown::pdf_document()}}} } \description{ @@ -69,8 +83,13 @@ Format for creating submissions to IEEE Transaction journals. Adapted from } \details{ Presently, only the \code{"conference"} paper mode offered by the -\code{IEEEtran.cls} is supported. +\code{IEEEtran.cls} is supported, with experimental support for the +\code{"journal"} mode. } +\section{Pandoc requirement}{ +This format requires at least Pandoc 2.8 and 2.10 when \code{journal} is used. +} + \references{ Shell, Michael. "How to use the IEEEtran LATEX class." Journal of LATEX Class Files 1.11 (2002): 10-20. diff --git a/tests/testit/test-formats.R b/tests/testit/test-formats.R index 1313ce929..fd4e88ba6 100644 --- a/tests/testit/test-formats.R +++ b/tests/testit/test-formats.R @@ -1,4 +1,4 @@ -test_format <- function(name, output_options = NULL, os_skip = NULL) { +test_format <- function(name, input = NULL, output_options = NULL, os_skip = NULL) { # don't run on CRAN due to complicated dependencies (Pandoc/LaTeX packages) if (!identical(Sys.getenv("NOT_CRAN"), "true")) return() @@ -18,8 +18,12 @@ test_format <- function(name, output_options = NULL, os_skip = NULL) { create_dir = FALSE, edit = FALSE ) + # override the render file if input is provided + if (!is.null(input)) testdoc <- input + message('Rendering the ', name, ' format...', - if(!is.null(output_options)) " (with output options)") + if(!is.null(output_options)) " (with output options)", + if (!is.null(input)) c(" using file ", input)) output_file <- rmarkdown::render(testdoc, output_options = output_options, quiet = TRUE) assert(paste(name, "format works"), { file.exists(output_file) @@ -45,7 +49,7 @@ test_format("copernicus") if (xfun::is_linux()) test_format("ctex") # only on linux due to fonts requirements test_format("elsevier") test_format("frontiers") -test_format("ieee") +if (rmarkdown::pandoc_available(2.8)) test_format("ieee") test_format("ims") test_format("ims", output_options = list(journal = "aap")) test_format("jasa") @@ -72,3 +76,9 @@ test_format("trb") # special case: the glossa format doesn't work with the microtype package tinytex::tlmgr_remove("microtype") test_format("glossa") + +# Multiple demo files +if (rmarkdown::pandoc_available("2.10")) { + test_format("ieee", input = "IEEE-journal-example.Rmd", + output_options = list(journal = "IEEE Transactions on Learning Technology")) +}