# What is rasciidoc?

Inspired by Karl Bromans 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.

# Knitting

## A Minimal Example

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
:toc2:
:numbered:
:data-uri:
:duration: 120

== A Section

=== A Subsection

* 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/Rtmp1AwfCx/knit.Rasciidoc.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/Rtmp1AwfCx. 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/Rtmp1AwfCx/knit.Rasciidoc
## output file: /tmp/Rtmp1AwfCx/knit.asciidoc
## [1] 0

# Spinnig

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
#' :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
#'
#' * Yet another entry in the list.
#'
#' == Including Code
#' Do not use the _include_ macro provided by asciidoc!
#' Instead prefix all source statements with
#' ----
#' #+ include = FALSE
#' ----
#' It est use
#' ----
#' #+ include = FALSE
#' source("src/sum.R")
#' ----
#' to produce
#+ include = FALSE
source("src/sum.R")
#'
#'
message("A message, probably different output hooks.")
#' == A new section
#'
#' === 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/Rtmp1AwfCx/spin.R_nolint.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/Rtmp1AwfCx. 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

# The Option “write_to_disk”

You may have noticed that output is written to tempdir(), instead to the subdirectories below it. 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.

# Knitr Hooks

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 knitrs 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/Rtmp1AwfCx/spin.R_nolint.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/Rtmp1AwfCx. 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