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