From 1e21739e450e185d453b36eac11bc5aab45d3c04 Mon Sep 17 00:00:00 2001
From: wfulp <wfulp@fredhutch.org>
Date: Wed, 7 Aug 2019 16:11:58 -0700
Subject: [PATCH] Adding Vignette for using the PDF and Word output template

---
 .Rbuildignore                             |  2 +
 .gitignore                                |  2 +
 DESCRIPTION                               |  3 ++
 vignettes/.gitignore                      |  2 +
 vignettes/using_pdf_and_word_template.Rmd | 64 +++++++++++++++++++++++
 5 files changed, 73 insertions(+)
 create mode 100644 vignettes/.gitignore
 create mode 100644 vignettes/using_pdf_and_word_template.Rmd

diff --git a/.Rbuildignore b/.Rbuildignore
index 539a3b5..504cee1 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -2,3 +2,5 @@
 ^LICENSE\.md$
 ^VISCtemplates\.Rproj$
 ^\.Rproj\.user$
+^doc$
+^Meta$
diff --git a/.gitignore b/.gitignore
index d387fe3..05a368a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
 .Rhistory
 .RData
 .Rproj.user
+doc
+Meta
diff --git a/DESCRIPTION b/DESCRIPTION
index 9bbf4dc..923a674 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -23,3 +23,6 @@ LazyData: true
 URL: https://github.com/FredHutch/VISCtemplates
 BugReports: https://github.com/FredHutch/VISCtemplates/issues
 RoxygenNote: 6.1.1
+Suggests: 
+    knitr
+VignetteBuilder: knitr
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
new file mode 100644
index 0000000..097b241
--- /dev/null
+++ b/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/vignettes/using_pdf_and_word_template.Rmd b/vignettes/using_pdf_and_word_template.Rmd
new file mode 100644
index 0000000..bdcbad9
--- /dev/null
+++ b/vignettes/using_pdf_and_word_template.Rmd
@@ -0,0 +1,64 @@
+---
+title: "Using the PDF and Word Output Template"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Using the PDF and Word Output Template}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+The VISC report Rmarkdown template knits to either a PDF or Word document. 
+
+* To create a new report, create a new Rmarkdown from the "VISC Report (PDF & Word Output)" template.
+* Use the Knit button select either the PDF (visc_report) or Word (word_document2) output.
+* Note the shortcut Ctrl-Shift-K will run the first output in the YAML, will be the last output run (starts off as PDF first)
+* If you want to run both reports in one command, either use `rmarkdown::render()` with `output_format = 'all'`, or install the loom package and create a RStudio Addin (<https://github.com/thebioengineer/loom>).
+
+
+There are some new functions and coding conventions that help with knitting the report to both outputs.
+
+## Page breaks
+
+* For page breaks use the `visc_clearpage()` function. You can use this as a simple inline code: `` `r knitr::inline_expr("visc_clearpage()")` ``.
+    + `\clearpage` (from previous template) will not work on Word output.
+    
+## Referencing
+`
+**Figure and table references**
+
+* For figure and table references use `visc_ref()` function.
+    + For example: `` `r knitr::inline_expr("visc_ref('fig:response-rate-plot')")` ``.
+* Make sure chunk names only use dashes or referring will not work (no spaces or underscores).
+* Do not use figure or table labels in chunk headings or kable code (e.g., don't use `fig.cap = "My Figure Caption \\label{my_figure_label}"`. Rmarkdown will automatically assign the chunk name as the figure/table reference label.
+
+**Sections** 
+
+* For referencing sections, use `[Section header text]` in the text.
+    + `[Background]` gives: [Background].
+    + `[Biological endpoints]` gives: [Biological endpoints].
+
+**References/Bibliography**
+
+*  For referencing papers, simply use the @ symbol before bib file reference (i.e. `@Huang:2013fl`).
+
+
+## Tables
+
+* Only output one table per code chunk.
+* Make sure to have `format = output_type` in the `kableExtra::kable()` call 
+    + `output_type` is either "latex" or "pandoc" depending on current report output.
+* The table name will be chunk name plus "tab:".
+    + For example, if chunk name is "descriptive-stats" then the table label will be "tab:descriptive-stats"
+* Note that Word output cannot support many kableExtra features, such as `kableExtra::kable_styling()`.
+   + Set `warning=kable_warnings` chunk option, otherwise Word output will have unwanted warnings.
+
+## Figures
+
+* Only output one figure per code chunk.
+* Figure name will be chunk name plus "fig:".
+    + i.e. if chunk name is "-stats" then the table label will be "fig:descriptive-stats".
+    
+## P values
+
+* When using `VISCfunctions::pretty_pvalues()` make sure to use `output_type = output_type`,  `bold  = pandoc_markup`, and ,  `italic = pandoc_markup`. This will give the appropriate markup depending on PDF or Word output.
+