1#' Convert to an MS Word document
2#'
3#' Format for converting from R Markdown to an MS Word document.
4#'
5#' See the \href{https://bookdown.org/yihui/rmarkdown/word-document.html}{online
6#' documentation} for additional details on using the \code{word_document} format.
7#'
8#' R Markdown documents can have optional metadata that is used to generate a
9#' document header that includes the title, author, and date. For more details
10#' see the documentation on R Markdown \link[=rmd_metadata]{metadata}.
11#'
12#' R Markdown documents also support citations. You can find more information on
13#' the markdown syntax for citations in the
14#' \href{https://pandoc.org/MANUAL.html#citations}{Bibliographies
15#' and Citations} article in the online documentation.
16#' @inheritParams pdf_document
17#' @inheritParams html_document
18#' @param reference_docx Use the specified file as a style reference in
19#'   producing a docx file. For best results, the reference docx should be a
20#'   modified version of a docx file produced using pandoc. Pass "default"
21#'   to use the rmarkdown default styles.
22#' @return R Markdown output format to pass to \code{\link{render}}
23#' @examples
24#' \dontrun{
25#' library(rmarkdown)
26#'
27#' # simple invocation
28#' render("input.Rmd", word_document())
29#'
30#' # specify an option for syntax highlighting
31#' render("input.Rmd", word_document(highlight = "zenburn"))
32#' }
33#' @export
34word_document <- function(toc = FALSE,
35                          toc_depth = 3,
36                          number_sections = FALSE,
37                          fig_width = 5,
38                          fig_height = 4,
39                          fig_caption = TRUE,
40                          df_print = "default",
41                          highlight = "default",
42                          reference_docx = "default",
43                          keep_md = FALSE,
44                          md_extensions = NULL,
45                          pandoc_args = NULL) {
46
47  # knitr options and hooks
48  knitr <- knitr_options(
49    opts_chunk = list(dev = 'png',
50                      dpi = 96,
51                      fig.width = fig_width,
52                      fig.height = fig_height)
53  )
54
55  # base pandoc options for all docx output
56  args <- c()
57
58  # table of contents
59  args <- c(args, pandoc_toc_args(toc, toc_depth))
60
61  # Lua filters (added if pandoc > 2)
62  lua_filters <- pkg_file_lua("pagebreak.lua")
63
64  # numbered sections
65  if (number_sections) {
66    if (pandoc_available("2.10.1")) {
67      args <- c(args, "--number-sections")
68    } else {
69      lua_filters <- c(lua_filters, pkg_file_lua("number-sections.lua"))
70    }
71  }
72
73  # highlighting
74  if (!is.null(highlight))
75    highlight <- match.arg(highlight, highlighters())
76  args <- c(args, pandoc_highlight_args(highlight))
77
78  # reference docx
79  args <- c(args, reference_doc_args("docx", reference_docx))
80
81  # pandoc args
82  args <- c(args, pandoc_args)
83
84  saved_files_dir <- NULL
85  pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
86    saved_files_dir <<- files_dir
87    NULL
88  }
89
90  intermediates_generator <- function(...) {
91    reference_intermediates_generator(saved_files_dir, ..., reference_docx)
92  }
93
94  # return output format
95  output_format(
96    knitr = knitr,
97    pandoc = pandoc_options(to = "docx",
98                            from = from_rmarkdown(fig_caption, md_extensions),
99                            args = args,
100                            lua_filters = lua_filters),
101    keep_md = keep_md,
102    df_print = df_print,
103    pre_processor = pre_processor,
104    intermediates_generator = intermediates_generator
105  )
106}
107
108reference_doc_args <- function(type, doc) {
109  if (is.null(doc) || identical(doc, "default")) return()
110  c(paste0("--reference-", if (pandoc2.0()) "doc" else {
111    match.arg(type, c("docx", "odt", "doc"))
112  }), pandoc_path_arg(doc))
113}
114
115