From 8d2d9b844406cbefed31835815964c542f7ff1aa Mon Sep 17 00:00:00 2001
From: atusy <30277794+atusy@users.noreply.github.com>
Date: Wed, 6 Sep 2023 01:57:34 +0900
Subject: [PATCH] enrich documentation of output_format_dependency (#2508)

---
 NEWS.md                         |  1 +
 R/output_format.R               | 42 +++++++++++++++++++++++++--------
 man/output_format_dependency.Rd | 40 +++++++++++++++++++++++--------
 3 files changed, 63 insertions(+), 20 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 37c38609ea..9c5006b6cd 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -3,6 +3,7 @@ rmarkdown 2.25
 
 - Fixed a bug that filenames beginning with `-` cause incorrect invocation of Pandoc (thanks, @mbaynton, #2503).
 
+- Documented how to merge `output_format_dependency()` to the output format (thanks, @atusy, #2508)
 
 rmarkdown 2.24
 ================================================================================
diff --git a/R/output_format.R b/R/output_format.R
index 7c42a0164d..13ff61843d 100644
--- a/R/output_format.R
+++ b/R/output_format.R
@@ -832,22 +832,44 @@ citeproc_required <- function(yaml_front_matter,
   )
 }
 
-#' Define an R Markdown's output format dependency
+#' Define and merge an R Markdown's output format dependency
 #'
-#' Define the dependency such as and pre/post-processors dynamically from
-#' within chunks. This function shares some arguments with
-#' \code{\link{output_format}}, but lacks the others because dependency
-#' is resolved after \code{post_knit} and before \code{pre_processor}.
+#' Define and merge a dependency such as pre/post-processors from within
+#' chunks. The merge happens explicitly when a list of dependencies are
+#' passed to \code{knitr::knit_meta_add()} or implicitly when a dependency
+#' is \code{knitr::knit_print}ed. Defining a function that does the former is
+#' the best way for package developers to share the dependency. On the
+#' contrary, the latter is useful to declare a document-specific dependency.
+#' This function shares some arguments with \code{\link{output_format}},
+#' but lacks the others because dependency is resolved after \code{post_knit}
+#' and before \code{pre_processor}.
 #'
 #' @param name A dependency name. If some dependencies share the same name,
-#'   then only the first one will be attached.
+#'   then only the first one will be merged to the output format.
 #' @inheritParams output_format
+#'
 #' @return An list of arguments with the "rmd_dependency" class.
+#'
 #' @examples
-#' # Add lua filters from within a chunk
-#' output_format_dependency("lua_filter", pre_processor = function(...) {
-#'   pandoc_lua_filter_args(c("example1.lua", "example2.lua"))
-#' })
+#' # Implicitly add lua filters from within a chunk
+#' # This relies on (implicit) printing of the dependency in a chunk via
+#' # knitr::knit_print()`
+#' output_format_dependency(
+#'   "lua_filter1",
+#'   pandoc = list(lua_filters = "example1.lua")
+#' )
+#'
+#' # Explicitly add lua filters from within a chunk
+#' knitr::knit_meta_add(list(output_format_dependency(
+#'   "lua_filter2",
+#'   pandoc = list(lua_filters = "example2.lua")
+#' )))
+#'
+#' # List the available dependencies
+#' # Note that the list may include dependencies with duplicated names. In that
+#' # case, the first one is merged to the output format and the others are
+#' # discarded.
+#' str(knitr::knit_meta("output_format_dependency", clean = FALSE))
 #'
 #' @export
 output_format_dependency <- function(name,
diff --git a/man/output_format_dependency.Rd b/man/output_format_dependency.Rd
index 7cd65be3aa..3daa2b3ebb 100644
--- a/man/output_format_dependency.Rd
+++ b/man/output_format_dependency.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/output_format.R
 \name{output_format_dependency}
 \alias{output_format_dependency}
-\title{Define an R Markdown's output format dependency}
+\title{Define and merge an R Markdown's output format dependency}
 \usage{
 output_format_dependency(
   name,
@@ -15,7 +15,7 @@ output_format_dependency(
 }
 \arguments{
 \item{name}{A dependency name. If some dependencies share the same name,
-then only the first one will be attached.}
+then only the first one will be merged to the output format.}
 
 \item{pandoc}{Pandoc options for an output format (see
 \code{\link{pandoc_options}})}
@@ -46,15 +46,35 @@ execution (as registered with a \code{\link{on.exit}} handler).}
 An list of arguments with the "rmd_dependency" class.
 }
 \description{
-Define the dependency such as and pre/post-processors dynamically from
-within chunks. This function shares some arguments with
-\code{\link{output_format}}, but lacks the others because dependency
-is resolved after \code{post_knit} and before \code{pre_processor}.
+Define and merge a dependency such as pre/post-processors from within
+chunks. The merge happens explicitly when a list of dependencies are
+passed to \code{knitr::knit_meta_add()} or implicitly when a dependency
+is \code{knitr::knit_print}ed. Defining a function that does the former is
+the best way for package developers to share the dependency. On the
+contrary, the latter is useful to declare a document-specific dependency.
+This function shares some arguments with \code{\link{output_format}},
+but lacks the others because dependency is resolved after \code{post_knit}
+and before \code{pre_processor}.
 }
 \examples{
-# Add lua filters from within a chunk
-output_format_dependency("lua_filter", pre_processor = function(...) {
-  pandoc_lua_filter_args(c("example1.lua", "example2.lua"))
-})
+# Implicitly add lua filters from within a chunk
+# This relies on (implicit) printing of the dependency in a chunk via
+# knitr::knit_print()`
+output_format_dependency(
+  "lua_filter1",
+  pandoc = list(lua_filters = "example1.lua")
+)
+
+# Explicitly add lua filters from within a chunk
+knitr::knit_meta_add(list(output_format_dependency(
+  "lua_filter2",
+  pandoc = list(lua_filters = "example2.lua")
+)))
+
+# List the available dependencies
+# Note that the list may include dependencies with duplicated names. In that
+# case, the first one is merged to the output format and the others are
+# discarded.
+str(knitr::knit_meta("output_format_dependency", clean = FALSE))
 
 }