Generalize number sections

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: rmarkdown
 Type: Package
 Title: Dynamic Documents for R
-Version: 2.3.4
+Version: 2.3.5
 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")),
@@ -16,7 +16,9 @@ Authors@R: c(
   #
   # Contributors, ordered alphabetically by first name
   person("Andrew", "Dunning", role = "ctb", comment = c(ORCID = "0000-0003-0464-5036")),
-  person("Atsushi", "Yasumoto", role = "ctb", comment = c(ORCID = "0000-0002-8335-495X")),
+  person("Atsushi", "Yasumoto", role = c("ctb", "cph"),
+         comment = c(ORCID = "0000-0002-8335-495X",
+                     cph = "Number sections lua filter")),
   person("Barret", "Schloerke", role = "ctb"),
   person("Christophe", "Dervieux", role = "ctb"),
   person("Frederik", "Aust", role = "ctb", email = "frederik.aust@uni-koeln.de", comment = c(ORCID = "0000-0003-4900-788X")),

NEWS.md

@@ -7,7 +7,8 @@ rmarkdown 2.4
 
 - When customizing formats with the `output_format` function, `pre_knit`, `opts_hooks`, and `knit_hooks` can now refer to `rmarkdown::metadata`. Previously, `rmarkdown::metadata` returned `list()` in these functions (thanks, @atusy, #1855).
 
-- Added the `number_sections` argument to the `word_document()` output format. This requires Pandoc >= v2.10.1, and is set to `FALSE` by default (thanks, @jooyoungseo, #1869).
+- Added the `number_sections` argument to following formats: `github_document`, `ioslides_presentation`, `md_document`, `odt_document`, `powerpoint_presentation`, `rtf_document`, `slidy_presentation`, `word_document`. These are powered by a lua filter and requires Pandoc > 2.0. It will silently have no effect has before with previous pandoc version (thanks @atusy 1893).  Pandoc >= 2.10.1 adds `--number-sections` for docx format, and thus `word_document` prefers the native feature to the lua filter (thanks, @jooyoungseo, #1869).
+
 
 - For the output format `pdf_document`, the option `fig_crop` will not be enabled unless both the programs `pdfcrop` and `ghostscript` are found (thanks, @dalupus, yihui/knitr#954).
 

R/github_document.R

@@ -18,6 +18,7 @@
 #' @export
 github_document <- function(toc = FALSE,
                             toc_depth = 3,
+                            number_sections = FALSE,
                             fig_width = 7,
                             fig_height = 5,
                             dev = 'png',
@@ -30,11 +31,14 @@ github_document <- function(toc = FALSE,
                             keep_html = FALSE) {
 
   # add special markdown rendering template to ensure we include the title fields
+  # and add an optional feature to number sections
   pandoc_args <- c(
     pandoc_args, "--template", pkg_file_arg(
-      "rmarkdown/templates/github_document/resources/default.md")
+      "rmarkdown/templates/github_document/resources/default.md"),
+    if (number_sections) pandoc_lua_filters("number-sections.lua")
   )
 
+
   pandoc2 <- pandoc2.0()
   # use md_document as base
   variant <- if (pandoc2) "gfm" else "markdown_github"

R/ioslides_presentation.R

@@ -223,7 +223,8 @@
 #'   To create a PDF version of a presentation you can use Print to PDF
 #'   from Google Chrome.
 #' @export
-ioslides_presentation <- function(logo = NULL,
+ioslides_presentation <- function(number_sections = FALSE,
+                                  logo = NULL,
                                   slide_level = 2,
                                   incremental = FALSE,
                                   fig_width = 7.5,
@@ -343,6 +344,9 @@ ioslides_presentation <- function(logo = NULL,
     # add any custom pandoc args
     args <- c(args, pandoc_args)
 
+    # number sections
+    if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+
     lua_writer <- file.path(dirname(input_file), "ioslides_presentation.lua")
     # The input directory may not be writable (on e.g. Shiny Server), so write
     # to the output directory in this case. We don't always do this since

R/md_document.R

@@ -37,6 +37,7 @@ md_document <- function(variant = "markdown_strict",
                         preserve_yaml = FALSE,
                         toc = FALSE,
                         toc_depth = 3,
+                        number_sections = FALSE,
                         fig_width = 7,
                         fig_height = 5,
                         fig_retina = NULL,
@@ -59,6 +60,9 @@ md_document <- function(variant = "markdown_strict",
   # pandoc args
   args <- c(args, pandoc_args)
 
+  # number sections with lua filter
+  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+
   # add post_processor for yaml preservation
   post_processor <- if (preserve_yaml && variant != 'markdown') {
     function(metadata, input_file, output_file, clean, verbose) {

R/odt_document.R

@@ -31,7 +31,8 @@
 #' render("input.Rmd", odt_document(highlight = "zenburn"))
 #' }
 #' @export
-odt_document <- function(fig_width = 5,
+odt_document <- function(number_sections = FALSE,
+                         fig_width = 5,
                          fig_height = 4,
                          fig_caption = TRUE,
                          template = "default",
@@ -68,6 +69,9 @@ odt_document <- function(fig_width = 5,
   # pandoc args
   args <- c(args, pandoc_args)
 
+  # number sections with lua filter
+  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+
   saved_files_dir <- NULL
   pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
     saved_files_dir <<- files_dir

R/powerpoint_presentation.R

@@ -9,7 +9,8 @@
 #' @export
 #' @return R Markdown output format to pass to \code{\link{render}}
 powerpoint_presentation <- function(
-  toc = FALSE, toc_depth = 2, fig_width = 5, fig_height = 4, fig_caption = TRUE,
+  toc = FALSE, toc_depth = 2, number_sections = FALSE,
+  fig_width = 5, fig_height = 4, fig_caption = TRUE,
   df_print = 'default', keep_md = FALSE, md_extensions = NULL,
   slide_level = NULL, reference_doc = 'default', pandoc_args = NULL
 ) {
@@ -35,6 +36,9 @@ powerpoint_presentation <- function(
   if (!is.null(slide_level))
     args <- c(args, '--slide-level', as.character(slide_level))
 
+  # number sections
+  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+
   # TODO: syntax highlighting
 
   # pandoc args

R/rtf_document.R

@@ -31,6 +31,7 @@
 #' @export
 rtf_document <- function(toc = FALSE,
                          toc_depth = 3,
+                         number_sections = FALSE,
                          fig_width = 5,
                          fig_height = 4,
                          keep_md = FALSE,
@@ -54,6 +55,9 @@ rtf_document <- function(toc = FALSE,
   # pandoc args
   args <- c(args, pandoc_args)
 
+  # number sections
+  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+
   preserved_chunks <- character()
 
   pre_processor <- function(metadata, input_file, runtime, knit_meta,

R/slidy_presentation.R

@@ -31,7 +31,8 @@
 #' render("pres.Rmd", slidy_presentation(incremental = TRUE))
 #' }
 #' @export
-slidy_presentation <- function(incremental = FALSE,
+slidy_presentation <- function(number_sections = FALSE,
+                               incremental = FALSE,
                                slide_level = NULL,
                                duration = NULL,
                                footer = NULL,
@@ -70,6 +71,9 @@ slidy_presentation <- function(incremental = FALSE,
     list(html_dependency_slidy(),
          html_dependency_slidy_shiny()))
 
+  # number sections
+  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+
   # incremental
   if (incremental)
     args <- c(args, "--incremental")

R/word_document.R

@@ -63,7 +63,7 @@ word_document <- function(toc = FALSE,
     if (pandoc_available("2.10.1")) {
       args <- c(args, "--number-sections")
     } else {
-      warning("number_sections for word_document requires Pandoc >= 2.10.1")
+      args <- c(args, pandoc_lua_filters("number-sections.lua"))
     }
   }
 

inst/rmd/lua/number-sections.lua

@@ -0,0 +1,53 @@
+--[[
+number-sections - Number sections like the --number-sections option
+
+# MIT License
+
+Copyright (c) 2020 Atsushi Yasumoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+https://github.com/atusy/lua-filters/blob/master/lua/number-sections.lua
+]]
+local section_number_table = {0, 0, 0, 0, 0, 0, 0, 0, 0}
+local n_section_number_table = #section_number_table
+local previous_header_level = 0
+local separator = pandoc.Space()
+if FORMAT == "docx" then -- to be consistent with Pandoc >= 2.10.1
+  separator = pandoc.Str("\t")
+end
+
+function Header(elem)
+  -- If unnumbered
+  if (elem.classes:find("unnumbered")) then
+    return elem
+  end
+
+  -- Else
+  --- Reset and update section_number_table
+  if (elem.level < previous_header_level) then
+    for i=elem.level+1,n_section_number_table do
+      section_number_table[i] = 0
+    end
+  end
+  previous_header_level = elem.level
+  section_number_table[elem.level] = section_number_table[elem.level] + 1
+
+  --- Define section number as string
+  local section_number_string = tostring(section_number_table[elem.level])
+  if elem.level > 1 then
+    for i = elem.level-1,1,-1 do
+      section_number_string = section_number_table[i] .. "." .. section_number_string
+    end
+  end
+
+  --- Update Header element
+  table.insert(elem.content, 1, separator)
+  table.insert(elem.content, 1, pandoc.Str(section_number_string))
+
+  return elem
+end

tests/testthat/test-lua-filters.R

@@ -25,3 +25,12 @@ test_that("pagebreak lua filters works", {
   expect_match(res[grep("HEADER 1", res)+2], "\\newpage", fixed = TRUE)
   expect_match(res[grep("HEADER 2", res)+2], "\\pagebreak", fixed = TRUE)
 })
+
+test_that("number_sections lua filter works", {
+  numbers <- c("1", "1.1", "2", "2.1")
+  headers <- c("#", "##", "#", "##")
+  rmd <- paste0(headers, " ", numbers, "\n\n")
+  result <- .generate_md_and_convert(rmd, md_document(number_sections = TRUE))
+  expected <- paste(numbers, numbers)
+  expect_identical(result[result %in% expected], expected)
+})

vignettes/lua-filters.Rmd

@@ -141,6 +141,34 @@ output:
 # First Header
 ````
 
+## Number sections
+
+Numbering sections are supported by Pandoc for limited formats (e.g., html and pdf).
+The rmarkdown package adds `number_sections.lua` to support this feature in other formats (e.g., docx, odt, and so on).
+Users do not have to know which formats use the Pandoc's feature or the Lua filter.
+
+```md
+---
+title: My main title
+output: 
+  md_document:
+    number_sections: true # implemented by Lua filter
+  html_document
+    number_sections: true # implemented by Pandoc
+---
+
+# First Header
+
+## A Header Belonging the First Header
+
+# Second Header
+```
+
+In general, numbers and titles of sections are separated by a space.
+An exception is the `word_document` function, which separates them by a tab in order to be consistent with Pandoc's number sections for docx format in Pandoc >= 2.10.1.
+If one wants to have fine controls on the format of section numbers, prepare customized docx file and specify it to the `reference_docx` argument of the `word_document` function.
+
+
 
 ## About lua filters {#lua-filter}