R: Built-in chunk hooks to extend knitr

hook_pdfcrop {knitr} | R Documentation

## Built-in chunk hooks to extend knitr

### Description

Hook functions are called when the corresponding chunk options are not `NULL` to do additional jobs beside the R code in chunks. This package provides a few useful hooks, which can also serve as examples of how to define chunk hooks in knitr.

### Usage

    hook_pdfcrop(before, options, envir)

    hook_optipng(before, options, envir)

    hook_pngquant(before, options, envir)

    hook_plot_custom(before, options, envir)

    hook_purl(before, options, envir)

### Arguments

`before, options, envir` | see references

### Details

The function `hook_pdfcrop()` can use the program `pdfcrop` to crop the extra white margin when the plot format is PDF to make better use of the space in the output document, otherwise we often have to struggle with `par` to set appropriate margins. Note `pdfcrop` often comes with a LaTeX distribution such as MiKTeX or TeXLive, and you may not need to install it separately (use `Sys.which('pdfcrop')` to check it; if it not empty, you are able to use it). Similarly, when the plot format is not PDF (e.g. PNG), the program `convert` in ImageMagick is used to trim the white margins (call `convert input -trim output`).

The function `hook_optipng()` calls the program `optipng` to optimize PNG images. Note the chunk option `optipng` can be used to provide additional parameters to the program `optipng`, e.g. `optipng = '-o7'`.

The function `hook_pngquant()` calls the program `pngquant` to optimize PNG images. Note the chunk option `pngquant` can be used to provide additional parameters to the program `pngquant`, e.g. `pngquant = '--speed=1 --quality=0-50'`.

When the plots are not recordable via `recordPlot` and we save the plots to files manually via other functions (e.g. rgl plots), we can use the chunk hook `hook_plot_custom` to help write code for graphics output into the output document.

The hook `hook_purl()` can be used to write the code chunks to an R script. It is an alternative approach to `purl`, and can be more reliable when the code chunks depend on the execution of them (e.g. `read_chunk()`, or `opts_chunk$set(eval = FALSE)`). To enable this hook, it is recommended to associate it with the chunk option `purl`, i.e. `knit_hooks$set(purl = hook_purl)`. When this hook is enabled, an R script will be written while the input document is being `knit`. Currently the code chunks that are not R code or have the chunk option `purl=FALSE` are ignored. Please note when the cache is turned on (the chunk option `cache = TRUE`), no chunk hooks will be executed, hence `hook_purl()` will not work, either. To solve this problem, we need `cache = 2` instead of `TRUE` (see https://yihui.name/knitr/demo/cache/ for the meaning of `cache = 2`).

### Note

The two hook functions `hook_rgl()` and `hook_webgl()` were moved from knitr to the rgl package (>= v0.95.1247) after knitr v1.10.5, and you can `library(rgl)` to get them.

### References

https://yihui.name/knitr/hooks/#chunk_hooks

### See Also

`rgl.snapshot`, `rgl.postscript`, `hook_rgl`, `hook_webgl`

### Examples

    if (require("rgl") && exists("hook_rgl")) knit_hooks$set(rgl = hook_rgl)
    # then in code chunks, use the option rgl=TRUE

[Package knitr version 1.16 Index]