In tjmahr/solarizeddocx: A 'Solarized' Theme for 'RMarkdown` `Docx` Documents

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

Overview

This package was created because I think the solarized color palette looks nice in Word documents created by pandoc, but solarized is not one of the supported highlighting styles.

This document is the result of calling rmarkdown::word_document() but customizing the output by passing along three files to pandoc.

First, the reference docx file defines the styles for the Word document. The main changes from the default style are that:

1. the "normal" text style now includes 10-pt of space before paragraphs. The "source code" blocks outputted by pandoc inherit from this style---I think this is how it works---so that space prevents code blocks from touching preceding text.
2. the blue in headings and links uses solarized's blue color
3. the verbatim text uses solarized's light body text color
4. titles and other front matter are now left aligned
5. the block text style is 1-pt smaller than the body text

basename(solarizeddocx::file_reference_docx())

Second, the solarized light highlighting theme file defines which colors to assign token types during syntax highlighting.

basename(solarizeddocx::file_solarized_light_theme())

I borrowed the color assignments mostly from the rsthemes package. These are:

```{scss, eval = FALSE} // R language colors $code_comment : $base1; $code_string : $cyan; $code_function : $blue; $code_reserved : $green; $code_operator : $yellow; $code_bracket : $yellow; $code_value : $magenta; $code_namespace: $red; $code_variable : $violet; $code_message : $orange; $code_namespace_font_style: italic;

$code_other: $code_variable;

Third, I customized the **R syntax language definition file** so make results
somewhat better for Word documents. The most important change is that regular
comments are light and italic and prompt-comments used for output are darker and
more upright. This change makes it easier to read output from dataframes.

```r
# this comment is italic. the output below is roman
basename(solarizeddocx::file_solarized_light_theme())

model <- lm(mpg ~ cyl, mtcars)
summary(model)

coef(summary(model))

```{=openxml}

## Code examples

Some basic examples:

```r
f <- function(x, ...) {
  mean(x, ...)
}

f(c(1, 2, 3, 4, NA), na.rm = TRUE)

print("Hello!")

Here is how wide we can make our code examples, comfortably, in Word.

# 75 characters fit okay
0123456789012345678901234567890123456789012345678901234567890123456789012345

Here are the changes I made to the default R language definition:

# italic code comments
print("but roman output comments")

# integers ending in L are now highlighted
c(1.0, 1, 1L)

# italicized package names in namespace calls
f <- stats::rnorm
f <- stats:::rnorm

# native pipe highlighted
x <- rnorm(10) |> round(1)

One feature we find in pandoc highlighting but do not find in RStudio is the highlighting of escape sequences like \n.

# escape sequences are highlighted inside of strings
x <- "this string has an \"escaped\" characters"
y <- "we escape things by using a \\. \nso that \\n is a newline"
cat(x)
cat(y)

Based on my tests, two things that are currently not correct with the default language definition and my modified language definition are the native pipe, lambda syntax, and imaginary numbers.

# lambda
round2 <- \(x) round(x, 2)
1 |> rnorm(1) |> round(2)

# immediately invoked lambda in a pipe
10.111 |> (\(x) round(x, 0))()

# imaginary number
-2 + 4i

The Gauntlet

Below is the syntax gauntlet where we try a bunch of things.

library(magrittr)

x
x2
x_2

# I don't think T and F should highlight because they are 
# overwritable
x <- TRUE | T
y <- FALSE || F

1L + 1L %% 2 == 0
1.0 * 1.0 / 1.0
+10 ^ 2 ** 2
-2 - 4i
.111
pi

package::my_function
package:::my_secret_function

NA
NA_character_
NA_complex_
NA_integer_
NA_real_
NaN
Inf
-Inf
NULL

for (x in 1:10) {
  !! no
  f <- function(...) {
    x <- c(..., ..1, ..2, ...elt(1))
    return(data)
  }
  f <- \(x) {
    c(x)
  }
  repeat
  break
  next
  while (FALSE) {
    print("never ever run"); print("not ever")
  }
}

# indexing
a <- list(x = 10, y = 100)
var <- "x"
a$x
a[1]
a["x"]
a[var]
a[[1]]
a[["x"]]
a[[var]]

# strings
'string'
"string"
"newline\n and escaped slash \\"

# names
`x y` <- "test"
`%in%`("a", letters)

# pipes
x %>% 
  rnorm(10, .) %>% 
  round(2)

x |> 
  round(2)

10.11 |> 
  (\(x) round(x))()

# I noticed message vs warning/stop having different RStudio colors
message("test")
warning("test")
stop("test")

if (TRUE) {
  print("hello")
} else {
  y ~ x + (1 | z:w)
}

Expanded string gauntlet from ?Quotes

# \n    newline
# \r    carriage return
# \t    tab
# \b    backspace
# \a    alert (bell)
# \f    form feed
# \v    vertical tab
# \\    backslash \
# \'    ASCII apostrophe '
# \"    ASCII quotation mark "
# \`    ASCII grave accent (backtick) `
# \nnn  character with given octal code (1, 2 or 3 digits)
# \xnn  character with given hex code (1 or 2 hex digits)
# \unnnn    Unicode character with given code (1--4 hex digits)
# or \u{nnnn} 
# \Unnnnnnnn    Unicode character with given code (1--8 hex digits)
# or \U{nnnnnnnn}

(hw2 <- "\110\x65\154\x6c\157\x20\127\x6f\162\x6c\144\x21")
(hw3 <- "\u48\u65\u6c\u6c\u6f\u20\u57\u6f\u72\u6c\u64\u21")
("\u0126\u0119\u1114\u022d\u2001\u03e2\u0954\u0f3f\u13d3\u147b\u203c")
("\U0126\U0119\U1114\U022d\U2001\U03e2\U0954\U0f3f\U13d3\U147b\U203c")

# 'Raw character constants are also available using a syntax similar to
# the one used in C++: r"(...)" with ... any character sequence, except
# that it must not contain the closing sequence )". The delimiter pairs
# [] and {} can also be used, and R can be used in place of r. For
# additional flexibility, a number of dashes can be placed between the
# opening quote and the opening delimiter, as long as the same number of
# dashes appear between the closing delimiter and the closing quote.'

r"(c:\Program files\R)"
r"{(\1\2)}"
r"(use both "double" and 'single' quotes)"
r"---(\1--)-)---"

Markup styles

We also would like to test markup styles here.

---

H1

H2

H3

H4

H5

H6

• list 1
• list 2
• list 1
• list 3

Paragraph.

1. list 1
2. list 2
3. list 1
4. list 1

blockquote

A paragraph followed by code. Strong. Emphasis. Code.

print("hello")

Code that emits a table:

knitr::kable(
  data.frame(
    day = c(1, 2, 3, 4),
    result = c("yes", "no", "yes", "yes")
  ), 
  caption = "Check it out"
)

tjmahr/solarizeddocx documentation built on May 4, 2022, 3:35 p.m.