export and document pandoc_to() and pandoc_from()

NAMESPACE

@@ -103,6 +103,8 @@ export(opts_hooks)
 export(opts_knit)
 export(opts_template)
 export(pandoc)
+export(pandoc_from)
+export(pandoc_to)
 export(pat_asciidoc)
 export(pat_brew)
 export(pat_html)

NEWS.md

@@ -2,6 +2,8 @@
 
 ## NEW FEATURES
 
+- Exported the functions `pandoc_to()` and `pandoc_from()` to get the output and input Pandoc format respectively when knitting R Markdown documents (thanks, @cderv, #1951).
+
 - Added a new chunk option `fig.alt` for users to specify the alternative text in the `alt` attribute of the `<img>` tag  (images). Previously, the `alt` attribute takes value from the chunk option `fig.cap` (it still does so if `fig.alt` is `NULL`). If there are multiple plots/images in a chunk, you can pass a character vector to `fig.alt`, and it will be applied to individual images (thanks, @cderv, #1900).
 
 - `include_url()` and `include_app()` can now take a vector of URLs (thanks, @cderv, #1948).

R/utils.R

@@ -306,34 +306,54 @@ fix_options = function(options) {
   options
 }
 
-#' Check if the current output type is LaTeX or HTML
+#' Check the current input and output type
 #'
 #' The function \code{is_latex_output()} returns \code{TRUE} when the output
 #' format is LaTeX; it works for both \file{.Rnw} and R Markdown documents (for
 #' the latter, the two Pandoc formats \code{latex} and \code{beamer} are
 #' considered LaTeX output). The function \code{is_html_output()} only works for
-#' R Markdown documents.
+#' R Markdown documents and will test for several Pandoc HTML based output
+#' formats (by default, these formats are considered as HTML formats:
+#' \code{c('markdown', 'epub', 'html', 'html4', 'html5', 'revealjs', 's5',
+#' 'slideous', 'slidy', 'gfm')}).
+#'
+#' The function \code{pandoc_to()} returns the Pandoc output format, and
+#' \code{pandoc_from()} returns Pandoc input format. \code{pandoc_to(fmt)}
+#' allows to check the current output format against a set of format names. Both
+#' are to be used with R Markdown documents.
 #'
 #' These functions may be useful for conditional output that depends on the
 #' output format. For example, you may write out a LaTeX table in an R Markdown
 #' document when the output format is LaTeX, and an HTML or Markdown table when
-#' the output format is HTML.
+#' the output format is HTML. Use \code{pandoc_to(fmt)} to test a more specific
+#' Pandoc format.
 #'
 #' Internally, the Pandoc output format of the current R Markdown document is
-#' stored in \code{knitr::\link{opts_knit}$get('rmarkdown.pandoc.to')}. By
-#' default, these formats are considered as HTML formats: \code{c('markdown',
-#' 'epub', 'html', 'html5', 'revealjs', 's5', 'slideous', 'slidy')}.
+#' stored in \code{knitr::\link{opts_knit}$get('rmarkdown.pandoc.to')}, and the
+#' Pandoc input format in
+#' \code{knitr::\link{opts_knit}$get('rmarkdown.pandoc.from')}
+#'
+#' @note See available Pandoc formats, in
+#'   \href{https://pandoc.org/MANUAL.html}{Pandoc's Manual}
 #' @rdname output_type
 #' @export
-#' @examples knitr::is_latex_output()
+#' @examples
+#' # check for output formats type
+#' knitr::is_latex_output()
 #' knitr::is_html_output()
 #' knitr::is_html_output(excludes = c('markdown', 'epub'))
+#' # Get current formats
+#' knitr::pandoc_from()
+#' knitr::pandoc_to()
+#' # Test if current output format is 'docx'
+#' knitr::pandoc_to('docx')
 is_latex_output = function() {
   out_format('latex') || pandoc_to(c('latex', 'beamer'))
 }
 
-#' @param fmt A character vector of output formats to be checked. By default, this
-#'   is the current Pandoc output format.
+#' @param fmt A character vector of output formats to be checked against. If not
+#'   provided, \code{is_html_output()} uses \code{pandoc_to()}, and
+#'   \code{pandoc_to()} returns the output format name.
 #' @param excludes A character vector of output formats that should not be
 #'   considered as HTML format.
 #' @rdname output_type
@@ -346,6 +366,20 @@ is_html_output = function(fmt = pandoc_to(), excludes = NULL) {
   fmt %in% setdiff(fmts, excludes)
 }
 
+#' @rdname output_type
+#' @export
+pandoc_to = function(fmt) {
+  # rmarkdown sets an option for the Pandoc output format from markdown
+  to = opts_knit$get('rmarkdown.pandoc.to')
+  if (missing(fmt)) to else !is.null(to) && (to %in% fmt)
+}
+
+#' @rdname output_type
+#' @export
+pandoc_from = function() {
+  # rmarkdown's input format, obtained from a package option set by rmarkdown
+  opts_knit$get('rmarkdown.pandoc.from') %n% 'markdown'
+}
 
 # turn percent width/height to LaTeX unit, e.g. out.width = 30% -> .3\linewidth
 latex_percent_size = function(x, which = c('width', 'height')) {
@@ -390,17 +424,6 @@ out_format = function(x) {
 # tempfile under the current working directory
 wd_tempfile = function(...) basename(tempfile(tmpdir = '.', ...))
 
-# rmarkdown sets an option for the Pandoc output format from markdown
-pandoc_to = function(x) {
-  fmt = opts_knit$get('rmarkdown.pandoc.to')
-  if (missing(x)) fmt else !is.null(fmt) && (fmt %in% x)
-}
-
-# rmarkdown's input format
-pandoc_from = function() {
-  opts_knit$get('rmarkdown.pandoc.from') %n% 'markdown'
-}
-
 pandoc_fragment = function(text, to = pandoc_to(), from = pandoc_from()) {
   if (length(text) == 0) return(text)
   f1 = wd_tempfile('pandoc', '.md'); f2 = wd_tempfile('pandoc')