Cross references in R Vignettes

[ralmond]

I would like to use the bookdown @ref(fig:example) style cross references in a R vignette. But I'm not sure how to set this up. I'm guessing, I need to add bookdown to the suggests in my package, and then add something to the YAML. I currently have:

---
title: "Dongle: A lightweight interface between EI, EA and AS processes and
      the Presentation Process"
author: Russell G. Almond
output: rmarkdown::html_vignette
bibliography: Proc4.bib
link-citations: TRUE
vignette: >
  %\VignetteIndexEntry{Proc4 Dongle}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

How do I need to tweak this to add the cross-referencing ability? I still want the html_vignette output format, but I want to add the cross references?

[cderv]

The way to use one of the bookdown format feature with another is described in

3.4 A single document | bookdown: Authoring Books and Technical Documents with...

it is using base_format.

For html_vignette that would be

output: 
  bookdown::html_document2:
      base_format: rmarkdown::html_vignette

Hopefully, the vignette will stay light and suitable for inclusing in a package. You would for sure need to add bookdown as a dependency of your package same way you did with rmarkdown for the vignette format.

It is still in our project to externalize the reference feature out of bookdown to be used more easily in other format, and especially in a more lightweight way

[ralmond]

Thanks for the tip above, that answers the question of what to put in the YAML header, but knitting the document is not producing what I expect.

I have in my document:

```{r P4Lamp, fig.cap="Proc4 Dongle Architecture", out.height="25%", echo=FALSE}
knitr::include_graphics("Proc4-Lamp.png")
```

This generates the figure with the caption, but it is unnumbered. Also \@ref(fig:P4Lamp) does not resolve to a number.

Also, I'm trying to include and number listings:

I include the following:

::: {.example #P4 "Sample Message in P4 format"}
```{json, fig.cap="(ex:P4) Sample message in P4 format", eval=FALSE}
{
    app: "ecd://epls.coe.fsu.edu/PP",
    uid: "Student 1",
    context: "SpiderWeb",
    sender: "Evidence Identification",
    mess: "Task Observables",
    timestamp: "2018-10-22 18:30:43 EDT",
    processed: false,
    data:{
        trophy: "gold",
        solved: true,
        objects: 10,
        agents: ["ramp","ramp","springboard"],
        solutionTime: {time:62.25, units:"secs"}
    }
}
```
:::
```
But this does not add a caption, and `\@ref(exm:P4)` is not resolved.

So I think I'm missing a switch to turn on the cross reference engine.

[cderv]

@ralmond

Thanks for the tip above, that answers the question of what to put in the YAML header, but knitting the document is not producing what I expect.

This is working for me with a simple example

---
title: "Untitled"
output: 
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
date: '2022-06-05'
---

```{r pressure, fig.cap = "pressure pot", echo = FALSE}
plot(pressure, pch = 19, type = "b")
```


```{r test, fig.cap="test plot", out.height="25%", echo=FALSE}
knitr::include_graphics(knitr::fig_chunk("pressure", "png"))
```


See first plot in \@ref(fig:pressure) and second plot \@ref(fig:test)

@ralmond

````{json, fig.cap="(ex:P4) Sample message in P4 format", eval=FALSE}`

fig.cap only works on figures in R, and it won't work on custom code chunk - json engine does not exists either. There will be no caption.

However, you can indeed do

---
title: "Untitled"
output: 
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
---

::: {.example #P4}
Sample message in P4 format
```json
{
    app: "ecd://epls.coe.fsu.edu/PP",
    uid: "Student 1",
    context: "SpiderWeb",
    sender: "Evidence Identification",
    mess: "Task Observables",
    timestamp: "2018-10-22 18:30:43 EDT",
    processed: false,
    data:{
        trophy: "gold",
        solved: true,
        objects: 10,
        agents: ["ramp","ramp","springboard"],
        solutionTime: {time:62.25, units:"secs"}
    }
}
```
:::

See Example \@ref(exm:P4) above

[ralmond]

I'm obviously missing something, as I'm not getting the cross references, and its not adding the title to the example.

Maybe I'm not invoking knitr correctly.

I'm invoking knitr through the "Knit" menu on RStudio. I've also checked that bookdown is at the latest version.

[cderv]

@ralmond

I'm obviously missing something, as I'm not getting the cross references, and its not adding the title to the example.

So you don't manage to make the example above I shared to work ?

FWIW my versions

sessioninfo::package_info("bookdown")
#>  package   * version date (UTC) lib source
#>  base64enc   0.1-3   2015-07-28 [1] CRAN (R 4.2.0)
#>  bookdown    0.26    2022-04-15 [1] CRAN (R 4.2.0)
#>  bslib       0.3.1   2021-10-06 [1] CRAN (R 4.2.0)
#>  digest      0.6.29  2021-12-01 [1] CRAN (R 4.2.0)
#>  evaluate    0.15    2022-02-18 [1] RSPM (R 4.2.0)
#>  fastmap     1.1.0   2021-01-25 [1] CRAN (R 4.2.0)
#>  fs          1.5.2   2021-12-08 [1] CRAN (R 4.2.0)
#>  glue        1.6.2   2022-02-24 [1] CRAN (R 4.2.0)
#>  highr       0.9     2021-04-16 [1] CRAN (R 4.2.0)
#>  htmltools   0.5.2   2021-08-25 [1] CRAN (R 4.2.0)
#>  jquerylib   0.1.4   2021-04-26 [1] CRAN (R 4.2.0)
#>  jsonlite    1.8.0   2022-02-22 [1] CRAN (R 4.2.0)
#>  knitr       1.39    2022-04-26 [1] CRAN (R 4.2.0)
#>  magrittr    2.0.3   2022-03-30 [1] CRAN (R 4.2.0)
#>  R6          2.5.1   2021-08-19 [1] CRAN (R 4.2.0)
#>  rappdirs    0.3.3   2021-01-31 [1] CRAN (R 4.2.0)
#>  rlang       1.0.2   2022-03-04 [1] CRAN (R 4.2.0)
#>  rmarkdown   2.14    2022-04-25 [1] RSPM (R 4.2.0)
#>  sass        0.4.1   2022-03-23 [1] CRAN (R 4.2.0)
#>  stringi     1.7.6   2021-11-29 [1] CRAN (R 4.2.0)
#>  stringr     1.4.0   2019-02-10 [1] CRAN (R 4.2.0)
#>  tinytex     0.39    2022-05-16 [1] CRAN (R 4.2.0)
#>  xfun        0.31    2022-05-10 [1] CRAN (R 4.2.0)
#>  yaml        2.3.5   2022-02-21 [1] CRAN (R 4.2.0)
#> 
#>  [1] C:/Users/chris/AppData/Local/R/win-library/4.2
#>  [2] C:/Program Files/R/R-4.2.0/library

[ralmond]

I figured out what I was missing. I had an incorrect YAML header

I should have had

___
output: 
    bookdown::html_document2:
        base_format: rmarkdown::html_vignette
___

but I was missing the base_format.
It now works.