= What the hell is *rasciidoc*? 
Andreas Dominik Cullmann
:toc2:

////
    %\VignetteIndexEntry{Knitting Asciidoc with R}
    %\VignetteEngine{rasciidoc::rasciidoc}
////
Inspired by Karl Broman`s reader on using knitr
with asciidoc
(https://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
//begin.rcode
file_name <- system.file("files", "minimal", "plot.Rasciidoc",
                         package = "rasciidoc")
cat(readLines(file_name), sep = "\n")
//end.rcode
If you run +render+ on this file (we use a temporary directory here)
//begin.rcode
withr::with_dir(tempdir(), {
                    file.copy(file_name, ".")
                    rasciidoc::render(basename(file_name))
})
//end.rcode
you will create an HTML file that is identical to [this file](https://fvafrcu.gitlab.io/rasciidoc/inst/files/minimal/plot.html) 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).

=== A Simple Example
Suppose you changed your file to be less minimalistic:
//begin.rcode
file_name <- system.file("files", "simple", "knit.Rasciidoc",
                         package = "rasciidoc")
cat(readLines(file_name), sep = "\n")
//end.rcode


This file obviously reads code from files in a subdirectory called "src/", 
so if you had that subdirectory and its files, too:

//begin.rcode
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)
})
dir(my_directory, recursive = TRUE, full.names = TRUE)
//end.rcode

you could +render+ the file 
//begin.rcode
rasciidoc::render(file.path(my_directory, basename(file_name)))
//end.rcode
and create an HTML file that is identical to [this file](https://fvafrcu.gitlab.io/rasciidoc/inst/files/simple/knit.html) and that you could browse using 
+browseURL(file.path(my_directory, paste0(sub("\\..*$", "", basename(file_name)), ".html")))+
from your current R session .

== Spinnig
You can also use a spinnig file for input:
//begin.rcode
file_name <- system.file("files", "simple", "spin.R_nolint",
                         package = "rasciidoc")
cat(readLines(file_name), sep = "\n")
//end.rcode
You run +render+ on it:
//begin.rcode
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))
})
//end.rcode

== Vignettes Using `rasciidoc`
This vignette is built by `rasciidoc`'s vignette engine 
(see https://gitlab.com/fvafrcu/rasciidoc/-/blob/master/vignettes/An_Introduction_to_rasciidoc.Rasciidoc for its input file).

Just add a 
----
////
    %\VignetteIndexEntry{Your Vignette Entry}
    %\VignetteEngine{rasciidoc::rasciidoc}
////
----
block to your `rasciidoc` input file and add `rasciidoc` to 
the _VignetteBuilder_ and _Suggests_ fields of 
your package's _DESCRIPTION_ file.