Markdown to HTML: Cross-references and captions for tables and figure

bookdowncrossreference.Rmd

---
title: "Markdown to HTML: Cross-references and captions for tables and figure"
output: 
  bookdown::html_document2
---

```{css, echo=FALSE}
blockquote {
  font-size: 16px;
}
```

# The first chapter {#firstchap}

See this [gist](https://gist.github.com/dmenne/ab32c6ef0d8d927927337f80d6904c6e) for a Word version; not all packages work in a portable way.

This is the first chapter with id `{#firstchap}.`

In recent versions of RStudio, there is a button labelled 'A' in the top right corner of the editor window to switch to the Visual Markdown Editor. Use Insert/Cross Reference to insert a cross reference.

## A subchapter {#subchapter}

-   Anchors have curly braces.
-   This is a subchapter with id `{#subchapter}`.
-   You can also link to [arbitrary text]{#atext}. Anchor looks like this: `[arbitrary text]{#atext}`. The hash is required.

## Another one {#another-one}

This chapter **without label** only exists to demonstrate implicit anchors. You should prefer the above explicit ones, these are more robust to changes in the title text. See the [Pandoc documentation](https://pandoc.org/MANUAL.html#extension-auto_identifiers "Rules for automatic identifiers") for rules of automatic identifiers.

```{r, echo = FALSE, warning=FALSE}
library(knitr)
library(pander)
library(DT)
library(kableExtra)
library(ggplot2)

mcaption = function(tag, caption){
  # Do not use underscores in tag!
  stopifnot(length(grep("_", tag)) == 0)
  cat("<caption>(#tab:", tag, ")", caption, "</caption>", sep="")
}
```

### `kable` Table

Too bad, caption is always at the top, but otherwise, `kable` does everything right.

```{r iris}
# Chunk iris, not tab:iris!. Gives Table 1.1
kable(head(iris), caption = "Iris with kable")
```

### `kableExtra` Table

`kableExtra` also plays well with numbering and captions.

```{r irisextra}
kable(head(iris), caption = "Iris with kableExtra") %>% 
   kable_styling()
```

### `pander` Table

Pander has a somewhat unusual way to set the caption globally and does not support table numbering. It can be used with my function mcaption to produce table numbers.

This once was a great package, but is seems to be abandoned now, last commit was on May 27, 2020, and issues abound.

```{r panderiris, results='asis', echo = FALSE}
# Must use echo = FALSE (or globally). 
#set.caption("This is a pander caption") # No numbering
mcaption("pandertable", "This is a pander caption") # Creates numbers
pander(head(iris))
```

### `DT` Table

Super for large tables when used with the search and export feature. It's the great brother by the same father as `kable`, but for reasons unknown needs hand-knitted intervention for autonumbering and caption.

```{r datatableiris, results='asis', echo=FALSE}
mcaption("dtiris", "This is a DT")
DT::datatable(head(iris), caption = "Iris with pander")
```

### `flextable`

[Great documentation](https://ardata-fr.github.io/flextable-book/), works in HTML, Word, PowerPoint and PDF.

```{r}
use_flex = TRUE # set to FALSE to test huxtable
```

```{r flexiris, echo=FALSE, eval = use_flex}
suppressPackageStartupMessages(library(flextable))
ft =  flextable( head( iris ) )
#ft = set_caption(ft, "Iris with flextable")
ft
```

Captions are documented [here](https://davidgohel.github.io/flextable/reference/set_caption.html). You can also set the caption in the chunk label:

```{r flexiriscap, tab.cap="Iris with flextable, caption in chunk label", echo=FALSE, eval = use_flex, label="flexiriscap"}
flextable( head( iris ) )
```

### `huxtable`

From the documentation: 

> Within knitr, huxtable labels will default to the same as the knitr chunk label. To turn off this behaviour, set options(huxtable.autolabel = FALSE).
> If you use bookdown, and set a label on your table, the table caption() will automatically be prefixed with `(#label)`. You can then refer to the table using `\@ref(label)` (The backslash is not required, only for knitting, DM). `label` needs to start with `"tab:"`; if it doesn't, the `"tab:"` prefix will be added automatically. To turn off this behaviour, set `options(huxtable.bookdown = FALSE)`.


```{r huxiris, echo=FALSE}
suppressPackageStartupMessages(library(huxtable))
hx =  hux( head( iris ) ) 
hx = add_colnames(hx)
hx = huxtable::set_caption(hx, "Iris with huxtable")
# The old and still working way: setting it explicit 
#hx = huxtable::set_label(hx, "tab:huxirisexplicit")
hx

```

### `gt`

Despite abounding bells and whistles and earrings, [rstudio/gt](https://github.com/rstudio/gt/issues/635) has caption and label in limbo only since it's existence. See [this issue](https://github.com/rstudio/gt/issues/635). Please drop me a note if something has changed.

### `rtables`

`rtables` has Roche as sponsor and so we can expect good code quality. As far I understand, the `rtables` is focused on ASCII output that is directly consumable, to create tables looking like the SPSS beloved since 50 years when I did my Diplom. Markdown is not on the list. The documentation is extensive, so I might have got something wrong; drop me a note when you know better, I would love to correct it here. 


### A figure

```{r irisf, fig.height=2.4, fig.width= 2.5, fig.cap="Figures work nicely", echo = FALSE}
ggplot(iris, aes(x=Sepal.Length, y=Sepal.Width) ) + geom_point()
```

```{=tex}
\begin{equation}
\bar{X} = \frac{\sum_{i=1}^n X_i}{n} (\#eq:mean)
\end{equation}
```
## References to tables, figures and equations

Currently, referencing tables and autonumbering only works for `kable`, not for pander or DT. Recent versions of `flextable` and partially `huxtable` can mimic the behavior of `kable` with a more verbose syntax.

-   Explicit reference to chapter: Check also Chapter \@ref(firstchap)...
-   Explicit reference to chapter with optional category: Check also Chapter \@ref(subchapter).
-   Implicit reference: As Chapter \@ref(another-one) shows...
-   Table: `kable` table \@ref(tab:iris) is best seen here. The `tab:` is implicit, the chunk must not have the `tab:` prefix.
-   Reference to a `kableExtra`table: As the extra Table \@ref(tab:irisextra) shows ....
-   Reference to `flextable`: Please look at flextable \@ref(tab:flexiris).
-   Reference to `huxtable`: Please look at huxtable \@ref(tab:huxiris); in more recent version, this refers to the chunk label.
-   Fig. \@ref(fig:irisf) shows that everything works nicely with figures. Great work by Yihui.
-   Equation: Also see Equation \@ref(eq:mean).

## Links to tables and figures

-   [An internal link](#atext) to arbitrary text. `[An internal link](#atext)`. The hash is required.
-   [An internal link](#subchapter) to a subchapter.
-   [An implicit internal link](#another-one) to a chapter heading.
-   [Link to figure](#fig:irisf), a link to a figure `[Link to figure](#fig:irisf)`, the hash is required.
-   [Link to flextable](#tab:flexiriscap)
-   [Link to huxtable](#tab:huxiris); 

For `pander` a link to the chunk label fails `\@ref(panderiris)`, but you can use the `mcaption` tag using the function defined in this document. Do not forget to put `results='asis'` into the chunk header.

-   You should check Table \@ref(tab:pandertable).... Don't use underscores in tag!
-   [Link to table](#tab:pandertable). Must use hash here, because it is part of the `mcaption` function.