fix #948: make the numbering scheme of figures and tables independent of number_sections (#1226)

Author: yihui

NEWS.md

@@ -2,6 +2,8 @@
 
 - This version has a brand new template project to start a HTML book in one of available format. Template project can be created using the RStudio IDE _New Project..._, or using one of the two new functions, `create_gitbook()` and `create_bs4_book()`, to easily create the template you want to start with from within the R Console (#225, #1123, #1201).
 
+- Added an argument `global_numbering` to most output format functions in this package to control the figure/table numbering scheme (thanks, @elfunesto #948, @Kodiologist #1057). If `TRUE`, number figures and tables globally throughout a document (e.g., Figure 1, Figure 2, ...). If `FALSE`, number them sequentially within sections (e.g., Figure 1.1, Figure 1.2, ..., Figure 5.1, Figure 5.2, ...). Previously, this numbering scheme was hard-coded internally according to the `number_sections` argument (`global_numbering = !number_sections`). Now the two arguments have become independent, e.g., you can use `global_numbering = TRUE` with `number_sections = TRUE`.
+
 - `bs4_book(splib_bib = TRUE)` can now be specified to have the same effect as in `gitbook()`. References will be shown at the end of each chapter and not only at the end of the book. This is useful with `bs4_book()` when a citation style not supporting footnotes is used because in that case, references are not shown inline in popups (thanks, @shirdekel, #1185).
 
 - For HTML book formats, a default `404.html` page will now be created if none exists already. This page can be customized by adding a `_404.md` or `_404.Rmd` file which will be rendered to HTML and inserted in the book. Most web serving platforms (e.g. Netlify, GH Pages, etc.) will use this file named `404.html` in the root as a custom error page. Otherwise, like browsers do, a default 404 page is shown. For context, a 404 error indicates that the file can’t be found, and it happens when a browser can’t find a requested web page. This could happen with your online book if you shared a link to a section but change the name of this section leading to a change in url (#1035).

R/bs4_book.R

@@ -91,7 +91,7 @@ bs4_book_build <- function(output = "bookdown.html",
   output2 <- split_chapters(
     output = output,
     build = function(...) bs4_book_page(..., rmd_index = rmd_index),
-    number_sections = TRUE,
+    global_numbering = FALSE,
     split_by = "chapter",
     split_bib = split_bib
   )

R/ebook.R

@@ -2,6 +2,7 @@
 #'
 #' Convert a book to the EPUB format, which is is an e-book format supported by
 #' many readers, such as Amazon Kindle Fire and iBooks on Apple devices.
+#' @inheritParams html_document2
 #' @param fig_width,fig_height,dev,fig_caption Figure options (width, height,
 #'   the graphical device, and whether to render figure captions).
 #' @param number_sections Whether to number sections.
@@ -32,7 +33,8 @@ epub_book = function(
   fig_width = 5, fig_height = 4, dev = 'png', fig_caption = TRUE,
   number_sections = TRUE, toc = FALSE, toc_depth = 3, stylesheet = NULL,
   cover_image = NULL, metadata = NULL, chapter_level = 1,
-  epub_version = c('epub3', 'epub', 'epub2'), md_extensions = NULL, pandoc_args = NULL,
+  epub_version = c('epub3', 'epub', 'epub2'), md_extensions = NULL,
+  global_numbering = !number_sections, pandoc_args = NULL,
   template = 'default'
 ) {
   epub_version = match.arg(epub_version)
@@ -57,7 +59,7 @@ epub_book = function(
     knitr = rmarkdown::knitr_options_html(fig_width, fig_height, NULL, FALSE, dev),
     pandoc = rmarkdown::pandoc_options(epub_version, from, args, ext = '.epub'),
     pre_processor = function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
-      process_markdown(input_file, from, args, !number_sections)
+      process_markdown(input_file, from, args, global_numbering)
       NULL
     },
     post_processor = function(metadata, input, output, clean, verbose) {

R/gitbook.R

@@ -1,6 +1,5 @@
 #' The GitBook output format
 #'
-#' @description
 #' This output format function ported a style provided by GitBook
 #' (\url{https://www.gitbook.com}) for R Markdown. To read more about this format, see:
 #' \url{https://bookdown.org/yihui/bookdown/html.html#gitbook-style}
@@ -24,7 +23,8 @@
 #' @export
 gitbook = function(
   fig_caption = TRUE, number_sections = TRUE, self_contained = FALSE,
-  anchor_sections = TRUE, lib_dir = 'libs', pandoc_args = NULL, ..., template = 'default',
+  anchor_sections = TRUE, lib_dir = 'libs', global_numbering = !number_sections,
+  pandoc_args = NULL, ..., template = 'default',
   split_by = c('chapter', 'chapter+number', 'section', 'section+number', 'rmd', 'none'),
   split_bib = TRUE, config = list(), table_css = TRUE
 ) {
@@ -57,7 +57,7 @@ gitbook = function(
 
     move_files_html(output, lib_dir)
     output2 = split_chapters(
-      output, gitbook_page, number_sections, split_by, split_bib, gb_config, split_by
+      output, gitbook_page, global_numbering, split_by, split_bib, gb_config, split_by
     )
     if (file.exists(output) && !same_path(output, output2)) file.remove(output)
     move_files_html(output2, lib_dir)

R/html.R

@@ -5,6 +5,7 @@
 #' Functions \code{html_book()} and \code{tufte_html_book()} are simple wrapper
 #' functions of \code{html_chapter()} using a specific base output format.
 #' @inheritParams pdf_book
+#' @inheritParams html_document2
 #' @param toc,number_sections,fig_caption,lib_dir,template,pandoc_args See
 #'   \code{rmarkdown::\link{html_document}},
 #'   \code{tufte::\link[tufte:tufte_handout]{tufte_html}}, or the documentation
@@ -50,7 +51,8 @@
 #' @export
 html_chapters = function(
   toc = TRUE, number_sections = TRUE, fig_caption = TRUE, lib_dir = 'libs',
-  template = bookdown_file('templates/default.html'), pandoc_args = NULL, ...,
+  template = bookdown_file('templates/default.html'),
+  global_numbering = !number_sections, pandoc_args = NULL, ...,
   base_format = rmarkdown::html_document, split_bib = TRUE, page_builder = build_chapter,
   split_by = c('section+number', 'section', 'chapter+number', 'chapter', 'rmd', 'none')
 ) {
@@ -64,7 +66,7 @@ html_chapters = function(
   config$post_processor = function(metadata, input, output, clean, verbose) {
     if (is.function(post)) output = post(metadata, input, output, clean, verbose)
     move_files_html(output, lib_dir)
-    output2 = split_chapters(output, page_builder, number_sections, split_by, split_bib)
+    output2 = split_chapters(output, page_builder, global_numbering, split_by, split_bib)
     if (file.exists(output) && !same_path(output, output2)) file.remove(output)
     move_files_html(output2, lib_dir)
     output2
@@ -111,6 +113,12 @@ tufte_html_book = function(...) {
 #'   (the i-th figure/table); if \code{FALSE}, figures/tables will be numbered
 #'   sequentially in the document from 1, 2, ..., and you cannot cross-reference
 #'   section headers in this case.
+#' @param global_numbering If \code{TRUE}, number figures and tables globally
+#'   throughout a document (e.g., Figure 1, Figure 2, ...). If \code{FALSE},
+#'   number them sequentially within sections (e.g., Figure 1.1, Figure 1.2,
+#'   ..., Figure 5.1, Figure 5.2, ...). Note that \code{global_numbering =
+#'   FALSE} will not work with \code{number_sections = FALSE} because sections
+#'   are not numbered.
 #' @inheritParams pdf_book
 #' @return An R Markdown output format object to be passed to
 #'   \code{rmarkdown::\link{render}()}.
@@ -123,7 +131,8 @@ tufte_html_book = function(...) {
 #' @references \url{https://bookdown.org/yihui/bookdown/}
 #' @export
 html_document2 = function(
-  ..., number_sections = TRUE, pandoc_args = NULL, base_format = rmarkdown::html_document
+  ..., number_sections = TRUE, global_numbering = !number_sections,
+  pandoc_args = NULL, base_format = rmarkdown::html_document
 ) {
   config = get_base_format(base_format, list(
     ..., number_sections = number_sections, pandoc_args = pandoc_args2(pandoc_args)
@@ -135,7 +144,7 @@ html_document2 = function(
     x = clean_html_tags(x)
     x = restore_appendix_html(x, remove = FALSE)
     x = restore_part_html(x, remove = FALSE)
-    x = resolve_refs_html(x, global = !number_sections)
+    x = resolve_refs_html(x, global_numbering)
     write_utf8(x, output)
     output
   }
@@ -240,7 +249,9 @@ build_chapter = function(
 
 r_chap_pattern = '^<!--chapter:end:(.+)-->$'
 
-split_chapters = function(output, build = build_chapter, number_sections, split_by, split_bib, ...) {
+split_chapters = function(
+  output, build = build_chapter, global_numbering, split_by, split_bib, ...
+) {
 
   use_rmd_names = split_by == 'rmd'
   split_level = switch(
@@ -311,7 +322,7 @@ split_chapters = function(output, build = build_chapter, number_sections, split_
 
   # no (or not enough) tokens found in the template
   if (any(c(i1, i2, i3, i4, i5, i6) == 0)) {
-    x = resolve_refs_html(x, !number_sections)
+    x = resolve_refs_html(x, global_numbering)
     x = add_chapter_prefix(x)
     write_utf8(x, output)
     return(output)
@@ -333,7 +344,7 @@ split_chapters = function(output, build = build_chapter, number_sections, split_
     ' first-level heading(s). Did you forget first-level headings in certain Rmd files?'
   )
 
-  html_body = resolve_refs_html(html_body, !number_sections)
+  html_body = resolve_refs_html(html_body, global_numbering)
 
   # do not split the HTML file
   if (split_level == 0) {

R/word.R

@@ -2,7 +2,8 @@
 #' @export
 markdown_document2 = function(
   number_sections = TRUE, fig_caption = TRUE, md_extensions = NULL,
-  pandoc_args = NULL, ..., base_format = rmarkdown::md_document
+  global_numbering = !number_sections, pandoc_args = NULL, ...,
+  base_format = rmarkdown::md_document
 ) {
   from = rmarkdown::from_rmarkdown(fig_caption, md_extensions)
 
@@ -12,9 +13,7 @@ markdown_document2 = function(
   ))
   pre = config$pre_processor
   config$pre_processor = function(metadata, input_file, ...) {
-    # Pandoc does not support numbered sections for Word, so figures/tables have
-    # to be numbered globally from 1 to n
-    process_markdown(input_file, from, pandoc_args, !number_sections)
+    process_markdown(input_file, from, pandoc_args, global_numbering)
     if (is.function(pre)) pre(metadata, input_file, ...)
   }
   post = config$post_processor