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
## = 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 a_plot, dev = "png", fig.cap = "A Plot"
## plot(1:10)
## //end.rcodeIf you run render on this file (we use a temporary directory here)
## 1/4
## 2/4 [unnamed-chunk-10]
## 3/4
## 4/4 [a_plot]## [1] TRUE
## attr(,"info")
## attr(,"info")$python
## [1] "/usr/bin/python3"
##
## attr(,"info")$input
## [1] "/tmp/RtmptFZUeH/plot.asciidoc"
##
## attr(,"info")$output
## [1] "/tmp/RtmptFZUeH/plot.Rasciidoc" "/tmp/RtmptFZUeH/plot.html"
##
## attr(,"info")$asciidoc
## [1] ""
##
## attr(,"info")$`source-highlight`
## [1] FALSE
##
## attr(,"info")$`git-asciidoc`
## attr(,"info")$`git-asciidoc`$python_cmd
## [1] "/usr/bin/python3"
##
## attr(,"info")$`git-asciidoc`$python_version
## [1] "3.12.3"
##
## attr(,"info")$`git-asciidoc`$asciidoc_source
## [1] "/tmp/RtmptFZUeH/asciidoc/asciidoc.py"
##
## attr(,"info")$`git-asciidoc`$url
## [1] "https://github.com/asciidoc-py/asciidoc-py"
##
## attr(,"info")$`git-asciidoc`$tag
## [1] "9.1.0"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:
## = 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, label = "sum", code = readLines("src/sum.R")
## //end.rcode
##
##
## == A new section
##
## //begin.rcode, label = "my_sum", code = readLines("src/my_sum.R")
## //end.rcode
## === A subsection
## //begin.rcode, label = "value"
## print(value)
## //end.rcode
##
## //begin.rcode, label = "run my_sum"
## print(my_sum(1:3))
## //end.rcode
##
## Some inline code: Object +value+ has value +r value+.
##
##
## === Second subsectionThis file obviously reads code from files in a subdirectory called "src/", so if you had that subdirectory and its files, too:
## [1] TRUE## [1] "/tmp/RtmptFZUeH/simple/knit.Rasciidoc"
## [2] "/tmp/RtmptFZUeH/simple/src/my_sum.R"
## [3] "/tmp/RtmptFZUeH/simple/src/sum.R"you could render the file
## 1/9
## 2/9 [sum]
## 3/9
## 4/9 [my_sum]
## 5/9
## 6/9 [value]
## 7/9
## 8/9 [run my_sum]
## 9/9## [1] TRUE
## attr(,"info")
## attr(,"info")$python
## [1] "/usr/bin/python3"
##
## attr(,"info")$input
## [1] "/tmp/RtmptFZUeH/knit.asciidoc"
##
## attr(,"info")$output
## [1] "/tmp/RtmptFZUeH/knit.html"
##
## attr(,"info")$asciidoc
## [1] ""
##
## attr(,"info")$`source-highlight`
## [1] FALSE
##
## attr(,"info")$`git-asciidoc`
## attr(,"info")$`git-asciidoc`$python_cmd
## [1] "/usr/bin/python3"
##
## attr(,"info")$`git-asciidoc`$python_version
## [1] "3.12.3"
##
## attr(,"info")$`git-asciidoc`$asciidoc_source
## [1] "/tmp/RtmptFZUeH/asciidoc/asciidoc.py"
##
## attr(,"info")$`git-asciidoc`$url
## [1] "https://github.com/asciidoc-py/asciidoc-py"
##
## attr(,"info")$`git-asciidoc`$tag
## [1] "9.1.0"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:
## #' = 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:
## 1/1## [1] TRUE
## attr(,"info")
## attr(,"info")$python
## [1] "/usr/bin/python3"
##
## attr(,"info")$input
## [1] "/tmp/RtmptFZUeH/spin.asciidoc_nolint"
##
## attr(,"info")$output
## [1] "/tmp/RtmptFZUeH/spin.R_nolint" "/tmp/RtmptFZUeH/spin.html"
##
## attr(,"info")$asciidoc
## [1] ""
##
## attr(,"info")$`source-highlight`
## [1] FALSE
##
## attr(,"info")$`git-asciidoc`
## attr(,"info")$`git-asciidoc`$python_cmd
## [1] "/usr/bin/python3"
##
## attr(,"info")$`git-asciidoc`$python_version
## [1] "3.12.3"
##
## attr(,"info")$`git-asciidoc`$asciidoc_source
## [1] "/tmp/RtmptFZUeH/asciidoc/asciidoc.py"
##
## attr(,"info")$`git-asciidoc`$url
## [1] "https://github.com/asciidoc-py/asciidoc-py"
##
## attr(,"info")$`git-asciidoc`$tag
## [1] "9.1.0"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.