README.md

In agoldst/scuro: An R Markdown Beamer-Presentation Setup

From R Markdown to PDF Slides, Fussily

This package provides an rmarkdown format and a template for creating presentation slides from R Markdown source, converting to PDF using Beamer to create slides, speaker notes (or a talk script), and audience handouts from a single source file. The color scheme is light-on-dark, using a system font (and not the trademark ugly sans-serif Beamer default) in both slide text and in figures generated by R. A supplied ggplot2 theme makes plots from ggplot as well as from base graphics likewise light-on-dark. Otherwise, it is very similar to the default pandoc Beamer formats.

To install, use

devtools::install_github("agoldst/scuro")

This package uses the pandoc templates and supporting files used in my Easy Lecture Slides Made Difficult, which supports generating slides, notes, and handouts from ordinary markdown. See that page for more detail on how to use ordinary markdown for this. (elsmd does not need to be separately installed; it is included in scuro.) This package then adds on support for generating some material (plots, tables...) using R code.

Using the package

To use the package, start from the supplied lectures template. Choose RStudio's "New File > R Markdown..." command, and select "Dark-on-Light Beamer Slides." Or, in R, do

rmarkdown::draft(file="course", template="lectures",
    package="scuro", edit=F)

which creates a new directory called course under the working directory. course contains two folders, notes and scripts, and a Makefile. R markdown files go in either of the two subfolders: if they are in notes, they are taken to be talks to be given from notes, and if they are in scripts, they are taken to be written-out lectures. Running make generates three PDF files for each R markdown, which appear in three newly created directories: slides for slides, handouts for slide handouts, and lectures for speaker notes or scripts.

Two example files are provided, notes/notes-sample.Rmd and scripts/script-sample.Rmd, which show how to compose talks in the two styles.

For displaying the slides, I recommend Présentation, a free program with an excellent presentation mode for PDFs.

The course directory also contains a course.Rmd file, which is just a stub required by the rmarkdown template structure. You can delete it.

Because xelatex and tikz graphics are slow individually and very slow in combination, you may wish to use the pdf graphics device while you are drafting and only switch to TikZ when you are nearly finished. (You could also use the pdflatex engine, if you are not inputting complex Unicode text, and then switch to xelatex when you are ready to work on the typesetting in your chosen typefaces.)

The format

The R package provides an rmarkdown format scuro::scuro_md. Using rmarkdown::render to this format (or RStudio's "Knit" button) generates a markdown file suitable for subsequent conversion into beamer slides, handouts, beamerarticle scripts, and 4-up speaker notes. The output is somewhat configurable; in particular, the YAML metadata can adjust fonts (by default the sansfont is used for the slides), code-highlighting schemes, and default figure dimensions. See the example Rmd files as well as the R help file for scuro_md.

One weakness of the dark-on-light scheme is that it doesn't look great on paper (and wastes ink); I am working on a solution.

You do not need to load the scuro library in your Rmd file.

Overlay specifications (incremental builds)

Beamer supports what it calls "overlay specifications," that is, ways of generating multiple copies of a slide with varying pieces of the content visible.

In past versions of this package, I specified beamer overlays with {<...>} to get round an issue with pandoc's processing of beamer's <...> notation. More recent (>= 2.7) pandoc versions manage these overlays without trouble, so such a filter is no longer necessary. However, newer pandoc versions also forced me to change the way I marked up written-out lectures (see, again, the Easy Lecture Slides M.D. documentation), so the markdown-processing stage uses a lua filter to remove native Divs with the noslide class.

Grid positioning

The minimalism of markdown and the text-oriented nature of LaTeX combine to make any tweaking of the layout of slides quite tricky. This is supposed to be a feature: this whole generating-from-plain-text thing is supposed to enable you to avoid laying things out! Nonetheless, sometimes a slide really does need a more complex layout than the basically left-to-right, top-to-bottom text-like sequencing of markdown. This package lets you use the textpos LaTeX package's grid-positioning features in your markdown. It sets up a 9 x 8 grid (and LaTeX length units \TPHorizModule and \TPVertModule), and you can use the LaTeX textblock environment in your markdown as normal:

\begin{textblock}{2}(4,3)
A two-unit-wide block with upper left corner at grid position 4, 3
\end{textblock}

knitr's chunk options for figures are also modified to interact with this. If a chunk has a textblock_width option, its output will be placed in a textblock environment of the specified width in grid units at a position given by the textblock_pos option (a two-element vector of grid coordinates); the out.width and out.height options are reinterpreted as grid units. If you wish to use the grid units but not the textblock environment, instead use the inside_textblock=T chunk option. For more details, see the package help in R on plot_hook_textpos.

Other tweaks

A few further knitr chunk options have different defaults from the built-in formats: tidy is off, and, in figures, size is footnotesize and dev.args is list(pointsize=9) (this small test will scale up fine when you project the beamer PDF). The package also sets up a custom option, dark_theme, which applies the dark_plot_theme contained in the package (see its help topic in R) to all ggplots. This is on by default, but if you wish to fall back to the ggplot default, set dark_theme=F (and/or simply add your own theme() to plots). To remove the dark-on-light theming of the slides themselves, put scuro: false in your YAML metadata.

The package defaults to TikZ graphics and the xelatex engine. This is slower than pdf graphics and pdflatex but visually worth it. If you are using TikZ but want to alter the tikzDevice options, note that the package installs a chunk hook to the tikz_xelatex option and sets all chunks to default to tikz_xelatex=T. Turn this off to change things (or look at the code for tikz_setup_hook).

Otherwise, the underlying pandoc template is close to the default beamer template, with a few tweaks and a few choices I've made for you. Some of the annoying beamer gewgaws are suppressed as well.

"Scuro"?

Because the slides are mostly dark, and little about knitr-xelatex-tikz wrangling is chiaro.

..."chiaro"?

The opposite of scuro. Also available here is a second R markdown format and template for articles-on-paper rather than presentations. This chiaro_pdf format (and the article template of this package) also support the xelatex-tikz combination. The only thing that is chiaro is the type on the page. See ?chiaro_pdf and the demonstration file in the template generated from:

rmarkdown::draft("essay", "article", "scuro", edit=F)

Unlike the triple-PDF setup for slides, this format is perfectly compatible with the "Knit" button in RStudio.

agoldst/scuro documentation built on Nov. 5, 2021, 3:44 a.m.