Custom environment using Fenced Divs

DESCRIPTION

@@ -61,9 +61,10 @@ License: GPL-3
 Imports:
     htmltools (>= 0.3.6),
     knitr (>= 1.22),
-    rmarkdown (>= 2.3.5),
+    rmarkdown (>= 2.4),
     xfun (>= 0.13),
-    tinytex (>= 0.12)
+    tinytex (>= 0.12),
+    yaml (>= 2.1.19)
 Suggests:
     htmlwidgets,
     rstudioapi,
@@ -80,4 +81,3 @@ SystemRequirements: Pandoc (>= 1.17.2)
 LazyData: TRUE
 RoxygenNote: 7.1.1
 Encoding: UTF-8
-Remotes: rstudio/rmarkdown

NAMESPACE

@@ -7,6 +7,7 @@ export(calibre)
 export(clean_book)
 export(context_document2)
 export(epub_book)
+export(fence_theorems)
 export(gitbook)
 export(github_document2)
 export(html_book)

NEWS.md

@@ -4,6 +4,8 @@
 
 - Add the `number_sections` argument to `markdown_document2()` and its family. This allows to have now figure references numbered by chapters in these formats, like `word_document2()` or `odt_document2()` for example. This argument default to `TRUE` like `html_document2()` and  `pdf_document2()`. Set it to `number_sections = FALSE` to get the same output as previous version without numbered chapters (thanks, @atusy, #756). 
 
+- Provided an alternative way to create theorem and proof environments using Pandoc's fenced Divs. Previously, **bookdown** supports theorems and proofs in special code chunks like ```` ```{theorem}````. Now you can use the new syntax ```::: {.theorem}```. You may use the helper function `bookdown::fence_theorems()` to convert the former syntax to the latter. The main benefit of using fenced Divs is that you can write arbitrary content in a theorem environment (here "theorem" includes other environments such as lemma, corollary, and definition, etc.), such as R code chunks and inline R code, which was not possible previously. Note that this feature is only supported for LaTeX and HTML output formats at the moment. To learn more about the fenced Divs in general, you may read this section in _R Markdown Cookbook_: https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html (thanks, @tchevri #924, @cderv #940).
+
 ## BUG FIXES
 
 - Correctly encode the document title when creating the Twitter sharing link from a bookdown chapter (thanks, @maelle, #934).

R/latex.R

@@ -211,7 +211,9 @@ add_toc_bib = function(x) {
 restore_block2 = function(x, global = FALSE) {
   i = grep('^\\\\begin\\{document\\}', x)[1]
   if (is.na(i)) return(x)
-  if (length(grep(sprintf('^\\\\BeginKnitrBlock\\{(%s)\\}', paste(all_math_env, collapse = '|')), x)) &&
+  # add the necessary definition in the preamble when block2 engine (\BeginKnitrBlock) or pandoc
+  # fenced div (\begin) is used
+  if (length(grep(sprintf('^\\\\(BeginKnitrBlock|begin)\\{(%s)\\}', paste(all_math_env, collapse = '|')), x)) &&
       length(grep('^\\s*\\\\newtheorem\\{theorem\\}', head(x, i))) == 0) {
     theorem_defs = sprintf(
       '%s\\newtheorem{%s}{%s}%s', theorem_style(names(theorem_abbr)), names(theorem_abbr),

R/utils.R

@@ -32,6 +32,13 @@ common_format_config = function(
   # provide file_scope if requested
   if (file_scope) config$file_scope = md_chapter_splitter
 
+  # prepend the custom-environment filter
+  config$pandoc$lua_filters = c(
+    lua_filter("custom-environment.lua"), config$pandoc$lua_filters
+  )
+  # and add bookdown metadata file for the filter to work
+  config$pandoc$args = c(bookdown_yml_arg(), config$pandoc$args)
+
   # set output format
   config$bookdown_output_format = format
 
@@ -559,3 +566,68 @@ strip_latex_body = function(x, alt = '\nThe content was intentionally removed.\n
   }
   c(x1, x2[sort(i)], '\\end{document}')
 }
+
+# bookdown Lua filters paths
+lua_filter = function (filters = NULL) {
+  rmarkdown::pkg_file_lua(filters, package = 'bookdown')
+}
+
+# pass _bookdown.yml to Pandoc's Lua filters
+bookdown_yml_arg = function(config = load_config(), path = tempfile()) {
+  # this is supported for Pandoc >= 2.0 only
+  if (!pandoc2.0() || length(config) == 0) return()
+  yaml::write_yaml(list(bookdown = config), path)
+  c("--metadata-file", rmarkdown::pandoc_path_arg(path))
+}
+
+#' Convert the syntax of theorem and proof environments from code blocks to
+#' fenced Divs
+#'
+#' This function converts the syntax \samp{```{theorem, label, ...}} to
+#' \samp{::: {.theorem #label ...}} (Pandoc's fenced Div) for theorem
+#' environments.
+#' @param input Path to an Rmd file that contains theorem environments written
+#'   in the syntax of code blocks.
+#' @param text A character vector of the Rmd source. When \code{text} is
+#'   provided, the \code{input} argument will be ignored.
+#' @param output The output file to write the converted input content. You can
+#'   specify \code{output} to be identical to \code{input}, which means the
+#'   input file will be overwritten. If you want to overwrite the input file,
+#'   you are strongly recommended to put the file under version control or make
+#'   a backup copy in advance.
+#' @references Learn more about
+#'   \href{https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#theorems}{theorems
+#'    and proofs} and
+#'   \href{https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html}{custom
+#'    blocks} in the \pkg{bookdown} book.
+#' @return If \code{output = NULL}, the converted text is returned, otherwise
+#'   the text is written to the output file.
+#' @export
+fence_theorems = function(input, text = xfun::read_utf8(input), output = NULL) {
+  # identify blocks
+  md_pattern = knitr::all_patterns$md
+  block_start = grep(md_pattern$chunk.begin, text)
+  # extract params
+  params = gsub(md_pattern$chunk.begin, "\\1", text[block_start])
+  # find block with custom environment engine
+  reg = sprintf("^(%s).*", paste(all_math_env, collapse = "|"))
+  to_convert = grepl(reg, params)
+  # only modify those blocks
+  params = params[to_convert]
+  block_start = block_start[to_convert]
+  block_end = grep(md_pattern$chunk.end, text)
+  block_end = vapply(block_start, function(x) block_end[block_end > x][1], integer(1))
+  # add a . to engine name
+  params = sprintf(".%s", params)
+  # change label to id
+  params = gsub(",\\s*([-/[:alnum:]]+)(,|\\s*$)", " #\\1", params)
+  params = gsub("label\\s*=\\s*\"([-/[:alnum:]]+)\"", "#\\1", params)
+  # clean , and space
+  params = gsub(",\\s*", " ", params)
+  params = gsub("\\s*=\\s*", "=", params)
+  # modify the blocks
+  text[block_start] = sprintf("::: {%s}", params)
+  text[block_end] = ":::"
+  # return the text or write to output file
+  if (is.null(output)) xfun::raw_string(text) else xfun::write_utf8(text, input)
+}

inst/resources/gitbook/css/plugin-bookdown.css

@@ -90,7 +90,7 @@ div.theorem, div.lemma, div.corollary, div.proposition, div.conjecture {
 span.theorem, span.lemma, span.corollary, span.proposition, span.conjecture {
   font-style: normal;
 }
-div.proof:after {
+div.proof>p:last-child:after {
   content: "\25a2";
   float: right;
 }

inst/rmarkdown/lua/custom-environment.lua

@@ -0,0 +1,188 @@
+--[[
+     A Pandoc 2 lua filter to deal with custom environment in bookdown
+--]]
+
+-- theorem types available to be used
+local theorem_abbr = {
+    theorem = 'thm',
+    lemma = 'lem',
+    corollary = 'cor',
+    proposition = 'prp',
+    conjecture = 'cnj',
+    definition = 'def',
+    example = 'exm',
+    exercise = 'exr'
+}
+
+-- other special proof envs
+local proof_label = {
+    proof = 'Proof',
+    remark = 'Remark',
+    solution = 'Solution'
+}
+
+-- for debuging purpose
+local debug_mode = os.getenv("DEBUG_PANDOC_LUA") == "TRUE"
+local function print_debug(label,obj,iter)
+    obj = obj or nil
+    iter = iter or pairs
+    label = label or ""
+    label = "DEBUG (from custom-environment.lua): "..label
+    if (debug_mode) then
+        if not obj then
+          print(label)
+        elseif (type(obj) == "string") then
+            print(label.." "..obj)
+        elseif type(obj) == "table" then
+            for k,v in iter(obj) do
+                print(label.."id:"..k.. " val:"..v)
+            end
+        end
+    end
+    return nil
+end
+
+-- create a unique id for a div with none provided
+local counter = 0
+local function unlabeled_div()
+    counter = counter + 1 
+    return "unlabeled-div-"..(counter)
+end
+
+-- return [name] for latex, and (name) for html
+local function get_name(format, options)
+    local name = options["name"]
+    if not name then return "" end
+    local template = {latex = "[%s]", html = " (%s)"}
+    name = string.format(template[format],  name)
+    print_debug("name -> ", name)
+    -- remove data-name from option
+    options["name"] = nil
+    return name
+end
+
+-- Get metadata specific to bookdown for this filter
+Meta = function(m) 
+    bookdownmeta = m.bookdown
+    if (bookdownmeta and bookdownmeta.language and bookdownmeta.language.label) then
+        -- For internationalization feature of bookdown
+        for k,v in pairs(bookdownmeta.language.label) do
+            if (type(v) == 'table' and v.t == 'MetaInlines' and proof_label[k] ~= nil) then
+                -- remove any undesired space (3 or less)
+                proof_label[k] = pandoc.utils.stringify(v):gsub("%.?%s?%s?%s?$", "")
+                print_debug("Translation-> "..k..":", proof_label[k])
+            end
+        end
+    end
+end
+
+-- Modify Pandoc AST for supported custom environment
+Div = function (div)
+    local classes = div.classes
+    -- we do nothing if no classes
+    if (#classes == 0) then
+        print_debug("No classes in the Div.")
+        return div
+    end
+    print_debug("Div classes -> " , classes)
+
+    -- checking if the class is one of the supported custom environment
+    local env_type = {type = nil, env = nil}
+    for i,v in ipairs(classes) do
+        if (theorem_abbr[v] ~= nil) then 
+            env_type.type = "theorem"
+            env_type.env = v
+            break
+        elseif (proof_label[v] ~= nil) then 
+            env_type.type = "proof"
+            env_type.env = v
+            break
+        end
+    end
+    -- classes is not a supported one, we return as is
+    if not env_type.env then
+        print_debug("Not a bookdown supported custom class")
+        return div
+    end
+    print_debug("Found types -> ", env_type)
+
+    -- get the id if it exists - it will we use to build label for reference
+    local id = div.identifier
+    -- if no id, one is generated so that bookdown labelling mechanism works
+    if #id == 0 then id = unlabeled_div() end
+    print_debug("id -> ", id)
+    -- remove unwanted identifier on the div, as it will be on the span
+    div.identifier = ""
+
+    -- get the attributes
+    local options = div.attributes
+    if (options["data-latex"] ~= nil) then 
+        -- so that latex-divs.lua in rmarkdown does not activate
+        print("[WARNING] data-latex attribute can't be used with one of bookdown custom environment. It has been removed.")
+        options["data-latex"] = nil
+    end
+
+    -- create the custom environment
+    local label
+    -- Create a label for referencing - only for theorem like env
+    if (env_type.type == "theorem") then
+        label = string.format("%s:%s", theorem_abbr[env_type.env], id)
+    end
+    print_debug("label for reference -> ", label)
+
+    -- TODO: should we support beamer also ?
+    if (FORMAT:match 'latex') then
+        local label_part 
+        if label then
+            label_part = string.format( "\n\\protect\\hypertarget{%s}{}\\label{%s}", label, label)
+        end
+        local name = get_name('latex', options)
+        table.insert(
+            div.content, 1,
+            pandoc.RawBlock('tex', string.format('\\begin{%s}%s%s', env_type.env, name, label_part or ""))
+        )
+        table.insert(
+            div.content,
+            pandoc.RawBlock('tex', string.format('\\end{%s}', env_type.env))
+        )
+    elseif (FORMAT:match 'html') then
+        local name = get_name('html', options)
+
+        -- if div is already processed by eng_theorem, it would also modify it. 
+        -- we can ignore knowing how eng_theorem modifies options$html.before2
+        -- It can be Plain or Para depending if a name was used or not.
+        -- MAYBE NOT VERY RELIABLE THOUGH
+        if (div.content[1].t == "Plain" or div.content[1].t == "Para") then
+            for i,el in pairs(div.content[1].content) do
+                if (el.t == "Span" and el.classes[1] == env_type.env) then
+                    print_debug("Already processed by knitr engine.")
+                    return div
+                end
+            end
+        end
+
+        -- inserted the correct span depending on the environment type
+        local span
+        if (env_type.type == "theorem") then
+            span = pandoc.Span(
+                pandoc.Strong(string.format("(#%s)%s ", label, name)),
+                pandoc.Attr(label, {env_type.env})
+            )
+        elseif (env_type.type == "proof") then
+            span = pandoc.Span({
+                pandoc.Emph(pandoc.Str(proof_label[env_type.env])),
+                pandoc.Str(name),
+                pandoc.Str("."),
+                pandoc.Space()
+            },
+                pandoc.Attr(id, {env_type.env})
+            )
+        end
+        -- add to the first block of the div, and not as first block
+        table.insert(div.content[1].content, 1, span)
+    end
+
+    return div
+end
+
+return {{Meta = Meta}, {Div = Div}}

tests/rmd/_bookdown.yml

@@ -0,0 +1,3 @@
+language:
+  label:
+    solution: 'SOLUTION'