From 928468efa0820c24424b562fdb977f149555cadf Mon Sep 17 00:00:00 2001 From: Yihui Xie Date: Tue, 10 Aug 2021 19:12:54 -0500 Subject: [PATCH] fix #948: make the numbering scheme of figures and tables independent of number_sections (#1226) --- NEWS.md | 2 ++ R/bs4_book.R | 2 +- R/ebook.R | 6 ++++-- R/gitbook.R | 6 +++--- R/html.R | 25 ++++++++++++++++++------- R/word.R | 7 +++---- man/epub_book.Rd | 8 ++++++++ man/gitbook.Rd | 8 ++++++++ man/html_chapters.Rd | 8 ++++++++ man/html_document2.Rd | 9 +++++++++ 10 files changed, 64 insertions(+), 17 deletions(-) diff --git a/NEWS.md b/NEWS.md index cea8ef821..a34cc230e 100644 --- a/NEWS.md +++ b/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). diff --git a/R/bs4_book.R b/R/bs4_book.R index e32726e92..165e91f0f 100644 --- a/R/bs4_book.R +++ b/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 ) diff --git a/R/ebook.R b/R/ebook.R index 4f38b42e0..ae370548b 100644 --- a/R/ebook.R +++ b/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) { diff --git a/R/gitbook.R b/R/gitbook.R index 5a6103707..00591b9e7 100644 --- a/R/gitbook.R +++ b/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) diff --git a/R/html.R b/R/html.R index da95d07fd..6ea35a642 100644 --- a/R/html.R +++ b/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 = '^$' -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) { diff --git a/R/word.R b/R/word.R index fe069c3e4..1bdb51ebe 100644 --- a/R/word.R +++ b/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 diff --git a/man/epub_book.Rd b/man/epub_book.Rd index e3a9f3c40..4e5ba5490 100644 --- a/man/epub_book.Rd +++ b/man/epub_book.Rd @@ -18,6 +18,7 @@ epub_book( chapter_level = 1, epub_version = c("epub3", "epub", "epub2"), md_extensions = NULL, + global_numbering = !number_sections, pandoc_args = NULL, template = "default" ) @@ -46,6 +47,13 @@ for \code{"epub3"} since Pandoc 2.0 and \code{"epub2"} for earlier version.} \item{md_extensions}{A character string of Pandoc Markdown extensions.} +\item{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.} + \item{pandoc_args}{A vector of additional Pandoc arguments.} \item{template}{Pandoc template to use for rendering. Pass \code{"default"} diff --git a/man/gitbook.Rd b/man/gitbook.Rd index 3c72bc761..2fa8303e2 100644 --- a/man/gitbook.Rd +++ b/man/gitbook.Rd @@ -10,6 +10,7 @@ gitbook( self_contained = FALSE, anchor_sections = TRUE, lib_dir = "libs", + global_numbering = !number_sections, pandoc_args = NULL, ..., template = "default", @@ -24,6 +25,13 @@ gitbook( Arguments to be passed to \code{rmarkdown::\link{html_document}()} (\code{...} not including \code{toc}, and \code{theme}).} +\item{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.} + \item{...}{Other arguments to be passed to \code{base_format}. For \code{html_book()} and \code{tufte_html_book()}, \code{...} is passed to \code{html_chapters()}.} diff --git a/man/html_chapters.Rd b/man/html_chapters.Rd index 6968f0c8f..3bb7b0e25 100644 --- a/man/html_chapters.Rd +++ b/man/html_chapters.Rd @@ -12,6 +12,7 @@ html_chapters( fig_caption = TRUE, lib_dir = "libs", template = bookdown_file("templates/default.html"), + global_numbering = !number_sections, pandoc_args = NULL, ..., base_format = rmarkdown::html_document, @@ -30,6 +31,13 @@ tufte_html_book(...) \code{tufte::\link[tufte:tufte_handout]{tufte_html}}, or the documentation of the \code{base_format} function.} +\item{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.} + \item{...}{Other arguments to be passed to \code{base_format}. For \code{html_book()} and \code{tufte_html_book()}, \code{...} is passed to \code{html_chapters()}.} diff --git a/man/html_document2.Rd b/man/html_document2.Rd index 97f71618e..ce0832282 100644 --- a/man/html_document2.Rd +++ b/man/html_document2.Rd @@ -25,6 +25,7 @@ figures/tables/equations} html_document2( ..., number_sections = TRUE, + global_numbering = !number_sections, pandoc_args = NULL, base_format = rmarkdown::html_document ) @@ -53,6 +54,7 @@ markdown_document2( number_sections = TRUE, fig_caption = TRUE, md_extensions = NULL, + global_numbering = !number_sections, pandoc_args = NULL, ..., base_format = rmarkdown::md_document @@ -83,6 +85,13 @@ current first-level section number, and \code{i} is an incremental number sequentially in the document from 1, 2, ..., and you cannot cross-reference section headers in this case.} +\item{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.} + \item{base_format}{An output format function to be used as the base format.} } \value{