render_roff: Knit an R troff document and typeset it with groff

In knitroff: Dynamic Reports in 'troff' with 'knitr'

Knit an R troff document and typeset it with groff

Description

Knits the document with knit_roff, then runs groff -ms -k -e -t -p: the ms macros, UTF-8 input, and the eqn, tbl and pic preprocessors.

Usage

render_roff(input, output = NULL, format = c("pdf", "ps", "utf8"), highlight = TRUE,
            groff = "groff")

Arguments

input	Path of the document, usually ‘.Rms’.
output	Path of the result. By default input with extension ‘.pdf’, ‘.ps’ or ‘.txt’.
format	"pdf", "ps", or "utf8": the draft for a terminal, as nroff gave, to read with less -R.
highlight	Passed to knit_roff: bold keywords and italic comments in the listings, or plain with FALSE.
groff	The groff program.

Details

Needs GNU groff in full; groff_available says whether this machine has it. On Debian and Ubuntu that is the ⁠groff⁠ package: ⁠groff-base⁠, installed for man pages, has no ms macros. PDF output uses groff's gropdf; figures in it need pdfinfo from poppler, and groff runs with -U because .PDFPIC asks pdfinfo for each picture's size. A terminal cannot set equations, so the "utf8" draft shows their eqn source, which was designed to read the way it is spoken.

On Windows, groff comes from MSYS2: in the Rtools45 bash shell, ⁠pacman -Sy groff⁠. Check with Sys.which("groff"), or pass the path to groff.exe as groff. pdfinfo, for figures in PDF, is not in the part of MSYS2 that Rtools allows; the package README describes other ways to get it.

Value

The path of the result, invisibly.

Examples

if (groff_available("utf8")) {
  doc <- file.path(tempdir(), "states.Rms")
  file.copy(system.file("examples", "states.Rms", package = "knitroff"), doc, overwrite = TRUE)
  draft <- render_roff(doc, format = "utf8")
  cat(head(readLines(draft), 40), sep = "\n")
}

knitroff documentation built on Oct. 16, 2026, 5:09 p.m.