Package 'rasciidoc'

Create Reports Using R and asciidoc

Description

Inspired by Karl Broman's reader on using knitr with asciidoc (https://kbroman.org/knitr_knutshell/pages/asciidoc.html), this is merely a wrapper to knitr and asciidoc.

Arguments

write_to_disk

Write to disk? See Warning.

Details

You will find the details in
vignette("An_Introduction_to_rasciidoc", package = "rasciidoc").

Warning

Due to the CRAN policy of not writing "anywhere else on the file system apart from the R session's temporary directory", we work on a temporary copy of file_name. Thus all internal sourcing and internal links will be broken and any output is written to tempdir(). Set the option "write_to_disk" to TRUE (using
options(write_to_disk = TRUE)
to bypass this. You may want to include the above line into your ‘~/.Rprofile’.

---

Adjust knitr's Hooks for asciidoc

Description

By default, knitr renders messages, warnings and errors to [NOTE|WARNING|ERROR]-blocks in asciidoc, which is ... not my choice. To restore knitr's behaviour, set hooks or replacement to NULL.

Usage

adjust_asciidoc_hooks(
  hooks = c("message", "error", "warning"),
  replacement = "source"
)

Arguments

hooks	Character vector naming the output hooks to be replaced by the replacement's hooks.
replacement	The hook with which to replace the hooks given by hooks.

Details

This is a modified version of render_asciidoc of knitr version 1.18.7.

Value

The return value of knit_hooks$set, invisibly NULL, currently.

---

Render an asciidoc File

Description

This is the basic interface to asciidoc. Not more than a call to system2 and checks on asciidoc and source-highlight. You should usually not call it directly, see render for a wrapper.

Usage

rasciidoc(
  file_name,
  ...,
  write_to_disk = getOption("write_to_disk"),
  enforce_requirements = getOption("enforce_requirements"),
  git_checkout_asciidoc_tag = NA
)

Arguments

file_name	The file to run asciidoc on.
...	arguments passed to asciidoc via system2.
write_to_disk	Write to disk? See Warning.
enforce_requirements	Should system requirements be enforced (CRAN requires packages to pass checks if system requirements (external commands) are not met)? Set to TRUE to enforce.
git_checkout_asciidoc_tag	If asciidoc is not installed, it is loaded from https://github.com/. Depending on your python version (python2 or python3), asciidoc for python2 or python3 is loaded. You may specify a tag to use with the repository. Either pass a tag number as a string ("9.1.0", for example), NULL to force the latest tagged version, or NA Don't mind, just stick with the default. You would have to know which python version will be used.

Value

Invisibly TRUE or FALSE, depending on success.

Warning

Due to the CRAN policy of not writing "anywhere else on the file system apart from the R session's temporary directory", we work on a temporary copy of file_name. Thus all internal sourcing and internal links will be broken and any output is written to tempdir(). Set the option "write_to_disk" to TRUE (using
options(write_to_disk = TRUE)
to bypass this. You may want to include the above line into your ‘~/.Rprofile’.

See Also

render

Examples

# CRAN complains about elapsed times
if (fritools::is_running_on_fvafrcu_machines()) {
    wd <- file.path(tempdir(), "rasciidoc")
    dir.create(wd)
    file  <- system.file("files", "minimal", "knit.asciidoc",
                         package = "rasciidoc")
    file.copy(file, wd)
    r <- rasciidoc(file_name = file.path(wd, basename(file)),
                   write_to_disk = getOption("write_to_disk"), "-b html")
    if (interactive()) browseURL(attr(r, "info")[["output"]])
    if (isTRUE(getOption("write_to_disk"))) {
        dir(wd, full.names = TRUE)
    } else {
        dir(tempdir(), full.names = TRUE)
    }
    unlink(wd, recursive = TRUE)
}

---

Spin or Knit and Render a 'Rasciidoc' File

Description

Spin or Knit (if required) and render an 'Rasciidoc' file.

Usage

render(
  file_name,
  knit = NA,
  write_to_disk = getOption("write_to_disk"),
  envir = parent.frame(),
  hooks = c("message", "error", "warning"),
  replacement = "source",
  asciidoc_args = "-b html",
  what = c("auto", "all", "no_slides", "slides"),
  git_checkout_asciidoc_tag = NA,
  clean = FALSE,
  ...
)

Arguments

file_name	The file to render.
knit	Knit the file first using knitr::knit? If set to NA, knitting is based on the file's contents or name. Set to TRUE to force knitting or to FALSE, to disable knitting.
write_to_disk	Write to disk? See Warning.
envir	The frame in which to render.
hooks	Character vector naming the output hooks to be replaced by the replacement's hooks.
replacement	The hook with which to replace the hooks given by hooks.
asciidoc_args	arguments passed to asciidoc via system2.
what	What is to be rendered? "all" renders everything, "no_slides" renders parts that are not meant for slides, "slides" renders parts that are meant for slides. The defaults looks for any in- or exclusion tagging and renders parts that are not meant for slides if found any, else it renders everything.
git_checkout_asciidoc_tag	If asciidoc is not installed, it is loaded from https://github.com/. Depending on your python version (python2 or python3), asciidoc for python2 or python3 is loaded. You may specify a tag to use with the repository. Either pass a tag number as a string ("9.1.0", for example), NULL to force the latest tagged version, or NA Don't mind, just stick with the default. You would have to know which python version will be used.
clean	Remove temporary file(s)?
...	Only there to register as vignette engine. Do not use!

Value

The return value of rasciidoc.

Warning

Due to the CRAN policy of not writing "anywhere else on the file system apart from the R session's temporary directory", we work on a temporary copy of file_name. Thus all internal sourcing and internal links will be broken and any output is written to tempdir(). Set the option "write_to_disk" to TRUE (using
options(write_to_disk = TRUE)
to bypass this. You may want to include the above line into your ‘~/.Rprofile’.

See Also

rasciidoc

Examples

# CRAN complains about elapsed times
if (fritools::is_running_on_fvafrcu_machines()) {
    wd <- file.path(tempdir(), "rasciidoc")
    dir.create(wd)
    file  <- system.file("files", "minimal", "knit.Rasciidoc",
                         package = "rasciidoc")
    file.copy(file, wd)
    r <- rasciidoc::render(file.path(wd, basename(file)),
                           write_to_disk = getOption("write_to_disk"),
                           asciidoc_args = "-b slidy")
    if (isTRUE(getOption("write_to_disk"))) {
        dir(wd, full.names = TRUE)
    } else {
        dir(tempdir(), full.names = TRUE)
    }
    unlink(wd, recursive = TRUE)
}

---