engine.Rmd

---
title: "Using texPreview Built-in Knitr Engine"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using texPreview Built-in Knitr Engine}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---




`texPreview` contains inside its own `knitr` engine to render TeX snippets more naturally within the RMarkdown workflow. We achieve this by leveraging texPreview's integration via S3 for various classes. 

The following inputs can be run inside texpreview chunks in RStudio version [1.2.5033](https://posit.co/download/rstudio-desktop/) and above. They will render in the same fashion as would a regular `texPreview::tex_preview` call. 

   - Raw TeX
   - TeX in a character vector
   - knitr_kable (kable/kableExtra)
   - xtable
   - texreg
   - equatiomatic
   
Arguments that were used in the `texPreview::tex_preview` function are now set in the chunk options. To make them unique to this engine we prefix them with `texpreview`, below is a table with the chunk options and their tex_preview analogue.

|tex_preview argument|chunk option|default value|
|:--|:--|:--|
|returnType|texpreview.return|'engine'|
|fileDir|texpreview.path|tex_opts$get('fileDir')|
|stem|texpreview.stem|'tex_temp'|

The user still has the option to use `texPreview::tex_opts` to control chunk outputs as they are passed into the call internally. The chunk options will override any settings that are in `texPreview::tex_opts`.

Rendering the chunk interactively will have different side effects depending on the `texpreview.return` setting. These settings have the same side effects as the returnType settings with one addition 'engine' which mimics returnType='viewer'. It should be the preferred settings when working with RMarkdown documents that return HTML outputs.

The following are examples of some uses of the `texpreview` engine.


```r
library(texPreview)
dir.create('images/engine',showWarnings = FALSE)
```


## Default

### Chunk Call

````markdown
```{texpreview, echo = FALSE}
knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
```
````

### Output


```texpreview
knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
```


<img src="images/engine/unnamed-chunk-2-1.png" width="1011" />

## No Echo

The texpreview engine respects regular 'r' engine chunk options such as 'echo':

### Chunk Call

````markdown
```{texpreview, echo = FALSE}
knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
```
````

### Output

<img src="images/engine/unnamed-chunk-3-3.png" width="1011" />

## Raw TeX Table

### Chunk Call

````markdown
```{texpreview}
\begin{tabular}{llr}
\hline
\multicolumn{2}{c}{Item} \\
\cline{1-2}
Animal    & Description & Price (\$) \\
\hline
Gnat      & per gram    & 13.65      \\
          & each        & 0.01       \\
Gnu       & stuffed     & 92.50      \\
Emu       & stuffed     & 33.33      \\
Armadillo & frozen      & 8.99       \\
\hline
\end{tabular}
```
````

### Output


```texpreview
\begin{tabular}{llr}
\hline
\multicolumn{2}{c}{Item} \\
\cline{1-2}
Animal    & Description & Price (\$) \\
\hline
Gnat      & per gram    & 13.65      \\
          & each        & 0.01       \\
Gnu       & stuffed     & 92.50      \\
Emu       & stuffed     & 33.33      \\
Armadillo & frozen      & 8.99       \\
\hline
\end{tabular}
```


<img src="images/engine/unnamed-chunk-4-5.png" width="1011" />

## Output Path

### Chunk Call

````markdown
```{texpreview, echo = FALSE, texpreview.path = 'images/engine',texpreview.stem = 'example'}
knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
```
````

### Output

<img src="images/engine/unnamed-chunk-5-7.png" width="1011" />


```r
list.files('images/engine')
#> [1] "example.png"           "example.tex"           "unnamed-chunk-2-1.png"
#> [4] "unnamed-chunk-3-3.png" "unnamed-chunk-4-5.png" "unnamed-chunk-5-7.png"
```

## PDF Documents

Setting texpreview.return = 'input' will have the chunk return an LateX 'input' call with the results 'asis' so the user can render the lines as part of a Rmarkdown pdf document.

````markdown
```{texpreview,texpreview.return = 'input', texpreview.path = 'images/engine',texpreview.stem = 'example'}
knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
```
\input{images/engine/example.tex}
````

\input{images/engine/example.tex}

Setting texpreview.return = 'tex' will have the chunk return the tex lines output with the results 'asis' so the user can render the lines as part of a Rmarkdown pdf document.

````markdown
```{texpreview,texpreview.return = 'tex'}
knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
```

\resizebox{\textwidth}{!}{
\begin{tabular}{rrrrl}
\toprule
Sepal.Length & Sepal.Width & Petal.Length & Petal.Width & Species\\
\midrule
5.1 & 3.5 & 1.4 & 0.2 & setosa\\
4.9 & 3.0 & 1.4 & 0.2 & setosa\\
4.7 & 3.2 & 1.3 & 0.2 & setosa\\
4.6 & 3.1 & 1.5 & 0.2 & setosa\\
5.0 & 3.6 & 1.4 & 0.2 & setosa\\
\addlinespace
5.4 & 3.9 & 1.7 & 0.4 & setosa\\
\bottomrule
\end{tabular}
}
````


\resizebox{\textwidth}{!}{
\begin{tabular}{rrrrl}
\toprule
Sepal.Length & Sepal.Width & Petal.Length & Petal.Width & Species\\
\midrule
5.1 & 3.5 & 1.4 & 0.2 & setosa\\
4.9 & 3.0 & 1.4 & 0.2 & setosa\\
4.7 & 3.2 & 1.3 & 0.2 & setosa\\
4.6 & 3.1 & 1.5 & 0.2 & setosa\\
5.0 & 3.6 & 1.4 & 0.2 & setosa\\
\addlinespace
5.4 & 3.9 & 1.7 & 0.4 & setosa\\
\bottomrule
\end{tabular}
}