From 0043c54fb34c8d529e0e6304a1a9cc1e80a23010 Mon Sep 17 00:00:00 2001
From: Johannes Ranke <jranke@uni-bremen.de>
Date: Sun, 26 Feb 2023 11:39:17 +0100
Subject: Improve documentation of the format

---
 R/hierarchical_kinetics.R    | 21 +++++++++++++++++++--
 man/hierarchical_kinetics.Rd | 20 +++++++++++++++++++-
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/R/hierarchical_kinetics.R b/R/hierarchical_kinetics.R
index e545754a..ae60d43c 100644
--- a/R/hierarchical_kinetics.R
+++ b/R/hierarchical_kinetics.R
@@ -1,7 +1,24 @@
 #' Hierarchical kinetics template
 #'
 #' R markdown format for setting up hierarchical kinetics based on a template
-#' provided with the mkin package.
+#' provided with the mkin package. This format is based on [rmarkdown::pdf_document].
+#' Chunk options are adapted. Echoing R code from code chunks and caching are
+#' turned on per default. character for prepending output from code chunks is
+#' set to the empty string, code tidying is off, figure alignment defaults to
+#' centering, and positioning of figures is set to "H", which means that
+#' figures will not move around in the document, but stay where the user
+#' includes them.
+#'
+#' The latter feature (positioning the figures with "H") depends on the LaTeX
+#' package 'float'. In addition, the LaTeX package 'listing' is used in the
+#' template for showing model fit summaries in the Appendix. This means that
+#' the LaTeX packages 'float' and 'listing' need to be installed in the TeX
+#' distribution used.
+#'
+#' On Windows, the easiest way to achieve this (if no TeX distribution
+#' is present before) is to install the 'tinytex' R package, to run
+#' 'tinytex::install_tinytex()' to get the basic tiny Tex distribution,
+#' and then to run 'tinytex::tlmgr_install(c("float", "listing"))'.
 #'
 #' @inheritParams rmarkdown::pdf_document
 #' @param ... Arguments to \code{rmarkdown::pdf_document}
@@ -24,7 +41,7 @@ hierarchical_kinetics <- function(..., keep_tex = FALSE) {
 
   if (!requireNamespace("knitr")) stop("Please install the knitr package to use this template")
   if (!requireNamespace("rmarkdown")) stop("Please install the rmarkdown package to use this template")
-  knitr::opts_chunk$set(echo = FALSE, cache = TRUE, comment = "", tidy = FALSE, echo = TRUE)
+  knitr::opts_chunk$set(cache = TRUE, comment = "", tidy = FALSE, echo = TRUE)
   knitr::opts_chunk$set(fig.align = "center", fig.pos = "H")
   options(knitr.kable.NA = "")
 
diff --git a/man/hierarchical_kinetics.Rd b/man/hierarchical_kinetics.Rd
index 2a8e211c..f965df1a 100644
--- a/man/hierarchical_kinetics.Rd
+++ b/man/hierarchical_kinetics.Rd
@@ -17,7 +17,25 @@ R Markdown output format to pass to
 }
 \description{
 R markdown format for setting up hierarchical kinetics based on a template
-provided with the mkin package.
+provided with the mkin package. This format is based on \link[rmarkdown:pdf_document]{rmarkdown::pdf_document}.
+Chunk options are adapted. Echoing R code from code chunks and caching are
+turned on per default. character for prepending output from code chunks is
+set to the empty string, code tidying is off, figure alignment defaults to
+centering, and positioning of figures is set to "H", which means that
+figures will not move around in the document, but stay where the user
+includes them.
+}
+\details{
+The latter feature (positioning the figures with "H") depends on the LaTeX
+package 'float'. In addition, the LaTeX package 'listing' is used in the
+template for showing model fit summaries in the Appendix. This means that
+the LaTeX packages 'float' and 'listing' need to be installed in the TeX
+distribution used.
+
+On Windows, the easiest way to achieve this (if no TeX distribution
+is present before) is to install the 'tinytex' R package, to run
+'tinytex::install_tinytex()' to get the basic tiny Tex distribution,
+and then to run 'tinytex::tlmgr_install(c("float", "listing"))'.
 }
 \examples{
 
-- 
cgit v1.2.1