From 716cdd71ef6aa273fd3c142a7a43ac4d398a9d97 Mon Sep 17 00:00:00 2001 From: Yihui Xie Date: Thu, 27 Aug 2026 14:10:06 -0400 Subject: [PATCH] feat: improve sentence style and convert roxygen docs to markdown Improve the roxygen documentation in two ways: 1. Sentence style (#1481): standardize @param descriptions to proper sentences (capitalized, ending with a period), convert "Boolean;/Logical:" prefixes to "Whether to ...", and fix serial commas in "e.g.". 2. Markdown conversion: enable Roxygen markdown support and convert LaTeX-style markup to markdown using the roxygen2md package: - \code{x} -> `x` - \emph{x} -> *x* - \url{x} -> - \href{u}{t} -> [t](u) - \code{\link{fn}} -> [fn()] - \code{pkg::\link{fn}} -> [pkg::fn()] Mixed link+method constructs (e.g. opts_chunk$set(), iconv(x, ...)) are kept as \code{\link{}} since markdown has no clean nested form. Object links (knit_patterns, all_patterns) use [obj] without parens. Special-cased to avoid breakage: - Inline `r ...` expressions in fig_chunk/inline_expr docs are kept literal so they are not evaluated. - Code blocks in convert_chunk_header docs use 4-backtick fences so the inner triple backticks survive markdown processing. All .Rd files regenerated and verified to parse cleanly. Closes #1481 Co-Authored-By: Claude Sonnet 4.5 --- DESCRIPTION | 1 + R/block.R | 8 +- R/cache.R | 62 ++++++------- R/citation.R | 4 +- R/defaults.R | 38 ++++---- R/engine.R | 62 ++++++------- R/header.R | 20 ++-- R/hooks-extra.R | 62 ++++++------- R/hooks-html.R | 18 ++-- R/hooks-latex.R | 88 +++++++++--------- R/hooks-md.R | 18 ++-- R/hooks.R | 16 ++-- R/output.R | 180 ++++++++++++++++++------------------ R/package.R | 16 ++-- R/pandoc.R | 34 +++---- R/params.R | 46 ++++----- R/parser.R | 160 ++++++++++++++++---------------- R/pattern.R | 14 +-- R/plot.R | 54 +++++------ R/rocco.R | 6 +- R/spin.R | 60 ++++++------ R/table.R | 78 ++++++++-------- R/template.R | 26 +++--- R/themes.R | 12 +-- R/utils-conversion.R | 109 +++++++++++----------- R/utils-rd2html.R | 12 +-- R/utils-sweave.R | 60 ++++++------ R/utils-upload.R | 6 +- R/utils-vignettes.R | 18 ++-- R/utils.R | 142 ++++++++++++++-------------- man/Sweave2knitr.Rd | 27 +++--- man/all_labels.Rd | 6 +- man/asis_output.Rd | 8 +- man/cache_engines.Rd | 2 +- man/chunk_hook.Rd | 23 ++--- man/clean_cache.Rd | 16 ++-- man/combine_words.Rd | 2 +- man/convert_chunk_header.Rd | 35 +++---- man/current_input.Rd | 8 +- man/dep_auto.Rd | 12 +-- man/dep_prev.Rd | 4 +- man/download_image.Rd | 6 +- man/engine_output.Rd | 4 +- man/fig_chunk.Rd | 12 +-- man/fig_path.Rd | 8 +- man/hook_animation.Rd | 2 +- man/hook_document.Rd | 8 +- man/hook_plot.Rd | 14 +-- man/image_uri.Rd | 2 +- man/imgur_upload.Rd | 2 +- man/include_graphics.Rd | 18 ++-- man/include_url.Rd | 6 +- man/inline_expr.Rd | 13 ++- man/is_low_change.Rd | 2 +- man/kable.Rd | 34 +++---- man/knit.Rd | 109 +++++++++++----------- man/knit2html.Rd | 30 +++--- man/knit2pandoc.Rd | 14 +-- man/knit2pdf.Rd | 16 ++-- man/knit2wp.Rd | 24 ++--- man/knit_child.Rd | 16 ++-- man/knit_code.Rd | 8 +- man/knit_engines.Rd | 12 +-- man/knit_exit.Rd | 10 +- man/knit_expand.Rd | 4 +- man/knit_filter.Rd | 4 +- man/knit_global.Rd | 2 +- man/knit_meta.Rd | 2 +- man/knit_params.Rd | 30 +++--- man/knit_params_yaml.Rd | 12 +-- man/knit_patterns.Rd | 6 +- man/knit_print.Rd | 14 +-- man/knit_rd.Rd | 15 ++- man/knit_theme.Rd | 8 +- man/knit_watch.Rd | 4 +- man/knitr-package.Rd | 12 +-- man/load_cache.Rd | 20 ++-- man/opts_chunk.Rd | 8 +- man/opts_knit.Rd | 6 +- man/output_hooks.Rd | 28 +++--- man/output_type.Rd | 9 +- man/pandoc.Rd | 20 ++-- man/partition_chunk.Rd | 2 +- man/pat_fun.Rd | 2 +- man/plot_crop.Rd | 8 +- man/raw_block.Rd | 2 +- man/raw_output.Rd | 10 +- man/read_chunk.Rd | 24 ++--- man/rnw2pdf.Rd | 26 +++--- man/rocco.Rd | 4 +- man/rst2pdf.Rd | 6 +- man/set_header.Rd | 8 +- man/set_parent.Rd | 10 +- man/sew.Rd | 2 +- man/spin.Rd | 48 +++++----- man/spin_child.Rd | 10 +- man/stitch.Rd | 16 ++-- man/vignette_engines.Rd | 22 ++--- man/wrap_rmd.Rd | 6 +- man/write_bib.Rd | 2 +- 100 files changed, 1174 insertions(+), 1181 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 979e7d8325..b0eb990387 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -203,3 +203,4 @@ Collate: 'utils-vignettes.R' 'zzz.R' Config/roxygen2/version: 8.1.0 +Roxygen: list(markdown = TRUE) diff --git a/R/block.R b/R/block.R index 123a3322f1..7550aee4bb 100644 --- a/R/block.R +++ b/R/block.R @@ -180,17 +180,17 @@ block_exec = function(options) { #' Engine for R #' #' This function handles the execution of R code blocks (when the chunk option -#' \code{engine} is \code{'R'}) and generates the R output for each code block. +#' `engine` is `'R'`) and generates the R output for each code block. #' -#' This engine function has one argument \code{options}: the source code of the -#' current chunk is in \code{options$code}. It returns a processed output that +#' This engine function has one argument `options`: the source code of the +#' current chunk is in `options$code`. It returns a processed output that #' can consist of data frames (as tables), graphs, or character output. This #' function is intended for advanced use to allow developers to extend R, and #' customize the pipeline with which R code is executed and processed within #' knitr. #' #' @param options A list of chunk options. Usually this is just the object -#' \code{options} associated with the current code chunk. +#' `options` associated with the current code chunk. #' @noRd eng_r = function(options) { # eval chunks (in an empty envir if cache) diff --git a/R/cache.R b/R/cache.R index 20b1f22b7f..609012ecf4 100644 --- a/R/cache.R +++ b/R/cache.R @@ -127,25 +127,25 @@ cache_rx = '_[abcdef0123456789]{32}[.](rdb|rdx|RData)$' #' Build automatic dependencies among chunks #' -#' When the chunk option \code{autodep = TRUE}, all names of objects created in +#' When the chunk option `autodep = TRUE`, all names of objects created in #' a chunk will be saved in a file named \file{__objects} and all global objects #' used in a chunk will be saved to \file{__globals}. This function can analyze #' object names in these files to automatically build cache dependencies, which -#' is similar to the effect of the \code{dependson} option. It is supposed to be +#' is similar to the effect of the `dependson` option. It is supposed to be #' used in the first chunk of a document and this chunk must not be cached. #' @param path Path to the dependency file. #' @param labels A vector of labels of chunks for which the dependencies will be #' built. By default, dependencies for all chunks will be built. -#' @return \code{NULL}. The dependencies are built as a side effect. -#' @note Be cautious about \code{path}: because this function is used in a +#' @return `NULL`. The dependencies are built as a side effect. +#' @note Be cautious about `path`: because this function is used in a #' chunk, the working directory when the chunk is evaluated is the directory -#' of the input document in \code{\link{knit}}, and if that directory differs -#' from the working directory before calling \code{knit()}, you need to adjust -#' the \code{path} argument here to make sure this function can find the cache +#' of the input document in [knit()], and if that directory differs +#' from the working directory before calling `knit()`, you need to adjust +#' the `path` argument here to make sure this function can find the cache #' files \file{__objects} and \file{__globals}. #' @export -#' @seealso \code{\link{dep_prev}} -#' @references \url{https://yihui.org/knitr/demo/cache/} +#' @seealso [dep_prev()] +#' @references dep_auto = function(path = opts_chunk$get('cache.path'), labels = all_labels()) { # this function should be evaluated in the original working directory owd = setwd(opts_knit$get('output.dir')); on.exit(setwd(owd)) @@ -179,7 +179,7 @@ parse_objects = function(path) { #' Load the cache database of a code chunk #' -#' If a code chunk has turned on the chunk option \code{cache = TRUE}, a cache +#' If a code chunk has turned on the chunk option `cache = TRUE`, a cache #' database will be established after the document is compiled. You can use this #' function to manually load the database anywhere in the document (even before #' the code chunk). This makes it possible to use objects created later in the @@ -189,28 +189,28 @@ parse_objects = function(path) { #' they are created. #' @param label The chunk label of the code chunk that has a cache database. #' @param object The name of the object to be fetched from the database. If it -#' is missing, \code{NULL} is returned). -#' @param notfound A value to use when the \code{object} cannot be found. +#' is missing, `NULL` is returned). +#' @param notfound A value to use when the `object` cannot be found. #' @param path Path of the cache database (normally set in the global chunk -#' option \code{cache.path}). +#' option `cache.path`). #' @param dir Path to use as the working directory. Defaults to the output #' directory if run inside a \pkg{knitr} context and to the current working -#' directory otherwise. Any relative \code{path} is defined from \code{dir}. +#' directory otherwise. Any relative `path` is defined from `dir`. #' @param envir Environment to use for cache loading, into which all objects in -#' the cache for the specified chunk (not just that in \code{object}) will be -#' loaded. Defaults to the value in \code{\link{knit_global}}. -#' @param lazy Whether to \code{\link{lazyLoad}} the cache database (depending -#' on the chunk option \code{cache.lazy = TRUE} or \code{FALSE} of that code +#' the cache for the specified chunk (not just that in `object`) will be +#' loaded. Defaults to the value in [knit_global()]. +#' @param lazy Whether to [lazyLoad()] the cache database (depending +#' on the chunk option `cache.lazy = TRUE` or `FALSE` of that code #' chunk). #' @note Apparently this function loads the value of the object from the -#' \emph{previous} run of the document, which may be problematic when the +#' *previous* run of the document, which may be problematic when the #' value of the object becomes different the next time the document is #' compiled. Normally you must compile the document twice to make sure the #' cache database is created, and the object can be read from it. Please use #' this function with caution. #' @references See the example #114 at -#' \url{https://github.com/yihui/knitr-examples}. -#' @return Invisible \code{NULL} when \code{object} is not specified (the cache +#' . +#' @return Invisible `NULL` when `object` is not specified (the cache #' database will be loaded as a side effect), otherwise the value of the #' object if found. #' @export @@ -250,11 +250,11 @@ load_cache = function( #' This function can be used to build dependencies among chunks so that all #' later chunks depend on previous chunks, i.e. whenever the cache of a previous #' chunk is updated, the cache of all its later chunks will be updated. -#' @return \code{NULL}; the internal dependency structure is updated as a side +#' @return `NULL`; the internal dependency structure is updated as a side #' effect. #' @export -#' @seealso \code{\link{dep_auto}} -#' @references \url{https://yihui.org/knitr/demo/cache/} +#' @seealso [dep_auto()] +#' @references dep_prev = function() { labs = names(knit_code$get()) if ((n <- length(labs)) < 2L) return() # one chunk or less; no sense of deps @@ -266,15 +266,15 @@ dep_prev = function() { #' An unevaluated expression to return .Random.seed if exists #' -#' This expression returns \code{.Random.seed} when \code{eval(rand_seed)} and -#' \code{NULL} otherwise. +#' This expression returns `.Random.seed` when `eval(rand_seed)` and +#' `NULL` otherwise. #' -#' It is designed to work with \code{opts_chunk$set(cache.extra = rand_seed)} +#' It is designed to work with `opts_chunk$set(cache.extra = rand_seed)` #' for reproducibility of chunks that involve with random number generation. See #' references. #' @export #' @format NULL -#' @references \url{https://yihui.org/knitr/demo/cache/} +#' @references #' @examples eval(rand_seed) #' rnorm(1) # .Random.seed is created (or modified) #' eval(rand_seed) @@ -288,12 +288,12 @@ rand_seed = quote({ #' will not be automatically cleaned. You can use this function to identify #' these possible files, and clean them if you are sure they are no longer #' needed. -#' @param clean Boolean; whether to remove the files. +#' @param clean Whether to remove the files. #' @param path Path to the cache. #' @note The identification is not guaranteed to be correct, especially when #' multiple documents share the same cache directory. You are recommended to -#' call \code{clean_cache(FALSE)} and carefully check the list of files (if -#' any) before you really delete them (\code{clean_cache(TRUE)}). +#' call `clean_cache(FALSE)` and carefully check the list of files (if +#' any) before you really delete them (`clean_cache(TRUE)`). #' #' This function must be called within a code chunk in a source document, #' since it needs to know all chunk labels of the current document to diff --git a/R/citation.R b/R/citation.R index a19a1fd129..fa93d383d8 100644 --- a/R/citation.R +++ b/R/citation.R @@ -1,7 +1,7 @@ #' Generate BibTeX bibliography databases for R packages #' -#' A wrapper function of \code{xfun::pkg_bib()}. -#' @param ...,prefix Arguments passed to \code{xfun::\link[xfun]{pkg_bib}()}. +#' A wrapper function of `xfun::pkg_bib()`. +#' @param ...,prefix Arguments passed to [xfun::pkg_bib()]. #' @export write_bib = function(..., prefix = getOption('knitr.bib.prefix', 'R-')) { xfun::pkg_bib(..., prefix = prefix) diff --git a/R/defaults.R b/R/defaults.R index b4b15a2973..f88a379d22 100644 --- a/R/defaults.R +++ b/R/defaults.R @@ -57,26 +57,26 @@ new_defaults = function(value = list()) { #' Default and current chunk options #' -#' Options for R code chunks. When running R code, the object \code{opts_chunk} +#' Options for R code chunks. When running R code, the object `opts_chunk` #' (default options) is not modified by chunk headers (local chunk options are -#' merged with default options), whereas \code{opts_current} (current options) +#' merged with default options), whereas `opts_current` (current options) #' changes with different chunk headers and it always reflects the options for #' the current chunk. #' #' Normally we set up the global options once in the first code chunk in a -#' document using \code{opts_chunk$set()}, so that all \emph{latter} chunks will +#' document using `opts_chunk$set()`, so that all *latter* chunks will #' use these options. Note the global options set in one chunk will not affect #' the options in this chunk itself, and that is why we often need to set global #' options in a separate chunk. #' -#' See \code{str(knitr::opts_chunk$get())} for a list of default chunk options. -#' @references Usage: \url{https://yihui.org/knitr/objects/} +#' See `str(knitr::opts_chunk$get())` for a list of default chunk options. +#' @references Usage: #' #' A list of available options: -#' \url{https://yihui.org/knitr/options/#chunk-options} -#' @note \code{opts_current} should be treated as read-only and you are supposed -#' to only query its values via \code{opts_current$get()}. Calling -#' \code{opts_current$set()} will throw an error. +#' +#' @note `opts_current` should be treated as read-only and you are supposed +#' to only query its values via `opts_current$get()`. Calling +#' `opts_current$set()` will throw an error. #' @export #' @examples opts_chunk$get('prompt'); opts_chunk$get('fig.keep') opts_chunk = new_defaults(list( @@ -164,7 +164,7 @@ opts_chunk_attr = local({ #' aliases and the elements in this vector are the real option names. #' @param ... Named arguments. Argument names are aliases, and argument values #' are real option names. -#' @return \code{NULL}. \code{opts_knit$get('aliases')} is modified as the side effect. +#' @return `NULL`. `opts_knit$get('aliases')` is modified as the side effect. #' @export #' @examples set_alias(w = 'fig.width', h = 'fig.height') #' # then we can use options w and h in chunk headers instead of fig.width and fig.height @@ -177,19 +177,19 @@ set_alias = function(...) { #' Options including whether to use a progress bar when knitting a document, and #' the base directory of images, etc. #' -#' Besides the standard usage (\code{opts_knit$set()}), we can also set package -#' options prior to loading \code{knitr} or calling \code{knit()} using -#' \code{\link{options}()} in base R. A global option \code{knitr.package.foo} -#' in \code{options()} will be set as an option \code{foo} in \code{opts_knit}, -#' i.e. global options in base R with the prefix \code{knitr.package.} -#' correspond to options in \code{opts_knit}. This can be useful to set package +#' Besides the standard usage (`opts_knit$set()`), we can also set package +#' options prior to loading `knitr` or calling `knit()` using +#' [options()] in base R. A global option `knitr.package.foo` +#' in `options()` will be set as an option `foo` in `opts_knit`, +#' i.e. global options in base R with the prefix `knitr.package.` +#' correspond to options in `opts_knit`. This can be useful to set package #' options in \file{~/.Rprofile} without loading \pkg{knitr}. #' -#' See \code{str(knitr::opts_knit$get())} for a list of default package options. -#' @references Usage: \url{https://yihui.org/knitr/objects/} +#' See `str(knitr::opts_knit$get())` for a list of default package options. +#' @references Usage: #' #' A list of available options: -#' \url{https://yihui.org/knitr/options/#package-options} +#' #' @export #' @examples opts_knit$get('verbose'); opts_knit$set(verbose = TRUE) # change it #' if (interactive()) { diff --git a/R/engine.R b/R/engine.R index 9f23e0a2fa..c65b98ecdd 100644 --- a/R/engine.R +++ b/R/engine.R @@ -1,32 +1,32 @@ #' Engines of other languages #' #' This object controls how to execute the code from languages other than R -#' (when the chunk option \code{engine} is not \code{'R'}). Each component in +#' (when the chunk option `engine` is not `'R'`). Each component in #' this object is a function that takes a list of current chunk options #' (including the source code) and returns a character string to be written into #' the output. #' -#' The engine function has one argument \code{options}: the source code of the -#' current chunk is in \code{options$code}. Usually we can call external -#' programs to run the code via \code{\link{system2}}. Other chunk options are -#' also contained in this argument, e.g. \code{options$echo} and -#' \code{options$eval}, etc. +#' The engine function has one argument `options`: the source code of the +#' current chunk is in `options$code`. Usually we can call external +#' programs to run the code via [system2()]. Other chunk options are +#' also contained in this argument, e.g. `options$echo` and +#' `options$eval`, etc. #' -#' In most cases, \code{options$engine} can be directly used in command line to -#' execute the code, e.g. \code{python} or \code{ruby}, but sometimes we may +#' In most cases, `options$engine` can be directly used in command line to +#' execute the code, e.g. `python` or `ruby`, but sometimes we may #' want to specify the path of the engine program, in which case we can pass it -#' through the \code{engine.path} option. For example, \code{engine='ruby', -#' engine.path='/usr/bin/ruby1.9.1'}. Additional command line arguments can be -#' passed through \code{options$engine.opts}, e.g. \code{engine='ruby', -#' engine.opts='-v'}. +#' through the `engine.path` option. For example, `engine='ruby', +#' engine.path='/usr/bin/ruby1.9.1'`. Additional command line arguments can be +#' passed through `options$engine.opts`, e.g. `engine='ruby', +#' engine.opts='-v'`. #' -#' See \code{str(knitr::knit_engines$get())} for a list of built-in language +#' See `str(knitr::knit_engines$get())` for a list of built-in language #' engines. #' @export -#' @note The Leiningen engine \code{lein} requires lein-exec plugin; see -#' \url{https://github.com/yihui/knitr/issues/1176} for details. -#' @references Usage: \url{https://yihui.org/knitr/objects/}; examples: -#' \url{https://yihui.org/knitr/demo/engines/} +#' @note The Leiningen engine `lein` requires lein-exec plugin; see +#' for details. +#' @references Usage: ; examples: +#' #' @examples knit_engines$get('python'); knit_engines$get('awk') #' names(knit_engines$get()) knit_engines = new_defaults() @@ -35,18 +35,18 @@ knit_engines = new_defaults() #' Cache engines of other languages #' #' This object controls how to load cached environments from languages other -#' than R (when the chunk option \code{engine} is not \code{'R'}). Each +#' than R (when the chunk option `engine` is not `'R'`). Each #' component in this object is a function that takes the current path to the #' chunk cache and loads it into the language environment. #' -#' The cache engine function has one argument \code{options}, a list containing -#' all chunk options. Note that \code{options$hash} is the path to the current +#' The cache engine function has one argument `options`, a list containing +#' all chunk options. Note that `options$hash` is the path to the current #' chunk cache with the chunk's hash, but without any file extension, and the #' language engine may write a cache database to this path (with an extension). #' #' The cache engine function should load the cache environment and should know #' the extension appropriate for the language. -#' @references See \url{https://github.com/rstudio/reticulate/pull/167} for an +#' @references See for an #' implementation of a cache engine for Python. #' @export cache_engines = new_defaults() @@ -57,17 +57,17 @@ cache_engines = new_defaults() #' to format and return the text output from your engine. #' #' For expert users, an advanced usage of this function is -#' \code{engine_output(options, out = LIST)} where \code{LIST} is a list that -#' has the same structure as the output of \code{evaluate::evaluate()}. In this -#' case, the arguments \code{code} and \code{extra} are ignored, and the list is -#' passed to \code{knitr::sew()} to return a character vector of final output. +#' `engine_output(options, out = LIST)` where `LIST` is a list that +#' has the same structure as the output of `evaluate::evaluate()`. In this +#' case, the arguments `code` and `extra` are ignored, and the list is +#' passed to `knitr::sew()` to return a character vector of final output. #' @param options A list of chunk options. Usually this is just the object -#' \code{options} passed to the engine function; see -#' \code{\link{knit_engines}}. -#' @param code Source code of the chunk, to which the output hook \code{source} -#' is applied, unless the chunk option \code{echo} is \code{FALSE}. -#' @param out Text output from the engine, to which the hook \code{output} is -#' applied, unless the chunk option \code{results} is \code{'hide'} +#' `options` passed to the engine function; see +#' [knit_engines()]. +#' @param code Source code of the chunk, to which the output hook `source` +#' is applied, unless the chunk option `echo` is `FALSE`. +#' @param out Text output from the engine, to which the hook `output` is +#' applied, unless the chunk option `results` is `'hide'` #' @param extra Any additional text output that you want to include. #' @return A character string generated from the source code and output using #' the appropriate output hooks. diff --git a/R/header.R b/R/header.R index df7b4193a4..ce27c35958 100644 --- a/R/header.R +++ b/R/header.R @@ -96,30 +96,30 @@ insert_header_html = function(doc, b) { #' Set the header information #' #' Some output documents may need appropriate header information. For example, -#' for LaTeX output, we need to write \samp{\\usepackage{tikz}} into the +#' for LaTeX output, we need to write `\usepackage{tikz}` into the #' preamble if we use tikz graphics; this function sets the header information #' to be written into the output. #' #' By default, \pkg{knitr} will set up the header automatically. For example, if -#' the tikz device is used, \pkg{knitr} will add \samp{\\usepackage{tikz}} to +#' the tikz device is used, \pkg{knitr} will add `\usepackage{tikz}` to #' the LaTeX preamble, and this is done by setting the header component -#' \code{tikz} to be a character string: \code{set_header(tikz = -#' '\\usepackage{tikz}')}. Similarly, when we highlight R code using the -#' \pkg{highlight} package (i.e. the chunk option \code{highlight = TRUE}), -#' \pkg{knitr} will set the \code{highlight} component of the header vector +#' `tikz` to be a character string: +#' `set_header(tikz = '\\usepackage{tikz}')`. Similarly, when we highlight R code using the +#' \pkg{highlight} package (i.e. the chunk option `highlight = TRUE`), +#' \pkg{knitr} will set the `highlight` component of the header vector #' automatically; if the output type is HTML, this component will be different #' -- instead of LaTeX commands, it contains CSS definitions. #' #' For power users, all the components can be modified to adapt to a customized -#' type of output. For instance, we can change \code{highlight} to LaTeX +#' type of output. For instance, we can change `highlight` to LaTeX #' definitions of the \pkg{listings} package (and modify the output hooks #' accordingly), so we can decorate R code using the \pkg{listings} package. #' @param ... Header components; currently possible components are -#' \code{highlight}, \code{tikz} and \code{framed}, which contain the +#' `highlight`, `tikz` and `framed`, which contain the #' necessary commands to be used in the HTML header or LaTeX preamble. Note that -#' HTML output does not use the \code{tikz} and \code{framed} components, since +#' HTML output does not use the `tikz` and `framed` components, since #' they do not make sense in the context of HTML. -#' @return The header vector in \code{opts_knit} is set. +#' @return The header vector in `opts_knit` is set. #' @export #' @examples set_header(tikz = '\\usepackage{tikz}') #' opts_knit$get('header') diff --git a/R/hooks-extra.R b/R/hooks-extra.R index 479a5b8bf5..b952bd4ae6 100644 --- a/R/hooks-extra.R +++ b/R/hooks-extra.R @@ -1,57 +1,55 @@ #' Built-in chunk hooks to extend knitr #' #' Hook functions are called when the corresponding chunk options are not -#' \code{NULL} to do additional jobs beside the R code in chunks. This package +#' `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 \pkg{knitr}. #' -#' The function \code{hook_pdfcrop()} calls \code{\link{plot_crop}()} to crop +#' The function `hook_pdfcrop()` calls [plot_crop()] to crop #' the white margins of PDF plots. #' -#' The function \code{hook_optipng()} calls the program \command{optipng} to -#' optimize PNG images. Note the chunk option \code{optipng} can be used to +#' The function `hook_optipng()` calls the program \command{optipng} to +#' optimize PNG images. Note the chunk option `optipng` can be used to #' provide additional parameters to the program \command{optipng}, e.g. -#' \code{optipng = '-o7'}. +#' `optipng = '-o7'`. #' -#' The function \code{hook_pngquant()} calls the program \command{pngquant} to -#' optimize PNG images. Note the chunk option \code{pngquant} can be used to +#' The function `hook_pngquant()` calls the program \command{pngquant} to +#' optimize PNG images. Note the chunk option `pngquant` can be used to #' provide additional parameters to the program \command{pngquant}, e.g. -#' \code{pngquant = '--speed=1 --quality=0-50'}. +#' `pngquant = '--speed=1 --quality=0-50'`. #' -#' The function \code{hook_mogrify()} calls the program \command{mogrify}. Note -#' the chunk option \code{mogrify} can be used to provide additional parameters -#' to the program \command{mogrify} (with default \code{-trim} to trim PNG +#' The function `hook_mogrify()` calls the program \command{mogrify}. Note +#' the chunk option `mogrify` can be used to provide additional parameters +#' to the program \command{mogrify} (with default `-trim` to trim PNG #' files). #' -#' When the plots are not recordable via \code{grDevices::\link{recordPlot}()} +#' When the plots are not recordable via [grDevices::recordPlot()] #' and we save the plots to files manually via other functions (e.g. \pkg{rgl} -#' plots), we can use the chunk hook \code{hook_plot_custom} to help write code +#' plots), we can use the chunk hook `hook_plot_custom` to help write code #' for graphics output into the output document. #' -#' The hook \code{hook_purl()} can be used to write the code chunks to an R -#' script. It is an alternative approach to \code{\link{purl}}, and can be more +#' 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. -#' \code{\link{read_chunk}()}, or \code{\link{opts_chunk}$set(eval = FALSE)}). +#' [read_chunk()], or \code{\link{opts_chunk}$set(eval = FALSE)}). #' To enable this hook, it is recommended to associate it with the chunk option -#' \code{purl}, i.e. \code{knit_hooks$set(purl = hook_purl)}. When this hook is +#' `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 -#' \code{\link{knit}}. Currently the code chunks that are not R code or have the -#' chunk option \code{purl=FALSE} are ignored. Please note when the cache is -#' turned on (the chunk option \code{cache = TRUE}), no chunk hooks will be -#' executed, hence \code{hook_purl()} will not work, either. To solve this -#' problem, we need \code{cache = 2} instead of \code{TRUE} (see -#' \url{https://yihui.org/knitr/demo/cache/} for the meaning of \code{cache = -#' 2}). +#' [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 +#' for the meaning of `cache = +#' 2`). #' @rdname chunk_hook -#' @param before,options,envir,... See \emph{References} below. -#' @references \url{https://yihui.org/knitr/hooks/#chunk-hooks} -#' @seealso \code{rgl::\link[rgl:snapshot]{rgl.snapshot}}, -#' \code{rgl::\link[rgl:postscript]{rgl.postscript}}, -#' \code{rgl::\link[rgl]{hook_rgl}}, -#' \code{rgl::\link[rgl:hook_rgl]{hook_webgl}} -#' @note The two hook functions \code{hook_rgl()} and \code{hook_webgl()} were +#' @param before,options,envir,... See *References* below. +#' @references +#' @seealso [rgl::rgl.snapshot()], [rgl::rgl.postscript()], +#' [rgl::hook_rgl()], [rgl::hook_webgl()] +#' @note The two hook functions `hook_rgl()` and `hook_webgl()` were #' moved from \pkg{knitr} to the \pkg{rgl} package (>= v0.95.1247) after -#' \pkg{knitr} v1.10.5, and you can \code{library(rgl)} to get them. +#' \pkg{knitr} v1.10.5, and you can `library(rgl)` to get them. #' @export #' @examples if (require('rgl') && exists('hook_rgl')) knit_hooks$set(rgl = hook_rgl) #' # then in code chunks, use the option rgl=TRUE diff --git a/R/hooks-html.R b/R/hooks-html.R index 8aa820b052..f8c772d0d5 100644 --- a/R/hooks-html.R +++ b/R/hooks-html.R @@ -101,18 +101,18 @@ hook_animation = function(options) { #' Hooks to create animations in HTML output #' -#' \code{hook_ffmpeg_html()} uses FFmpeg to convert images to a video; -#' \code{hook_gifski()} uses the \pkg{gifski} to convert images to a GIF -#' animation; \code{hook_scianimator()} uses the JavaScript library SciAnimator -#' to create animations; \code{hook_r2swf()} uses the \pkg{R2SWF} package. +#' `hook_ffmpeg_html()` uses FFmpeg to convert images to a video; +#' `hook_gifski()` uses the \pkg{gifski} to convert images to a GIF +#' animation; `hook_scianimator()` uses the JavaScript library SciAnimator +#' to create animations; `hook_r2swf()` uses the \pkg{R2SWF} package. #' -#' These hooks are mainly for the package option \code{animation.fun}, e.g. you -#' can set \code{opts_knit$set(animation.fun = hook_scianimator)}. +#' These hooks are mainly for the package option `animation.fun`, e.g. you +#' can set `opts_knit$set(animation.fun = hook_scianimator)`. #' #' Note that these hooks generate HTML code. For LaTeX output, you can set the -#' chunk option \code{animation.hook} (or the package option -#' \code{animation.fun}) to a function that generates LaTeX code; see -#' \code{\link{hook_plot_tex}}. +#' chunk option `animation.hook` (or the package option +#' `animation.fun`) to a function that generates LaTeX code; see +#' [hook_plot_tex()]. #' @inheritParams hook_plot_tex #' @rdname hook_animation #' @export diff --git a/R/hooks-latex.R b/R/hooks-latex.R index 48e73fb8e7..a461cb4060 100644 --- a/R/hooks-latex.R +++ b/R/hooks-latex.R @@ -3,33 +3,33 @@ #' These hook functions define how to mark up graphics output in different #' output formats. #' -#' Depending on the options passed over, \code{hook_plot_tex} may return the -#' normal \samp{\\includegraphics{}} command, or \samp{\\input{}} (for tikz -#' files), or \samp{\\animategraphics{}} (for animations); it also takes many +#' Depending on the options passed over, `hook_plot_tex` may return the +#' normal `\includegraphics{}` command, or `\input{}` (for tikz +#' files), or `\animategraphics{}` (for animations); it also takes many #' other options into consideration to align plots and set figure sizes, etc. -#' Similarly, \code{hook_plot_html}, \code{hook_plot_md} and -#' \code{hook_plot_rst} return character strings which are HTML, Markdown, reST +#' Similarly, `hook_plot_html`, `hook_plot_md` and +#' `hook_plot_rst` return character strings which are HTML, Markdown, reST #' code. #' -#' For animations (i.e. when the chunk option \code{fig.show} is \code{'animate'}), -#' \code{hook_plot_tex} generates \samp{\\animategraphics{}} unless a hook function -#' has been provided via the chunk option \code{animation.hook} or the package option -#' \code{animation.fun}, in which case that function generates the LaTeX code instead. +#' For animations (i.e. when the chunk option `fig.show` is `'animate'`), +#' `hook_plot_tex` generates `\animategraphics{}` unless a hook function +#' has been provided via the chunk option `animation.hook` or the package option +#' `animation.fun`, in which case that function generates the LaTeX code instead. #' It is called only once per chunk, with the filename of the last plot. The -#' built-in hooks (e.g. \code{\link{hook_ffmpeg_html}}) generate HTML, and are +#' built-in hooks (e.g. [hook_ffmpeg_html()]) generate HTML, and are #' ignored for LaTeX output. #' #' In most cases we do not need to call these hooks explicitly, and they were #' designed to be used internally. Sometimes we may not be able to record R -#' plots using \code{grDevices::\link{recordPlot}()}, and we can make use of +#' plots using [grDevices::recordPlot()], and we can make use of #' these hooks to insert graphics output in the output document; see -#' \code{\link{hook_plot_custom}} for details. +#' [hook_plot_custom()] for details. #' @param x Filename for the plot (a character string). #' @param options A list of the current chunk options. #' @rdname hook_plot #' @return A character string of code, with plot filenames wrapped. -#' @references \url{https://yihui.org/knitr/hooks/} -#' @seealso \code{\link{hook_plot_custom}} +#' @references +#' @seealso [hook_plot_custom()] #' @export #' @examples # this is what happens for a chunk like this #' @@ -290,51 +290,51 @@ escape_percent = function(x) gsub('(?, and #' some examples in -#' \url{https://bookdown.org/yihui/rmarkdown-cookbook/output-hooks.html} +#' #' #' Jekyll and Liquid: -#' \url{https://github.com/jekyll/jekyll/wiki/Liquid-Extensions}; prettify.js: -#' \url{https://code.google.com/archive/p/google-code-prettify} +#' ; prettify.js: +#' #' @examples #' # below is pretty much what knitr::render_markdown() does: #' knitr::knit_hooks$set(knitr::hooks_markdown()) @@ -436,23 +436,23 @@ hooks_listings = hooks_sweave #' #' A document hook is a function to post-process the output document. #' -#' \code{hook_movecode()} is a document hook to move code chunks out of LaTeX -#' floating environments like \samp{figure} and \samp{table} when the chunks +#' `hook_movecode()` is a document hook to move code chunks out of LaTeX +#' floating environments like `figure` and `table` when the chunks #' were actually written inside the floats. This function is primarily designed #' for LyX: we often insert code chunks into floats to generate figures or #' tables, but in the final output we do not want the code to float with the #' environments, so we use regular expressions to find out the floating #' environments, extract the code chunks and move them out. To disable this -#' behavior, use a comment \code{\% knitr_do_not_move} in the floating +#' behavior, use a comment `\% knitr_do_not_move` in the floating #' environment. #' @rdname hook_document #' @param x A character string (the whole output document). #' @return The post-processed document as a character string. -#' @note These functions are hackish. Also note \code{hook_movecode()} assumes +#' @note These functions are hackish. Also note `hook_movecode()` assumes #' you to use the default output hooks for LaTeX (not Sweave or listings), and #' every figure/table environment must have a label. #' @export -#' @references \url{https://yihui.org/knitr/hooks/} +#' @references #' @examples \dontrun{knit_hooks$set(document = hook_movecode)} #' # see example 103 at https://github.com/yihui/knitr-examples hook_movecode = function(x) { diff --git a/R/hooks-md.R b/R/hooks-md.R index a16af8d256..6b9423707c 100644 --- a/R/hooks-md.R +++ b/R/hooks-md.R @@ -162,11 +162,11 @@ css_text_align = function(align) { #' @rdname output_hooks #' @export -#' @param strict Boolean; whether to use strict markdown or reST syntax. For markdown, if -#' \code{TRUE}, code blocks will be indented by 4 spaces, otherwise they are -#' put in fences made by three backticks. For reST, if \code{TRUE}, code is +#' @param strict Whether to use strict markdown or reST syntax. For markdown, if +#' `TRUE`, code blocks will be indented by 4 spaces, otherwise they are +#' put in fences made by three backticks. For reST, if `TRUE`, code is #' put under two colons and indented by 4 spaces, otherwise it is put under the -#' \samp{sourcecode} directive (this is useful for e.g. Sphinx). +#' `sourcecode` directive (this is useful for e.g., Sphinx). #' @param fence_char A single character to be used in the code blocks fence. #' This can be e.g. a backtick or a tilde, depending on your Markdown rendering #' engine. @@ -261,13 +261,13 @@ eng2lang = function(x) { if (x %in% names(d)) d[x] else x } -#' @param highlight Which code highlighting engine to use: if \code{pygments}, -#' the Liquid syntax is used (default approach Jekyll); if \code{prettify}, +#' @param highlight Which code highlighting engine to use: if `pygments`, +#' the Liquid syntax is used (default approach Jekyll); if `prettify`, #' the output is prepared for the JavaScript library \file{prettify.js}; if -#' \code{none}, no highlighting engine will be used, and code blocks are simply +#' `none`, no highlighting engine will be used, and code blocks are simply #' indented by 4 spaces). -#' @param extra Extra tags for the highlighting engine. For \code{pygments}, this -#' can be \code{'linenos'}; for \code{prettify}, it can be \code{'linenums'}. +#' @param extra Extra tags for the highlighting engine. For `pygments`, this +#' can be `'linenos'`; for `prettify`, it can be `'linenums'`. #' @rdname output_hooks #' @export render_jekyll = function(highlight = c('pygments', 'prettify', 'none'), extra = '') { diff --git a/R/hooks.R b/R/hooks.R index 9775d63655..a77508cffe 100644 --- a/R/hooks.R +++ b/R/hooks.R @@ -20,12 +20,12 @@ #' Hooks for R code chunks, inline R code and output #' #' A hook is a function of a pre-defined form (arguments) that takes values of -#' arguments and returns desired output. The object \code{knit_hooks} is used to +#' arguments and returns desired output. The object `knit_hooks` is used to #' access or set hooks in this package. #' @export -#' @references Usage: \url{https://yihui.org/knitr/objects/} +#' @references Usage: #' -#' Components in \code{knit_hooks}: \url{https://yihui.org/knitr/hooks/} +#' Components in `knit_hooks`: #' @examples knit_hooks$get('source'); knit_hooks$get('inline') knit_hooks = new_defaults(.default.hooks) @@ -58,12 +58,12 @@ hook_suppress = function(x, options) { #' Like \code{\link{knit_hooks}}, this object can be used to set hook functions #' to manipulate chunk options. #' -#' For every code chunk, if the chunk option named, say, \code{FOO}, is not -#' \code{NULL}, and a hook function with the same name has been set via -#' \code{opts_hooks$set(FOO = function(options) { options })} (you can manipuate -#' the \code{options} argument in the function and return it), the hook function +#' For every code chunk, if the chunk option named, say, `FOO`, is not +#' `NULL`, and a hook function with the same name has been set via +#' `opts_hooks$set(FOO = function(options) { options })` (you can manipuate +#' the `options` argument in the function and return it), the hook function #' will be called to update the chunk options. -#' @references \url{https://yihui.org/knitr/hooks/} +#' @references #' @export #' @examples # make sure the figure width is no smaller than fig.height #' opts_hooks$set(fig.width = function(options) { diff --git a/R/output.R b/R/output.R index 63a2e7d5a0..0bd6183382 100644 --- a/R/output.R +++ b/R/output.R @@ -2,14 +2,14 @@ #' #' This function takes an input file, extracts the R code in it according to a #' list of patterns, evaluates the code and writes the output in another file. -#' It can also tangle R source code from the input document (\code{purl()} is a -#' wrapper to \code{knit(..., tangle = TRUE)}). The \code{knitr.purl.inline} +#' It can also tangle R source code from the input document (`purl()` is a +#' wrapper to `knit(..., tangle = TRUE)`). The `knitr.purl.inline` #' option can be used to also tangle the code of inline expressions (disabled by #' default). #' #' For most of the time, it is not necessary to set any options outside the #' input document; in other words, a single call like -#' \code{knit('my_input.Rnw')} is usually enough. This function will try to +#' `knit('my_input.Rnw')` is usually enough. This function will try to #' determine many internal settings automatically. For the sake of #' reproducibility, it is better practice to include the options inside the #' input document (to be self-contained), instead of setting them before @@ -20,100 +20,100 @@ #' \file{.Rtex}, \file{.Rhtml} (\file{.Rhtm}) and \file{.Rmd} #' (\file{.Rmarkdown}) will generate \file{.tex}, \file{.html} and \file{.md} #' respectively. For other types of files, if the filename contains -#' \samp{_knit_}, this part will be removed in the output file, e.g., -#' \file{foo_knit_.html} creates the output \file{foo.html}; if \samp{_knit_} is +#' `_knit_`, this part will be removed in the output file, e.g., +#' \file{foo_knit_.html} creates the output \file{foo.html}; if `_knit_` is #' not found in the filename, \file{foo.ext} will produce \file{foo.txt} if -#' \code{ext} is not \code{txt}, otherwise the output is \file{foo-out.txt}. If -#' \code{tangle = TRUE}, \file{foo.ext} generates an R script \file{foo.R}. +#' `ext` is not `txt`, otherwise the output is \file{foo-out.txt}. If +#' `tangle = TRUE`, \file{foo.ext} generates an R script \file{foo.R}. #' #' We need a set of syntax to identify special markups for R code chunks and R #' options, etc. The syntax is defined in a pattern list. All built-in pattern -#' lists can be found in \code{all_patterns} (call it \code{apat}). First +#' lists can be found in `all_patterns` (call it `apat`). First #' \pkg{knitr} will try to decide the pattern list based on the filename -#' extension of the input document, e.g. \samp{Rnw} files use the list -#' \code{apat$rnw}, \samp{tex} uses the list \code{apat$tex}, \samp{brew} uses -#' \code{apat$brew} and HTML files use \code{apat$html}; for unknown extensions, +#' extension of the input document, e.g. `Rnw` files use the list +#' `apat$rnw`, `tex` uses the list `apat$tex`, `brew` uses +#' `apat$brew` and HTML files use `apat$html`; for unknown extensions, #' the content of the input document is matched against all pattern lists to #' automatically determine which pattern list is being used. You can also #' manually set the pattern list using the \code{\link{knit_patterns}} object or -#' the \code{\link{pat_rnw}} series functions in advance and \pkg{knitr} will +#' the [pat_rnw()] series functions in advance and \pkg{knitr} will #' respect the setting. #' -#' According to the output format (\code{opts_knit$get('out.format')}), a set of +#' According to the output format (`opts_knit$get('out.format')`), a set of #' output hooks will be set to mark up results from R (see -#' \code{\link{render_latex}}). The output format can be LaTeX, Sweave and HTML, +#' [render_latex()]). The output format can be LaTeX, Sweave and HTML, #' etc. The output hooks decide how to mark up the results (you can customize #' the hooks). #' -#' The name \code{knit} comes from its counterpart \samp{weave} (as in Sweave), -#' and the name \code{purl} (as \samp{tangle} in Stangle) comes from a knitting +#' The name `knit` comes from its counterpart `weave` (as in Sweave), +#' and the name `purl` (as `tangle` in Stangle) comes from a knitting #' method `knit one, purl one'. #' #' If the input document has child documents, they will also be compiled -#' recursively. See \code{\link{knit_child}}. +#' recursively. See [knit_child()]. #' #' See the package website and manuals in the references to know more about #' \pkg{knitr}, including the full documentation of chunk options and demos, #' etc. #' @param input Path to the input file. -#' @param output Path to the output file for \code{knit()}. If \code{NULL}, this +#' @param output Path to the output file for `knit()`. If `NULL`, this #' function will try to guess a default, which will be under the current #' working directory. -#' @param tangle Boolean; whether to tangle the R code from the input file (like -#' \code{utils::\link{Stangle}}). +#' @param tangle Whether to tangle the R code from the input file (like +#' [utils::Stangle()]). #' @param text A character vector. This is an alternative way to provide the #' input file. -#' @param quiet Boolean; suppress the progress bar and messages? +#' @param quiet Whether to suppress the progress bar and messages. #' @param envir Environment in which code chunks are to be evaluated, for -#' example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -#' \code{\link{globalenv}()}). +#' example, [parent.frame()], [new.env()], or +#' [globalenv()]). #' @param encoding Encoding of the input file; always assumed to be UTF-8 (i.e., #' this argument is effectively ignored). #' @return The compiled document is written into the output file, and the path -#' of the output file is returned. If the \code{text} argument is not -#' \code{NULL}, the compiled output is returned as a character vector. In +#' of the output file is returned. If the `text` argument is not +#' `NULL`, the compiled output is returned as a character vector. In #' other words, if you provide a file input, you get an output filename; if #' you provide a character vector input, you get a character vector output. #' @note The working directory when evaluating R code chunks is the directory of #' the input document by default, so if the R code involves external files -#' (like \code{read.table()}), it is better to put these files under the same +#' (like `read.table()`), it is better to put these files under the same #' directory of the input document so that we can use relative paths. However, #' it is possible to change this directory with the package option #' \code{\link{opts_knit}$set(root.dir = ...)} so all paths in code chunks are -#' relative to this \code{root.dir}. It is not recommended to change the -#' working directory via \code{\link{setwd}()} in a code chunk, because it may +#' relative to this `root.dir`. It is not recommended to change the +#' working directory via [setwd()] in a code chunk, because it may #' lead to terrible consequences (e.g. figure and cache files may be written -#' to wrong places). If you do use \code{setwd()}, please note that +#' to wrong places). If you do use `setwd()`, please note that #' \pkg{knitr} will always restore the working directory to the original one. -#' Whenever you feel confused, print \code{getwd()} in a code chunk to see +#' Whenever you feel confused, print `getwd()` in a code chunk to see #' what the working directory really is. #' -#' If the \code{output} argument is a file path, it is strongly recommended to +#' If the `output` argument is a file path, it is strongly recommended to #' be in the current working directory (e.g. \file{foo.tex} instead of #' \file{somewhere/foo.tex}), especially when the output has external #' dependencies such as figure files. If you want to write the output to a #' different directory, it is recommended to set the working directory to that #' directory before you knit a document. For example, if the source document #' is \file{foo.Rmd} and the expected output is \file{out/foo.md}, you can -#' write \code{setwd('out/'); knit('../foo.Rmd')} instead of -#' \code{knit('foo.Rmd', 'out/foo.md')}. +#' write `setwd('out/'); knit('../foo.Rmd')` instead of +#' `knit('foo.Rmd', 'out/foo.md')`. #' -#' N.B. There is no guarantee that the R script generated by \code{purl()} can -#' reproduce the computation done in \code{knit()}. The \code{knit()} process +#' N.B. There is no guarantee that the R script generated by `purl()` can +#' reproduce the computation done in `knit()`. The `knit()` process #' can be fairly complicated (special values for chunk options, custom chunk -#' hooks, computing engines besides R, and the \code{envir} argument, etc). If +#' hooks, computing engines besides R, and the `envir` argument, etc). If #' you want to reproduce the computation in a report generated by -#' \code{knit()}, be sure to use \code{knit()}, instead of merely executing -#' the R script generated by \code{purl()}. This seems to be obvious, but some +#' `knit()`, be sure to use `knit()`, instead of merely executing +#' the R script generated by `purl()`. This seems to be obvious, but some #' people -#' \href{https://stat.ethz.ch/pipermail/r-devel/2014-May/069113.html}{do not -#' get it}. +#' [do not +#' get it](https://stat.ethz.ch/pipermail/r-devel/2014-May/069113.html). #' @export -#' @references Package homepage: \url{https://yihui.org/knitr/}. The \pkg{knitr} -#' \href{https://yihui.org/knitr/demo/manual/}{main manual}: and -#' \href{https://yihui.org/knitr/demo/graphics/}{graphics manual}. +#' @references Package homepage: . The \pkg{knitr} +#' [main manual](https://yihui.org/knitr/demo/manual/): and +#' [graphics manual](https://yihui.org/knitr/demo/graphics/). #' -#' See \code{citation('knitr')} for the citation information. +#' See `citation('knitr')` for the citation information. #' @examples library(knitr) #' (f = system.file('examples', 'knitr-minimal.Rnw', package = 'knitr')) #' knit(f) # compile to tex @@ -288,10 +288,10 @@ knit = function( } #' @rdname knit #' @param documentation An integer specifying the level of documentation to add to -#' the tangled script. \code{0} means to output pure code, discarding all text chunks); -#' \code{1} (the default) means to add the chunk headers to the code; \code{2} means to +#' the tangled script. `0` means to output pure code, discarding all text chunks); +#' `1` (the default) means to add the chunk headers to the code; `2` means to #' add all text chunks to code as roxygen comments. -#' @param ... arguments passed to \code{\link{knit}()} from \code{purl()} +#' @param ... Arguments passed to [knit()] from `purl()`. #' @export purl = function(..., documentation = 1L) { doc = opts_knit$get('documentation'); on.exit(opts_knit$set(documentation = doc)) @@ -406,21 +406,21 @@ auto_format = function(ext) { #' #' This function knits a child document and returns a character string to input #' the result into the main document. It is designed to be used in the chunk -#' option \code{child} and serves as the alternative to the +#' option `child` and serves as the alternative to the #' \command{SweaveInput} command in Sweave. -#' @param ... Arguments passed to \code{\link{knit}}. +#' @param ... Arguments passed to [knit()]. #' @param options A list of chunk options to be used as global options inside -#' the child document. When one uses the \code{child} +#' the child document. When one uses the `child` #' option in a parent chunk, the chunk options of the parent chunk will be -#' passed to the \code{options} argument here. Ignored if not a list. +#' passed to the `options` argument here. Ignored if not a list. #' @inheritParams knit #' @return A character string of the content of the compiled child document is #' returned as a character string so it can be written back to the parent #' document directly. -#' @references \url{https://yihui.org/knitr/demo/child/} +#' @references #' @note This function is not supposed be called directly like -#' \code{\link{knit}()}; instead it must be placed in a parent document to let -#' \code{\link{knit}()} call it indirectly. +#' [knit()]; instead it must be placed in a parent document to let +#' [knit()] call it indirectly. #' #' The path of the child document is determined relative to the parent document. #' @export @@ -451,16 +451,16 @@ knit_child = function(..., options = NULL, envir = knit_global()) { #' #' Sometimes we may want to exit the knitting process early, and completely #' ignore the rest of the document. This function provides a mechanism to -#' terminate \code{\link{knit}()}. +#' terminate [knit()]. #' @param append A character vector to be appended to the results from -#' \code{knit()} so far. By default, this is \samp{\end{document}} for LaTeX -#' output, and \samp{} for HTML output, to make the output +#' `knit()` so far. By default, this is `\end{document}` for LaTeX +#' output, and `` for HTML output, to make the output #' document complete. For other types of output, it is an empty string. -#' @param fully Whether to fully exit the knitting process if \code{knit_exit()} -#' is called from a child document. If \code{FALSE}, only exit the knitting +#' @param fully Whether to fully exit the knitting process if `knit_exit()` +#' is called from a child document. If `FALSE`, only exit the knitting #' process of the child document. -#' @return Invisible \code{NULL}. An internal signal is set up (as a side -#' effect) to notify \code{knit()} to quit as if it had reached the end of the +#' @return Invisible `NULL`. An internal signal is set up (as a side +#' effect) to notify `knit()` to quit as if it had reached the end of the #' document. #' @export #' @examples # see https://github.com/yihui/knitr-examples/blob/master/096-knit-exit.Rmd @@ -480,7 +480,7 @@ knit_log = new_defaults() # knitr log for errors, warnings and messages #' output of the code chunk (code, messages, text output, and plots, etc.) after #' all statements in the code chunk have been evaluated, and will sew these #' pieces of output together into a character vector. -#' @param x Output from \code{evaluate::\link[evaluate]{evaluate}()}. +#' @param x Output from [evaluate::evaluate()]. #' @param options A list of chunk options used to control output. #' @param ... Other arguments to pass to methods. #' @export @@ -713,29 +713,29 @@ add_html_caption = function(options, code, id = NULL) { #' A custom printing function #' -#' The S3 generic function \code{knit_print} is the default printing function in -#' \pkg{knitr}. The chunk option \code{render} uses this function by default. +#' The S3 generic function `knit_print` is the default printing function in +#' \pkg{knitr}. The chunk option `render` uses this function by default. #' The main purpose of this S3 generic function is to customize printing of R #' objects in code chunks. We can fall back to the normal printing behavior by -#' setting the chunk option \code{render = normal_print}. +#' setting the chunk option `render = normal_print`. #' #' Users can write custom methods based on this generic function. For example, #' if we want to print all data frames as tables in the output, we can define a -#' method \code{knit_print.data.frame} that turns a data.frame into a table (the +#' method `knit_print.data.frame` that turns a data.frame into a table (the #' implementation may use other R packages or functions, e.g. \pkg{xtable} or -#' \code{\link{kable}()}). -#' @param x An R object to be printed +#' [kable()]). +#' @param x An R object to be printed. #' @param ... Additional arguments passed to the S3 method. Currently ignored, -#' except two optional arguments \code{options} and \code{inline}; see +#' except two optional arguments `options` and `inline`; see #' the references below. #' @return The value returned from the print method should be a character vector #' or can be converted to a character value. You can wrap the value in -#' \code{\link{asis_output}()} so that \pkg{knitr} writes the character value +#' [asis_output()] so that \pkg{knitr} writes the character value #' as is in the output. -#' @note It is recommended to leave a \code{...} argument in your method, to -#' allow future changes of the \code{knit_print()} API without breaking your +#' @note It is recommended to leave a `...` argument in your method, to +#' allow future changes of the `knit_print()` API without breaking your #' method. -#' @references See \code{vignette('knit_print', package = 'knitr')}. +#' @references See `vignette('knit_print', package = 'knitr')`. #' @export #' @examples library(knitr) #' # write tables for data frames @@ -780,17 +780,17 @@ normal_print = function(x, ...) { #' Mark an R object with a special class #' #' This is a convenience function that assigns the input object a class named -#' \code{knit_asis}, so that \pkg{knitr} will treat it as is (the effect is the -#' same as the chunk option \code{results = 'asis'}) when it is written to the +#' `knit_asis`, so that \pkg{knitr} will treat it as is (the effect is the +#' same as the chunk option `results = 'asis'`) when it is written to the #' output. #' #' This function is normally used in a custom S3 method based on the printing -#' function \code{\link{knit_print}()}. +#' function [knit_print()]. #' -#' For the \code{cacheable} argument, you need to be careful when printing the +#' For the `cacheable` argument, you need to be careful when printing the #' object involves non-trivial side effects, in which case it is strongly -#' recommended to use \code{cacheable = FALSE} to instruct \pkg{knitr} that this -#' object should not be cached using the chunk option \code{cache = TRUE}, +#' recommended to use `cacheable = FALSE` to instruct \pkg{knitr} that this +#' object should not be cached using the chunk option `cache = TRUE`, #' otherwise the side effects will be lost the next time the chunk is knitted. #' For example, printing a \pkg{shiny} input element or an HTML widget in an R #' Markdown document may involve registering metadata about some JavaScript @@ -801,16 +801,16 @@ normal_print = function(x, ...) { #' metadata can be saved and loaded next time and still works in the new R #' session. #' @param x An R object. Typically a character string, or an object which can -#' be converted to a character string via \code{\link{as.character}()}. +#' be converted to a character string via [as.character()]. #' @param meta Additional metadata of the object to be printed. The metadata #' will be collected when the object is printed, and accessible via -#' \code{knit_meta()}. +#' `knit_meta()`. #' @param cacheable Boolean indicating whether this object is cacheable. If -#' \code{FALSE}, \pkg{knitr} will stop when caching is enabled on code chunks -#' that contain \code{asis_output()}. +#' `FALSE`, \pkg{knitr} will stop when caching is enabled on code chunks +#' that contain `asis_output()`. #' @note This function only works in top-level R expressions, and it will not #' work when it is called inside another expression, such as a for-loop. See -#' \url{https://github.com/yihui/knitr/issues/1137} for a discussion. +#' for a discussion. #' @export #' @examples # see ?knit_print asis_output = function(x, meta = NULL, cacheable = NA) { @@ -822,17 +822,17 @@ asis_output = function(x, meta = NULL, cacheable = NA) { #' As an object is printed, \pkg{knitr} will collect metadata about it (if #' available). After knitting is done, all the metadata is accessible via this #' function. You can manually add metadata to the \pkg{knitr} session via -#' \code{knit_meta_add()}. +#' `knit_meta_add()`. #' @param class Optionally return only metadata entries that inherit from the -#' specified class. The default, \code{NULL}, returns all entries. +#' specified class. The default, `NULL`, returns all entries. #' @param clean Whether to clean the collected metadata. By default, the #' metadata stored in \pkg{knitr} is cleaned up once retrieved, because we may -#' not want the metadata to be passed to the next \code{knit()} call; to be +#' not want the metadata to be passed to the next `knit()` call; to be #' defensive (i.e. not to have carryover metadata), you can call -#' \code{knit_meta()} before \code{knit()}. +#' `knit_meta()` before `knit()`. #' @export -#' @return \code{knit_meta()} returns the matched metadata specified by -#' \code{class}; \code{knit_meta_add()} returns all current metadata. +#' @return `knit_meta()` returns the matched metadata specified by +#' `class`; `knit_meta_add()` returns all current metadata. knit_meta = function(class = NULL, clean = TRUE) { if (is.null(class)) { if (clean) on.exit({.knitEnv$meta = list()}, add = TRUE) diff --git a/R/package.R b/R/package.R index a0e50bceea..2ed69d3f3c 100644 --- a/R/package.R +++ b/R/package.R @@ -15,15 +15,15 @@ #' @name knitr-package #' @aliases knitr #' @import graphics grDevices stats utils -#' @author Yihui Xie <\url{https://yihui.org}> -#' @seealso The core function in this package: \code{\link{knit}}. If you are an -#' Sweave user, see \code{\link{Sweave2knitr}} on how to convert Sweave files +#' @author Yihui Xie <> +#' @seealso The core function in this package: [knit()]. If you are an +#' Sweave user, see [Sweave2knitr()] on how to convert Sweave files #' to \pkg{knitr}. -#' @note The pronunciation of \pkg{knitr} is similar to \emph{neater} or you can -#' think of \emph{knitter} (but it is \emph{single t}). The name comes from -#' \code{knit} + \code{R} (while \code{Sweave} = \code{S} + \code{weave}). -#' @references Full documentation and demos: \url{https://yihui.org/knitr/}; -#' FAQ's: \url{https://yihui.org/knitr/faq/} +#' @note The pronunciation of \pkg{knitr} is similar to *neater* or you can +#' think of *knitter* (but it is *single t*). The name comes from +#' `knit` + `R` (while `Sweave` = `S` + `weave`). +#' @references Full documentation and demos: ; +#' FAQ's: #' @importFrom xfun file_ext html_escape is_windows loadable parse_only #' sans_ext try_silent with_ext read_utf8 write_utf8 file_string #' is_R_CMD_check is_abs_path file_exists strip_html diff --git a/R/pandoc.R b/R/pandoc.R index 044cd61798..fc8d8e1a48 100644 --- a/R/pandoc.R +++ b/R/pandoc.R @@ -8,41 +8,41 @@ #' file, or embed the configurations in the input file as special comments #' between \verb{}. #' -#' The configuration file is a DCF file (see \code{\link{read.dcf}}). This file -#' must contain a field named \code{t} which means the output format. The -#' configurations are written in the form of \code{tag:value} and passed to +#' The configuration file is a DCF file (see [read.dcf()]). This file +#' must contain a field named `t` which means the output format. The +#' configurations are written in the form of `tag:value` and passed to #' Pandoc (if no value is needed, just leave it empty, e.g. the option -#' \code{standalone} or \code{s} for short). If there are multiple output +#' `standalone` or `s` for short). If there are multiple output #' formats, write each format and relevant configurations in a block, and #' separate blocks with blank lines. #' -#' If there are multiple records of the \code{t} field in the configuration, the +#' If there are multiple records of the `t` field in the configuration, the #' input markdown file will be converted to all these formats by default, unless -#' the \code{format} argument is specified as one single format. +#' the `format` argument is specified as one single format. #' @param input A character vector of Markdown filenames (must be encoded in #' UTF-8). #' @param format Name of the output format (see References). This can be a #' character vector of multiple formats; by default, it is obtained from the -#' \code{t} field in the configuration. If the configuration is empty or the -#' \code{t} field is not found, the default output format will be -#' \code{'html'}. +#' `t` field in the configuration. If the configuration is empty or the +#' `t` field is not found, the default output format will be +#' `'html'`. #' @param config Path to the Pandoc configuration file. If missing, it is -#' assumed to be a file with the same base name as the \code{input} file and -#' an extension \code{.pandoc} (e.g. for \file{foo.md} it looks for +#' assumed to be a file with the same base name as the `input` file and +#' an extension `.pandoc` (e.g. for \file{foo.md} it looks for #' \file{foo.pandoc}) #' @param ext Filename extensions. By default, the extension is inferred from -#' the \code{format}, e.g. \code{latex} creates \code{pdf}, \code{dzslides} -#' creates \code{html}, and so on +#' the `format`, e.g., `latex` creates `pdf`, `dzslides` +#' creates `html`, and so on. #' @return The output filename(s) (or an error if the conversion failed). -#' @references Pandoc: \url{https://pandoc.org}; Examples and rules of the -#' configurations: \url{https://yihui.org/knitr/demo/pandoc/} +#' @references Pandoc: ; Examples and rules of the +#' configurations: #' -#' Also see R Markdown (v2) at \url{https://rmarkdown.rstudio.com}. The +#' Also see R Markdown (v2) at . The #' \pkg{rmarkdown} package has several convenience functions and templates #' that make it very easy to use Pandoc. The RStudio IDE also has #' comprehensive support for it, so I'd recommend users who are not familiar #' with command-line tools to use the \pkg{rmarkdown} package instead. -#' @seealso \code{\link{read.dcf}} +#' @seealso [read.dcf()] #' @export #' @examples system('pandoc -h') # see possible output formats pandoc = function(input, format, config = getOption('config.pandoc'), ext = NA) { diff --git a/R/params.R b/R/params.R index 85cbd0a228..4648be4886 100644 --- a/R/params.R +++ b/R/params.R @@ -3,32 +3,32 @@ #' This function reads the YAML front-matter section of a document and returns a #' list of any parameters declared there. This function exists primarily to #' support the parameterized reports feature of the \pkg{rmarkdown} package, -#' however is also used by the knitr \code{\link{purl}} function to include +#' however is also used by the knitr [purl()] function to include #' the default parameter values in the R code it emits. #' #' @param text Character vector containing the document text. -#' @param evaluate Boolean. If \code{TRUE} (the default), expression values embedded -#' within the YAML will be evaluated. If \code{FALSE}, parameters defined with an -#' expression will have the parsed but unevaluated expression in their \code{value} -#' field. +#' @param evaluate Boolean. If `TRUE` (the default), expression values +#' embedded within the YAML will be evaluated. If `FALSE`, parameters +#' defined with an expression will have the parsed but unevaluated expression +#' in their `value` field. #' -#' @return List of objects of class \code{knit_param} that correspond to the -#' parameters declared in the \code{params} section of the YAML front matter. +#' @return List of objects of class `knit_param` that correspond to the +#' parameters declared in the `params` section of the YAML front matter. #' These objects have the following fields: #' #' \describe{ -#' \item{\code{name}}{The parameter name.} -#' \item{\code{value}}{The default value for the parameter.} -#' \item{\code{expr}}{The R expression (if any) that yielded the default value.} +#' \item{`name`}{The parameter name.} +#' \item{`value`}{The default value for the parameter.} +#' \item{`expr`}{The R expression (if any) that yielded the default value.} #' } #' #' In addition, other fields included in the YAML may also be present -#' alongside the name, type, and value fields (e.g. a \code{label} field +#' alongside the name, type, and value fields (e.g. a `label` field #' that provides front-ends with a human readable name for the parameter). #' #' @details #' -#' Parameters are included in YAML front matter using the \code{params} key. +#' Parameters are included in YAML front matter using the `params` key. #' This key can have any number of subkeys each of which represents a #' parameter. For example: #' @@ -43,7 +43,7 @@ #' } #' #' Parameter values can be provided inline as illustrated above or can be -#' included in a \code{value} sub-key. For example: +#' included in a `value` sub-key. For example: #' #' \preformatted{ #' --- @@ -56,10 +56,10 @@ #' } #' #' This second form is useful when you need to provide additional details -#' about the parameter (e.g. a \code{label} field as describe above). +#' about the parameter (e.g. a `label` field as describe above). #' #' You can also use R code to yield the value of a parameter by prefacing the value -#' with \code{!r}, for example: +#' with `!r`, for example: #' #' \preformatted{ #' --- @@ -89,16 +89,16 @@ knit_params = function(text, evaluate = TRUE) { #' from a document and returns a list of any parameters declared there. #' #' @param yaml Character vector containing the YAML text. -#' @param evaluate If \code{TRUE} (the default) expression values -#' embedded within the YAML will be evaluated. If \code{FALSE}, parameters -#' defined with an expression will have the parsed but unevaluated expression -#' in their \code{value} field. +#' @param evaluate If `TRUE` (the default), expression values embedded +#' within the YAML will be evaluated. If `FALSE`, parameters defined with +#' an expression will have the parsed but unevaluated expression in their +#' `value` field. #' -#' @return List of objects of class \code{knit_param} that correspond to the -#' parameters declared in the \code{params} section of the YAML. See -#' \code{\link{knit_params}} for a full description of these objects. +#' @return List of objects of class `knit_param` that correspond to the +#' parameters declared in the `params` section of the YAML. See +#' [knit_params()] for a full description of these objects. #' -#' @seealso \code{\link{knit_params}} +#' @seealso [knit_params()] #' #' @export knit_params_yaml = function(yaml, evaluate = TRUE) { diff --git a/R/parser.R b/R/parser.R index 30eac0c7dc..6d2f40c17b 100644 --- a/R/parser.R +++ b/R/parser.R @@ -54,15 +54,15 @@ extract_params_src = function(chunk.begin, line) { #' #' This object provides methods to manage code (as character vectors) in all #' chunks in \pkg{knitr} source documents. For example, -#' \code{knitr::knit_code$get()} returns a named list of all code chunks (the -#' names are chunk labels), and \code{knitr::knit_code$get('foo')} returns the -#' character vector of the code in the chunk with the label \code{foo}. -#' @note The methods on this object include the \code{set()} method (i.e., you -#' could do something like \code{knitr::knit_code$set(foo = "'my precious new -#' code'")}), but we recommend that you do not use this method to modify the +#' `knitr::knit_code$get()` returns a named list of all code chunks (the +#' names are chunk labels), and `knitr::knit_code$get('foo')` returns the +#' character vector of the code in the chunk with the label `foo`. +#' @note The methods on this object include the `set()` method (i.e., you +#' could do something like `knitr::knit_code$set(foo = "'my precious new +#' code'")`), but we recommend that you do not use this method to modify the #' content of code chunks, unless you are -#' \href{https://emitanaka.rbind.io/post/knitr-knitr-code/}{as creative as Emi -#' Tanaka} and know what you are doing. +#' [as creative as Emi +#' Tanaka](https://emitanaka.rbind.io/post/knitr-knitr-code/) and know what you are doing. #' @export knit_code = new_defaults() @@ -197,7 +197,7 @@ parse_params = function(params, label = TRUE) { #' Partition chunk options from the code chunk body #' -#' This is a wrapper function calling \code{xfun::\link[xfun]{divide_chunk}()} +#' This is a wrapper function calling [xfun::divide_chunk()] #' under the hood. #' @export #' @keywords internal @@ -261,44 +261,44 @@ print_inline = function(x) { #' Read chunks from an external script #' #' Chunks can be put in an external script, and this function reads chunks into -#' the current \pkg{knitr} session; \code{read_demo()} is a convenience function +#' the current \pkg{knitr} session; `read_demo()` is a convenience function #' to read a demo script from a package. #' #' There are two approaches to read external code into the current session: (1) -#' Use a special separator of the from \code{## ---- chunk-label} (at least four +#' Use a special separator of the from `## ---- chunk-label` (at least four #' dashes before the chunk label) in the script; (2) Manually specify the #' labels, starting and ending positions of code chunks in the script. #' -#' The second approach will be used only when \code{labels} is not \code{NULL}. -#' For this approach, if \code{from} is \code{NULL}, the starting position is 1; -#' if \code{to} is \code{NULL}, each of its element takes the next element of -#' \code{from} minus 1, and the last element of \code{to} will be the length of -#' \code{lines} (e.g. when \code{from = c(1, 3, 8)} and the script has 10 lines -#' in total, \code{to} will be \code{c(2, 7, 10)}). Alternatively, \code{from} -#' and \code{to} can be character vectors as regular expressions to specify the +#' The second approach will be used only when `labels` is not `NULL`. +#' For this approach, if `from` is `NULL`, the starting position is 1; +#' if `to` is `NULL`, each of its element takes the next element of +#' `from` minus 1, and the last element of `to` will be the length of +#' `lines` (e.g. when `from = c(1, 3, 8)` and the script has 10 lines +#' in total, `to` will be `c(2, 7, 10)`). Alternatively, `from` +#' and `to` can be character vectors as regular expressions to specify the #' positions; when their length is 1, the single regular expression will be -#' matched against the \code{lines} vector, otherwise each element of -#' \code{from}/\code{to} is matched against \code{lines} and the match is +#' matched against the `lines` vector, otherwise each element of +#' `from`/`to` is matched against `lines` and the match is #' supposed to be unique so that the numeric positions returned from -#' \code{grep()} will be of the same length of \code{from}/\code{to}. Note -#' \code{labels} always has to match the length of \code{from} and \code{to}. +#' `grep()` will be of the same length of `from`/`to`. Note +#' `labels` always has to match the length of `from` and `to`. #' @param path Path to the R script. #' @param lines Character vector of lines of code. By default, this is read from -#' \code{path}. -#' @param labels Character vector of chunk labels (default \code{NULL}). +#' `path`. +#' @param labels Character vector of chunk labels (default `NULL`). #' @param from,to Numeric vector specifying the starting/ending line numbers of #' code chunks, or a character vector; see Details. -#' @param from.offset,to.offset Offsets to be added to \code{from}/\code{to}. -#' @param roxygen_comments Logical dictating whether to keep trailing -#' roxygen-style comments from code chunks in addition to whitespace +#' @param from.offset,to.offset Offsets to be added to `from`/`to`. +#' @param roxygen_comments Whether to keep trailing roxygen-style comments from +#' code chunks in addition to whitespace. #' @return As a side effect, code chunks are read into the current session so #' that future chunks can (re)use the code by chunk label references. If an #' external chunk has the same label as a chunk in the current session, chunk #' label references by future chunks will refer to the external chunk. -#' @references \url{https://yihui.org/knitr/demo/externalization/} -#' @note This function can only be used in a chunk which is \emph{not} cached -#' (chunk option \code{cache = FALSE}), and the code is read and stored in the -#' current session \emph{without} being executed (to actually run the code, +#' @references +#' @note This function can only be used in a chunk which is *not* cached +#' (chunk option `cache = FALSE`), and the code is read and stored in the +#' current session *without* being executed (to actually run the code, #' you have to use a chunk with a corresponding label). #' @author Yihui Xie; the idea of the second approach came from Peter #' Ruckdeschel (author of the \pkg{SweaveListingUtils} package) @@ -363,8 +363,8 @@ read_chunk = function( #' @rdname read_chunk #' @param topic,package Name of the demo and the package. See -#' \code{utils::\link{demo}}. -#' @param ... Arguments passed to \code{\link{read_chunk}}. +#' [utils::demo()]. +#' @param ... Arguments passed to [read_chunk()]. #' @export read_demo = function(topic, package = NULL, ...) { paths = list.files(file.path(find.package(package), 'demo'), full.names = TRUE) @@ -492,26 +492,26 @@ match_chunk_end = function(pattern, line, i, b, lines) { #' Get all chunk labels in a document #' -#' The function \code{all_labels()} returns all chunk labels as a character +#' The function `all_labels()` returns all chunk labels as a character #' vector. Optionally, you can specify a series of conditions to filter the #' labels. The function `all_rcpp_labels()` is a wrapper function for -#' \code{all_labels(engine == 'Rcpp')}. +#' `all_labels(engine == 'Rcpp')`. #' -#' For example, suppose the condition expression is \code{engine == 'Rcpp'}, the -#' object \code{engine} is the local chunk option \code{engine}. If an +#' For example, suppose the condition expression is `engine == 'Rcpp'`, the +#' object `engine` is the local chunk option `engine`. If an #' expression fails to be evaluated (e.g. when a certain object does not exist), -#' \code{FALSE} is returned and the label for this chunk will be filtered out. -#' @param ... A vector of R expressions, each of which should return \code{TRUE} -#' or \code{FALSE}. The expressions are evaluated using the \emph{local} chunk +#' `FALSE` is returned and the label for this chunk will be filtered out. +#' @param ... A vector of R expressions, each of which should return `TRUE` +#' or `FALSE`. The expressions are evaluated using the *local* chunk #' options of each code chunk as the environment, which means global chunk #' options are not considered when evaluating these expressions. For example, -#' if you set the global chunk option \code{opts_chunk$set(purl = TRUE)}, -#' \code{all_labels(purl == TRUE)} will \emph{not} return the labels of all +#' if you set the global chunk option `opts_chunk$set(purl = TRUE)`, +#' `all_labels(purl == TRUE)` will *not* return the labels of all #' code chunks, but will only return the labels of those code chunks that have -#' local chunk options \code{purl = TRUE}. +#' local chunk options `purl = TRUE`. #' @note Empty code chunks are always ignored, including those chunks that are #' empty in the original document but filled with code using chunk options -#' such as \code{ref.label} or \code{code}. +#' such as `ref.label` or `code`. #' @return A character vector. #' @export #' @examples # the examples below are meaningless unless you put them in a knitr document @@ -557,14 +557,13 @@ all_rcpp_labels = function(...) all_labels(expression(engine == 'Rcpp'), ...) #' Wrap code using the inline R expression syntax #' #' This is a convenience function to write the "source code" of inline R -#' expressions. For example, if you want to write \samp{`r 1+1`} literally in an -#' R Markdown document, you may write \samp{`` `r knitr::inline_expr('1+1')` -#' ``}; for Rnw documents, this may be -#' \samp{\verb|\Sexpr{knitr::inline_expr{'1+1'}}|}. +#' expressions. For example, if you want to write `` `r 1+1` `` literally in an +#' R Markdown document, you may write ``` `` `r knitr::inline_expr('1+1')` `` ```; +#' for Rnw documents, this may be `\Sexpr{knitr::inline_expr{'1+1'}}`. #' @param code Character string of the inline R source code. -#' @param syntax A character string to specify the syntax, e.g. \code{rnw}, -#' \code{html}, or \code{md}. If not specified, this will be guessed from -#' the knitting context. +#' @param syntax A character string to specify the syntax, e.g., `rnw`, +#' `html`, or `md`. If not specified, this will be guessed from the +#' knitting context. #' @return A character string marked up using the inline R code syntax. #' @export #' @examples library(knitr) @@ -596,59 +595,64 @@ inline_expr = function(code, syntax) { #' This is a helper function for moving chunk options from the chunk header to #' the chunk body using the new syntax. #' @param input File path to the document with code chunks to convert. -#' @param output The default \code{NULL} will output to console. Other values +#' @param output The default `NULL` will output to console. Other values #' can be a file path to write the converted content into or a function which -#' takes \code{input} as argument and returns a file path to write into (e.g., -#' \code{output = identity} to overwrite the input file). +#' takes `input` as argument and returns a file path to write into (e.g., +#' `output = identity` to overwrite the input file). #' @param type This determines how the in-body options will be formatted. -#' \code{"mutiline"} (the default, except for \file{qmd} documents, for which -#' the default is \code{"yaml"}) will write each chunk option on a separate +#' `"mutiline"` (the default, except for \file{qmd} documents, for which +#' the default is `"yaml"`) will write each chunk option on a separate #' line. Long chunk option values will be wrapped onto several lines, and you -#' can use \code{width = 0} to keep one line per option only. \code{"wrap"} +#' can use `width = 0` to keep one line per option only. `"wrap"` #' will wrap all chunk options together using -#' \code{\link[base:strwrap]{base::strwrap}()}. \code{"yaml"} will convert +#' [base::strwrap()]. `"yaml"` will convert #' chunk options to YAML. -#' @param width An integer passed to \code{base::strwrap()} for \code{type = -#' "wrap"} and \code{type = "multiline"}. If set to \code{0}, deactivate the -#' wrapping (for \code{type = "multiline"} only). -#' @return A character vector of converted \code{input} when \code{output = -#' NULL}. The output file path with converted content otherwise. +#' @param width An integer passed to `base::strwrap()` for `type = +#' "wrap"` and `type = "multiline"`. If set to `0`, deactivate the +#' wrapping (for `type = "multiline"` only). +#' @return A character vector of converted `input` when `output = +#' NULL`. The output file path with converted content otherwise. #' @note Learn more about the new chunk option syntax in -#' \url{https://yihui.org/en/2022/01/knitr-news/} +#' #' @section About \pkg{knitr} option syntax: #' #' Historical chunk option syntax have chunk option in the chunk header using #' valid R syntax. This is an example for \verb{.Rmd} document -#' \preformatted{ -#' ```\{r, echo = FALSE, fig.width: 10\} +#' +#' ```` +#' ```{r, echo = FALSE, fig.width = 10} #' ``` -#' } +#' ```` #' #' New syntax allows to pass option inside the chunk using several variants #' \itemize{ -#' \item Passing options one per line using valid R syntax. This corresponds to \code{convert_chunk_header(type = "multiline")}. -#' \preformatted{ -#' ```\{r\} +#' \item Passing options one per line using valid R syntax. This corresponds to `convert_chunk_header(type = "multiline")`. +#' +#' ```` +#' ```{r} #' #| echo = FALSE, #' #| fig.width = 10 #' ``` -#' } +#' ```` #' #' \item Passing option part from header in-chunk with several line if wrapping is -#' needed. This corresponds to \code{convert_chunk_header(type = "wrap")} -#' \preformatted{ -#' ```\{r\} +#' needed. This corresponds to `convert_chunk_header(type = "wrap")` +#' +#' ```` +#' ```{r} #' #| echo = FALSE, fig.width = 10 #' ``` -#' } +#' ```` #' \item Passing options key value pairs in-chunk using YAML syntax. Values are no #' more R expression but valid YAML syntax. This corresponds to -#' \code{convert_chunk_header(type = "yaml")} (not implement yet). -#' \preformatted{```\{r\} +#' `convert_chunk_header(type = "yaml")` (not implement yet). +#' +#' ```` +#' ```{r} #' #| echo: false, #' #| fig.width: 10 #' ``` -#' } +#' ```` #' } #' @examples #' knitr_example = function(...) system.file('examples', ..., package = 'knitr') diff --git a/R/pattern.R b/R/pattern.R index 25db468e86..eb6a6e7c71 100644 --- a/R/pattern.R +++ b/R/pattern.R @@ -1,7 +1,7 @@ #' All built-in patterns #' #' This object is a named list of all built-in patterns. -#' @references Usage: \url{https://yihui.org/knitr/patterns/} +#' @references Usage: #' @export #' @seealso \code{\link{knit_patterns}} #' @examples all_patterns$rnw; all_patterns$html @@ -71,15 +71,15 @@ all_patterns = list( #' Patterns to match and extract R code in a document #' #' Patterns are regular expressions and will be used in functions like -#' \code{base::\link{grep}()} to extract R code and chunk options. The object -#' \code{knit_patterns} controls the patterns currently used; see the references +#' [base::grep()] to extract R code and chunk options. The object +#' `knit_patterns` controls the patterns currently used; see the references #' and examples for usage. All built-in patterns are available in the list -#' \link{all_patterns}. +#' \code{\link{all_patterns}}. #' #' @seealso \code{\link{all_patterns}} -#' @references Usage: \url{https://yihui.org/knitr/objects/} +#' @references Usage: #' -#' Components in \code{knit_patterns}: \url{https://yihui.org/knitr/patterns/} +#' Components in `knit_patterns`: #' @export #' @examples library(knitr) #' opat = knit_patterns$get() # old pattern list (to restore later) @@ -110,7 +110,7 @@ set_pattern = function(type) { #' #' These are convenience functions to set pre-defined pattern lists (the syntax #' to read input documents). The function names are built from corresponding -#' file extensions, e.g. \code{pat_rnw()} can set the Sweave syntax to read Rnw +#' file extensions, e.g. `pat_rnw()` can set the Sweave syntax to read Rnw #' documents. #' @rdname pat_fun #' @return The patterns object \code{\link{knit_patterns}} is modified as a side diff --git a/R/plot.R b/R/plot.R index 93b4d05f4a..dbe4fddb65 100644 --- a/R/plot.R +++ b/R/plot.R @@ -256,8 +256,8 @@ merge_low_plot = function(x, idx = sapply(x, evaluate::is.recordedplot)) { #' #' Check if one plot only contains a low-level update of another plot. #' @param p1,p2 Plot objects. -#' @return Logical value indicating whether \code{p2} is a low-level update of -#' \code{p1}. +#' @return Logical value indicating whether `p2` is a low-level update of +#' `p1`. #' @export #' @examples #' pdf(NULL) @@ -336,24 +336,24 @@ fig_process = function(FUN, path, options) { #' #' The program \command{pdfcrop} (often shipped with a LaTeX distribution) is #' executed on a PDF plot file, and -#' \code{magick::\link[magick:transform]{image_trim}()} is executed for other +#' [magick::image_trim()] is executed for other #' types of plot files. #' #' The program \command{pdfcrop} can crop the extra white margins when the plot #' format is PDF, to make better use of the space in the output document, -#' otherwise we often have to struggle with \code{graphics::\link{par}()} to set +#' otherwise we often have to struggle with [graphics::par()] to set #' appropriate margins. Note \command{pdfcrop} often comes with a LaTeX #' distribution such as TinyTeX, MiKTeX, or TeX Live, and you may not need to -#' install it separately (use \code{Sys.which('pdfcrop')} to check it; if it not +#' install it separately (use `Sys.which('pdfcrop')` to check it; if it not #' empty, you are able to use it). Note that \command{pdfcrop} depends on #' GhostScript. You can check if GhostScript is installed via -#' \code{tools::find_gs_cmd()}. +#' `tools::find_gs_cmd()`. #' @param x Filename of the plot. #' @param quiet Whether to suppress standard output from the command. #' @export -#' @references PDFCrop: \url{https://www.ctan.org/pkg/pdfcrop}. If you use +#' @references PDFCrop: . If you use #' TinyTeX, you may install \command{pdfcrop} with -#' \code{tinytex::tlmgr_install('pdfcrop')}. +#' `tinytex::tlmgr_install('pdfcrop')`. #' @return The original filename. plot_crop = function(x, quiet = TRUE) { is_pdf = grepl('[.]pdf$', x, ignore.case = TRUE) @@ -418,25 +418,25 @@ par2 = function(x) { #' so you do not need to think if you have to use, for example, LaTeX or #' Markdown syntax, to embed an external image. Chunk options related to #' graphics output that work for normal R plots also work for these images, such -#' as \code{out.width} and \code{out.height}. +#' as `out.width` and `out.height`. #' @param path A character vector of image paths. Both local file paths and web -#' paths are supported. Note that the \code{auto_pdf} and \code{dpi} arguments +#' paths are supported. Note that the `auto_pdf` and `dpi` arguments #' are not supported for web paths. #' @param auto_pdf Whether to use PDF images automatically when the output -#' format is LaTeX. If \code{TRUE}, then e.g. \file{foo/bar.png} will be +#' format is LaTeX. If `TRUE`, then e.g. \file{foo/bar.png} will be #' replaced by \file{foo/bar.pdf} if the latter exists. This can be useful #' since normally PDF images are of higher quality than raster images like #' PNG, when the output is LaTeX/PDF. #' @param dpi DPI (dots per inch) value. Used to calculate the output width (in #' inches) of the images. This will be their actual width in pixels, divided -#' by \code{dpi}. If not provided, the chunk option \code{dpi} is used; if -#' \code{NA}, the output width will not be calculated. +#' by `dpi`. If not provided, the chunk option `dpi` is used; if +#' `NA`, the output width will not be calculated. #' @param rel_path Whether to automatically convert absolute paths to relative #' paths. If you know for sure that absolute paths work, you may set this -#' argument or the global option \code{knitr.graphics.rel_path} to -#' \code{FALSE}. +#' argument or the global option `knitr.graphics.rel_path` to +#' `FALSE`. #' @param error Whether to signal an error if any files specified in the -#' \code{path} argument do not exist and are not web resources. +#' `path` argument do not exist and are not web resources. #' @note This function is supposed to be used in R code chunks or inline R code #' expressions. For local images, you are recommended to use relative paths #' with forward slashes instead of backslashes (e.g., \file{images/fig1.png} @@ -444,9 +444,9 @@ par2 = function(x) { #' #' The automatic calculation of the output width requires the \pkg{png} #' package (for PNG images) or the \pkg{jpeg} package (for JPEG images). The -#' width will not be calculated if the chunk option \code{out.width} is -#' already provided or \code{dpi = NA}. -#' @return The same as the input character vector \code{path} but it is marked +#' width will not be calculated if the chunk option `out.width` is +#' already provided or `dpi = NA`. +#' @return The same as the input character vector `path` but it is marked #' with special internal S3 classes so that \pkg{knitr} will convert the file #' paths to proper output code according to the output format. #' @export @@ -496,8 +496,8 @@ include_graphics = function( #' #' When including images in non-HTML output formats such as LaTeX/PDF, URLs will #' not work as image paths. In this case, we have to download the images. This -#' function is a wrapper of \code{xfun::\link[xfun]{download_file}()} and -#' \code{\link{include_graphics}()}. +#' function is a wrapper of [xfun::download_file()] and +#' [include_graphics()]. #' @param url The URL of an image. #' @param path The download path (inferred from the URL by default). If the file #' exists, it will not be downloaded (downloading can take time and requires @@ -506,7 +506,7 @@ include_graphics = function( #' @param use_file Whether to use the URL or the download path to include the #' image. By default, the URL is used for HTML output formats, and the file #' path is used for other output formats. -#' @param ... Other arguments to be passed to \code{\link{include_graphics}()}. +#' @param ... Other arguments to be passed to [include_graphics()]. #' @export #' @examplesIf interactive() #' knitr::download_image('https://www.r-project.org/Rlogo.png') @@ -541,16 +541,16 @@ raster_dpi_width = function(path, dpi) { #' Embed a URL as an HTML iframe or a screenshot in \pkg{knitr} documents #' -#' When the output format is HTML, \code{include_url()} inserts an iframe in the +#' When the output format is HTML, `include_url()` inserts an iframe in the #' output; otherwise it takes a screenshot of the URL and insert the image in -#' the output. \code{include_app()} takes the URL of a Shiny app and adds -#' \samp{?showcase=0} to it (to disable the showcase mode), then passes the URL -#' to \code{include_url()}. +#' the output. `include_app()` takes the URL of a Shiny app and adds +#' `?showcase=0` to it (to disable the showcase mode), then passes the URL +#' to `include_url()`. #' @param url A character vector of URLs. #' @param height A character vector to specify the height of iframes. #' @return An R object with a special class that \pkg{knitr} recognizes #' internally to generate the iframes or screenshots. -#' @seealso \code{\link{include_graphics}} +#' @seealso [include_graphics()] #' @export include_url = function(url, height = '400px') { include_url2(url, height) diff --git a/R/rocco.R b/R/rocco.R index d25f3c6554..64395db1b4 100644 --- a/R/rocco.R +++ b/R/rocco.R @@ -6,14 +6,14 @@ #' The output HTML page supports resizing and hiding/showing the two columns. #' Move the cursor to the center of the page, and it will change to a #' bidirectional resize cursor; drag the cursor to resize the two columns. Press -#' the key \code{t} to hide the code column (show the text column only), and +#' the key `t` to hide the code column (show the text column only), and #' press again to hide the text column (show code). #' @param input Path of the input R Markdown file. -#' @param ... Arguments to be passed to \code{\link{knit2html}} +#' @param ... Arguments to be passed to [knit2html()] #' @return An HTML file is written, and its name is returned. #' @author Weicheng Zhu and Yihui Xie #' @references The Docco package by Jeremy Ashkenas: -#' \url{https://github.com/jashkenas/docco} +#' #' @export #' @examples rocco_view=function(input) { #' owd = setwd(tempdir()); on.exit(setwd(owd)) diff --git a/R/spin.R b/R/spin.R index 01f001d592..5099544ff5 100644 --- a/R/spin.R +++ b/R/spin.R @@ -2,52 +2,52 @@ #' #' This function takes a specially formatted R script and converts it to a #' literate programming document. By default normal text (documentation) should -#' be written after the roxygen comment (\code{#'}) and code chunk options are -#' written after \code{#|} or \code{#+} or \code{# \%\%} or \code{# ----}. +#' be written after the roxygen comment (`#'`) and code chunk options are +#' written after `#|` or `#+` or `# \%\%` or `# ----`. #' #' Obviously the goat's hair is the original R script, and the wool is the #' literate programming document (ready to be knitted). #' @param hair Path to the R script. The script must be encoded in UTF-8 if it #' contains multibyte characters. -#' @param knit Logical; whether to compile the document after conversion. -#' @param report Logical; whether to generate a report for \file{Rmd}, -#' \file{Rnw} and \file{Rtex} output. Ignored if \code{knit = FALSE}. +#' @param knit Whether to compile the document after conversion. +#' @param report Whether to generate a report for \file{Rmd}, \file{Rnw}, and +#' \file{Rtex} output. Ignored if `knit = FALSE`. #' @param text A character vector of code, as an alternative way to provide the -#' R source. If \code{text} is not \code{NULL}, \code{hair} will be ignored. -#' @param envir Environment for \code{\link{knit}()} to evaluate the code. +#' R source. If `text` is not `NULL`, `hair` will be ignored. +#' @param envir Environment for [knit()] to evaluate the code. #' @param format Character; the output format. The default is R Markdown. #' @param doc A regular expression to identify the documentation lines; by #' default it follows the roxygen convention, but it can be customized, e.g. -#' if you want to use \code{##} to denote documentation, you can use -#' \code{'^##\\\\s*'}. +#' if you want to use `##` to denote documentation, you can use +#' `'^##\\\\s*'`. #' @param inline A regular expression to identify inline R expressions; by -#' default, code of the form \code{\{\{code\}\}} on its own line is treated as +#' default, code of the form `{{code}}` on its own line is treated as #' an inline expression. #' @param comment A pair of regular expressions for the start and end delimiters #' of comments; the lines between a start and an end delimiter will be #' ignored. By default, the delimiters are \verb{/*} at the beginning of a #' line, and \verb{*/} at the end, following the convention of C comments. -#' @param precious logical: whether intermediate files (e.g., \code{.Rmd} files -#' when \code{format} is \code{"Rmd"}) should be preserved. The default is -#' \code{FALSE} if \code{knit} is \code{TRUE} and the input is a file. +#' @param precious Whether to preserve intermediate files (e.g., `.Rmd` +#' files when `format` is `"Rmd"`). The default is `FALSE` if +#' `knit` is `TRUE` and the input is a file. #' @author Yihui Xie, with the original idea from Richard FitzJohn (who named it -#' as \code{sowsear()} which meant to make a silk purse out of a sow's ear) -#' @return If \code{text} is \code{NULL}, the path of the final output document, +#' as `sowsear()` which meant to make a silk purse out of a sow's ear) +#' @return If `text` is `NULL`, the path of the final output document, #' otherwise the content of the output. -#' @note If the output format is \code{Rnw} and no document class is specified +#' @note If the output format is `Rnw` and no document class is specified #' in roxygen comments, this function will automatically add the -#' \code{article} class to the LaTeX document so that it is complete and can +#' `article` class to the LaTeX document so that it is complete and can #' be compiled. You can always specify the document class and other LaTeX #' settings in roxygen comments manually. #' -#' When the output format is \code{Rmd}, it is compiled to HTML via -#' \code{\link{knit2html}()}, which uses R Markdown v1 instead of v2. If you +#' When the output format is `Rmd`, it is compiled to HTML via +#' [knit2html()], which uses R Markdown v1 instead of v2. If you #' want to use the latter, you should call -#' \code{rmarkdown::\link[rmarkdown]{render}()} instead. Similarly, if the -#' output format is \code{qmd}, you need to render the output with Quarto. +#' [rmarkdown::render()] instead. Similarly, if the +#' output format is `qmd`, you need to render the output with Quarto. #' @export -#' @seealso \code{\link{stitch}} (feed a template with an R script) -#' @references \url{https://yihui.org/knitr/demo/stitch/} +#' @seealso [stitch()] (feed a template with an R script) +#' @references spin = function( hair, knit = TRUE, report = TRUE, text = NULL, envir = parent.frame(), format = c('Rmd', 'Rnw', 'Rhtml', 'Rtex', 'Rrst', 'qmd'), @@ -177,16 +177,16 @@ pipe_comment_start = function(x) { #' Spin a child R script #' -#' This function is similar to \code{\link{knit_child}()} but is used in R +#' This function is similar to [knit_child()] but is used in R #' scripts instead. When the main R script is not called via -#' \code{\link{spin}()}, this function simply executes the child script via -#' \code{\link{sys.source}()}, otherwise it calls \code{\link{spin}()} to spin -#' the child script into a source document, and uses \code{\link{knit_child}()} +#' [spin()], this function simply executes the child script via +#' [sys.source()], otherwise it calls [spin()] to spin +#' the child script into a source document, and uses [knit_child()] #' to compile it. You can call this function in R code, or using the syntax of -#' inline R expressions in \code{\link{spin}()} (e.g. -#' \code{{{knitr::spin_child('script.R')}}}). +#' inline R expressions in [spin()] (e.g. +#' `{{knitr::spin_child('script.R')}}`). #' @param input Filename of the input R script. -#' @param format Passed to \code{format} in \code{spin()}. If not +#' @param format Passed to `format` in `spin()`. If not #' provided, it will be guessed from the current knitting process. #' @return A character string of the knitted R script. #' @export diff --git a/R/table.R b/R/table.R index a77f82e674..d5c23e3f15 100644 --- a/R/table.R +++ b/R/table.R @@ -1,53 +1,53 @@ #' Create tables in LaTeX, HTML, Markdown and reStructuredText #' #' A very simple table generator, and it is simple by design. It is not intended -#' to replace any other R packages for making tables. The \code{kable()} +#' to replace any other R packages for making tables. The `kable()` #' function returns a single table for a single data object, and returns a table #' that contains multiple tables if the input object is a list of data objects. -#' The \code{kables()} function is similar to \code{kable(x)} when \code{x} is a -#' list of data objects, but \code{kables()} accepts a list of \code{kable()} +#' The `kables()` function is similar to `kable(x)` when `x` is a +#' list of data objects, but `kables()` accepts a list of `kable()` #' values directly instead of data objects (see examples below). #' -#' Missing values (\code{NA}) in the table are displayed as \code{NA} by +#' Missing values (`NA`) in the table are displayed as `NA` by #' default. If you want to display them with other characters, you can set the -#' option \code{knitr.kable.NA}, e.g. \code{options(knitr.kable.NA = '')} to -#' hide \code{NA} values. +#' option `knitr.kable.NA`, e.g. `options(knitr.kable.NA = '')` to +#' hide `NA` values. #' -#' You can set the option \code{knitr.kable.max_rows} to limit the number of -#' rows to show in the table, e.g., \code{options(knitr.kable.max_rows = 30)}. -#' @param x For \code{kable()}, \code{x} is an R object, which is typically a -#' matrix or data frame. For \code{kables()}, a list with each element being a -#' returned value from \code{kable()}. -#' @param format A character string. Possible values are \code{latex}, -#' \code{html}, \code{pipe} (Pandoc's pipe tables), \code{simple} (Pandoc's -#' simple tables), \code{rst}, \code{jira}, and \code{org} (Emacs Org-mode). +#' You can set the option `knitr.kable.max_rows` to limit the number of +#' rows to show in the table, e.g., `options(knitr.kable.max_rows = 30)`. +#' @param x For `kable()`, `x` is an R object, which is typically a +#' matrix or data frame. For `kables()`, a list with each element being a +#' returned value from `kable()`. +#' @param format A character string. Possible values are `latex`, +#' `html`, `pipe` (Pandoc's pipe tables), `simple` (Pandoc's +#' simple tables), `rst`, `jira`, and `org` (Emacs Org-mode). #' The value of this argument will be automatically determined if the function -#' is called within a \pkg{knitr} document. The \code{format} value can also -#' be set in the global option \code{knitr.table.format}. If \code{format} is +#' is called within a \pkg{knitr} document. The `format` value can also +#' be set in the global option `knitr.table.format`. If `format` is #' a function, it must return a character string. #' @param digits Maximum number of digits for numeric columns, passed to -#' \code{round()}. This can also be a vector of length \code{ncol(x)}, to set +#' `round()`. This can also be a vector of length `ncol(x)`, to set #' the number of digits for individual columns. -#' @param row.names Logical: whether to include row names. By default, row names -#' are included if \code{rownames(x)} is neither \code{NULL} nor identical to -#' \code{1:nrow(x)}. +#' @param row.names Whether to include row names. By default, row names are +#' included if `rownames(x)` is neither `NULL` nor identical to +#' `1:nrow(x)`. #' @param col.names A character vector of column names to be used in the table. -#' @param align Column alignment: a character vector consisting of \code{'l'} -#' (left), \code{'c'} (center) and/or \code{'r'} (right). By default or if -#' \code{align = NULL}, numeric columns are right-aligned, and other columns -#' are left-aligned. If \code{length(align) == 1L}, the string will be -#' expanded to a vector of individual letters, e.g. \code{'clc'} becomes -#' \code{c('c', 'l', 'c')}, unless the output format is LaTeX. +#' @param align Column alignment: a character vector consisting of `'l'` +#' (left), `'c'` (center) and/or `'r'` (right). By default or if +#' `align = NULL`, numeric columns are right-aligned, and other columns +#' are left-aligned. If `length(align) == 1L`, the string will be +#' expanded to a vector of individual letters, e.g. `'clc'` becomes +#' `c('c', 'l', 'c')`, unless the output format is LaTeX. #' @param caption The table caption. By default, it is retrieved from the chunk -#' option \code{tab.cap}. +#' option `tab.cap`. #' @param label The table reference label. By default, the label is obtained #' from \code{knitr::\link{opts_current}$get('label')} (i.e., the current -#' chunk label). To disable the label, use \code{label = NA}. -#' @param format.args A list of arguments to be passed to \code{\link{format}()} -#' to format table values, e.g. \code{list(big.mark = ',')}. -#' @param escape Boolean; whether to escape special characters when producing -#' HTML or LaTeX tables. When \code{escape = FALSE}, you have to make sure -#' that special characters will not trigger syntax errors in LaTeX or HTML. +#' chunk label). To disable the label, use `label = NA`. +#' @param format.args A list of arguments to be passed to [format()] +#' to format table values, e.g. `list(big.mark = ',')`. +#' @param escape Whether to escape special characters when producing HTML or +#' LaTeX tables. When `escape = FALSE`, you have to make sure that +#' special characters will not trigger syntax errors in LaTeX or HTML. #' @param ... Other arguments (see Examples and References). #' @return A character vector of the table source code. #' @seealso Other R packages such as \pkg{huxtable}, \pkg{xtable}, @@ -55,15 +55,15 @@ #' \pkg{ascii} and \pkg{pander} for different flavors of markdown output and #' some advanced features and table styles. For more on other packages for #' creating tables, see -#' \url{https://bookdown.org/yihui/rmarkdown-cookbook/table-other.html}. -#' @note When using \code{kable()} as a \emph{top-level} expression, you do not -#' need to explicitly \code{print()} it due to R's automatic implicit +#' . +#' @note When using `kable()` as a *top-level* expression, you do not +#' need to explicitly `print()` it due to R's automatic implicit #' printing. When it is wrapped inside other expressions (such as a -#' \code{\link{for}} loop), you must explicitly \code{print(kable(...))}. +#' `for` loop), you must explicitly `print(kable(...))`. #' @references See -#' \url{https://bookdown.org/yihui/rmarkdown-cookbook/kable.html} for some +#' for some #' examples about this function, including specific arguments according to the -#' \code{format} selected. +#' `format` selected. #' @export #' @examples d1 = head(iris); d2 = head(mtcars) #' # pipe tables by default diff --git a/R/template.R b/R/template.R index 77221942e3..8a7c31b4bf 100644 --- a/R/template.R +++ b/R/template.R @@ -2,27 +2,27 @@ #' #' This is a convenience function for small-scale automatic reporting based on #' an R script and a template. The default template is an Rnw file (LaTeX); -#' \code{stitch_rhtml()} and \code{stitch_rmd()} are wrappers on top of -#' \code{stitch()} using the R HTML and R Markdown templates respectively. +#' `stitch_rhtml()` and `stitch_rmd()` are wrappers on top of +#' `stitch()` using the R HTML and R Markdown templates respectively. #' #' The first two lines of the R script can contain the title and author of the -#' report in comments of the form \samp{## title:} and \samp{## author:}. The -#' template must have a token \samp{\%sCHUNK_LABEL_HERE}, which will be used to +#' report in comments of the form `## title:` and `## author:`. The +#' template must have a token `\%sCHUNK_LABEL_HERE`, which will be used to #' input all the R code from the script. See the examples below. #' -#' The R script may contain chunk headers of the form \samp{## ---- label, -#' opt1=val1, opt2=val2}, which will be copied to the template; if no chunk +#' The R script may contain chunk headers of the form +#' `## ---- label, opt1=val1, opt2=val2`, which will be copied to the template; if no chunk #' headers are found, the whole R script will be inserted into the template as #' one code chunk. #' @param script Path to the R script. #' @param template Path of the template to use. By default, the Rnw template in #' this package; there is also an HTML template in \pkg{knitr}. -#' @param output Output filename, passed to \code{\link{knit}}). By default, +#' @param output Output filename, passed to [knit()]). By default, #' the base filename of the script is used. #' @inheritParams knit #' @return path of the output document #' @export -#' @seealso \code{\link{spin}} (turn a specially formatted R script to a report) +#' @seealso [spin()] (turn a specially formatted R script to a report) #' @examples s = system.file('misc', 'stitch-test.R', package = 'knitr') #' if (interactive()) stitch(s) # compile to PDF #' @@ -77,7 +77,7 @@ stitch = function(script, out } #' @rdname stitch -#' @param ... Arguments passed to \code{stitch()}. +#' @param ... Arguments passed to `stitch()`. #' @export stitch_rhtml = function(..., envir = parent.frame()) stitch( ..., envir = envir, @@ -93,20 +93,20 @@ stitch_rmd = function(..., envir = parent.frame()) stitch( #' A simple macro preprocessor for templating purposes #' -#' This function expands a template based on the R expressions in \code{{{}}} -#' (this tag can be customized by the \code{delim} argument). These expressions +#' This function expands a template based on the R expressions in `{{}}` +#' (this tag can be customized by the `delim` argument). These expressions #' are extracted, evaluated and replaced by their values in the original #' template. #' @param file The template file. #' @param ... A list of variables to be used for the code in the template; note that #' the variables will be searched for in the parent frame as well. #' @param text Character vector of lines of code. An alternative way to specify -#' the template code directly. If \code{text} is provided, \code{file} will be ignored. +#' the template code directly. If `text` is provided, `file` will be ignored. #' @param delim A pair of opening and closing delimiters for the templating tags. #' @return A character vector, with the tags evaluated and replaced by their #' values. #' @references This function was inspired by the pyexpander and m4 -#' (\url{http://www.gnu.org/software/m4/}), thanks to Frank Harrell. +#' (), thanks to Frank Harrell. #' @export #' @examples # see the knit_expand vignette #' if (interactive()) browseVignettes(package='knitr') diff --git a/R/themes.R b/R/themes.R index 593b7b76bf..c8e34c7b8c 100644 --- a/R/themes.R +++ b/R/themes.R @@ -22,18 +22,18 @@ get_theme = function(theme = NULL) { #' This object can be used to set or get themes in \pkg{knitr} for syntax #' highlighting. #' -#' We can use \code{knit_theme$set(theme)} to set the theme, and -#' \code{knit_theme$get(theme)} to get a theme. The \code{theme} is a character +#' We can use `knit_theme$set(theme)` to set the theme, and +#' `knit_theme$get(theme)` to get a theme. The `theme` is a character #' string for both methods (either the name of the theme, or the path to the CSS -#' file of a theme), and for the \code{set()} method, it can also be a list -#' returned by the \code{get()} method. See examples below. +#' file of a theme), and for the `set()` method, it can also be a list +#' returned by the `get()` method. See examples below. #' @author Ramnath Vaidyanathan and Yihui Xie #' @references For a preview of all themes, see -#' \url{https://gist.github.com/yihui/3422133}. +#' . #' @note The syntax highlighting here only applies to \file{.Rnw} (LaTeX) and #' \file{.Rhtml} (HTML) documents, and it does not work for other types of #' documents, such as \file{.Rmd} (R Markdown, which has its own syntax -#' highlighting themes; see \url{https://rmarkdown.rstudio.com}). +#' highlighting themes; see ). #' @export #' @examples opts_knit$set(out.format='latex'); knit_theme$set('edit-vim') #' diff --git a/R/utils-conversion.R b/R/utils-conversion.R index 66d1958cba..d46367cb1d 100644 --- a/R/utils-conversion.R +++ b/R/utils-conversion.R @@ -6,32 +6,32 @@ #' @param command Character string giving the path of the #' \command{rst2pdf} program. If the program is not in your PATH, the full path has to be #' given here. -#' @param options Extra command line options, e.g. \code{'-v'}. +#' @param options Extra command line options, e.g., `'-v'`. #' @author Alex Zvoleff and Yihui Xie #' @return An input file \file{*.rst} will produce \file{*.pdf} and this output #' filename is returned if the conversion was successful. #' @export -#' @seealso \code{\link{knit2pdf}} -#' @references \url{https://github.com/rst2pdf/rst2pdf} +#' @seealso [knit2pdf()] +#' @references rst2pdf = function(input, command = 'rst2pdf', options = '') { out = with_ext(input, 'pdf') system2(command, paste(shQuote(input), '-o', shQuote(out), options)) if (file.exists(out)) out else stop('conversion by rst2pdf failed!') } -#' Convert various input files to various output files using \code{knit()} and +#' Convert various input files to various output files using `knit()` and #' Pandoc #' #' Knits the input file and compiles to an output format using Pandoc. #' @inheritParams knit #' @param to Character string giving the Pandoc output format to use. -#' @param pandoc_wrapper An R function used to call Pandoc. If \code{NULL} (the -#' default), \code{rmarkdown::\link[rmarkdown]{pandoc_convert}()} will be used -#' if \pkg{rmarkdown} is installed, otherwise \code{\link{pandoc}()}. -#' @param ... Options to be passed to the \code{pandoc_wrapper} function. +#' @param pandoc_wrapper An R function used to call Pandoc. If `NULL` (the +#' default), [rmarkdown::pandoc_convert()] will be used +#' if \pkg{rmarkdown} is installed, otherwise [pandoc()]. +#' @param ... Options to be passed to the `pandoc_wrapper` function. #' @param encoding Ignored (always assumes UTF-8). #' @author Trevor L. Davis -#' @return Returns the output of the \code{pandoc_wrapper} function. +#' @return Returns the output of the `pandoc_wrapper` function. #' @export knit2pandoc = function( input, output = NULL, tangle = FALSE, text = NULL, quiet = FALSE, @@ -47,19 +47,19 @@ knit2pandoc = function( #' Convert Rnw or Rrst files to PDF #' #' Knit the input Rnw or Rrst document, and compile to PDF using -#' \code{tinytex::\link[tinytex]{latexmk}()} or \code{\link{rst2pdf}()}. +#' [tinytex::latexmk()] or [rst2pdf()]. #' @inheritParams knit #' @param compiler A character string giving the LaTeX engine used to compile -#' the tex document to PDF. For an Rrst file, setting \code{compiler} to -#' \code{'rst2pdf'} will use \code{\link{rst2pdf}} to compile the rst file to +#' the tex document to PDF. For an Rrst file, setting `compiler` to +#' `'rst2pdf'` will use [rst2pdf()] to compile the rst file to #' PDF using the ReportLab open-source library. For an Rtyp file, setting -#' \code{compiler} to \code{'typst'} will use the \command{typst} command-line +#' `compiler` to `'typst'` will use the \command{typst} command-line #' tool to compile the typ file to PDF. -#' @param ... Options to be passed to \code{tinytex::\link[tinytex]{latexmk}()} -#' or \code{\link{rst2pdf}()}. +#' @param ... Options to be passed to [tinytex::latexmk()] +#' or [rst2pdf()]. #' @author Ramnath Vaidyanathan, Alex Zvoleff and Yihui Xie #' @return The filename of the PDF file. -#' @note The \code{output} argument specifies the output filename to be passed +#' @note The `output` argument specifies the output filename to be passed #' to the PDF compiler (e.g. a tex document) instead of the PDF filename. #' @export #' @examples #' compile with xelatex @@ -100,28 +100,28 @@ knit2pdf = function( #' Convert an \file{Rnw} document to PDF #' -#' Call \code{\link{knit}()} to compile the \file{.Rnw} input to \file{.tex}, -#' and then \code{tinytex::\link[tinytex]{latexmk}()} to convert \file{.tex} to +#' Call [knit()] to compile the \file{.Rnw} input to \file{.tex}, +#' and then [tinytex::latexmk()] to convert \file{.tex} to #' \file{.pdf}. #' -#' This function is similar to \code{\link{knit2pdf}()}, with the following differences: +#' This function is similar to [knit2pdf()], with the following differences: #' \enumerate{ #' \item The default compiler is "xelatex" instead of "pdflatex". -#' \item \code{output} uses the file extension ".pdf" instead of ".tex". -#' \item Before knitting, it tries to remove the \code{output} file and will throw a clear error if the file cannot be removed. -#' \item \code{output} could be under any dir, not necessarily the same directory as \code{input}. +#' \item `output` uses the file extension ".pdf" instead of ".tex". +#' \item Before knitting, it tries to remove the `output` file and will throw a clear error if the file cannot be removed. +#' \item `output` could be under any dir, not necessarily the same directory as `input`. #' \item It cleans up intermediate files by default, including the ".tex" file. -#' \item It stops knitting when any error occurs (by setting the chunk option \code{error = FALSE}). +#' \item It stops knitting when any error occurs (by setting the chunk option `error = FALSE`). #' } #' @inheritParams knit #' @param output Path of the PDF output file. By default, it uses the same name -#' as the \code{input}, but changes the file extension to ".pdf". +#' as the `input`, but changes the file extension to ".pdf". #' @param compiler,... The LaTeX engine and other arguments to be passed to -#' \code{tinytex::\link[tinytex]{latexmk}()}. The default compiler is -#' \code{xelatex}. -#' @param clean If \code{TRUE}, the intermediate files will be removed. -#' @param error If \code{FALSE}, knitting stops when any error occurs. -#' @return The \code{output} file path. +#' [tinytex::latexmk()]. The default compiler is +#' `xelatex`. +#' @param clean If `TRUE`, the intermediate files will be removed. +#' @param error If `FALSE`, knitting stops when any error occurs. +#' @return The `output` file path. #' @export rnw2pdf = function( input, output = with_ext(input, 'pdf'), compiler = 'xelatex', @@ -155,22 +155,22 @@ mark_html = function(..., template = TRUE) { #' Convert markdown to HTML using knit() and litedown::mark() #' #' This is a convenience function to knit the input markdown source and call -#' \code{litedown::\link[litedown]{mark}()} to convert the result to HTML. +#' [litedown::mark()] to convert the result to HTML. #' @inheritParams knit -#' @param ... Options passed to \code{litedown::\link[litedown]{mark}()}. -#' @param force_v1 Boolean; whether to force rendering the input document as an -#' R Markdown v1 document, even if it is for v2. +#' @param ... Options passed to [litedown::mark()]. +#' @param force_v1 Whether to force rendering the input document as an R +#' Markdown v1 document, even if it is for v2. #' @export -#' @seealso \code{\link{knit}}, \code{litedown::\link[litedown]{mark}} -#' @return If the argument \code{text} is NULL, a character string (HTML code) +#' @seealso [knit()], [litedown::mark()] +#' @return If the argument `text` is NULL, a character string (HTML code) #' is returned; otherwise the result is written into a file and the filename #' is returned. #' @note This function renders R Markdown v1, which is much less powerful than R #' Markdown v2, i.e. the \pkg{rmarkdown} package -#' (\url{https://rmarkdown.rstudio.com}). To render R Markdown v2 documents to -#' HTML, please use \code{rmarkdown::render()} instead. For a lighter-weight +#' (). To render R Markdown v2 documents to +#' HTML, please use `rmarkdown::render()` instead. For a lighter-weight #' alternative that handles figure paths robustly, see -#' \code{litedown::\link[litedown]{fuse}()}. +#' [litedown::fuse()]. #' @examples # a minimal example #' writeLines(c("# hello markdown", '```{r hello-random, echo=TRUE}', 'rnorm(5)', '```'), 'test.Rmd') #' knit2html('test.Rmd') @@ -220,25 +220,26 @@ knit2html = function( #' This function is a wrapper around the \pkg{RWordPress} package. It compiles #' an R Markdown document to HTML and post the results to WordPress. Please note #' that \pkg{RWordPress} has not been updated for several years, which is -#' \href{https://github.com/yihui/knitr/issues/1866}{not a good sign}. For +#' [not a good sign](https://github.com/yihui/knitr/issues/1866). For #' blogging with R, you may want to try the \pkg{blogdown} package instead. #' @param input Filename of the Rmd document. #' @param title Title of the post. -#' @param ... Other meta information of the post, e.g. \code{categories = c('R', -#' 'Stats')} and \code{mt_keywords = c('knitr', 'wordpress')}, et cetera. -#' @param shortcode A length-2 logical vector: whether to use the shortcode -#' \samp{[sourcecode lang='lang']}, which can be useful to WordPress.com users -#' for syntax highlighting of source code and output. The first element +#' @param ... Other meta information of the post, e.g., `categories = +#' c('R', 'Stats')` and `mt_keywords = c('knitr', 'wordpress')`, etc. +#' @param shortcode A length-2 logical vector indicating whether to use the +#' shortcode `[sourcecode lang='lang']`, which can be useful to +#' WordPress.com users for syntax highlighting of source code and output. The +#' first element #' applies to source code, and the second applies to text output. By default, -#' both are \code{FALSE}. +#' both are `FALSE`. #' @param action Whether to create a new post, update an existing post, or #' create a new page. -#' @param postid If \code{action} is \code{editPost}, the post id \code{postid} +#' @param postid If `action` is `editPost`, the post id `postid` #' must be specified. -#' @param publish Boolean: publish the post immediately? +#' @param publish Whether to publish the post immediately. #' @inheritParams knit #' @export -#' @references \url{https://yihui.org/knitr/demo/wordpress/} +#' @references #' @author William K. Morris, Yihui Xie, and Jared Lander #' @note This function will convert the encoding of the post and the title to #' UTF-8 internally. If you have additional data to send to WordPress (e.g. @@ -300,16 +301,16 @@ knit2wp = function( #' recompile the input file. #' #' This is actually a general function not necessarily restricted to -#' applications in \pkg{knitr}. You may specify any \code{compile} function to -#' process the \code{input} file. To stop the infinite loop, press the -#' \samp{Escape} key or \samp{Ctrl + C} (depending on your editing environment +#' applications in \pkg{knitr}. You may specify any `compile` function to +#' process the `input` file. To stop the infinite loop, press the +#' `Escape` key or `Ctrl + C` (depending on your editing environment #' and operating system). #' @param input An input file path, or a character vector of multiple input file paths. -#' @param compile A function to compile the \code{input} file. This could be e.g. -#' \code{\link{knit}} or \code{\link{knit2pdf}}, depending on the input file +#' @param compile A function to compile the `input` file. This could be e.g. +#' [knit()] or [knit2pdf()], depending on the input file #' and the output you want. #' @param interval A time interval to pause in each cycle of the infinite loop. -#' @param ... Other arguments to be passed to the \code{compile} function. +#' @param ... Other arguments to be passed to the `compile` function. #' @export #' @examples # knit_watch('foo.Rnw', knit2pdf) #' diff --git a/R/utils-rd2html.R b/R/utils-rd2html.R index a440f3095e..c449cd2e1b 100644 --- a/R/utils-rd2html.R +++ b/R/utils-rd2html.R @@ -1,19 +1,19 @@ #' Knit package documentation #' #' Run examples in a package and insert output into the examples code; -#' \code{knit_rd_all()} is a wrapper around \code{knit_rd()} to build static +#' `knit_rd_all()` is a wrapper around `knit_rd()` to build static #' HTML help pages for all packages under the \file{html} directory of them. #' @param pkg Package name. #' @param links A character vector of links to be passed to -#' \code{tools::\link{Rd2HTML}()}. -#' @param frame Boolean: whether to put a navigation frame on the left of the -#' index page. +#' [tools::Rd2HTML()]. +#' @param frame Whether to put a navigation frame on the left of the index +#' page. #' @return All HTML pages corresponding to topics in the package are written #' under the current working directory. An \file{index.html} is also written #' as a table of content. #' @note Ideally the html pages should be put under the \file{html} directory of -#' an installed package which can be found via \code{system.file('html', -#' package = 'your_package_name')}, otherwise some links may not work (e.g. +#' an installed package which can be found via `system.file('html', +#' package = 'your_package_name')`, otherwise some links may not work (e.g. #' the link to the DESCRIPTION file). #' @examples library(knitr) #' \dontrun{ diff --git a/R/utils-sweave.R b/R/utils-sweave.R index 38a9fc3685..af21c3e524 100644 --- a/R/utils-sweave.R +++ b/R/utils-sweave.R @@ -3,52 +3,52 @@ #' This function converts an Sweave document to a \pkg{knitr}-compatible #' document. #' -#' The pseudo command \samp{\\SweaveInput{file.Rnw}} is converted to a code -#' chunk header \code{<>=}. +#' The pseudo command `\SweaveInput{file.Rnw}` is converted to a code +#' chunk header `<>=`. #' -#' Similarly \samp{\\SweaveOpts{opt = value}} is converted to a code chunk -#' \samp{opts_chunk$set(opt = value)} with the chunk option \code{include = -#' FALSE}; the options are automatically fixed in the same way as local chunk +#' Similarly `\SweaveOpts{opt = value}` is converted to a code chunk +#' `opts_chunk$set(opt = value)` with the chunk option `include = +#' FALSE`; the options are automatically fixed in the same way as local chunk #' options (explained below). #' -#' The Sweave package \samp{\\usepackage{Sweave}} in the preamble is removed +#' The Sweave package `\usepackage{Sweave}` in the preamble is removed #' because it is not required. #' -#' Chunk options are updated if necessary: option values \code{true} and -#' \code{false} are changed to \code{TRUE} and \code{FALSE} respectively; -#' \code{fig=TRUE} is removed because it is not necessary for \pkg{knitr} (plots -#' will be automatically generated); \code{fig=FALSE} is changed to -#' \code{fig.keep='none'}; the devices \code{pdf/jpeg/png/eps/tikz=TRUE} are -#' converted to \code{dev='pdf'/'jpeg'/'png'/'postscript'/'tikz'}; -#' \code{pdf/jpeg/png/eps/tikz=FALSE} are removed; -#' \code{results=tex/verbatim/hide} are changed to -#' \code{results='asis'/'markup'/'hide'}; \code{width/height} are changed to -#' \code{fig.width/fig.height}; \code{prefix.string} is changed to -#' \code{fig.path}; \code{print/term/prefix=TRUE/FALSE} are removed; most of the -#' character options (e.g. \code{engine} and \code{out.width}) are quoted; -#' \code{keep.source=TRUE/FALSE} is changed to \code{tidy=FALSE/TRUE} (note the +#' Chunk options are updated if necessary: option values `true` and +#' `false` are changed to `TRUE` and `FALSE` respectively; +#' `fig=TRUE` is removed because it is not necessary for \pkg{knitr} (plots +#' will be automatically generated); `fig=FALSE` is changed to +#' `fig.keep='none'`; the devices `pdf/jpeg/png/eps/tikz=TRUE` are +#' converted to `dev='pdf'/'jpeg'/'png'/'postscript'/'tikz'`; +#' `pdf/jpeg/png/eps/tikz=FALSE` are removed; +#' `results=tex/verbatim/hide` are changed to +#' `results='asis'/'markup'/'hide'`; `width/height` are changed to +#' `fig.width/fig.height`; `prefix.string` is changed to +#' `fig.path`; `print/term/prefix=TRUE/FALSE` are removed; most of the +#' character options (e.g. `engine` and `out.width`) are quoted; +#' `keep.source=TRUE/FALSE` is changed to `tidy=FALSE/TRUE` (note the #' order of values). #' -#' If a line \code{@@} (it closes a chunk) directly follows a previous -#' \code{@@}, it is removed; if a line \code{@@} appears before a code chunk and +#' If a line `@@` (it closes a chunk) directly follows a previous +#' `@@`, it is removed; if a line `@@` appears before a code chunk and #' no chunk is before it, it is also removed, because \pkg{knitr} only uses one -#' \samp{@@} after \samp{<<>>=} by default (which is not the original Noweb +#' `@@` after `<<>>=` by default (which is not the original Noweb #' syntax but more natural). #' @param file Path to the Rnw file (must be encoded in UTF-8). #' @param output Output file path. By default, \file{file.Rnw} produces -#' \file{file-knitr.Rnw}); if \code{text} is not NULL, no output file will be +#' \file{file-knitr.Rnw}); if `text` is not NULL, no output file will be #' produced. #' @param text An alternative way to provide the Sweave code as a character -#' string. If \code{text} is provided, \code{file} will be ignored. -#' @return If \code{text} is \code{NULL}, the \code{output} file is written and -#' \code{NULL} is returned. Otherwise, the converted text string is returned. -#' @note If \samp{\\SweaveOpts{}} spans across multiple lines, it will not be +#' string. If `text` is provided, `file` will be ignored. +#' @return If `text` is `NULL`, the `output` file is written and +#' `NULL` is returned. Otherwise, the converted text string is returned. +#' @note If `\SweaveOpts{}` spans across multiple lines, it will not be #' fixed, and you have to fix it manually. The LaTeX-style syntax of Sweave -#' chunks are ignored (see \code{?SweaveSyntaxLatex}); only the Noweb syntax +#' chunks are ignored (see `?SweaveSyntaxLatex`); only the Noweb syntax #' is supported. -#' @seealso \code{\link{Sweave}}, \code{\link{gsub}} +#' @seealso [Sweave()], [gsub()] #' @references The motivation of the changes in the syntax: -#' \url{https://yihui.org/knitr/demo/sweave/} +#' #' @export #' @examples Sweave2knitr(text='<>=') # this is valid #' Sweave2knitr(text="<>=") # dev='png' diff --git a/R/utils-upload.R b/R/utils-upload.R index 995bad49da..28a207dfb1 100644 --- a/R/utils-upload.R +++ b/R/utils-upload.R @@ -1,9 +1,9 @@ #' Upload an image to imgur.com #' -#' This function is an alias to \code{xfun::upload_imgur()}. It is kept in +#' This function is an alias to `xfun::upload_imgur()`. It is kept in #' \pkg{knitr} only for backward-compatibility reasons. You are recommended to -#' use \code{xfun::upload_imgur()} directly instead. -#' @param file,key,... See \code{xfun::\link[xfun]{upload_imgur}()}. +#' use `xfun::upload_imgur()` directly instead. +#' @param file,key,... See [xfun::upload_imgur()]. #' @export #' @keywords internal imgur_upload = function(file, key = xfun::env_option('knitr.imgur.key'), ...) { diff --git a/R/utils-vignettes.R b/R/utils-vignettes.R index f9240821dd..c635d5cd14 100644 --- a/R/utils-vignettes.R +++ b/R/utils-vignettes.R @@ -1,21 +1,21 @@ #' Package vignette engines #' #' Since R 3.0.0, package vignettes can use non-Sweave engines, and \pkg{knitr} -#' has provided a few engines to compile vignettes via \code{\link{knit}()} with -#' different templates. See \url{https://yihui.org/knitr/demo/vignette/} for +#' has provided a few engines to compile vignettes via [knit()] with +#' different templates. See for #' more information. #' @name vignette_engines -#' @note If you use the \code{knitr::rmarkdown} engine, please make sure that -#' you put \pkg{rmarkdown} in the \samp{Suggests} field of your +#' @note If you use the `knitr::rmarkdown` engine, please make sure that +#' you put \pkg{rmarkdown} in the `Suggests` field of your #' \file{DESCRIPTION} file. Also make sure \command{pandoc} is available #' during \command{R CMD build}. If you build your package from RStudio, this #' is normally not a problem. If you build the package outside RStudio, run -#' \code{rmarkdown::find_pandoc()} in an R session to check if Pandoc can be +#' `rmarkdown::find_pandoc()` in an R session to check if Pandoc can be #' found. #' #' When the \pkg{rmarkdown} package is not installed or not available, or -#' \command{pandoc} cannot be found, the \code{knitr::rmarkdown} engine will -#' fall back to the \code{knitr::knitr} engine, which uses R Markdown v1 based +#' \command{pandoc} cannot be found, the `knitr::rmarkdown` engine will +#' fall back to the `knitr::knitr` engine, which uses R Markdown v1 based #' on the \pkg{litedown} package. #' @examples library(knitr) #' vig_list = tools::vignetteEngine(package = 'knitr') @@ -135,10 +135,10 @@ vig_engine = function(..., tangle = vtangle) { #' When performing spell checking on source documents, we may need to skip R #' code chunks and inline R expressions, because many R functions and symbols #' are likely to be identified as typos. This function is designed for the -#' \code{filter} argument of \code{\link{aspell}()} to filter out code chunks +#' `filter` argument of [aspell()] to filter out code chunks #' and inline expressions. #' @param ifile Filename of the source document. -#' @param encoding Ignored (the file \code{ifile} must be encoded in UTF-8). +#' @param encoding Ignored (the file `ifile` must be encoded in UTF-8). #' @return A character vector of the file content, excluding code chunks and #' inline expressions. #' @export diff --git a/R/utils.R b/R/utils.R index eec38ab136..73643f6246 100644 --- a/R/utils.R +++ b/R/utils.R @@ -128,10 +128,10 @@ pure_preamble = function(preamble, patterns) { #' complete output is written. #' @note Obviously this function is only useful when the output format is LaTeX. #' This function only works when the child document is compiled in a -#' standalone mode using \code{\link{knit}()} (instead of being called in -#' \code{\link{knit_child}()}); when the parent document is compiled, this +#' standalone mode using [knit()] (instead of being called in +#' [knit_child()]); when the parent document is compiled, this #' function in the child document will be ignored. -#' @references \url{https://yihui.org/knitr/demo/child/} +#' @references #' @export #' @examples ## can use, e.g. \Sexpr{set_parent('parent_doc.Rnw')} or #' @@ -364,24 +364,24 @@ fix_options = function(options) { #' Check the current input and output type #' -#' The function \code{is_latex_output()} returns \code{TRUE} when the output +#' The function `is_latex_output()` returns `TRUE` when the output #' format is LaTeX; it works for both \file{.Rnw} and R Markdown documents (for -#' the latter, the two Pandoc formats \code{latex} and \code{beamer} are -#' considered LaTeX output). The function \code{is_html_output()} only works for +#' the latter, the two Pandoc formats `latex` and `beamer` are +#' considered LaTeX output). The function `is_html_output()` only works for #' R Markdown documents and will test for several Pandoc HTML based output #' formats (by default, these formats are considered as HTML formats: -#' \code{c('markdown', 'epub', 'epub2', 'html', 'html4', 'html5', 'revealjs', 's5', -#' 'slideous', 'slidy', 'gfm')}). +#' `c('markdown', 'epub', 'epub2', 'html', 'html4', 'html5', 'revealjs', 's5', +#' 'slideous', 'slidy', 'gfm')`). #' -#' The function \code{pandoc_to()} returns the Pandoc output format, and -#' \code{pandoc_from()} returns Pandoc input format. \code{pandoc_to(fmt)} +#' The function `pandoc_to()` returns the Pandoc output format, and +#' `pandoc_from()` returns Pandoc input format. `pandoc_to(fmt)` #' allows to check the current output format against a set of format names. Both #' are to be used with R Markdown documents. #' #' These functions may be useful for conditional output that depends on the #' output format. For example, you may write out a LaTeX table in an R Markdown #' document when the output format is LaTeX, and an HTML or Markdown table when -#' the output format is HTML. Use \code{pandoc_to(fmt)} to test a more specific +#' the output format is HTML. Use `pandoc_to(fmt)` to test a more specific #' Pandoc format. #' #' Internally, the Pandoc output format of the current R Markdown document is @@ -390,7 +390,7 @@ fix_options = function(options) { #' \code{knitr::\link{opts_knit}$get('rmarkdown.pandoc.from')} #' #' @note See available Pandoc formats, in -#' \href{https://pandoc.org/MANUAL.html}{Pandoc's Manual} +#' [Pandoc's Manual](https://pandoc.org/MANUAL.html) #' @rdname output_type #' @export #' @examples @@ -408,8 +408,8 @@ is_latex_output = function() { } #' @param fmt A character vector of output formats to be checked against. If not -#' provided, \code{is_html_output()} uses \code{pandoc_to()}, and -#' \code{pandoc_to()} returns the output format name. +#' provided, `is_html_output()` uses `pandoc_to()`, and +#' `pandoc_to()` returns the output format name. #' @param excludes A character vector of output formats that should not be #' considered as HTML format. Options are: markdown, epub, epub2, html, html4, html5, #' revealjs, s5, slideous, slidy, and gfm. @@ -425,8 +425,8 @@ is_html_output = function(fmt = pandoc_to(), excludes = NULL) { } #' @param exact Whether to return or use the exact format name. If not, Pandoc -#' extensions will be removed from the format name, e.g., \samp{latex-smart} -#' will be treated as \samp{latex}. +#' extensions will be removed from the format name, e.g., `latex-smart` +#' will be treated as `latex`. #' @rdname output_type #' @export pandoc_to = function(fmt, exact = FALSE) { @@ -502,18 +502,18 @@ pandoc_fragment = function(text, to = pandoc_to(), from = pandoc_from()) { #' Path for figure files #' -#' The filename of figure files is the combination of options \code{fig.path} -#' and \code{label}. This function returns the path of figures for the current +#' The filename of figure files is the combination of options `fig.path` +#' and `label`. This function returns the path of figures for the current #' chunk by default. #' @param suffix A filename suffix; if it is non-empty and does not -#' contain a dot \code{.}, it will be treated as the filename extension (e.g. -#' \code{png} will be used as \code{.png}) +#' contain a dot `.`, it will be treated as the filename extension (e.g. +#' `png` will be used as `.png`) #' @param options A list of options; by default the options of the current chunk. #' @param number The current figure number. The default is the internal chunk option -#' \code{fig.cur}, if this is available. +#' `fig.cur`, if this is available. #' @return A character vector of the form \file{fig.path-label-i.suffix}. -#' @note When there are special characters (not alphanumeric or \samp{-} or -#' \samp{_}) in the path, they will be automatically replaced with \samp{_}. +#' @note When there are special characters (not alphanumeric or `-` or +#' `_`) in the path, they will be automatically replaced with `_`. #' For example, \file{a b/c.d-} will be sanitized to \file{a_b/c_d-}. This #' makes the filenames safe to LaTeX. #' @export @@ -540,25 +540,25 @@ sanitize_fn = function(path, warn = TRUE) { #' Obtain the figure filenames for a chunk #' #' Given a chunk label, the figure file extension, the figure number(s), and the -#' chunk option \code{fig.path}, return the filename(s). +#' chunk option `fig.path`, return the filename(s). #' #' This function can be used in an inline R expression to write out the figure #' filenames without hard-coding them. For example, if you created a plot in a -#' code chunk with the label \code{foo} and figure path \file{my-figure/}, you +#' code chunk with the label `foo` and figure path \file{my-figure/}, you #' are not recommended to use hard-coded figure paths like -#' \samp{\includegraphics{my-figure/foo-1.pdf}} (in \file{.Rnw} documents) or -#' \samp{![](my-figure/foo-1.png)} (R Markdown) in your document. Instead, you -#' should use \samp{\\Sexpr{fig_chunk('foo', 'pdf')}} or \samp{![](`r -#' fig_chunk('foo', 'png')`)}. +#' `\includegraphics{my-figure/foo-1.pdf}` (in \file{.Rnw} documents) or +#' `![](my-figure/foo-1.png)` (R Markdown) in your document. Instead, you +#' should use `\Sexpr{fig_chunk('foo', 'pdf')}` or +#' ``` ![](`r fig_chunk('foo', 'png')`) ```. #' #' You can generate plots in a code chunk but not show them inside the code -#' chunk by using the chunk option \code{fig.show = 'hide'}. Then you can use +#' chunk by using the chunk option `fig.show = 'hide'`. Then you can use #' this function if you want to show them elsewhere. #' @param label The chunk label. -#' @param ext The figure file extension, e.g. \code{png} or \code{pdf}. -#' @param number The figure number (by default \code{1}). -#' @param fig.path Passed to \code{\link{fig_path}}. By default, the chunk -#' option \code{fig.path} is used. +#' @param ext The figure file extension, e.g., `png` or `pdf`. +#' @param number The figure number (by default `1`). +#' @param fig.path Passed to [fig_path()]. By default, the chunk +#' option `fig.path` is used. #' @return A character vector of filenames. #' @export #' @examples library(knitr) @@ -574,8 +574,8 @@ fig_chunk = function(label, ext = '', number, fig.path = opts_chunk$get('fig.pat #' #' Get or set the environment in which code chunks are evaluated. #' -#' @param envir If \code{NULL}, the function returns the \code{envir} argument -#' of \code{\link{knit}}, otherwise it should be a new environment for +#' @param envir If `NULL`, the function returns the `envir` argument +#' of [knit()], otherwise it should be a new environment for #' evaluating code, in which case the function returns the old environment #' after setting the new environment. #' @export @@ -719,12 +719,12 @@ is_utf8 = function(x) { #' easier to review differences in version control. #' @param file The input Rmd file. #' @param width The expected line width. -#' @param text A character vector of text lines, as an alternative to \code{file}. If -#' \code{text} is not \code{NULL}, \code{file} is ignored. +#' @param text A character vector of text lines, as an alternative to `file`. If +#' `text` is not `NULL`, `file` is ignored. #' @param backup Path to back up the original file in case anything goes -#' wrong. If set to \code{NULL}, no backup is made. The default value is constructed -#' from \code{file} by adding \code{__} before the base filename. -#' @return If \code{file} is provided, it is overwritten; if \code{text} is +#' wrong. If set to `NULL`, no backup is made. The default value is constructed +#' from `file` by adding `__` before the base filename. +#' @return If `file` is provided, it is overwritten; if `text` is #' provided, a character vector is returned. #' @note Currently it does not wrap blockquotes or lists (ordered or unordered). #' This feature may or may not be added in the future. @@ -827,11 +827,11 @@ has_crop_tools = function(warn = TRUE) { #' Query the current input filename #' -#' Returns the name of the input file passed to \code{\link{knit}()}. -#' @param dir Boolean; whether to prepend the current working directory to the file path, -#' i.e. whether to return an absolute path or a relative path. +#' Returns the name of the input file passed to [knit()]. +#' @param dir Whether to prepend the current working directory to the file +#' path, i.e., whether to return an absolute path or a relative path. #' @return A character string, if this function is called inside an input -#' document. Otherwise \code{NULL}. +#' document. Otherwise `NULL`. #' @export current_input = function(dir = FALSE) { input = knit_concord$get('infile') @@ -899,8 +899,8 @@ create_label = function(..., latex = FALSE) { #' Combine multiple words into a single string #' -#' This is a wrapper function of \code{xfun::join_words()}. -#' @param ... Arguments passed to \code{xfun::\link[xfun]{join_words}()}. +#' This is a wrapper function of `xfun::join_words()`. +#' @param ... Arguments passed to [xfun::join_words()]. #' @export combine_words = function(...) xfun::join_words(...) @@ -950,32 +950,32 @@ restore_raw_output = function(text, chunks, markers = raw_markers) { #' Mark character strings as raw output that should not be converted #' #' These functions provide a mechanism to protect the character output of R code -#' chunks. The output is annotated with special markers in \code{raw_output}; -#' \code{extract_raw_output()} will extract raw output wrapped in the markers, -#' and replace the raw output with its MD5 digest; \code{restore_raw_output()} +#' chunks. The output is annotated with special markers in `raw_output`; +#' `extract_raw_output()` will extract raw output wrapped in the markers, +#' and replace the raw output with its MD5 digest; `restore_raw_output()` #' will restore the MD5 digest with the original raw output. #' #' This mechanism is designed primarily for R Markdown pre/post-processors. In -#' an R code chunk, you generate \code{raw_output()} to the Markdown output. In -#' the pre-processor, you can \code{extract_raw_output()} from the Markdown +#' an R code chunk, you generate `raw_output()` to the Markdown output. In +#' the pre-processor, you can `extract_raw_output()` from the Markdown #' file, store the raw output and MD5 digests, and remove the actual raw output #' from Markdown so Pandoc will never see it. In the post-processor, you can #' read the Pandoc output (e.g., an HTML or RTF file), and restore the raw #' output. #' @param x The character vector to be protected. -#' @param markers A length-2 character vector to be used to wrap \code{x}; -#' see \code{knitr:::raw_markers} for the default value. -#' @param ... Arguments to be passed to \code{\link{asis_output}()}. -#' @param text For \code{extract_raw_output()}, the content of the input file -#' (e.g. Markdown); for \code{restore_raw_output()}, the content of the output +#' @param markers A length-2 character vector to be used to wrap `x`; +#' see `knitr:::raw_markers` for the default value. +#' @param ... Arguments to be passed to [asis_output()]. +#' @param text For `extract_raw_output()`, the content of the input file +#' (e.g. Markdown); for `restore_raw_output()`, the content of the output #' file (e.g. HTML generated by Pandoc from Markdown). #' @param chunks A named character vector returned from -#' \code{extract_raw_output()}. -#' @return For \code{extract_raw_output()}, a list of two components: -#' \code{value} (the \code{text} with raw output replaced by MD5 digests) and -#' \code{chunks} (a named character vector, of which the names are MD5 digests -#' and values are the raw output). For \code{restore_raw_output()}, the -#' restored \code{text}. +#' `extract_raw_output()`. +#' @return For `extract_raw_output()`, a list of two components: +#' `value` (the `text` with raw output replaced by MD5 digests) and +#' `chunks` (a named character vector, of which the names are MD5 digests +#' and values are the raw output). For `restore_raw_output()`, the +#' restored `text`. #' @export #' @examples library(knitr) #' out = c('*hello*', raw_output('content *protect* me!'), '*world*') @@ -993,15 +993,15 @@ raw_output = function(x, markers = raw_markers, ...) { #' Mark character strings as raw blocks in R Markdown #' #' Wraps content in a raw attribute block, which protects it from being escaped -#' by Pandoc. See \url{https://pandoc.org/MANUAL.html#generic-raw-attribute}. -#' Functions \code{raw_latex()} and \code{raw_html()} are shorthands of -#' \code{raw_block(x, 'latex')} and \code{raw_block(x, 'html')}, respectively. +#' by Pandoc. See . +#' Functions `raw_latex()` and `raw_html()` are shorthands of +#' `raw_block(x, 'latex')` and `raw_block(x, 'html')`, respectively. #' @param x The character vector to be protected. #' @param type The type of raw blocks (i.e., the Pandoc output format). If you #' are not sure about the Pandoc output format of your document, insert a code -#' chunk \code{knitr:::pandoc_to()} and see what it returns after the document +#' chunk `knitr:::pandoc_to()` and see what it returns after the document #' is compiled. -#' @param ... Arguments to be passed to \code{\link{asis_output}()}. +#' @param ... Arguments to be passed to [asis_output()]. #' @export #' @examples #' knitr::raw_latex('\\emph{some text}') @@ -1055,14 +1055,14 @@ quote_vec = function(x, sep = '; ') paste0(sprintf('"%s"', x), collapse = sep) #' Encode an image file to a data URI #' -#' This function is the same as \code{xfun::\link[xfun]{base64_uri}()} (only with a +#' This function is the same as [xfun::base64_uri()] (only with a #' different function name). It can encode an image file as a base64 string, -#' which can be used in the \code{img} tag in HTML. +#' which can be used in the `img` tag in HTML. #' @param f Path to the image file. #' @return The data URI as a character string. #' @author Wush Wu and Yihui Xie #' @export -#' @references \url{https://en.wikipedia.org/wiki/Data_URI_scheme} +#' @references #' @examples uri = image_uri(file.path(R.home('doc'), 'html', 'logo.jpg')) #' if (interactive()) {cat(sprintf('', uri), file = 'logo.html') #' browseURL('logo.html') # you can check its HTML source diff --git a/man/Sweave2knitr.Rd b/man/Sweave2knitr.Rd index 657ed1c40e..0f3e37647d 100644 --- a/man/Sweave2knitr.Rd +++ b/man/Sweave2knitr.Rd @@ -22,22 +22,21 @@ string. If \code{text} is provided, \code{file} will be ignored.} } \value{ If \code{text} is \code{NULL}, the \code{output} file is written and - \code{NULL} is returned. Otherwise, the converted text string is returned. +\code{NULL} is returned. Otherwise, the converted text string is returned. } \description{ This function converts an Sweave document to a \pkg{knitr}-compatible document. } \details{ -The pseudo command \samp{\\SweaveInput{file.Rnw}} is converted to a code -chunk header \code{<>=}. +The pseudo command \verb{\\SweaveInput\{file.Rnw\}} is converted to a code +chunk header \verb{<>=}. -Similarly \samp{\\SweaveOpts{opt = value}} is converted to a code chunk -\samp{opts_chunk$set(opt = value)} with the chunk option \code{include = -FALSE}; the options are automatically fixed in the same way as local chunk +Similarly \verb{\\SweaveOpts\{opt = value\}} is converted to a code chunk +\code{opts_chunk$set(opt = value)} with the chunk option \code{include = FALSE}; the options are automatically fixed in the same way as local chunk options (explained below). -The Sweave package \samp{\\usepackage{Sweave}} in the preamble is removed +The Sweave package \verb{\\usepackage\{Sweave\}} in the preamble is removed because it is not required. Chunk options are updated if necessary: option values \code{true} and @@ -58,14 +57,14 @@ order of values). If a line \code{@} (it closes a chunk) directly follows a previous \code{@}, it is removed; if a line \code{@} appears before a code chunk and no chunk is before it, it is also removed, because \pkg{knitr} only uses one -\samp{@} after \samp{<<>>=} by default (which is not the original Noweb +\code{@} after \verb{<<>>=} by default (which is not the original Noweb syntax but more natural). } \note{ -If \samp{\\SweaveOpts{}} spans across multiple lines, it will not be - fixed, and you have to fix it manually. The LaTeX-style syntax of Sweave - chunks are ignored (see \code{?SweaveSyntaxLatex}); only the Noweb syntax - is supported. +If \verb{\\SweaveOpts\{\}} spans across multiple lines, it will not be +fixed, and you have to fix it manually. The LaTeX-style syntax of Sweave +chunks are ignored (see \code{?SweaveSyntaxLatex}); only the Noweb syntax +is supported. } \examples{ Sweave2knitr(text = "<>=") # this is valid @@ -82,8 +81,8 @@ unlink("Sweave-test-knitr.Rnw") } \references{ The motivation of the changes in the syntax: - \url{https://yihui.org/knitr/demo/sweave/} +\url{https://yihui.org/knitr/demo/sweave/} } \seealso{ -\code{\link{Sweave}}, \code{\link{gsub}} +\code{\link[=Sweave]{Sweave()}}, \code{\link[=gsub]{gsub()}} } diff --git a/man/all_labels.Rd b/man/all_labels.Rd index aca44d1c38..f9cf55d853 100644 --- a/man/all_labels.Rd +++ b/man/all_labels.Rd @@ -25,7 +25,7 @@ A character vector. \description{ The function \code{all_labels()} returns all chunk labels as a character vector. Optionally, you can specify a series of conditions to filter the -labels. The function `all_rcpp_labels()` is a wrapper function for +labels. The function \code{all_rcpp_labels()} is a wrapper function for \code{all_labels(engine == 'Rcpp')}. } \details{ @@ -36,8 +36,8 @@ expression fails to be evaluated (e.g. when a certain object does not exist), } \note{ Empty code chunks are always ignored, including those chunks that are - empty in the original document but filled with code using chunk options - such as \code{ref.label} or \code{code}. +empty in the original document but filled with code using chunk options +such as \code{ref.label} or \code{code}. } \examples{ # the examples below are meaningless unless you put them in a knitr document diff --git a/man/asis_output.Rd b/man/asis_output.Rd index a96db47c49..d5bac418b2 100644 --- a/man/asis_output.Rd +++ b/man/asis_output.Rd @@ -8,7 +8,7 @@ asis_output(x, meta = NULL, cacheable = NA) } \arguments{ \item{x}{An R object. Typically a character string, or an object which can -be converted to a character string via \code{\link{as.character}()}.} +be converted to a character string via \code{\link[=as.character]{as.character()}}.} \item{meta}{Additional metadata of the object to be printed. The metadata will be collected when the object is printed, and accessible via @@ -26,7 +26,7 @@ output. } \details{ This function is normally used in a custom S3 method based on the printing -function \code{\link{knit_print}()}. +function \code{\link[=knit_print]{knit_print()}}. For the \code{cacheable} argument, you need to be careful when printing the object involves non-trivial side effects, in which case it is strongly @@ -44,8 +44,8 @@ session. } \note{ This function only works in top-level R expressions, and it will not - work when it is called inside another expression, such as a for-loop. See - \url{https://github.com/yihui/knitr/issues/1137} for a discussion. +work when it is called inside another expression, such as a for-loop. See +\url{https://github.com/yihui/knitr/issues/1137} for a discussion. } \examples{ # see ?knit_print diff --git a/man/cache_engines.Rd b/man/cache_engines.Rd index 76c200db70..2dc91d3fe1 100644 --- a/man/cache_engines.Rd +++ b/man/cache_engines.Rd @@ -23,5 +23,5 @@ the extension appropriate for the language. } \references{ See \url{https://github.com/rstudio/reticulate/pull/167} for an - implementation of a cache engine for Python. +implementation of a cache engine for Python. } diff --git a/man/chunk_hook.Rd b/man/chunk_hook.Rd index 9112c3451a..43b08d68e5 100644 --- a/man/chunk_hook.Rd +++ b/man/chunk_hook.Rd @@ -31,7 +31,7 @@ provides a few useful hooks, which can also serve as examples of how to define chunk hooks in \pkg{knitr}. } \details{ -The function \code{hook_pdfcrop()} calls \code{\link{plot_crop}()} to crop +The function \code{hook_pdfcrop()} calls \code{\link[=plot_crop]{plot_crop()}} to crop the white margins of PDF plots. The function \code{hook_optipng()} calls the program \command{optipng} to @@ -49,30 +49,29 @@ the chunk option \code{mogrify} can be used to provide additional parameters to the program \command{mogrify} (with default \code{-trim} to trim PNG files). -When the plots are not recordable via \code{grDevices::\link{recordPlot}()} +When the plots are not recordable via \code{\link[grDevices:recordPlot]{grDevices::recordPlot()}} and we save the plots to files manually via other functions (e.g. \pkg{rgl} plots), we can use the chunk hook \code{hook_plot_custom} to help write code for graphics output into the output document. The hook \code{hook_purl()} can be used to write the code chunks to an R -script. It is an alternative approach to \code{\link{purl}}, and can be more +script. It is an alternative approach to \code{\link[=purl]{purl()}}, and can be more reliable when the code chunks depend on the execution of them (e.g. -\code{\link{read_chunk}()}, or \code{\link{opts_chunk}$set(eval = FALSE)}). +\code{\link[=read_chunk]{read_chunk()}}, or \code{\link{opts_chunk}$set(eval = FALSE)}). To enable this hook, it is recommended to associate it with the chunk option \code{purl}, i.e. \code{knit_hooks$set(purl = hook_purl)}. When this hook is enabled, an R script will be written while the input document is being -\code{\link{knit}}. Currently the code chunks that are not R code or have the +\code{\link[=knit]{knit()}}. Currently the code chunks that are not R code or have the chunk option \code{purl=FALSE} are ignored. Please note when the cache is turned on (the chunk option \code{cache = TRUE}), no chunk hooks will be executed, hence \code{hook_purl()} will not work, either. To solve this problem, we need \code{cache = 2} instead of \code{TRUE} (see -\url{https://yihui.org/knitr/demo/cache/} for the meaning of \code{cache = -2}). +\url{https://yihui.org/knitr/demo/cache/} for the meaning of \code{cache = 2}). } \note{ The two hook functions \code{hook_rgl()} and \code{hook_webgl()} were - moved from \pkg{knitr} to the \pkg{rgl} package (>= v0.95.1247) after - \pkg{knitr} v1.10.5, and you can \code{library(rgl)} to get them. +moved from \pkg{knitr} to the \pkg{rgl} package (>= v0.95.1247) after +\pkg{knitr} v1.10.5, and you can \code{library(rgl)} to get them. } \examples{ if (require("rgl") && exists("hook_rgl")) knit_hooks$set(rgl = hook_rgl) @@ -82,8 +81,6 @@ if (require("rgl") && exists("hook_rgl")) knit_hooks$set(rgl = hook_rgl) \url{https://yihui.org/knitr/hooks/#chunk-hooks} } \seealso{ -\code{rgl::\link[rgl:snapshot]{rgl.snapshot}}, - \code{rgl::\link[rgl:postscript]{rgl.postscript}}, - \code{rgl::\link[rgl]{hook_rgl}}, - \code{rgl::\link[rgl:hook_rgl]{hook_webgl}} +\code{\link[rgl:rgl.snapshot]{rgl::rgl.snapshot()}}, \code{\link[rgl:rgl.postscript]{rgl::rgl.postscript()}}, +\code{\link[rgl:hook_rgl]{rgl::hook_rgl()}}, \code{\link[rgl:hook_webgl]{rgl::hook_webgl()}} } diff --git a/man/clean_cache.Rd b/man/clean_cache.Rd index 535f8ae595..e2abbb801c 100644 --- a/man/clean_cache.Rd +++ b/man/clean_cache.Rd @@ -7,7 +7,7 @@ clean_cache(clean = FALSE, path = opts_chunk$get("cache.path")) } \arguments{ -\item{clean}{Boolean; whether to remove the files.} +\item{clean}{Whether to remove the files.} \item{path}{Path to the cache.} } @@ -19,12 +19,12 @@ needed. } \note{ The identification is not guaranteed to be correct, especially when - multiple documents share the same cache directory. You are recommended to - call \code{clean_cache(FALSE)} and carefully check the list of files (if - any) before you really delete them (\code{clean_cache(TRUE)}). +multiple documents share the same cache directory. You are recommended to +call \code{clean_cache(FALSE)} and carefully check the list of files (if +any) before you really delete them (\code{clean_cache(TRUE)}). - This function must be called within a code chunk in a source document, - since it needs to know all chunk labels of the current document to - determine which labels are no longer present, and delete cache - corresponding to these labels. +This function must be called within a code chunk in a source document, +since it needs to know all chunk labels of the current document to +determine which labels are no longer present, and delete cache +corresponding to these labels. } diff --git a/man/combine_words.Rd b/man/combine_words.Rd index acc791476c..9abe46ac54 100644 --- a/man/combine_words.Rd +++ b/man/combine_words.Rd @@ -7,7 +7,7 @@ combine_words(...) } \arguments{ -\item{...}{Arguments passed to \code{xfun::\link[xfun]{join_words}()}.} +\item{...}{Arguments passed to \code{\link[xfun:join_words]{xfun::join_words()}}.} } \description{ This is a wrapper function of \code{xfun::join_words()}. diff --git a/man/convert_chunk_header.Rd b/man/convert_chunk_header.Rd index c3ecd1760d..9c44d55d77 100644 --- a/man/convert_chunk_header.Rd +++ b/man/convert_chunk_header.Rd @@ -25,16 +25,14 @@ the default is \code{"yaml"}) will write each chunk option on a separate line. Long chunk option values will be wrapped onto several lines, and you can use \code{width = 0} to keep one line per option only. \code{"wrap"} will wrap all chunk options together using -\code{\link[base:strwrap]{base::strwrap}()}. \code{"yaml"} will convert +\code{\link[base:strwrap]{base::strwrap()}}. \code{"yaml"} will convert chunk options to YAML.} -\item{width}{An integer passed to \code{base::strwrap()} for \code{type = -"wrap"} and \code{type = "multiline"}. If set to \code{0}, deactivate the +\item{width}{An integer passed to \code{base::strwrap()} for \code{type = "wrap"} and \code{type = "multiline"}. If set to \code{0}, deactivate the wrapping (for \code{type = "multiline"} only).} } \value{ -A character vector of converted \code{input} when \code{output = - NULL}. The output file path with converted content otherwise. +A character vector of converted \code{input} when \code{output = NULL}. The output file path with converted content otherwise. } \description{ This is a helper function for moving chunk options from the chunk header to @@ -42,43 +40,46 @@ the chunk body using the new syntax. } \note{ Learn more about the new chunk option syntax in - \url{https://yihui.org/en/2022/01/knitr-news/} +\url{https://yihui.org/en/2022/01/knitr-news/} } \section{About \pkg{knitr} option syntax}{ Historical chunk option syntax have chunk option in the chunk header using valid R syntax. This is an example for \verb{.Rmd} document -\preformatted{ -```\{r, echo = FALSE, fig.width: 10\} + +\if{html}{\out{
}}\preformatted{```\{r, echo = FALSE, fig.width = 10\} ``` -} +}\if{html}{\out{
}} New syntax allows to pass option inside the chunk using several variants \itemize{ \item Passing options one per line using valid R syntax. This corresponds to \code{convert_chunk_header(type = "multiline")}. -\preformatted{ -```\{r\} + +\if{html}{\out{
}}\preformatted{```\{r\} #| echo = FALSE, #| fig.width = 10 ``` -} +}\if{html}{\out{
}} \item Passing option part from header in-chunk with several line if wrapping is needed. This corresponds to \code{convert_chunk_header(type = "wrap")} -\preformatted{ -```\{r\} + +\if{html}{\out{
}}\preformatted{```\{r\} #| echo = FALSE, fig.width = 10 ``` -} +}\if{html}{\out{
}} + \item Passing options key value pairs in-chunk using YAML syntax. Values are no more R expression but valid YAML syntax. This corresponds to \code{convert_chunk_header(type = "yaml")} (not implement yet). -\preformatted{```\{r\} + +\if{html}{\out{
}}\preformatted{```\{r\} #| echo: false, #| fig.width: 10 ``` -} +}\if{html}{\out{
}} + } } diff --git a/man/current_input.Rd b/man/current_input.Rd index c024aaf3fa..41d7b257eb 100644 --- a/man/current_input.Rd +++ b/man/current_input.Rd @@ -7,13 +7,13 @@ current_input(dir = FALSE) } \arguments{ -\item{dir}{Boolean; whether to prepend the current working directory to the file path, -i.e. whether to return an absolute path or a relative path.} +\item{dir}{Whether to prepend the current working directory to the file +path, i.e., whether to return an absolute path or a relative path.} } \value{ A character string, if this function is called inside an input - document. Otherwise \code{NULL}. +document. Otherwise \code{NULL}. } \description{ -Returns the name of the input file passed to \code{\link{knit}()}. +Returns the name of the input file passed to \code{\link[=knit]{knit()}}. } diff --git a/man/dep_auto.Rd b/man/dep_auto.Rd index 5180a2bedc..d6c7c43c07 100644 --- a/man/dep_auto.Rd +++ b/man/dep_auto.Rd @@ -25,15 +25,15 @@ used in the first chunk of a document and this chunk must not be cached. } \note{ Be cautious about \code{path}: because this function is used in a - chunk, the working directory when the chunk is evaluated is the directory - of the input document in \code{\link{knit}}, and if that directory differs - from the working directory before calling \code{knit()}, you need to adjust - the \code{path} argument here to make sure this function can find the cache - files \file{__objects} and \file{__globals}. +chunk, the working directory when the chunk is evaluated is the directory +of the input document in \code{\link[=knit]{knit()}}, and if that directory differs +from the working directory before calling \code{knit()}, you need to adjust +the \code{path} argument here to make sure this function can find the cache +files \file{__objects} and \file{__globals}. } \references{ \url{https://yihui.org/knitr/demo/cache/} } \seealso{ -\code{\link{dep_prev}} +\code{\link[=dep_prev]{dep_prev()}} } diff --git a/man/dep_prev.Rd b/man/dep_prev.Rd index 1509c4ea95..3ce9f308a5 100644 --- a/man/dep_prev.Rd +++ b/man/dep_prev.Rd @@ -8,7 +8,7 @@ dep_prev() } \value{ \code{NULL}; the internal dependency structure is updated as a side - effect. +effect. } \description{ This function can be used to build dependencies among chunks so that all @@ -19,5 +19,5 @@ chunk is updated, the cache of all its later chunks will be updated. \url{https://yihui.org/knitr/demo/cache/} } \seealso{ -\code{\link{dep_auto}} +\code{\link[=dep_auto]{dep_auto()}} } diff --git a/man/download_image.Rd b/man/download_image.Rd index 7945911403..f7837bbc3b 100644 --- a/man/download_image.Rd +++ b/man/download_image.Rd @@ -23,13 +23,13 @@ again, delete it beforehand.} image. By default, the URL is used for HTML output formats, and the file path is used for other output formats.} -\item{...}{Other arguments to be passed to \code{\link{include_graphics}()}.} +\item{...}{Other arguments to be passed to \code{\link[=include_graphics]{include_graphics()}}.} } \description{ When including images in non-HTML output formats such as LaTeX/PDF, URLs will not work as image paths. In this case, we have to download the images. This -function is a wrapper of \code{xfun::\link[xfun]{download_file}()} and -\code{\link{include_graphics}()}. +function is a wrapper of \code{\link[xfun:download_file]{xfun::download_file()}} and +\code{\link[=include_graphics]{include_graphics()}}. } \examples{\dontshow{if (interactive()) \{} knitr::download_image("https://www.r-project.org/Rlogo.png") diff --git a/man/engine_output.Rd b/man/engine_output.Rd index b89e145c89..2a013bedf8 100644 --- a/man/engine_output.Rd +++ b/man/engine_output.Rd @@ -9,7 +9,7 @@ engine_output(options, code, out, extra = NULL) \arguments{ \item{options}{A list of chunk options. Usually this is just the object \code{options} passed to the engine function; see -\code{\link{knit_engines}}.} +\code{\link[=knit_engines]{knit_engines()}}.} \item{code}{Source code of the chunk, to which the output hook \code{source} is applied, unless the chunk option \code{echo} is \code{FALSE}.} @@ -21,7 +21,7 @@ applied, unless the chunk option \code{results} is \code{'hide'}} } \value{ A character string generated from the source code and output using - the appropriate output hooks. +the appropriate output hooks. } \description{ If you have designed a language engine, you may call this function in the end diff --git a/man/fig_chunk.Rd b/man/fig_chunk.Rd index 97e088f751..99a599e994 100644 --- a/man/fig_chunk.Rd +++ b/man/fig_chunk.Rd @@ -9,11 +9,11 @@ fig_chunk(label, ext = "", number, fig.path = opts_chunk$get("fig.path")) \arguments{ \item{label}{The chunk label.} -\item{ext}{The figure file extension, e.g. \code{png} or \code{pdf}.} +\item{ext}{The figure file extension, e.g., \code{png} or \code{pdf}.} \item{number}{The figure number (by default \code{1}).} -\item{fig.path}{Passed to \code{\link{fig_path}}. By default, the chunk +\item{fig.path}{Passed to \code{\link[=fig_path]{fig_path()}}. By default, the chunk option \code{fig.path} is used.} } \value{ @@ -28,10 +28,10 @@ This function can be used in an inline R expression to write out the figure filenames without hard-coding them. For example, if you created a plot in a code chunk with the label \code{foo} and figure path \file{my-figure/}, you are not recommended to use hard-coded figure paths like -\samp{\includegraphics{my-figure/foo-1.pdf}} (in \file{.Rnw} documents) or -\samp{![](my-figure/foo-1.png)} (R Markdown) in your document. Instead, you -should use \samp{\\Sexpr{fig_chunk('foo', 'pdf')}} or \samp{![](`r -fig_chunk('foo', 'png')`)}. +\verb{\\includegraphics\{my-figure/foo-1.pdf\}} (in \file{.Rnw} documents) or +\verb{![](my-figure/foo-1.png)} (R Markdown) in your document. Instead, you +should use \verb{\\Sexpr\{fig_chunk('foo', 'pdf')\}} or +\verb{![](`r fig_chunk('foo', 'png')`)}. You can generate plots in a code chunk but not show them inside the code chunk by using the chunk option \code{fig.show = 'hide'}. Then you can use diff --git a/man/fig_path.Rd b/man/fig_path.Rd index ebb4623637..4dd59b704f 100644 --- a/man/fig_path.Rd +++ b/man/fig_path.Rd @@ -25,10 +25,10 @@ and \code{label}. This function returns the path of figures for the current chunk by default. } \note{ -When there are special characters (not alphanumeric or \samp{-} or - \samp{_}) in the path, they will be automatically replaced with \samp{_}. - For example, \file{a b/c.d-} will be sanitized to \file{a_b/c_d-}. This - makes the filenames safe to LaTeX. +When there are special characters (not alphanumeric or \code{-} or +\verb{_}) in the path, they will be automatically replaced with \verb{_}. +For example, \file{a b/c.d-} will be sanitized to \file{a_b/c_d-}. This +makes the filenames safe to LaTeX. } \examples{ fig_path(".pdf", options = list(fig.path = "figure/abc-", label = "first-plot")) diff --git a/man/hook_animation.Rd b/man/hook_animation.Rd index 89aa83d873..2d4d0393e2 100644 --- a/man/hook_animation.Rd +++ b/man/hook_animation.Rd @@ -33,5 +33,5 @@ can set \code{opts_knit$set(animation.fun = hook_scianimator)}. Note that these hooks generate HTML code. For LaTeX output, you can set the chunk option \code{animation.hook} (or the package option \code{animation.fun}) to a function that generates LaTeX code; see -\code{\link{hook_plot_tex}}. +\code{\link[=hook_plot_tex]{hook_plot_tex()}}. } diff --git a/man/hook_document.Rd b/man/hook_document.Rd index 60cc6dcb00..3ce6695789 100644 --- a/man/hook_document.Rd +++ b/man/hook_document.Rd @@ -17,19 +17,19 @@ A document hook is a function to post-process the output document. } \details{ \code{hook_movecode()} is a document hook to move code chunks out of LaTeX -floating environments like \samp{figure} and \samp{table} when the chunks +floating environments like \code{figure} and \code{table} when the chunks were actually written inside the floats. This function is primarily designed for LyX: we often insert code chunks into floats to generate figures or tables, but in the final output we do not want the code to float with the environments, so we use regular expressions to find out the floating environments, extract the code chunks and move them out. To disable this -behavior, use a comment \code{\% knitr_do_not_move} in the floating +behavior, use a comment \verb{\\\% knitr_do_not_move} in the floating environment. } \note{ These functions are hackish. Also note \code{hook_movecode()} assumes - you to use the default output hooks for LaTeX (not Sweave or listings), and - every figure/table environment must have a label. +you to use the default output hooks for LaTeX (not Sweave or listings), and +every figure/table environment must have a label. } \examples{ \dontrun{ diff --git a/man/hook_plot.Rd b/man/hook_plot.Rd index b596764f80..488a96b4cf 100644 --- a/man/hook_plot.Rd +++ b/man/hook_plot.Rd @@ -40,26 +40,26 @@ output formats. } \details{ Depending on the options passed over, \code{hook_plot_tex} may return the -normal \samp{\\includegraphics{}} command, or \samp{\\input{}} (for tikz -files), or \samp{\\animategraphics{}} (for animations); it also takes many +normal \verb{\\includegraphics\{\}} command, or \verb{\\input\{\}} (for tikz +files), or \verb{\\animategraphics\{\}} (for animations); it also takes many other options into consideration to align plots and set figure sizes, etc. Similarly, \code{hook_plot_html}, \code{hook_plot_md} and \code{hook_plot_rst} return character strings which are HTML, Markdown, reST code. For animations (i.e. when the chunk option \code{fig.show} is \code{'animate'}), -\code{hook_plot_tex} generates \samp{\\animategraphics{}} unless a hook function +\code{hook_plot_tex} generates \verb{\\animategraphics\{\}} unless a hook function has been provided via the chunk option \code{animation.hook} or the package option \code{animation.fun}, in which case that function generates the LaTeX code instead. It is called only once per chunk, with the filename of the last plot. The -built-in hooks (e.g. \code{\link{hook_ffmpeg_html}}) generate HTML, and are +built-in hooks (e.g. \code{\link[=hook_ffmpeg_html]{hook_ffmpeg_html()}}) generate HTML, and are ignored for LaTeX output. In most cases we do not need to call these hooks explicitly, and they were designed to be used internally. Sometimes we may not be able to record R -plots using \code{grDevices::\link{recordPlot}()}, and we can make use of +plots using \code{\link[grDevices:recordPlot]{grDevices::recordPlot()}}, and we can make use of these hooks to insert graphics output in the output document; see -\code{\link{hook_plot_custom}} for details. +\code{\link[=hook_plot_custom]{hook_plot_custom()}} for details. } \examples{ # this is what happens for a chunk like this @@ -80,5 +80,5 @@ hook_plot_tex("foo5.pdf", opts_chunk$merge(list(fig.show = "animate", interval = \url{https://yihui.org/knitr/hooks/} } \seealso{ -\code{\link{hook_plot_custom}} +\code{\link[=hook_plot_custom]{hook_plot_custom()}} } diff --git a/man/image_uri.Rd b/man/image_uri.Rd index ba7279ef5a..1aadf560a6 100644 --- a/man/image_uri.Rd +++ b/man/image_uri.Rd @@ -13,7 +13,7 @@ image_uri(f) The data URI as a character string. } \description{ -This function is the same as \code{xfun::\link[xfun]{base64_uri}()} (only with a +This function is the same as \code{\link[xfun:base64_uri]{xfun::base64_uri()}} (only with a different function name). It can encode an image file as a base64 string, which can be used in the \code{img} tag in HTML. } diff --git a/man/imgur_upload.Rd b/man/imgur_upload.Rd index 5bcd3f9442..ad969b4be8 100644 --- a/man/imgur_upload.Rd +++ b/man/imgur_upload.Rd @@ -7,7 +7,7 @@ imgur_upload(file, key = xfun::env_option("knitr.imgur.key"), ...) } \arguments{ -\item{file, key, ...}{See \code{xfun::\link[xfun]{upload_imgur}()}.} +\item{file, key, ...}{See \code{\link[xfun:upload_imgur]{xfun::upload_imgur()}}.} } \description{ This function is an alias to \code{xfun::upload_imgur()}. It is kept in diff --git a/man/include_graphics.Rd b/man/include_graphics.Rd index f3960499a9..200e8ae740 100644 --- a/man/include_graphics.Rd +++ b/man/include_graphics.Rd @@ -38,8 +38,8 @@ argument or the global option \code{knitr.graphics.rel_path} to } \value{ The same as the input character vector \code{path} but it is marked - with special internal S3 classes so that \pkg{knitr} will convert the file - paths to proper output code according to the output format. +with special internal S3 classes so that \pkg{knitr} will convert the file +paths to proper output code according to the output format. } \description{ When plots are not generated from R code, there is no way for \pkg{knitr} to @@ -54,12 +54,12 @@ as \code{out.width} and \code{out.height}. } \note{ This function is supposed to be used in R code chunks or inline R code - expressions. For local images, you are recommended to use relative paths - with forward slashes instead of backslashes (e.g., \file{images/fig1.png} - instead of \file{/Users/me/code/images/fig1.png}). +expressions. For local images, you are recommended to use relative paths +with forward slashes instead of backslashes (e.g., \file{images/fig1.png} +instead of \file{/Users/me/code/images/fig1.png}). - The automatic calculation of the output width requires the \pkg{png} - package (for PNG images) or the \pkg{jpeg} package (for JPEG images). The - width will not be calculated if the chunk option \code{out.width} is - already provided or \code{dpi = NA}. +The automatic calculation of the output width requires the \pkg{png} +package (for PNG images) or the \pkg{jpeg} package (for JPEG images). The +width will not be calculated if the chunk option \code{out.width} is +already provided or \code{dpi = NA}. } diff --git a/man/include_url.Rd b/man/include_url.Rd index d7c2bb0f22..468dfe0b8d 100644 --- a/man/include_url.Rd +++ b/man/include_url.Rd @@ -16,15 +16,15 @@ include_app(url, height = "400px") } \value{ An R object with a special class that \pkg{knitr} recognizes - internally to generate the iframes or screenshots. +internally to generate the iframes or screenshots. } \description{ When the output format is HTML, \code{include_url()} inserts an iframe in the output; otherwise it takes a screenshot of the URL and insert the image in the output. \code{include_app()} takes the URL of a Shiny app and adds -\samp{?showcase=0} to it (to disable the showcase mode), then passes the URL +\code{?showcase=0} to it (to disable the showcase mode), then passes the URL to \code{include_url()}. } \seealso{ -\code{\link{include_graphics}} +\code{\link[=include_graphics]{include_graphics()}} } diff --git a/man/inline_expr.Rd b/man/inline_expr.Rd index dedce8cfc7..fb419675fd 100644 --- a/man/inline_expr.Rd +++ b/man/inline_expr.Rd @@ -9,19 +9,18 @@ inline_expr(code, syntax) \arguments{ \item{code}{Character string of the inline R source code.} -\item{syntax}{A character string to specify the syntax, e.g. \code{rnw}, -\code{html}, or \code{md}. If not specified, this will be guessed from -the knitting context.} +\item{syntax}{A character string to specify the syntax, e.g., \code{rnw}, +\code{html}, or \code{md}. If not specified, this will be guessed from the +knitting context.} } \value{ A character string marked up using the inline R code syntax. } \description{ This is a convenience function to write the "source code" of inline R -expressions. For example, if you want to write \samp{`r 1+1`} literally in an -R Markdown document, you may write \samp{`` `r knitr::inline_expr('1+1')` -``}; for Rnw documents, this may be -\samp{\verb|\Sexpr{knitr::inline_expr{'1+1'}}|}. +expressions. For example, if you want to write \code{`r 1+1`} literally in an +R Markdown document, you may write \verb{`` `r knitr::inline_expr('1+1')` ``}; +for Rnw documents, this may be \verb{\\Sexpr\{knitr::inline_expr\{'1+1'\}\}}. } \examples{ library(knitr) diff --git a/man/is_low_change.Rd b/man/is_low_change.Rd index 6931649f73..5f5fb0ceaf 100644 --- a/man/is_low_change.Rd +++ b/man/is_low_change.Rd @@ -11,7 +11,7 @@ is_low_change(p1, p2) } \value{ Logical value indicating whether \code{p2} is a low-level update of - \code{p1}. +\code{p1}. } \description{ Check if one plot only contains a low-level update of another plot. diff --git a/man/kable.Rd b/man/kable.Rd index dfd7fa4d2b..805bd63930 100644 --- a/man/kable.Rd +++ b/man/kable.Rd @@ -38,8 +38,8 @@ a function, it must return a character string.} \code{round()}. This can also be a vector of length \code{ncol(x)}, to set the number of digits for individual columns.} -\item{row.names}{Logical: whether to include row names. By default, row names -are included if \code{rownames(x)} is neither \code{NULL} nor identical to +\item{row.names}{Whether to include row names. By default, row names are +included if \code{rownames(x)} is neither \code{NULL} nor identical to \code{1:nrow(x)}.} \item{col.names}{A character vector of column names to be used in the table.} @@ -58,12 +58,12 @@ option \code{tab.cap}.} from \code{knitr::\link{opts_current}$get('label')} (i.e., the current chunk label). To disable the label, use \code{label = NA}.} -\item{format.args}{A list of arguments to be passed to \code{\link{format}()} +\item{format.args}{A list of arguments to be passed to \code{\link[=format]{format()}} to format table values, e.g. \code{list(big.mark = ',')}.} -\item{escape}{Boolean; whether to escape special characters when producing -HTML or LaTeX tables. When \code{escape = FALSE}, you have to make sure -that special characters will not trigger syntax errors in LaTeX or HTML.} +\item{escape}{Whether to escape special characters when producing HTML or +LaTeX tables. When \code{escape = FALSE}, you have to make sure that +special characters will not trigger syntax errors in LaTeX or HTML.} \item{...}{Other arguments (see Examples and References).} } @@ -90,9 +90,9 @@ rows to show in the table, e.g., \code{options(knitr.kable.max_rows = 30)}. } \note{ When using \code{kable()} as a \emph{top-level} expression, you do not - need to explicitly \code{print()} it due to R's automatic implicit - printing. When it is wrapped inside other expressions (such as a - \code{\link{for}} loop), you must explicitly \code{print(kable(...))}. +need to explicitly \code{print()} it due to R's automatic implicit +printing. When it is wrapped inside other expressions (such as a +\code{for} loop), you must explicitly \code{print(kable(...))}. } \examples{ d1 = head(iris) @@ -137,15 +137,15 @@ kables(list(kable(d1, align = "l"), kable(d2)), caption = "A tale of two tables" } \references{ See - \url{https://bookdown.org/yihui/rmarkdown-cookbook/kable.html} for some - examples about this function, including specific arguments according to the - \code{format} selected. +\url{https://bookdown.org/yihui/rmarkdown-cookbook/kable.html} for some +examples about this function, including specific arguments according to the +\code{format} selected. } \seealso{ Other R packages such as \pkg{huxtable}, \pkg{xtable}, - \pkg{kableExtra}, \pkg{gt} and \pkg{tables} for HTML and LaTeX tables, and - \pkg{ascii} and \pkg{pander} for different flavors of markdown output and - some advanced features and table styles. For more on other packages for - creating tables, see - \url{https://bookdown.org/yihui/rmarkdown-cookbook/table-other.html}. +\pkg{kableExtra}, \pkg{gt} and \pkg{tables} for HTML and LaTeX tables, and +\pkg{ascii} and \pkg{pander} for different flavors of markdown output and +some advanced features and table styles. For more on other packages for +creating tables, see +\url{https://bookdown.org/yihui/rmarkdown-cookbook/table-other.html}. } diff --git a/man/knit.Rd b/man/knit.Rd index bf7cd0c5f8..52681f2a93 100644 --- a/man/knit.Rd +++ b/man/knit.Rd @@ -24,22 +24,22 @@ purl(..., documentation = 1L) function will try to guess a default, which will be under the current working directory.} -\item{tangle}{Boolean; whether to tangle the R code from the input file (like -\code{utils::\link{Stangle}}).} +\item{tangle}{Whether to tangle the R code from the input file (like +\code{\link[utils:Stangle]{utils::Stangle()}}).} \item{text}{A character vector. This is an alternative way to provide the input file.} -\item{quiet}{Boolean; suppress the progress bar and messages?} +\item{quiet}{Whether to suppress the progress bar and messages.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} \item{encoding}{Encoding of the input file; always assumed to be UTF-8 (i.e., this argument is effectively ignored).} -\item{...}{arguments passed to \code{\link{knit}()} from \code{purl()}} +\item{...}{Arguments passed to \code{\link[=knit]{knit()}} from \code{purl()}.} \item{documentation}{An integer specifying the level of documentation to add to the tangled script. \code{0} means to output pure code, discarding all text chunks); @@ -48,10 +48,10 @@ add all text chunks to code as roxygen comments.} } \value{ The compiled document is written into the output file, and the path - of the output file is returned. If the \code{text} argument is not - \code{NULL}, the compiled output is returned as a character vector. In - other words, if you provide a file input, you get an output filename; if - you provide a character vector input, you get a character vector output. +of the output file is returned. If the \code{text} argument is not +\code{NULL}, the compiled output is returned as a character vector. In +other words, if you provide a file input, you get an output filename; if +you provide a character vector input, you get a character vector output. } \description{ This function takes an input file, extracts the R code in it according to a @@ -75,8 +75,8 @@ First the filename of the output document is determined in this way: \file{.Rtex}, \file{.Rhtml} (\file{.Rhtm}) and \file{.Rmd} (\file{.Rmarkdown}) will generate \file{.tex}, \file{.html} and \file{.md} respectively. For other types of files, if the filename contains -\samp{_knit_}, this part will be removed in the output file, e.g., -\file{foo_knit_.html} creates the output \file{foo.html}; if \samp{_knit_} is +\verb{_knit_}, this part will be removed in the output file, e.g., +\file{foo_knit_.html} creates the output \file{foo.html}; if \verb{_knit_} is not found in the filename, \file{foo.ext} will produce \file{foo.txt} if \code{ext} is not \code{txt}, otherwise the output is \file{foo-out.txt}. If \code{tangle = TRUE}, \file{foo.ext} generates an R script \file{foo.R}. @@ -85,27 +85,27 @@ We need a set of syntax to identify special markups for R code chunks and R options, etc. The syntax is defined in a pattern list. All built-in pattern lists can be found in \code{all_patterns} (call it \code{apat}). First \pkg{knitr} will try to decide the pattern list based on the filename -extension of the input document, e.g. \samp{Rnw} files use the list -\code{apat$rnw}, \samp{tex} uses the list \code{apat$tex}, \samp{brew} uses +extension of the input document, e.g. \code{Rnw} files use the list +\code{apat$rnw}, \code{tex} uses the list \code{apat$tex}, \code{brew} uses \code{apat$brew} and HTML files use \code{apat$html}; for unknown extensions, the content of the input document is matched against all pattern lists to automatically determine which pattern list is being used. You can also manually set the pattern list using the \code{\link{knit_patterns}} object or -the \code{\link{pat_rnw}} series functions in advance and \pkg{knitr} will +the \code{\link[=pat_rnw]{pat_rnw()}} series functions in advance and \pkg{knitr} will respect the setting. According to the output format (\code{opts_knit$get('out.format')}), a set of output hooks will be set to mark up results from R (see -\code{\link{render_latex}}). The output format can be LaTeX, Sweave and HTML, +\code{\link[=render_latex]{render_latex()}}). The output format can be LaTeX, Sweave and HTML, etc. The output hooks decide how to mark up the results (you can customize the hooks). -The name \code{knit} comes from its counterpart \samp{weave} (as in Sweave), -and the name \code{purl} (as \samp{tangle} in Stangle) comes from a knitting +The name \code{knit} comes from its counterpart \code{weave} (as in Sweave), +and the name \code{purl} (as \code{tangle} in Stangle) comes from a knitting method `knit one, purl one'. If the input document has child documents, they will also be compiled -recursively. See \code{\link{knit_child}}. +recursively. See \code{\link[=knit_child]{knit_child()}}. See the package website and manuals in the references to know more about \pkg{knitr}, including the full documentation of chunk options and demos, @@ -113,39 +113,38 @@ etc. } \note{ The working directory when evaluating R code chunks is the directory of - the input document by default, so if the R code involves external files - (like \code{read.table()}), it is better to put these files under the same - directory of the input document so that we can use relative paths. However, - it is possible to change this directory with the package option - \code{\link{opts_knit}$set(root.dir = ...)} so all paths in code chunks are - relative to this \code{root.dir}. It is not recommended to change the - working directory via \code{\link{setwd}()} in a code chunk, because it may - lead to terrible consequences (e.g. figure and cache files may be written - to wrong places). If you do use \code{setwd()}, please note that - \pkg{knitr} will always restore the working directory to the original one. - Whenever you feel confused, print \code{getwd()} in a code chunk to see - what the working directory really is. - - If the \code{output} argument is a file path, it is strongly recommended to - be in the current working directory (e.g. \file{foo.tex} instead of - \file{somewhere/foo.tex}), especially when the output has external - dependencies such as figure files. If you want to write the output to a - different directory, it is recommended to set the working directory to that - directory before you knit a document. For example, if the source document - is \file{foo.Rmd} and the expected output is \file{out/foo.md}, you can - write \code{setwd('out/'); knit('../foo.Rmd')} instead of - \code{knit('foo.Rmd', 'out/foo.md')}. - - N.B. There is no guarantee that the R script generated by \code{purl()} can - reproduce the computation done in \code{knit()}. The \code{knit()} process - can be fairly complicated (special values for chunk options, custom chunk - hooks, computing engines besides R, and the \code{envir} argument, etc). If - you want to reproduce the computation in a report generated by - \code{knit()}, be sure to use \code{knit()}, instead of merely executing - the R script generated by \code{purl()}. This seems to be obvious, but some - people - \href{https://stat.ethz.ch/pipermail/r-devel/2014-May/069113.html}{do not - get it}. +the input document by default, so if the R code involves external files +(like \code{read.table()}), it is better to put these files under the same +directory of the input document so that we can use relative paths. However, +it is possible to change this directory with the package option +\code{\link{opts_knit}$set(root.dir = ...)} so all paths in code chunks are +relative to this \code{root.dir}. It is not recommended to change the +working directory via \code{\link[=setwd]{setwd()}} in a code chunk, because it may +lead to terrible consequences (e.g. figure and cache files may be written +to wrong places). If you do use \code{setwd()}, please note that +\pkg{knitr} will always restore the working directory to the original one. +Whenever you feel confused, print \code{getwd()} in a code chunk to see +what the working directory really is. + +If the \code{output} argument is a file path, it is strongly recommended to +be in the current working directory (e.g. \file{foo.tex} instead of +\file{somewhere/foo.tex}), especially when the output has external +dependencies such as figure files. If you want to write the output to a +different directory, it is recommended to set the working directory to that +directory before you knit a document. For example, if the source document +is \file{foo.Rmd} and the expected output is \file{out/foo.md}, you can +write \verb{setwd('out/'); knit('../foo.Rmd')} instead of +\code{knit('foo.Rmd', 'out/foo.md')}. + +N.B. There is no guarantee that the R script generated by \code{purl()} can +reproduce the computation done in \code{knit()}. The \code{knit()} process +can be fairly complicated (special values for chunk options, custom chunk +hooks, computing engines besides R, and the \code{envir} argument, etc). If +you want to reproduce the computation in a report generated by +\code{knit()}, be sure to use \code{knit()}, instead of merely executing +the R script generated by \code{purl()}. This seems to be obvious, but some +people +\href{https://stat.ethz.ch/pipermail/r-devel/2014-May/069113.html}{do not get it}. } \examples{ library(knitr) @@ -160,8 +159,8 @@ unlink(c("knitr-minimal.tex", "knitr-minimal.R", "figure"), recursive = TRUE) } \references{ Package homepage: \url{https://yihui.org/knitr/}. The \pkg{knitr} - \href{https://yihui.org/knitr/demo/manual/}{main manual}: and - \href{https://yihui.org/knitr/demo/graphics/}{graphics manual}. +\href{https://yihui.org/knitr/demo/manual/}{main manual}: and +\href{https://yihui.org/knitr/demo/graphics/}{graphics manual}. - See \code{citation('knitr')} for the citation information. +See \code{citation('knitr')} for the citation information. } diff --git a/man/knit2html.Rd b/man/knit2html.Rd index 8832f4a0b2..cf0254e368 100644 --- a/man/knit2html.Rd +++ b/man/knit2html.Rd @@ -22,39 +22,39 @@ knit2html( function will try to guess a default, which will be under the current working directory.} -\item{...}{Options passed to \code{litedown::\link[litedown]{mark}()}.} +\item{...}{Options passed to \code{\link[litedown:mark]{litedown::mark()}}.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} \item{text}{A character vector. This is an alternative way to provide the input file.} -\item{quiet}{Boolean; suppress the progress bar and messages?} +\item{quiet}{Whether to suppress the progress bar and messages.} \item{encoding}{Encoding of the input file; always assumed to be UTF-8 (i.e., this argument is effectively ignored).} -\item{force_v1}{Boolean; whether to force rendering the input document as an -R Markdown v1 document, even if it is for v2.} +\item{force_v1}{Whether to force rendering the input document as an R +Markdown v1 document, even if it is for v2.} } \value{ If the argument \code{text} is NULL, a character string (HTML code) - is returned; otherwise the result is written into a file and the filename - is returned. +is returned; otherwise the result is written into a file and the filename +is returned. } \description{ This is a convenience function to knit the input markdown source and call -\code{litedown::\link[litedown]{mark}()} to convert the result to HTML. +\code{\link[litedown:mark]{litedown::mark()}} to convert the result to HTML. } \note{ This function renders R Markdown v1, which is much less powerful than R - Markdown v2, i.e. the \pkg{rmarkdown} package - (\url{https://rmarkdown.rstudio.com}). To render R Markdown v2 documents to - HTML, please use \code{rmarkdown::render()} instead. For a lighter-weight - alternative that handles figure paths robustly, see - \code{litedown::\link[litedown]{fuse}()}. +Markdown v2, i.e. the \pkg{rmarkdown} package +(\url{https://rmarkdown.rstudio.com}). To render R Markdown v2 documents to +HTML, please use \code{rmarkdown::render()} instead. For a lighter-weight +alternative that handles figure paths robustly, see +\code{\link[litedown:fuse]{litedown::fuse()}}. } \examples{ # a minimal example @@ -66,5 +66,5 @@ if (interactive()) browseURL("test.html") unlink(c("test.Rmd", "test.html", "test.md")) } \seealso{ -\code{\link{knit}}, \code{litedown::\link[litedown]{mark}} +\code{\link[=knit]{knit()}}, \code{\link[litedown:mark]{litedown::mark()}} } diff --git a/man/knit2pandoc.Rd b/man/knit2pandoc.Rd index 756029313e..90a76431a7 100644 --- a/man/knit2pandoc.Rd +++ b/man/knit2pandoc.Rd @@ -25,23 +25,23 @@ knit2pandoc( function will try to guess a default, which will be under the current working directory.} -\item{tangle}{Boolean; whether to tangle the R code from the input file (like -\code{utils::\link{Stangle}}).} +\item{tangle}{Whether to tangle the R code from the input file (like +\code{\link[utils:Stangle]{utils::Stangle()}}).} \item{text}{A character vector. This is an alternative way to provide the input file.} -\item{quiet}{Boolean; suppress the progress bar and messages?} +\item{quiet}{Whether to suppress the progress bar and messages.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} \item{to}{Character string giving the Pandoc output format to use.} \item{pandoc_wrapper}{An R function used to call Pandoc. If \code{NULL} (the -default), \code{rmarkdown::\link[rmarkdown]{pandoc_convert}()} will be used -if \pkg{rmarkdown} is installed, otherwise \code{\link{pandoc}()}.} +default), \code{\link[rmarkdown:pandoc_convert]{rmarkdown::pandoc_convert()}} will be used +if \pkg{rmarkdown} is installed, otherwise \code{\link[=pandoc]{pandoc()}}.} \item{...}{Options to be passed to the \code{pandoc_wrapper} function.} diff --git a/man/knit2pdf.Rd b/man/knit2pdf.Rd index 40f8f2a00e..5fda8dfa1e 100644 --- a/man/knit2pdf.Rd +++ b/man/knit2pdf.Rd @@ -22,30 +22,30 @@ working directory.} \item{compiler}{A character string giving the LaTeX engine used to compile the tex document to PDF. For an Rrst file, setting \code{compiler} to -\code{'rst2pdf'} will use \code{\link{rst2pdf}} to compile the rst file to +\code{'rst2pdf'} will use \code{\link[=rst2pdf]{rst2pdf()}} to compile the rst file to PDF using the ReportLab open-source library. For an Rtyp file, setting \code{compiler} to \code{'typst'} will use the \command{typst} command-line tool to compile the typ file to PDF.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} -\item{quiet}{Boolean; suppress the progress bar and messages?} +\item{quiet}{Whether to suppress the progress bar and messages.} -\item{...}{Options to be passed to \code{tinytex::\link[tinytex]{latexmk}()} -or \code{\link{rst2pdf}()}.} +\item{...}{Options to be passed to \code{\link[tinytex:latexmk]{tinytex::latexmk()}} +or \code{\link[=rst2pdf]{rst2pdf()}}.} } \value{ The filename of the PDF file. } \description{ Knit the input Rnw or Rrst document, and compile to PDF using -\code{tinytex::\link[tinytex]{latexmk}()} or \code{\link{rst2pdf}()}. +\code{\link[tinytex:latexmk]{tinytex::latexmk()}} or \code{\link[=rst2pdf]{rst2pdf()}}. } \note{ The \code{output} argument specifies the output filename to be passed - to the PDF compiler (e.g. a tex document) instead of the PDF filename. +to the PDF compiler (e.g. a tex document) instead of the PDF filename. } \examples{ #' compile with xelatex diff --git a/man/knit2wp.Rd b/man/knit2wp.Rd index f94032c476..49cf1008a8 100644 --- a/man/knit2wp.Rd +++ b/man/knit2wp.Rd @@ -20,16 +20,16 @@ knit2wp( \item{title}{Title of the post.} -\item{...}{Other meta information of the post, e.g. \code{categories = c('R', -'Stats')} and \code{mt_keywords = c('knitr', 'wordpress')}, et cetera.} +\item{...}{Other meta information of the post, e.g., \code{categories = c('R', 'Stats')} and \code{mt_keywords = c('knitr', 'wordpress')}, etc.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} -\item{shortcode}{A length-2 logical vector: whether to use the shortcode -\samp{[sourcecode lang='lang']}, which can be useful to WordPress.com users -for syntax highlighting of source code and output. The first element +\item{shortcode}{A length-2 logical vector indicating whether to use the +shortcode \verb{[sourcecode lang='lang']}, which can be useful to +WordPress.com users for syntax highlighting of source code and output. The +first element applies to source code, and the second applies to text output. By default, both are \code{FALSE}.} @@ -39,7 +39,7 @@ create a new page.} \item{postid}{If \code{action} is \code{editPost}, the post id \code{postid} must be specified.} -\item{publish}{Boolean: publish the post immediately?} +\item{publish}{Whether to publish the post immediately.} } \description{ This function is a wrapper around the \pkg{RWordPress} package. It compiles @@ -50,10 +50,10 @@ blogging with R, you may want to try the \pkg{blogdown} package instead. } \note{ This function will convert the encoding of the post and the title to - UTF-8 internally. If you have additional data to send to WordPress (e.g. - keywords and categories), you may have to manually convert them to the - UTF-8 encoding with the \code{\link{iconv}(x, to = 'UTF-8')} function - (especially when using Windows). +UTF-8 internally. If you have additional data to send to WordPress (e.g. +keywords and categories), you may have to manually convert them to the +UTF-8 encoding with the \code{\link{iconv}(x, to = 'UTF-8')} function +(especially when using Windows). } \examples{ # see the reference diff --git a/man/knit_child.Rd b/man/knit_child.Rd index a554283094..b42a9ff0da 100644 --- a/man/knit_child.Rd +++ b/man/knit_child.Rd @@ -7,7 +7,7 @@ knit_child(..., options = NULL, envir = knit_global()) } \arguments{ -\item{...}{Arguments passed to \code{\link{knit}}.} +\item{...}{Arguments passed to \code{\link[=knit]{knit()}}.} \item{options}{A list of chunk options to be used as global options inside the child document. When one uses the \code{child} @@ -15,13 +15,13 @@ option in a parent chunk, the chunk options of the parent chunk will be passed to the \code{options} argument here. Ignored if not a list.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} } \value{ A character string of the content of the compiled child document is - returned as a character string so it can be written back to the parent - document directly. +returned as a character string so it can be written back to the parent +document directly. } \description{ This function knits a child document and returns a character string to input @@ -31,10 +31,10 @@ option \code{child} and serves as the alternative to the } \note{ This function is not supposed be called directly like - \code{\link{knit}()}; instead it must be placed in a parent document to let - \code{\link{knit}()} call it indirectly. +\code{\link[=knit]{knit()}}; instead it must be placed in a parent document to let +\code{\link[=knit]{knit()}} call it indirectly. - The path of the child document is determined relative to the parent document. +The path of the child document is determined relative to the parent document. } \examples{ # you can write \Sexpr{knit_child('child-doc.Rnw')} in an Rnw file 'main.Rnw' diff --git a/man/knit_code.Rd b/man/knit_code.Rd index 48f06df8d4..0f5ade6537 100644 --- a/man/knit_code.Rd +++ b/man/knit_code.Rd @@ -15,9 +15,7 @@ character vector of the code in the chunk with the label \code{foo}. } \note{ The methods on this object include the \code{set()} method (i.e., you - could do something like \code{knitr::knit_code$set(foo = "'my precious new - code'")}), but we recommend that you do not use this method to modify the - content of code chunks, unless you are - \href{https://emitanaka.rbind.io/post/knitr-knitr-code/}{as creative as Emi - Tanaka} and know what you are doing. +could do something like \code{knitr::knit_code$set(foo = "'my precious new code'")}), but we recommend that you do not use this method to modify the +content of code chunks, unless you are +\href{https://emitanaka.rbind.io/post/knitr-knitr-code/}{as creative as Emi Tanaka} and know what you are doing. } diff --git a/man/knit_engines.Rd b/man/knit_engines.Rd index 85fe55783a..36bc822a10 100644 --- a/man/knit_engines.Rd +++ b/man/knit_engines.Rd @@ -16,24 +16,22 @@ the output. \details{ The engine function has one argument \code{options}: the source code of the current chunk is in \code{options$code}. Usually we can call external -programs to run the code via \code{\link{system2}}. Other chunk options are +programs to run the code via \code{\link[=system2]{system2()}}. Other chunk options are also contained in this argument, e.g. \code{options$echo} and \code{options$eval}, etc. In most cases, \code{options$engine} can be directly used in command line to execute the code, e.g. \code{python} or \code{ruby}, but sometimes we may want to specify the path of the engine program, in which case we can pass it -through the \code{engine.path} option. For example, \code{engine='ruby', -engine.path='/usr/bin/ruby1.9.1'}. Additional command line arguments can be -passed through \code{options$engine.opts}, e.g. \code{engine='ruby', -engine.opts='-v'}. +through the \code{engine.path} option. For example, \verb{engine='ruby', engine.path='/usr/bin/ruby1.9.1'}. Additional command line arguments can be +passed through \code{options$engine.opts}, e.g. \verb{engine='ruby', engine.opts='-v'}. See \code{str(knitr::knit_engines$get())} for a list of built-in language engines. } \note{ The Leiningen engine \code{lein} requires lein-exec plugin; see - \url{https://github.com/yihui/knitr/issues/1176} for details. +\url{https://github.com/yihui/knitr/issues/1176} for details. } \examples{ knit_engines$get("python") @@ -42,5 +40,5 @@ names(knit_engines$get()) } \references{ Usage: \url{https://yihui.org/knitr/objects/}; examples: - \url{https://yihui.org/knitr/demo/engines/} +\url{https://yihui.org/knitr/demo/engines/} } diff --git a/man/knit_exit.Rd b/man/knit_exit.Rd index 9eb42f7f59..86e510065e 100644 --- a/man/knit_exit.Rd +++ b/man/knit_exit.Rd @@ -8,8 +8,8 @@ knit_exit(append, fully = TRUE) } \arguments{ \item{append}{A character vector to be appended to the results from -\code{knit()} so far. By default, this is \samp{\end{document}} for LaTeX -output, and \samp{} for HTML output, to make the output +\code{knit()} so far. By default, this is \verb{\\end\{document\}} for LaTeX +output, and \verb{} for HTML output, to make the output document complete. For other types of output, it is an empty string.} \item{fully}{Whether to fully exit the knitting process if \code{knit_exit()} @@ -18,13 +18,13 @@ process of the child document.} } \value{ Invisible \code{NULL}. An internal signal is set up (as a side - effect) to notify \code{knit()} to quit as if it had reached the end of the - document. +effect) to notify \code{knit()} to quit as if it had reached the end of the +document. } \description{ Sometimes we may want to exit the knitting process early, and completely ignore the rest of the document. This function provides a mechanism to -terminate \code{\link{knit}()}. +terminate \code{\link[=knit]{knit()}}. } \examples{ # see https://github.com/yihui/knitr-examples/blob/master/096-knit-exit.Rmd diff --git a/man/knit_expand.Rd b/man/knit_expand.Rd index 501bd900a1..031b84b773 100644 --- a/man/knit_expand.Rd +++ b/man/knit_expand.Rd @@ -19,7 +19,7 @@ the template code directly. If \code{text} is provided, \code{file} will be igno } \value{ A character vector, with the tags evaluated and replaced by their - values. +values. } \description{ This function expands a template based on the R expressions in \code{{{}}} @@ -33,5 +33,5 @@ if (interactive()) browseVignettes(package = "knitr") } \references{ This function was inspired by the pyexpander and m4 - (\url{http://www.gnu.org/software/m4/}), thanks to Frank Harrell. +(\url{http://www.gnu.org/software/m4/}), thanks to Frank Harrell. } diff --git a/man/knit_filter.Rd b/man/knit_filter.Rd index f8213ff0b0..681f4a8117 100644 --- a/man/knit_filter.Rd +++ b/man/knit_filter.Rd @@ -13,13 +13,13 @@ knit_filter(ifile, encoding = "UTF-8") } \value{ A character vector of the file content, excluding code chunks and - inline expressions. +inline expressions. } \description{ When performing spell checking on source documents, we may need to skip R code chunks and inline R expressions, because many R functions and symbols are likely to be identified as typos. This function is designed for the -\code{filter} argument of \code{\link{aspell}()} to filter out code chunks +\code{filter} argument of \code{\link[=aspell]{aspell()}} to filter out code chunks and inline expressions. } \examples{ diff --git a/man/knit_global.Rd b/man/knit_global.Rd index db8ca17684..9feb568005 100644 --- a/man/knit_global.Rd +++ b/man/knit_global.Rd @@ -8,7 +8,7 @@ knit_global(envir = NULL) } \arguments{ \item{envir}{If \code{NULL}, the function returns the \code{envir} argument -of \code{\link{knit}}, otherwise it should be a new environment for +of \code{\link[=knit]{knit()}}, otherwise it should be a new environment for evaluating code, in which case the function returns the old environment after setting the new environment.} } diff --git a/man/knit_meta.Rd b/man/knit_meta.Rd index dfe4f00bd0..5555bb5a54 100644 --- a/man/knit_meta.Rd +++ b/man/knit_meta.Rd @@ -25,7 +25,7 @@ defensive (i.e. not to have carryover metadata), you can call } \value{ \code{knit_meta()} returns the matched metadata specified by - \code{class}; \code{knit_meta_add()} returns all current metadata. +\code{class}; \code{knit_meta_add()} returns all current metadata. } \description{ As an object is printed, \pkg{knitr} will collect metadata about it (if diff --git a/man/knit_params.Rd b/man/knit_params.Rd index 4bb6dc4938..08b9425965 100644 --- a/man/knit_params.Rd +++ b/man/knit_params.Rd @@ -9,31 +9,31 @@ knit_params(text, evaluate = TRUE) \arguments{ \item{text}{Character vector containing the document text.} -\item{evaluate}{Boolean. If \code{TRUE} (the default), expression values embedded -within the YAML will be evaluated. If \code{FALSE}, parameters defined with an -expression will have the parsed but unevaluated expression in their \code{value} -field.} +\item{evaluate}{Boolean. If \code{TRUE} (the default), expression values +embedded within the YAML will be evaluated. If \code{FALSE}, parameters +defined with an expression will have the parsed but unevaluated expression +in their \code{value} field.} } \value{ List of objects of class \code{knit_param} that correspond to the - parameters declared in the \code{params} section of the YAML front matter. - These objects have the following fields: +parameters declared in the \code{params} section of the YAML front matter. +These objects have the following fields: - \describe{ - \item{\code{name}}{The parameter name.} - \item{\code{value}}{The default value for the parameter.} - \item{\code{expr}}{The R expression (if any) that yielded the default value.} - } +\describe{ +\item{\code{name}}{The parameter name.} +\item{\code{value}}{The default value for the parameter.} +\item{\code{expr}}{The R expression (if any) that yielded the default value.} +} - In addition, other fields included in the YAML may also be present - alongside the name, type, and value fields (e.g. a \code{label} field - that provides front-ends with a human readable name for the parameter). +In addition, other fields included in the YAML may also be present +alongside the name, type, and value fields (e.g. a \code{label} field +that provides front-ends with a human readable name for the parameter). } \description{ This function reads the YAML front-matter section of a document and returns a list of any parameters declared there. This function exists primarily to support the parameterized reports feature of the \pkg{rmarkdown} package, -however is also used by the knitr \code{\link{purl}} function to include +however is also used by the knitr \code{\link[=purl]{purl()}} function to include the default parameter values in the R code it emits. } \details{ diff --git a/man/knit_params_yaml.Rd b/man/knit_params_yaml.Rd index 510e2667c8..6ba80ee19e 100644 --- a/man/knit_params_yaml.Rd +++ b/man/knit_params_yaml.Rd @@ -9,20 +9,20 @@ knit_params_yaml(yaml, evaluate = TRUE) \arguments{ \item{yaml}{Character vector containing the YAML text.} -\item{evaluate}{If \code{TRUE} (the default) expression values -embedded within the YAML will be evaluated. If \code{FALSE}, parameters -defined with an expression will have the parsed but unevaluated expression -in their \code{value} field.} +\item{evaluate}{If \code{TRUE} (the default), expression values embedded +within the YAML will be evaluated. If \code{FALSE}, parameters defined with +an expression will have the parsed but unevaluated expression in their +\code{value} field.} } \value{ List of objects of class \code{knit_param} that correspond to the parameters declared in the \code{params} section of the YAML. See -\code{\link{knit_params}} for a full description of these objects. +\code{\link[=knit_params]{knit_params()}} for a full description of these objects. } \description{ This function reads the YAML front-matter that has already been extracted from a document and returns a list of any parameters declared there. } \seealso{ -\code{\link{knit_params}} +\code{\link[=knit_params]{knit_params()}} } diff --git a/man/knit_patterns.Rd b/man/knit_patterns.Rd index fe4c038b77..24a0133406 100644 --- a/man/knit_patterns.Rd +++ b/man/knit_patterns.Rd @@ -8,10 +8,10 @@ knit_patterns } \description{ Patterns are regular expressions and will be used in functions like -\code{base::\link{grep}()} to extract R code and chunk options. The object +\code{\link[base:grep]{base::grep()}} to extract R code and chunk options. The object \code{knit_patterns} controls the patterns currently used; see the references and examples for usage. All built-in patterns are available in the list -\link{all_patterns}. +\code{\link{all_patterns}}. } \examples{ library(knitr) @@ -34,7 +34,7 @@ knit_patterns$set(opat) # put the old patterns back \references{ Usage: \url{https://yihui.org/knitr/objects/} - Components in \code{knit_patterns}: \url{https://yihui.org/knitr/patterns/} +Components in \code{knit_patterns}: \url{https://yihui.org/knitr/patterns/} } \seealso{ \code{\link{all_patterns}} diff --git a/man/knit_print.Rd b/man/knit_print.Rd index 121be0b08e..ecb9cfd0d1 100644 --- a/man/knit_print.Rd +++ b/man/knit_print.Rd @@ -10,7 +10,7 @@ knit_print(x, ...) normal_print(x, ...) } \arguments{ -\item{x}{An R object to be printed} +\item{x}{An R object to be printed.} \item{...}{Additional arguments passed to the S3 method. Currently ignored, except two optional arguments \code{options} and \code{inline}; see @@ -18,9 +18,9 @@ the references below.} } \value{ The value returned from the print method should be a character vector - or can be converted to a character value. You can wrap the value in - \code{\link{asis_output}()} so that \pkg{knitr} writes the character value - as is in the output. +or can be converted to a character value. You can wrap the value in +\code{\link[=asis_output]{asis_output()}} so that \pkg{knitr} writes the character value +as is in the output. } \description{ The S3 generic function \code{knit_print} is the default printing function in @@ -34,12 +34,12 @@ Users can write custom methods based on this generic function. For example, if we want to print all data frames as tables in the output, we can define a method \code{knit_print.data.frame} that turns a data.frame into a table (the implementation may use other R packages or functions, e.g. \pkg{xtable} or -\code{\link{kable}()}). +\code{\link[=kable]{kable()}}). } \note{ It is recommended to leave a \code{...} argument in your method, to - allow future changes of the \code{knit_print()} API without breaking your - method. +allow future changes of the \code{knit_print()} API without breaking your +method. } \examples{ library(knitr) diff --git a/man/knit_rd.Rd b/man/knit_rd.Rd index 941c05d470..b99b860981 100644 --- a/man/knit_rd.Rd +++ b/man/knit_rd.Rd @@ -13,15 +13,15 @@ knit_rd_all() \item{pkg}{Package name.} \item{links}{A character vector of links to be passed to -\code{tools::\link{Rd2HTML}()}.} +\code{\link[tools:Rd2HTML]{tools::Rd2HTML()}}.} -\item{frame}{Boolean: whether to put a navigation frame on the left of the -index page.} +\item{frame}{Whether to put a navigation frame on the left of the index +page.} } \value{ All HTML pages corresponding to topics in the package are written - under the current working directory. An \file{index.html} is also written - as a table of content. +under the current working directory. An \file{index.html} is also written +as a table of content. } \description{ Run examples in a package and insert output into the examples code; @@ -30,9 +30,8 @@ HTML help pages for all packages under the \file{html} directory of them. } \note{ Ideally the html pages should be put under the \file{html} directory of - an installed package which can be found via \code{system.file('html', - package = 'your_package_name')}, otherwise some links may not work (e.g. - the link to the DESCRIPTION file). +an installed package which can be found via \code{system.file('html', package = 'your_package_name')}, otherwise some links may not work (e.g. +the link to the DESCRIPTION file). } \examples{ library(knitr) diff --git a/man/knit_theme.Rd b/man/knit_theme.Rd index afbeb20d3d..2886c300d0 100644 --- a/man/knit_theme.Rd +++ b/man/knit_theme.Rd @@ -19,9 +19,9 @@ returned by the \code{get()} method. See examples below. } \note{ The syntax highlighting here only applies to \file{.Rnw} (LaTeX) and - \file{.Rhtml} (HTML) documents, and it does not work for other types of - documents, such as \file{.Rmd} (R Markdown, which has its own syntax - highlighting themes; see \url{https://rmarkdown.rstudio.com}). +\file{.Rhtml} (HTML) documents, and it does not work for other types of +documents, such as \file{.Rmd} (R Markdown, which has its own syntax +highlighting themes; see \url{https://rmarkdown.rstudio.com}). } \examples{ opts_knit$set(out.format = "latex") @@ -36,7 +36,7 @@ opts_knit$set(out.format = NULL) # restore option } \references{ For a preview of all themes, see - \url{https://gist.github.com/yihui/3422133}. +\url{https://gist.github.com/yihui/3422133}. } \author{ Ramnath Vaidyanathan and Yihui Xie diff --git a/man/knit_watch.Rd b/man/knit_watch.Rd index a8851f197d..66ea65ecc2 100644 --- a/man/knit_watch.Rd +++ b/man/knit_watch.Rd @@ -10,7 +10,7 @@ knit_watch(input, compile = knit, interval = 1, ...) \item{input}{An input file path, or a character vector of multiple input file paths.} \item{compile}{A function to compile the \code{input} file. This could be e.g. -\code{\link{knit}} or \code{\link{knit2pdf}}, depending on the input file +\code{\link[=knit]{knit()}} or \code{\link[=knit2pdf]{knit2pdf()}}, depending on the input file and the output you want.} \item{interval}{A time interval to pause in each cycle of the infinite loop.} @@ -26,7 +26,7 @@ recompile the input file. This is actually a general function not necessarily restricted to applications in \pkg{knitr}. You may specify any \code{compile} function to process the \code{input} file. To stop the infinite loop, press the -\samp{Escape} key or \samp{Ctrl + C} (depending on your editing environment +\code{Escape} key or \code{Ctrl + C} (depending on your editing environment and operating system). } \examples{ diff --git a/man/knitr-package.Rd b/man/knitr-package.Rd index 1c148aabd9..041fbd140b 100644 --- a/man/knitr-package.Rd +++ b/man/knitr-package.Rd @@ -22,17 +22,17 @@ package website in the references for more information and examples. } \note{ The pronunciation of \pkg{knitr} is similar to \emph{neater} or you can - think of \emph{knitter} (but it is \emph{single t}). The name comes from - \code{knit} + \code{R} (while \code{Sweave} = \code{S} + \code{weave}). +think of \emph{knitter} (but it is \emph{single t}). The name comes from +\code{knit} + \code{R} (while \code{Sweave} = \code{S} + \code{weave}). } \references{ Full documentation and demos: \url{https://yihui.org/knitr/}; - FAQ's: \url{https://yihui.org/knitr/faq/} +FAQ's: \url{https://yihui.org/knitr/faq/} } \seealso{ -The core function in this package: \code{\link{knit}}. If you are an - Sweave user, see \code{\link{Sweave2knitr}} on how to convert Sweave files - to \pkg{knitr}. +The core function in this package: \code{\link[=knit]{knit()}}. If you are an +Sweave user, see \code{\link[=Sweave2knitr]{Sweave2knitr()}} on how to convert Sweave files +to \pkg{knitr}. } \author{ Yihui Xie <\url{https://yihui.org}> diff --git a/man/load_cache.Rd b/man/load_cache.Rd index f6c75802f2..24569dc8ad 100644 --- a/man/load_cache.Rd +++ b/man/load_cache.Rd @@ -31,16 +31,16 @@ directory otherwise. Any relative \code{path} is defined from \code{dir}.} \item{envir}{Environment to use for cache loading, into which all objects in the cache for the specified chunk (not just that in \code{object}) will be -loaded. Defaults to the value in \code{\link{knit_global}}.} +loaded. Defaults to the value in \code{\link[=knit_global]{knit_global()}}.} -\item{lazy}{Whether to \code{\link{lazyLoad}} the cache database (depending +\item{lazy}{Whether to \code{\link[=lazyLoad]{lazyLoad()}} the cache database (depending on the chunk option \code{cache.lazy = TRUE} or \code{FALSE} of that code chunk).} } \value{ Invisible \code{NULL} when \code{object} is not specified (the cache - database will be loaded as a side effect), otherwise the value of the - object if found. +database will be loaded as a side effect), otherwise the value of the +object if found. } \description{ If a code chunk has turned on the chunk option \code{cache = TRUE}, a cache @@ -54,13 +54,13 @@ they are created. } \note{ Apparently this function loads the value of the object from the - \emph{previous} run of the document, which may be problematic when the - value of the object becomes different the next time the document is - compiled. Normally you must compile the document twice to make sure the - cache database is created, and the object can be read from it. Please use - this function with caution. +\emph{previous} run of the document, which may be problematic when the +value of the object becomes different the next time the document is +compiled. Normally you must compile the document twice to make sure the +cache database is created, and the object can be read from it. Please use +this function with caution. } \references{ See the example #114 at - \url{https://github.com/yihui/knitr-examples}. +\url{https://github.com/yihui/knitr-examples}. } diff --git a/man/opts_chunk.Rd b/man/opts_chunk.Rd index 7674772f54..e3043eac08 100644 --- a/man/opts_chunk.Rd +++ b/man/opts_chunk.Rd @@ -27,8 +27,8 @@ See \code{str(knitr::opts_chunk$get())} for a list of default chunk options. } \note{ \code{opts_current} should be treated as read-only and you are supposed - to only query its values via \code{opts_current$get()}. Calling - \code{opts_current$set()} will throw an error. +to only query its values via \code{opts_current$get()}. Calling +\code{opts_current$set()} will throw an error. } \examples{ opts_chunk$get("prompt") @@ -37,6 +37,6 @@ opts_chunk$get("fig.keep") \references{ Usage: \url{https://yihui.org/knitr/objects/} - A list of available options: - \url{https://yihui.org/knitr/options/#chunk-options} +A list of available options: +\url{https://yihui.org/knitr/options/#chunk-options} } diff --git a/man/opts_knit.Rd b/man/opts_knit.Rd index 3b59c59bd4..85fcecabb5 100644 --- a/man/opts_knit.Rd +++ b/man/opts_knit.Rd @@ -13,7 +13,7 @@ the base directory of images, etc. \details{ Besides the standard usage (\code{opts_knit$set()}), we can also set package options prior to loading \code{knitr} or calling \code{knit()} using -\code{\link{options}()} in base R. A global option \code{knitr.package.foo} +\code{\link[=options]{options()}} in base R. A global option \code{knitr.package.foo} in \code{options()} will be set as an option \code{foo} in \code{opts_knit}, i.e. global options in base R with the prefix \code{knitr.package.} correspond to options in \code{opts_knit}. This can be useful to set package @@ -33,6 +33,6 @@ if (interactive()) { \references{ Usage: \url{https://yihui.org/knitr/objects/} - A list of available options: - \url{https://yihui.org/knitr/options/#package-options} +A list of available options: +\url{https://yihui.org/knitr/options/#package-options} } diff --git a/man/output_hooks.Rd b/man/output_hooks.Rd index 08ae0fffec..4a741467dd 100644 --- a/man/output_hooks.Rd +++ b/man/output_hooks.Rd @@ -68,11 +68,11 @@ hooks_typst() \arguments{ \item{envirs}{Names of LaTeX environments for code input, output, and chunk.} -\item{strict}{Boolean; whether to use strict markdown or reST syntax. For markdown, if +\item{strict}{Whether to use strict markdown or reST syntax. For markdown, if \code{TRUE}, code blocks will be indented by 4 spaces, otherwise they are put in fences made by three backticks. For reST, if \code{TRUE}, code is put under two colons and indented by 4 spaces, otherwise it is put under the -\samp{sourcecode} directive (this is useful for e.g. Sphinx).} +\code{sourcecode} directive (this is useful for e.g., Sphinx).} \item{fence_char}{A single character to be used in the code blocks fence. This can be e.g. a backtick or a tilde, depending on your Markdown rendering @@ -88,13 +88,13 @@ indented by 4 spaces).} can be \code{'linenos'}; for \code{prettify}, it can be \code{'linenums'}.} } \value{ -\code{NULL} for \code{render_*} functions; corresponding hooks are - set as a side effect. A list of output hooks for \code{hooks_*()} - functions. +\code{NULL} for \verb{render_*} functions; corresponding hooks are +set as a side effect. A list of output hooks for \verb{hooks_*()} +functions. } \description{ -The \code{render_*()} functions set built-in output hooks for LaTeX, HTML, -Markdown, reStructuredText, AsciiDoc, and Textile. The \code{hooks_*()} +The \verb{render_*()} functions set built-in output hooks for LaTeX, HTML, +Markdown, reStructuredText, AsciiDoc, and Textile. The \verb{hooks_*()} functions return a list of the output hooks for the corresponding format. } \details{ @@ -118,13 +118,13 @@ for reStructuredText; \code{render_textile()} (which calls \code{hooks_textile()}) is for Textile, and \code{render_asciidoc()} (which calls \code{hooks_asciidoc()}) is AsciiDoc. -The \code{render_*()} functions can be used before \code{knit()} or in the +The \verb{render_*()} functions can be used before \code{knit()} or in the first chunk of the input document (ideally this chunk has options \code{include = FALSE} and \code{cache = FALSE}) so that all the following chunks will be formatted as expected. You can also use \code{\link{knit_hooks}} to set the format's hooks with the -\code{hooks_*()} functions; see references for more info on further +\verb{hooks_*()} functions; see references for more info on further customizing output hooks. } \examples{ @@ -138,10 +138,10 @@ knitr::knit_hooks$restore() } \references{ See output hooks in \url{https://yihui.org/knitr/hooks/}, and - some examples in - \url{https://bookdown.org/yihui/rmarkdown-cookbook/output-hooks.html} +some examples in +\url{https://bookdown.org/yihui/rmarkdown-cookbook/output-hooks.html} - Jekyll and Liquid: - \url{https://github.com/jekyll/jekyll/wiki/Liquid-Extensions}; prettify.js: - \url{https://code.google.com/archive/p/google-code-prettify} +Jekyll and Liquid: +\url{https://github.com/jekyll/jekyll/wiki/Liquid-Extensions}; prettify.js: +\url{https://code.google.com/archive/p/google-code-prettify} } diff --git a/man/output_type.Rd b/man/output_type.Rd index 94e5aa61b7..1ff71eb5a9 100644 --- a/man/output_type.Rd +++ b/man/output_type.Rd @@ -25,8 +25,8 @@ considered as HTML format. Options are: markdown, epub, epub2, html, html4, html revealjs, s5, slideous, slidy, and gfm.} \item{exact}{Whether to return or use the exact format name. If not, Pandoc -extensions will be removed from the format name, e.g., \samp{latex-smart} -will be treated as \samp{latex}.} +extensions will be removed from the format name, e.g., \code{latex-smart} +will be treated as \code{latex}.} } \description{ The function \code{is_latex_output()} returns \code{TRUE} when the output @@ -35,8 +35,7 @@ the latter, the two Pandoc formats \code{latex} and \code{beamer} are considered LaTeX output). The function \code{is_html_output()} only works for R Markdown documents and will test for several Pandoc HTML based output formats (by default, these formats are considered as HTML formats: -\code{c('markdown', 'epub', 'epub2', 'html', 'html4', 'html5', 'revealjs', 's5', -'slideous', 'slidy', 'gfm')}). +\code{c('markdown', 'epub', 'epub2', 'html', 'html4', 'html5', 'revealjs', 's5', 'slideous', 'slidy', 'gfm')}). } \details{ The function \code{pandoc_to()} returns the Pandoc output format, and @@ -57,7 +56,7 @@ Pandoc input format in } \note{ See available Pandoc formats, in - \href{https://pandoc.org/MANUAL.html}{Pandoc's Manual} +\href{https://pandoc.org/MANUAL.html}{Pandoc's Manual} } \examples{ # check for output formats type diff --git a/man/pandoc.Rd b/man/pandoc.Rd index 79d7f32fee..f12079ff09 100644 --- a/man/pandoc.Rd +++ b/man/pandoc.Rd @@ -22,8 +22,8 @@ an extension \code{.pandoc} (e.g. for \file{foo.md} it looks for \file{foo.pandoc})} \item{ext}{Filename extensions. By default, the extension is inferred from -the \code{format}, e.g. \code{latex} creates \code{pdf}, \code{dzslides} -creates \code{html}, and so on} +the \code{format}, e.g., \code{latex} creates \code{pdf}, \code{dzslides} +creates \code{html}, and so on.} } \value{ The output filename(s) (or an error if the conversion failed). @@ -38,7 +38,7 @@ There are two ways to input the Pandoc configurations -- through a config file, or embed the configurations in the input file as special comments between \verb{}. -The configuration file is a DCF file (see \code{\link{read.dcf}}). This file +The configuration file is a DCF file (see \code{\link[=read.dcf]{read.dcf()}}). This file must contain a field named \code{t} which means the output format. The configurations are written in the form of \code{tag:value} and passed to Pandoc (if no value is needed, just leave it empty, e.g. the option @@ -55,14 +55,14 @@ system("pandoc -h") # see possible output formats } \references{ Pandoc: \url{https://pandoc.org}; Examples and rules of the - configurations: \url{https://yihui.org/knitr/demo/pandoc/} +configurations: \url{https://yihui.org/knitr/demo/pandoc/} - Also see R Markdown (v2) at \url{https://rmarkdown.rstudio.com}. The - \pkg{rmarkdown} package has several convenience functions and templates - that make it very easy to use Pandoc. The RStudio IDE also has - comprehensive support for it, so I'd recommend users who are not familiar - with command-line tools to use the \pkg{rmarkdown} package instead. +Also see R Markdown (v2) at \url{https://rmarkdown.rstudio.com}. The +\pkg{rmarkdown} package has several convenience functions and templates +that make it very easy to use Pandoc. The RStudio IDE also has +comprehensive support for it, so I'd recommend users who are not familiar +with command-line tools to use the \pkg{rmarkdown} package instead. } \seealso{ -\code{\link{read.dcf}} +\code{\link[=read.dcf]{read.dcf()}} } diff --git a/man/partition_chunk.Rd b/man/partition_chunk.Rd index 638f5a01c0..6f242f99f6 100644 --- a/man/partition_chunk.Rd +++ b/man/partition_chunk.Rd @@ -7,7 +7,7 @@ partition_chunk(engine, code) } \description{ -This is a wrapper function calling \code{xfun::\link[xfun]{divide_chunk}()} +This is a wrapper function calling \code{\link[xfun:divide_chunk]{xfun::divide_chunk()}} under the hood. } \keyword{internal} diff --git a/man/pat_fun.Rd b/man/pat_fun.Rd index a8c3a2ae98..fbd7e8075f 100644 --- a/man/pat_fun.Rd +++ b/man/pat_fun.Rd @@ -32,7 +32,7 @@ pat_typst() } \value{ The patterns object \code{\link{knit_patterns}} is modified as a side - effect. +effect. } \description{ These are convenience functions to set pre-defined pattern lists (the syntax diff --git a/man/plot_crop.Rd b/man/plot_crop.Rd index f4cae84352..ba2d990594 100644 --- a/man/plot_crop.Rd +++ b/man/plot_crop.Rd @@ -17,13 +17,13 @@ The original filename. \description{ The program \command{pdfcrop} (often shipped with a LaTeX distribution) is executed on a PDF plot file, and -\code{magick::\link[magick:transform]{image_trim}()} is executed for other +\code{\link[magick:image_trim]{magick::image_trim()}} is executed for other types of plot files. } \details{ The program \command{pdfcrop} can crop the extra white margins when the plot format is PDF, to make better use of the space in the output document, -otherwise we often have to struggle with \code{graphics::\link{par}()} to set +otherwise we often have to struggle with \code{\link[graphics:par]{graphics::par()}} to set appropriate margins. Note \command{pdfcrop} often comes with a LaTeX distribution such as TinyTeX, MiKTeX, or TeX Live, and you may not need to install it separately (use \code{Sys.which('pdfcrop')} to check it; if it not @@ -33,6 +33,6 @@ GhostScript. You can check if GhostScript is installed via } \references{ PDFCrop: \url{https://www.ctan.org/pkg/pdfcrop}. If you use - TinyTeX, you may install \command{pdfcrop} with - \code{tinytex::tlmgr_install('pdfcrop')}. +TinyTeX, you may install \command{pdfcrop} with +\code{tinytex::tlmgr_install('pdfcrop')}. } diff --git a/man/raw_block.Rd b/man/raw_block.Rd index 6ece27320b..a6dac3f65c 100644 --- a/man/raw_block.Rd +++ b/man/raw_block.Rd @@ -20,7 +20,7 @@ are not sure about the Pandoc output format of your document, insert a code chunk \code{knitr:::pandoc_to()} and see what it returns after the document is compiled.} -\item{...}{Arguments to be passed to \code{\link{asis_output}()}.} +\item{...}{Arguments to be passed to \code{\link[=asis_output]{asis_output()}}.} } \description{ Wraps content in a raw attribute block, which protects it from being escaped diff --git a/man/raw_output.Rd b/man/raw_output.Rd index 35a865c561..86883bd1cd 100644 --- a/man/raw_output.Rd +++ b/man/raw_output.Rd @@ -25,14 +25,14 @@ see \code{knitr:::raw_markers} for the default value.} \item{x}{The character vector to be protected.} -\item{...}{Arguments to be passed to \code{\link{asis_output}()}.} +\item{...}{Arguments to be passed to \code{\link[=asis_output]{asis_output()}}.} } \value{ For \code{extract_raw_output()}, a list of two components: - \code{value} (the \code{text} with raw output replaced by MD5 digests) and - \code{chunks} (a named character vector, of which the names are MD5 digests - and values are the raw output). For \code{restore_raw_output()}, the - restored \code{text}. +\code{value} (the \code{text} with raw output replaced by MD5 digests) and +\code{chunks} (a named character vector, of which the names are MD5 digests +and values are the raw output). For \code{restore_raw_output()}, the +restored \code{text}. } \description{ These functions provide a mechanism to protect the character output of R code diff --git a/man/read_chunk.Rd b/man/read_chunk.Rd index 55dd1ffdd7..57b1cc714e 100644 --- a/man/read_chunk.Rd +++ b/man/read_chunk.Rd @@ -31,19 +31,19 @@ code chunks, or a character vector; see Details.} \item{from.offset, to.offset}{Offsets to be added to \code{from}/\code{to}.} -\item{roxygen_comments}{Logical dictating whether to keep trailing -roxygen-style comments from code chunks in addition to whitespace} +\item{roxygen_comments}{Whether to keep trailing roxygen-style comments from +code chunks in addition to whitespace.} \item{topic, package}{Name of the demo and the package. See -\code{utils::\link{demo}}.} +\code{\link[utils:demo]{utils::demo()}}.} -\item{...}{Arguments passed to \code{\link{read_chunk}}.} +\item{...}{Arguments passed to \code{\link[=read_chunk]{read_chunk()}}.} } \value{ As a side effect, code chunks are read into the current session so - that future chunks can (re)use the code by chunk label references. If an - external chunk has the same label as a chunk in the current session, chunk - label references by future chunks will refer to the external chunk. +that future chunks can (re)use the code by chunk label references. If an +external chunk has the same label as a chunk in the current session, chunk +label references by future chunks will refer to the external chunk. } \description{ Chunks can be put in an external script, and this function reads chunks into @@ -52,7 +52,7 @@ to read a demo script from a package. } \details{ There are two approaches to read external code into the current session: (1) -Use a special separator of the from \code{## ---- chunk-label} (at least four +Use a special separator of the from \verb{## ---- chunk-label} (at least four dashes before the chunk label) in the script; (2) Manually specify the labels, starting and ending positions of code chunks in the script. @@ -72,9 +72,9 @@ supposed to be unique so that the numeric positions returned from } \note{ This function can only be used in a chunk which is \emph{not} cached - (chunk option \code{cache = FALSE}), and the code is read and stored in the - current session \emph{without} being executed (to actually run the code, - you have to use a chunk with a corresponding label). +(chunk option \code{cache = FALSE}), and the code is read and stored in the +current session \emph{without} being executed (to actually run the code, +you have to use a chunk with a corresponding label). } \examples{ ## put this in foo.R and read_chunk('foo.R') @@ -105,5 +105,5 @@ knitr::knit_code$restore() # clean up the session } \author{ Yihui Xie; the idea of the second approach came from Peter - Ruckdeschel (author of the \pkg{SweaveListingUtils} package) +Ruckdeschel (author of the \pkg{SweaveListingUtils} package) } diff --git a/man/rnw2pdf.Rd b/man/rnw2pdf.Rd index 50df7e381a..29d536bc54 100644 --- a/man/rnw2pdf.Rd +++ b/man/rnw2pdf.Rd @@ -22,14 +22,14 @@ rnw2pdf( as the \code{input}, but changes the file extension to ".pdf".} \item{compiler, ...}{The LaTeX engine and other arguments to be passed to -\code{tinytex::\link[tinytex]{latexmk}()}. The default compiler is +\code{\link[tinytex:latexmk]{tinytex::latexmk()}}. The default compiler is \code{xelatex}.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} -\item{quiet}{Boolean; suppress the progress bar and messages?} +\item{quiet}{Whether to suppress the progress bar and messages.} \item{clean}{If \code{TRUE}, the intermediate files will be removed.} @@ -39,18 +39,18 @@ example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or The \code{output} file path. } \description{ -Call \code{\link{knit}()} to compile the \file{.Rnw} input to \file{.tex}, -and then \code{tinytex::\link[tinytex]{latexmk}()} to convert \file{.tex} to +Call \code{\link[=knit]{knit()}} to compile the \file{.Rnw} input to \file{.tex}, +and then \code{\link[tinytex:latexmk]{tinytex::latexmk()}} to convert \file{.tex} to \file{.pdf}. } \details{ -This function is similar to \code{\link{knit2pdf}()}, with the following differences: +This function is similar to \code{\link[=knit2pdf]{knit2pdf()}}, with the following differences: \enumerate{ - \item The default compiler is "xelatex" instead of "pdflatex". - \item \code{output} uses the file extension ".pdf" instead of ".tex". - \item Before knitting, it tries to remove the \code{output} file and will throw a clear error if the file cannot be removed. - \item \code{output} could be under any dir, not necessarily the same directory as \code{input}. - \item It cleans up intermediate files by default, including the ".tex" file. - \item It stops knitting when any error occurs (by setting the chunk option \code{error = FALSE}). +\item The default compiler is "xelatex" instead of "pdflatex". +\item \code{output} uses the file extension ".pdf" instead of ".tex". +\item Before knitting, it tries to remove the \code{output} file and will throw a clear error if the file cannot be removed. +\item \code{output} could be under any dir, not necessarily the same directory as \code{input}. +\item It cleans up intermediate files by default, including the ".tex" file. +\item It stops knitting when any error occurs (by setting the chunk option \code{error = FALSE}). } } diff --git a/man/rocco.Rd b/man/rocco.Rd index 23e69ffd87..860e7b0b22 100644 --- a/man/rocco.Rd +++ b/man/rocco.Rd @@ -9,7 +9,7 @@ rocco(input, ...) \arguments{ \item{input}{Path of the input R Markdown file.} -\item{...}{Arguments to be passed to \code{\link{knit2html}}} +\item{...}{Arguments to be passed to \code{\link[=knit2html]{knit2html()}}} } \value{ An HTML file is written, and its name is returned. @@ -41,7 +41,7 @@ rocco_view(system.file("doc", "knit_expand.Rmd", package = "knitr")) } \references{ The Docco package by Jeremy Ashkenas: - \url{https://github.com/jashkenas/docco} +\url{https://github.com/jashkenas/docco} } \author{ Weicheng Zhu and Yihui Xie diff --git a/man/rst2pdf.Rd b/man/rst2pdf.Rd index 775dbf28d5..05ad7f54f6 100644 --- a/man/rst2pdf.Rd +++ b/man/rst2pdf.Rd @@ -13,11 +13,11 @@ rst2pdf(input, command = "rst2pdf", options = "") \command{rst2pdf} program. If the program is not in your PATH, the full path has to be given here.} -\item{options}{Extra command line options, e.g. \code{'-v'}.} +\item{options}{Extra command line options, e.g., \code{'-v'}.} } \value{ An input file \file{*.rst} will produce \file{*.pdf} and this output - filename is returned if the conversion was successful. +filename is returned if the conversion was successful. } \description{ Convert reST to PDF using \command{rst2pdf} (which converts from rst to PDF @@ -27,7 +27,7 @@ using the ReportLab open-source library). \url{https://github.com/rst2pdf/rst2pdf} } \seealso{ -\code{\link{knit2pdf}} +\code{\link[=knit2pdf]{knit2pdf()}} } \author{ Alex Zvoleff and Yihui Xie diff --git a/man/set_header.Rd b/man/set_header.Rd index cc54dc4101..a3f9df1a5f 100644 --- a/man/set_header.Rd +++ b/man/set_header.Rd @@ -18,16 +18,16 @@ The header vector in \code{opts_knit} is set. } \description{ Some output documents may need appropriate header information. For example, -for LaTeX output, we need to write \samp{\\usepackage{tikz}} into the +for LaTeX output, we need to write \verb{\\usepackage\{tikz\}} into the preamble if we use tikz graphics; this function sets the header information to be written into the output. } \details{ By default, \pkg{knitr} will set up the header automatically. For example, if -the tikz device is used, \pkg{knitr} will add \samp{\\usepackage{tikz}} to +the tikz device is used, \pkg{knitr} will add \verb{\\usepackage\{tikz\}} to the LaTeX preamble, and this is done by setting the header component -\code{tikz} to be a character string: \code{set_header(tikz = -'\\usepackage{tikz}')}. Similarly, when we highlight R code using the +\code{tikz} to be a character string: +\code{set_header(tikz = '\\\\usepackage{tikz}')}. Similarly, when we highlight R code using the \pkg{highlight} package (i.e. the chunk option \code{highlight = TRUE}), \pkg{knitr} will set the \code{highlight} component of the header vector automatically; if the output type is HTML, this component will be different diff --git a/man/set_parent.Rd b/man/set_parent.Rd index e2e70ef9d8..d4eba739b5 100644 --- a/man/set_parent.Rd +++ b/man/set_parent.Rd @@ -12,7 +12,7 @@ document.} } \value{ The preamble is extracted and stored to be used later when the - complete output is written. +complete output is written. } \description{ This function extracts the LaTeX preamble of the parent document to use for @@ -27,10 +27,10 @@ the parent document, it will apply to the child document as well. } \note{ Obviously this function is only useful when the output format is LaTeX. - This function only works when the child document is compiled in a - standalone mode using \code{\link{knit}()} (instead of being called in - \code{\link{knit_child}()}); when the parent document is compiled, this - function in the child document will be ignored. +This function only works when the child document is compiled in a +standalone mode using \code{\link[=knit]{knit()}} (instead of being called in +\code{\link[=knit_child]{knit_child()}}); when the parent document is compiled, this +function in the child document will be ignored. } \examples{ ## can use, e.g. \Sexpr{set_parent('parent_doc.Rnw')} or diff --git a/man/sew.Rd b/man/sew.Rd index 8c221ce241..d0fa2afeb2 100644 --- a/man/sew.Rd +++ b/man/sew.Rd @@ -7,7 +7,7 @@ sew(x, options = list(), ...) } \arguments{ -\item{x}{Output from \code{evaluate::\link[evaluate]{evaluate}()}.} +\item{x}{Output from \code{\link[evaluate:evaluate]{evaluate::evaluate()}}.} \item{options}{A list of chunk options used to control output.} diff --git a/man/spin.Rd b/man/spin.Rd index 0ca3ece232..e4c9deadc3 100644 --- a/man/spin.Rd +++ b/man/spin.Rd @@ -21,25 +21,25 @@ spin( \item{hair}{Path to the R script. The script must be encoded in UTF-8 if it contains multibyte characters.} -\item{knit}{Logical; whether to compile the document after conversion.} +\item{knit}{Whether to compile the document after conversion.} -\item{report}{Logical; whether to generate a report for \file{Rmd}, -\file{Rnw} and \file{Rtex} output. Ignored if \code{knit = FALSE}.} +\item{report}{Whether to generate a report for \file{Rmd}, \file{Rnw}, and +\file{Rtex} output. Ignored if \code{knit = FALSE}.} \item{text}{A character vector of code, as an alternative way to provide the R source. If \code{text} is not \code{NULL}, \code{hair} will be ignored.} -\item{envir}{Environment for \code{\link{knit}()} to evaluate the code.} +\item{envir}{Environment for \code{\link[=knit]{knit()}} to evaluate the code.} \item{format}{Character; the output format. The default is R Markdown.} \item{doc}{A regular expression to identify the documentation lines; by default it follows the roxygen convention, but it can be customized, e.g. -if you want to use \code{##} to denote documentation, you can use -\code{'^##\\\\s*'}.} +if you want to use \verb{##} to denote documentation, you can use +\code{'^##\\\\\\\\s*'}.} \item{inline}{A regular expression to identify inline R expressions; by -default, code of the form \code{\{\{code\}\}} on its own line is treated as +default, code of the form \code{{{code}}} on its own line is treated as an inline expression.} \item{comment}{A pair of regular expressions for the start and end delimiters @@ -47,19 +47,19 @@ of comments; the lines between a start and an end delimiter will be ignored. By default, the delimiters are \verb{/*} at the beginning of a line, and \verb{*/} at the end, following the convention of C comments.} -\item{precious}{logical: whether intermediate files (e.g., \code{.Rmd} files -when \code{format} is \code{"Rmd"}) should be preserved. The default is -\code{FALSE} if \code{knit} is \code{TRUE} and the input is a file.} +\item{precious}{Whether to preserve intermediate files (e.g., \code{.Rmd} +files when \code{format} is \code{"Rmd"}). The default is \code{FALSE} if +\code{knit} is \code{TRUE} and the input is a file.} } \value{ If \code{text} is \code{NULL}, the path of the final output document, - otherwise the content of the output. +otherwise the content of the output. } \description{ This function takes a specially formatted R script and converts it to a literate programming document. By default normal text (documentation) should -be written after the roxygen comment (\code{#'}) and code chunk options are -written after \code{#|} or \code{#+} or \code{# \%\%} or \code{# ----}. +be written after the roxygen comment (\verb{#'}) and code chunk options are +written after \verb{#|} or \verb{#+} or \verb{# \\\%\\\%} or \verb{# ----}. } \details{ Obviously the goat's hair is the original R script, and the wool is the @@ -67,24 +67,24 @@ literate programming document (ready to be knitted). } \note{ If the output format is \code{Rnw} and no document class is specified - in roxygen comments, this function will automatically add the - \code{article} class to the LaTeX document so that it is complete and can - be compiled. You can always specify the document class and other LaTeX - settings in roxygen comments manually. +in roxygen comments, this function will automatically add the +\code{article} class to the LaTeX document so that it is complete and can +be compiled. You can always specify the document class and other LaTeX +settings in roxygen comments manually. - When the output format is \code{Rmd}, it is compiled to HTML via - \code{\link{knit2html}()}, which uses R Markdown v1 instead of v2. If you - want to use the latter, you should call - \code{rmarkdown::\link[rmarkdown]{render}()} instead. Similarly, if the - output format is \code{qmd}, you need to render the output with Quarto. +When the output format is \code{Rmd}, it is compiled to HTML via +\code{\link[=knit2html]{knit2html()}}, which uses R Markdown v1 instead of v2. If you +want to use the latter, you should call +\code{\link[rmarkdown:render]{rmarkdown::render()}} instead. Similarly, if the +output format is \code{qmd}, you need to render the output with Quarto. } \references{ \url{https://yihui.org/knitr/demo/stitch/} } \seealso{ -\code{\link{stitch}} (feed a template with an R script) +\code{\link[=stitch]{stitch()}} (feed a template with an R script) } \author{ Yihui Xie, with the original idea from Richard FitzJohn (who named it - as \code{sowsear()} which meant to make a silk purse out of a sow's ear) +as \code{sowsear()} which meant to make a silk purse out of a sow's ear) } diff --git a/man/spin_child.Rd b/man/spin_child.Rd index 51aa72a1de..5181a1a160 100644 --- a/man/spin_child.Rd +++ b/man/spin_child.Rd @@ -16,12 +16,12 @@ provided, it will be guessed from the current knitting process.} A character string of the knitted R script. } \description{ -This function is similar to \code{\link{knit_child}()} but is used in R +This function is similar to \code{\link[=knit_child]{knit_child()}} but is used in R scripts instead. When the main R script is not called via -\code{\link{spin}()}, this function simply executes the child script via -\code{\link{sys.source}()}, otherwise it calls \code{\link{spin}()} to spin -the child script into a source document, and uses \code{\link{knit_child}()} +\code{\link[=spin]{spin()}}, this function simply executes the child script via +\code{\link[=sys.source]{sys.source()}}, otherwise it calls \code{\link[=spin]{spin()}} to spin +the child script into a source document, and uses \code{\link[=knit_child]{knit_child()}} to compile it. You can call this function in R code, or using the syntax of -inline R expressions in \code{\link{spin}()} (e.g. +inline R expressions in \code{\link[=spin]{spin()}} (e.g. \code{{{knitr::spin_child('script.R')}}}). } diff --git a/man/stitch.Rd b/man/stitch.Rd index 8ccb207fe5..17be498f9a 100644 --- a/man/stitch.Rd +++ b/man/stitch.Rd @@ -24,15 +24,15 @@ stitch_rmd(..., envir = parent.frame()) \item{template}{Path of the template to use. By default, the Rnw template in this package; there is also an HTML template in \pkg{knitr}.} -\item{output}{Output filename, passed to \code{\link{knit}}). By default, +\item{output}{Output filename, passed to \code{\link[=knit]{knit()}}). By default, the base filename of the script is used.} \item{text}{A character vector. This is an alternative way to provide the input file.} \item{envir}{Environment in which code chunks are to be evaluated, for -example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or -\code{\link{globalenv}()}).} +example, \code{\link[=parent.frame]{parent.frame()}}, \code{\link[=new.env]{new.env()}}, or +\code{\link[=globalenv]{globalenv()}}).} \item{...}{Arguments passed to \code{stitch()}.} } @@ -47,12 +47,12 @@ an R script and a template. The default template is an Rnw file (LaTeX); } \details{ The first two lines of the R script can contain the title and author of the -report in comments of the form \samp{## title:} and \samp{## author:}. The -template must have a token \samp{\%sCHUNK_LABEL_HERE}, which will be used to +report in comments of the form \verb{## title:} and \verb{## author:}. The +template must have a token \verb{\\\%sCHUNK_LABEL_HERE}, which will be used to input all the R code from the script. See the examples below. -The R script may contain chunk headers of the form \samp{## ---- label, -opt1=val1, opt2=val2}, which will be copied to the template; if no chunk +The R script may contain chunk headers of the form +\verb{## ---- label, opt1=val1, opt2=val2}, which will be copied to the template; if no chunk headers are found, the whole R script will be inserted into the template as one code chunk. } @@ -69,5 +69,5 @@ stitch(s, system.file("misc", "knitr-template.Rmd", package = "knitr")) unlink(c("stitch-test.html", "stitch-test.md", "figure"), recursive = TRUE) } \seealso{ -\code{\link{spin}} (turn a specially formatted R script to a report) +\code{\link[=spin]{spin()}} (turn a specially formatted R script to a report) } diff --git a/man/vignette_engines.Rd b/man/vignette_engines.Rd index 790ae0daea..e8f0266dbc 100644 --- a/man/vignette_engines.Rd +++ b/man/vignette_engines.Rd @@ -5,23 +5,23 @@ \title{Package vignette engines} \description{ Since R 3.0.0, package vignettes can use non-Sweave engines, and \pkg{knitr} -has provided a few engines to compile vignettes via \code{\link{knit}()} with +has provided a few engines to compile vignettes via \code{\link[=knit]{knit()}} with different templates. See \url{https://yihui.org/knitr/demo/vignette/} for more information. } \note{ If you use the \code{knitr::rmarkdown} engine, please make sure that - you put \pkg{rmarkdown} in the \samp{Suggests} field of your - \file{DESCRIPTION} file. Also make sure \command{pandoc} is available - during \command{R CMD build}. If you build your package from RStudio, this - is normally not a problem. If you build the package outside RStudio, run - \code{rmarkdown::find_pandoc()} in an R session to check if Pandoc can be - found. +you put \pkg{rmarkdown} in the \code{Suggests} field of your +\file{DESCRIPTION} file. Also make sure \command{pandoc} is available +during \command{R CMD build}. If you build your package from RStudio, this +is normally not a problem. If you build the package outside RStudio, run +\code{rmarkdown::find_pandoc()} in an R session to check if Pandoc can be +found. - When the \pkg{rmarkdown} package is not installed or not available, or - \command{pandoc} cannot be found, the \code{knitr::rmarkdown} engine will - fall back to the \code{knitr::knitr} engine, which uses R Markdown v1 based - on the \pkg{litedown} package. +When the \pkg{rmarkdown} package is not installed or not available, or +\command{pandoc} cannot be found, the \code{knitr::rmarkdown} engine will +fall back to the \code{knitr::knitr} engine, which uses R Markdown v1 based +on the \pkg{litedown} package. } \examples{ library(knitr) diff --git a/man/wrap_rmd.Rd b/man/wrap_rmd.Rd index decd33c979..aa3f1e7a30 100644 --- a/man/wrap_rmd.Rd +++ b/man/wrap_rmd.Rd @@ -16,11 +16,11 @@ wrap_rmd(file, width = 80, text = NULL, backup) \item{backup}{Path to back up the original file in case anything goes wrong. If set to \code{NULL}, no backup is made. The default value is constructed -from \code{file} by adding \code{__} before the base filename.} +from \code{file} by adding \verb{__} before the base filename.} } \value{ If \code{file} is provided, it is overwritten; if \code{text} is - provided, a character vector is returned. +provided, a character vector is returned. } \description{ This function wraps long paragraphs in an R Markdown file. Other elements are @@ -30,7 +30,7 @@ easier to review differences in version control. } \note{ Currently it does not wrap blockquotes or lists (ordered or unordered). - This feature may or may not be added in the future. +This feature may or may not be added in the future. } \examples{ wrap_rmd(text = c("```", "1+1", "```", "- a list item", "> a quote", "", diff --git a/man/write_bib.Rd b/man/write_bib.Rd index e77bb7669f..cd551f0efc 100644 --- a/man/write_bib.Rd +++ b/man/write_bib.Rd @@ -7,7 +7,7 @@ write_bib(..., prefix = getOption("knitr.bib.prefix", "R-")) } \arguments{ -\item{..., prefix}{Arguments passed to \code{xfun::\link[xfun]{pkg_bib}()}.} +\item{..., prefix}{Arguments passed to \code{\link[xfun:pkg_bib]{xfun::pkg_bib()}}.} } \description{ A wrapper function of \code{xfun::pkg_bib()}.