properly document the output_yaml option

03-documents.Rmd

@@ -438,30 +438,40 @@ output:
 
 Documentation on all available pandoc arguments can be found in the [Pandoc User Guide](http://pandoc.org/MANUAL.html#options).
 
-### Shared options {#shared-options}
+### Shared output options {#shared-options}
 
-If you want to specify a set of default options to be shared by multiple documents within a directory, you can include a file named `_output.yml` within the directory. Note that no YAML delimiters (`---`) or the enclosing `output` field are used in this file. For example:
+You can outsource part or all of the _output_ options to a separate YAML file. This is very convenient to specify a set of default options for multiple documents and thus avoid redundancies (think of it as an "output option template"). The path to this file can be set by the option `output_yaml`. For example:
 
 ```yaml
-html_document:
-  self_contained: false
-  theme: united
-  highlight: textmate
+output_yaml: config/my_custom_opts.yml
 ```
 
-It should not be written as:
+Note that
 
-```yaml
----
-output:
+- options explicitly defined within a document will always override those specified in the separate `output_yaml` file.
+
+- if the `output_yaml` option is not explicitly set in a document, it will default to the file `_output.yml` within the same directory and -- if it exists -- automatically inherit its content.
+
+- in the `output_yaml` file no YAML delimiters (`---`) or the enclosing `output` field are used. A correct example of the file's content could look like:
+
+  ```yaml
   html_document:
     self_contained: false
     theme: united
     highlight: textmate
----
-```
+  ```
+
+  But _not_:
 
-All documents located in the same directory as `_output.yml` will inherit its options. Options defined explicitly within documents will override those specified in the shared options file.
+  ```yaml
+  ---
+  output:
+    html_document:
+      self_contained: false
+      theme: united
+      highlight: textmate
+  ---
+  ```
 
 ### HTML fragments
 
@@ -962,7 +972,7 @@ Consult the documentation on [Pandoc templates](https://pandoc.org/README.html#t
 
 ### Other features
 
-Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section \@ref(markdown-extensions) for details. You can also pass more custom Pandoc arguments through the `pandoc_args` option (Section \@ref(pandoc-arguments)), and define shared options in `_output.yml` (Section \@ref(shared-options)).
+Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section \@ref(markdown-extensions) for details. You can also pass more custom Pandoc arguments through the `pandoc_args` option (Section \@ref(pandoc-arguments)), and define shared output options in a separate YAML file (Section \@ref(shared-options)).
 
 ## Word document
 
@@ -992,7 +1002,7 @@ For more on how to create and use a reference document, you may watch this short
 
 ### Other features
 
-Refer to Section \@ref(html-document) for the documentation of most features of Word documents, including figure options (Section \@ref(figure-options)), data frame printing (Section \@ref(data-frame-printing)), syntax highlighting (Section \@ref(appearance-and-style)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)).
+Refer to Section \@ref(html-document) for the documentation of most features of Word documents, including figure options (Section \@ref(figure-options)), data frame printing (Section \@ref(data-frame-printing)), syntax highlighting (Section \@ref(appearance-and-style)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)).
 
 ## OpenDocument Text document
 
@@ -1020,7 +1030,7 @@ output:
 
 ### Other features
 
-Refer to Section \@ref(html-document) for the documentation of most features of ODT documents, including figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), header and before/after body inclusions (Section \@ref(includes)), custom templates (Section \@ref(custom-templates)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)).
+Refer to Section \@ref(html-document) for the documentation of most features of ODT documents, including figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), header and before/after body inclusions (Section \@ref(includes)), custom templates (Section \@ref(custom-templates)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)).
 
 ## Rich Text Format document
 
@@ -1045,7 +1055,7 @@ knitr::raw_output(readLines('table.rtf'))
 
 ### Other features
 
-Refer to Section \@ref(html-document) for the documentation of most features of RTF documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)).
+Refer to Section \@ref(html-document) for the documentation of most features of RTF documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), keeping Markdown (Section \@ref(keeping-markdown)), Markdown extensions (Section \@ref(markdown-extensions)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)).
 
 ## Markdown document
 
@@ -1111,7 +1121,7 @@ In many cases, you can simply copy and paste the Markdown generated by `rmarkdow
 
 ### Other features
 
-Refer to Section \@ref(html-document) for the documentation of other features of Markdown documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), header and before/after body inclusions (Section \@ref(includes)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared options (Section \@ref(shared-options)).
+Refer to Section \@ref(html-document) for the documentation of other features of Markdown documents, including table of contents (Section \@ref(table-of-contents)), figure options (Section \@ref(figure-options)), header and before/after body inclusions (Section \@ref(includes)), Pandoc arguments (Section \@ref(pandoc-arguments)), and shared output options (Section \@ref(shared-options)).
 
 ## R package vignette