Home

FAQ

1. How do I make my table and figure captions in french automatically?

See the Wiki page dedicated to English/French document building: Producing-English-and-French-versions-of-the-same-document

2. How do I include a citation or figure reference or r object value in a figure or table caption?

    ```{r chunk1}
    x <- 7
    ```

    (ref:my-caption) A figure caption. See Appendix \@ref(app:my-appendix)). x has 
    the value `r x`. See @viridis2018.

    ```{r my-figure, fig.cap="(ref:my-caption)"}
    plot(1)
    ```

3. How do I include extra packages for latex-rendered documents?

In the index.Rmd file, add the following to the YAML part (the section between the --- and ---) for whatever package you want to include. For this example it is the threeparttablex package:

header-includes:
  - \usepackage{threeparttablex}

Note that if you need to include more than one package you will have to have them on the same line like this:

header-includes:
  - \usepackage{threeparttablex} \usepackage{caption}

This will NOT work, only the first one is added:

header-includes:
  - \usepackage{threeparttablex}
  - \usepackage{caption}

4. I have added appendices after the bibliography, but they are appearing in the document before the bibliography. How do > I make the bibliography appear before the appendices?

Add the following line where you want the bibliography to be placed:

<div id="refs"></div>

5. When I click on links in the PDF (e.g. figures or citations) they don't take me to the appropriate figure or reference. How do I fix that?

Try running tinytex::tlmgr_install("hyperref").

6. When I render the document using bookdown::render_book("index.Rmd") and I have a browser() call, the code stops at the browser but when I type in the name of a variable to see what it's value is it shows nothing for it. Why?

You need to type in sink() first.

7. I have a script to make all my figures and no time to break the code into individual chunks. Can I just run my script and then add the finished figures into the document?

Yes. Use this code to do so. You would have created all your figures in a directory called figures located in your project's root directory.

knitr::include_graphics(here::here("figures/figure_name.png"))

8. I tried to make a heading at 5 levels deep (or more) and it isn't working right. Why can't I go deeper than 4 levels of headings?

This is a limitation of LaTeX. They have stated that this was done to avoid production of documents that are too complex (See [https://texfaq.org/FAQ-subsubsub]). There are non-standard ways to allow for more heading depths but we have decided not to pursue those in favour of keeping more maintainable LaTeX style-file code in the csasdown repository.

Notes

1. To see the variables declared in _bookdown.yml, you can do the following from any R chunk within the project:

config <- bookdown:::load_config()

2. To access the YAML metadata located at the beginning of index.Rmd, you can look at the following list from any R chunk within the project:

rmarkdown::metadata

For example if creating a CSAS SR document in French, the following YAML metadata will be in index.Rmd:

output:
 csasdown::sr_pdf:
   french: true

In the setup R chunk, the following lines of code set the language for R:

french <- rmarkdown::metadata$output$`csasdown::sr_pdf`$french
if(french){
  options(OutDec =  ",")
}

3. Knitr chunk names can only have numbers, letters, and dashes. Underscores are not permitted and will cause major problems in rendering with bookdown. Here is an example of a bad chunk:

```{r bad_chunkname, results = "asis"}
    d <- data.frame(x = c(1,2,3,4),
                    y = c(5,6,7,8),
                    z = c(9,10,11,12))
    csasdown::csas_table(d,
                         format = "latex",
                         font_size = 8,
                         caption = "XX - This table is broken")
```

The error for this was:

! Misplaced \noalign.
\toprule ->\noalign 
                    {\ifnum 0=`}\fi \@aboverulesep =\abovetopsep \global \@b...
l.125 ...able is broken\}\textbackslash{} \toprule
                                                   x \& y \& z\textbackslash...

Error: Failed to compile resdoc.tex. See https://yihui.name/tinytex/r/#debugging for debugging tips. See resdoc.log for more info.
Execution halted

And the resulting TeX file had broken code for the table with many \textbackslash{} commands peppered through it:

\textbackslash{}begin\{longtable\}\{rrr\} \textbackslash{}caption\{(\#tab:broken\_table)XX - This table is broken\}\textbackslash{} \toprule x \& y \& z\textbackslash{} \midrule 1 \& 5 \& 9\textbackslash{} 2 \& 6 \& 10\textbackslash{} 3 \& 7 \& 11\textbackslash{} 4 \& 8 \& 12\textbackslash{} \bottomrule \textbackslash{}end\{longtable\}

4. Do not include spaces or ~ in any folders in the path to your document. LaTeX doesn't play nicely with them.

5. In order for proper formatting of headers according to CSAS layout requirements, the headers must be typed in the appropriate case in .Rmd files. For example:

Heading 1-beginning of a section or chapter; all caps. Prints as e.g. 1. INTRODUCTION

# THIS IS A MAIN HEADER 

Heading 2-subsection; all caps. Prints as e.g. 1.1 FIRST SUBSECTION

## THIS IS A SUBSECTION

Heading 3; sentence case. Prints as e.g. 1.2.1 This is the next layer

### This is the next layer

Heading 4-sentence case. Prints as e.g. 1.2.4.1 Yet another

#### Yet another

6. This is a great resource for inserting newlines in kable tables:(http://haozhu233.github.io/kableExtra/best_practice_for_newline_in_latex_table.pdf)