knitr (version 1.29)

hook_pdfcrop: 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_mogrify(before, options, envir)
hook_plot_custom(before, options, envir)
hook_purl(before, options, envir)

Arguments

before, options, envir

See References below.

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 graphics::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 magick package is used to crop the plot.

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

The function hook_mogrify() calls the program mogrify. Note the chunk option mogrify can be used to provide additional parameters to the program mogrify (with default -trim to trim PNG files).

When the plots are not recordable via grDevices::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.org/knitr/demo/cache/ for the meaning of cache = 2).

References

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

See Also

rgl::rgl.snapshot, rgl::rgl.postscript, rgl::hook_rgl, rgl::hook_webgl

Examples

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