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 TexFAQ). 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. If you have any tables in your document which span multiple pages and you want to repeat the header row on each page, you must use the repeat_header argument in csas_table() instead of piping using kable_styling(). If you do not, your page numbering in the citations will be off by one. See Issue #138 for more context. This code shows how it should be done:

csasdown::csas_table(df,
                     caption = "Caption text",
                     format = "latex",
                     landscape = FALSE,
                     font_size = 7,
                     repeat_header = TRUE)

This code shows how it should not be done:

csasdown::csas_table(df,
                     caption = "Caption text",
                     format = "latex",
                     landscape = FALSE,
                     font_size = 7) %>%
kableExtra::kable_styling(latex_options = "repeat_header")

The reason is that you need to have the extra argument repeat_header_method for kable_styling() set to "replace" otherwise it uses its default of "append" which tells LaTeX that the table is on the same page, and throws off the numbering. repeat_header_method = "replace" is coded as the default in csas_table() so you don't have to worry about it if you use the correct code above.

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