# Using texPreview Built-in Knitr Engine

`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 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.

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

## Default

### Chunk Call

### Output

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

## No Echo

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

### Chunk Call

### Output

## Raw TeX Table

### Chunk Call

    ```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

    \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 Path

### Chunk Call

### Output

    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.

    ```texpreview
    knitr::kable(head(iris),format = 'latex',booktabs = TRUE)
    ```
    \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.

    ```texpreview
    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}
    }