An_Introduction_to_rasciidoc.Rasciidoc 3.35 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
= What the hell is *rasciidoc*? 
Andreas Dominik Cullmann
:toc2:

////
    %\VignetteIndexEntry{An Introduction with rasciidoc}
    %\VignetteEngine{rasciidoc::rasciidoc}
////
Inspired by Karl Broman`s reader on using knitr
with asciidoc
fvafrcu's avatar
fvafrcu committed
11
(https://kbroman.org/knitr_knutshell/pages/asciidoc.html), this is a
12
13
14
15
16
17
wrapper to and a slight modification of knitr.

== Knitting
=== A Minimal Example
Suppose, you have a file that reads
//begin.rcode
fvafrcu's avatar
fvafrcu committed
18
file_name <- system.file("files", "minimal", "plot.Rasciidoc",
19
20
21
22
23
24
25
26
27
28
                         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
fvafrcu's avatar
fvafrcu committed
29
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 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
+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
fvafrcu's avatar
fvafrcu committed
61
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 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
+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.