Inspired by Karl Broman`s reader on using knitr with asciidoc (http://kbroman.org/knitr_knutshell/pages/asciidoc.html), this is a wrapper to and a slight modification of knitr.
Suppose, you have a file that reads
file_name <- system.file("files", "minimal", "knit.Rasciidoc",
package = "rasciidoc")
cat(readLines(file_name), sep = "\n")
= Some Title
Your Name
:toc2:
:numbered:
:data-uri:
:duration: 120
== A Section
=== A Subsection
* A list with a https://en.wikipedia.org/wiki/Hyperlink[link].
* Yet another entry in the list.
== Code
//begin.rcode
a <- c(2, 3, 4, 10) # <1>
value <- 0 # <2>
for (a_i in a) { # <3>
value <- value + a_i # <4>
}
print(value) # <5>
//end.rcode
== A new section
//begin.rcode
my_sum <- function(x) {
value <- 0
for (x_i in x) {
value <- value + x_i
}
return(value)
}
//end.rcode
If you run render
on this file (we use a temporary directory here)
withr::with_dir(tempdir(), {
file.copy(file_name, ".")
rasciidoc::render(basename(file_name))
})
## Warning in run_knit(file_name, knit = knit, envir = envir): Setting option knit
## to TRUE based on the file contents!
## 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 /tmp/RtmpcZokEj/knit.Rasciidoc.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/RtmpcZokEj. 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.
## processing file: /tmp/RtmpcZokEj/knit.Rasciidoc
## output file: /tmp/RtmpcZokEj/knit.asciidoc
## [1] 0
you will create an HTML file that is identical to this file and that you could browse using browseURL(file.path(tempdir(), paste0(sub("\\..*$", "", basename(file_name)), ".html")))
from your current R session (vignettes like this are not allowed to start external programs like browsers, so you’ll have to do it yourself).
Suppose you changed your file to be less minimalistic:
file_name <- system.file("files", "simple", "knit.Rasciidoc",
package = "rasciidoc")
cat(readLines(file_name), sep = "\n")
= Some Title
Your Name
:toc2:
:numbered:
:data-uri:
:duration: 120
== What is this About?
=== Some simple asciidoc
* A list with a https://en.wikipedia.org/wiki/Hyperlink[link].
* Yet another entry in the list.
== Including Code
Do not use the _include_ macro provided by asciidoc!
//begin.rcode, code = readLines("src/sum.R")
//end.rcode
== A new section
//begin.rcode, code = readLines("src/my_sum.R")
//end.rcode
=== A subsection
//begin.rcode
print(value)
//end.rcode
//begin.rcode
print(my_sum(1:3))
//end.rcode
Some inline code: Object +value+ has value +r value+.
=== Second subsection
This file obviously reads code from files in a subdirectory called “src/”, so if you had that subdirectory and its files, too:
my_directory <- file.path(tempdir(), "simple")
dir.create(my_directory)
withr::with_dir(my_directory, {
file.copy(file_name, ".")
file.copy(file.path(dirname(file_name), "src"), ".",
recursive = TRUE)
})
## [1] TRUE
dir(my_directory, recursive = TRUE, full.names = TRUE)
## [1] "/tmp/RtmpcZokEj/simple/knit.Rasciidoc"
## [2] "/tmp/RtmpcZokEj/simple/src/my_sum.R"
## [3] "/tmp/RtmpcZokEj/simple/src/sum.R"
you could render
the file
rasciidoc::render(file.path(my_directory, basename(file_name)))
## Warning in run_knit(file_name, knit = knit, envir = envir): Setting option knit
## to TRUE based on the file contents!
## 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 /tmp/RtmpcZokEj/simple/knit.Rasciidoc.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/RtmpcZokEj. 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.
## processing file: /tmp/RtmpcZokEj/simple/knit.Rasciidoc
## output file: /tmp/RtmpcZokEj/knit.asciidoc
## [1] 0
and create an HTML file that is identical to this file and that you could browse using browseURL(file.path(tempdir(), paste0(sub("\\..*$", "", basename(file_name)), ".html")))
from your current R session .
You can also use a spinnig file for input:
file_name <- system.file("files", "simple", "spin.R_nolint",
package = "rasciidoc")
cat(readLines(file_name), sep = "\n")
#' = Some Title
#' Your Name
#' :toc2:
#' :numbered:
#' :data-uri:
#' :duration: 120
#'
#' == What is this About?
#'
#' //begin_no_slide
#' This will not show up on slides.
#' //end_no_slide
#'
#' === Some simple asciidoc
#'
#' * A list with a https://en.wikipedia.org/wiki/Hyperlink[link].
#' * Yet another entry in the list.
#'
#' == Including Code
#' Do not use the _include_ macro provided by asciidoc!
#' Instead prefix all source statements with
#' ----
#' #+ code = readLines("file_to_be_sourced")
#' #+ include = FALSE
#' ----
#' It est use
#' ----
#' #+ code = readLines("src/sum.R")
#' #+ include = FALSE
#' source("src/sum.R")
#' ----
#' to produce
#+ code = readLines("src/sum.R")
#+ include = FALSE
source("src/sum.R")
#'
#'
message("A message, probably different output hooks.")
#' == A new section
#'
#+ code = readLines("src/my_sum.R")
#' === A subsection
print(value)
#'
print(my_sum(1:3))
#'
#' Inline code does not work: Object +value+ has value +r value+.
#'
You run render
on it:
withr::with_dir(tempdir(), {
file.copy(file_name, ".", overwrite = TRUE)
file.copy(file.path(dirname(file_name), "src"), ".",
recursive = TRUE)
rasciidoc::render(basename(file_name))
})
## 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 /tmp/RtmpcZokEj/spin.R_nolint.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/RtmpcZokEj. 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.
## [1] 0
You may have noticed that output is written to tempdir()
instead of to the directory of your Rasciidoc input. This is due to the CRAN policy of not writing “anywhere else on the file system apart from the R session’s temporary directory”. 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.
I change the way knitr translates (see here), as it 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.
rasciidoc::render(file.path(tempdir(), basename(file_name)), hooks = NULL)
## 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 /tmp/RtmpcZokEj/spin.R_nolint.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/RtmpcZokEj. 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.
## [1] 0