Save a help page to a file

Renders an R help page for a given topic and writes it to a file.

Usage

save_help(topic, output, md_format = md_format_default, wrap = Inf)

Arguments

topic

(bare base::name or string literal)
The topic/function to look up. Accepts bare names (mean, base::mean) or string literals ("mean", "base::mean"). Uses non-standard evaluation, thus passing a variable that holds a string is not supported. When no package is specified, all loaded packages are searched.

output

(Scalar character)
File path where the rendered help page will be written. The extension must be one of .md, .html, .htm, or .txt.

md_format

(Scalar character: md_format_default)
Pandoc output format string used for Markdown conversion. Only applies when output has a .md extension. See Pandoc manual for available formats and extensions.

wrap

(Scalar integer: Inf; [1, Inf])
Column width for word wrapping in Markdown output. Inf disables wrapping. Only applies when output has a .md extension.

Value

The value of output, invisibly.

Details

For Markdown output, the function first renders the help page to a temporary HTML file via tools::Rd2HTML(), converts argument tables to HTML definition lists for cleaner Markdown output, then converts to Markdown using Pandoc. Pandoc must be installed and on the system PATH. The default markdown format is:

md_format_default <- paste0(
  "markdown",
  "-raw_html",
  "-inline_code_attributes",
  "-header_attributes",
  "-link_attributes",
  "-native_divs",
  "-native_spans",
  "-auto_identifiers",
  "-fenced_divs",
  "-bracketed_spans",
  "-smart"
)

See also

utils::help()

Examples

#----------------------------------------------------------------------------
# save_help() example
#----------------------------------------------------------------------------
library(bkmisc)

# Help file for mean function
tmp <- tempfile(fileext = ".md")
save_help(base::mean, output = tmp)
readLines(tmp) |> head(20)
#>  [1] "  ------------- -----------------"                  
#>  [2] "  mean {base}     R Documentation"                  
#>  [3] "  ------------- -----------------"                  
#>  [4] ""                                                   
#>  [5] "## Arithmetic Mean"                                 
#>  [6] ""                                                   
#>  [7] "### Description"                                    
#>  [8] ""                                                   
#>  [9] "Generic function for the (trimmed) arithmetic mean."
#> [10] ""                                                   
#> [11] "### Usage"                                          
#> [12] ""                                                   
#> [13] "``` R"                                              
#> [14] "mean(x, ...)"                                       
#> [15] ""                                                   
#> [16] "## Default S3 method:"                              
#> [17] "mean(x, trim = 0, na.rm = FALSE, ...)"              
#> [18] "```"                                                
#> [19] ""                                                   
#> [20] "### Arguments"                                      

# Help file for Arithmetic topic
tmp <- tempfile(fileext = ".md")
save_help(Arithmetic, output = tmp)
readLines(tmp) |> head(20)
#>  [1] "  ------------------- -----------------"                                                                                     
#>  [2] "  Arithmetic {base}     R Documentation"                                                                                     
#>  [3] "  ------------------- -----------------"                                                                                     
#>  [4] ""                                                                                                                            
#>  [5] "## Arithmetic Operators"                                                                                                     
#>  [6] ""                                                                                                                            
#>  [7] "### Description"                                                                                                             
#>  [8] ""                                                                                                                            
#>  [9] "These unary and binary operators perform arithmetic on numeric or complex vectors (or objects which can be coerced to them)."
#> [10] ""                                                                                                                            
#> [11] "### Usage"                                                                                                                   
#> [12] ""                                                                                                                            
#> [13] "``` R"                                                                                                                       
#> [14] "+ x"                                                                                                                         
#> [15] "- x"                                                                                                                         
#> [16] "x + y"                                                                                                                       
#> [17] "x - y"                                                                                                                       
#> [18] "x * y"                                                                                                                       
#> [19] "x / y"                                                                                                                       
#> [20] "x ^ y"