Package 'redoc'

Reversible Reproducible Documents

Description

Implements a reversible 'R Markdown' to 'Microsoft Word' pipeline.

Support

The development repository for the redoc package is found at https://github.com/noamross/redoc. Please file bug reports or other feedback at https://github.com/noamross/redoc/issues

Author(s)

Noam Ross [email protected]

---

Convert an Reversible Document back to R Markdown

Description

Converts a document originally created with redoc() back to R Markdown, including changes made to text in MS Word.

Usage

dedoc(
  docx,
  to = NULL,
  dir = ".",
  track_changes = "comments_only",
  block_missing = "comment",
  inline_missing = "omit",
  wrap = getOption("redoc.wrap", 80),
  overwrite = FALSE,
  orig_docx = NULL,
  orig_codefile = NULL,
  verbose = FALSE
)

Arguments

docx	The '.docx“ file to convert
to	the filename to write the resulting .Rmd file. The default is to use the same basename as the docx document
dir	The directory to write the '.Rmd“ to. Defaults to current working directory
track_changes	How to deal with tracked changes and comments in the .docx file. "accept" accepts all changes, and "reject" rejects all of them. The default, "criticmarkup", converts the tracked changes to Critic Markup syntax. "comments_only" will only convert comments, as other changes can be viewed with redoc_diff(). "all" marks up tracked changes and comments in ⁠<span>⁠ tags and is useful for debugging. See the pandoc manual for details.
block_missing, inline_missing	What to do about code blocks or inline code whose output has been removed in the editing of the Word document. "restore" attempts to restore the code as close to its original location in the document as possible. "comment" will do so but wrap it in HTML comments. "omit" will not restore the code at all.
wrap	The width at which to wrap text. If NA, text is not wrapped. Set the default with "redoc.wrap" in options().
overwrite	Whether to overwrite an existing file
orig_codefile, orig_docx	The original .codelist.yml or Word document created when the document was first knit. Useful for debugging, or in cases where the word file has been corrupted or transformed, for instance, by copy-and-pasting the content into a new file. If provided, dedoc will use this codefile or word file to re-create the .Rmd file with the text of the input.
verbose	whether to print pandoc progress text

Details

R chunks may be lost in the editing process if using non-Microsoft word processors (e.g. LibreOffice or in copy-and-pasting text into a new document.

---

Is this a reversible document?

Description

A function for testing is the file can be de-rendered. If not, un-knitting may be attempted with the orig_chunkfile or orig_docx files in dedoc().

Usage

is_redoc(docx)

Arguments

docx	A path to a .docx file or an rdocx object produced by officer::read_docx()

Value

a logical value

Examples

is_redoc(redoc_example_docx())

---

Generate a function to run prior to knitting

Description

redoc modifies R Markdown documents prior to knitting to capture and store document elements that will need to be restored later. It does this via a function passed to the pre_knit argument of rmarkdown::output_format(). make_preknitter generates this function from a list of wrapper functions.

Usage

make_preknitter(wrappers = list())

Arguments

wrappers

a list of wrapper functions.

Details

rmarkdown does not provide a mechanism to modify the file prior to knitting, so redoc accomplishes this by reaching up the call stack and modifying the environment in the rmarkdown::render() function. The function generated by make_preknitter will do this by generating the pre-processed R Markdown file and associated list of code chunks, adding these the list of intermediates for cleanup, and switching the document input to this pre-processed document.

Value

A function to be used in 'output_format(pre_knit = ...)“

Examples

make_preknitter(wrappers = list(htmlcommentwrap, latexwrap))

---

Make a wrapper function

Description

Wrapper functions are passed to the ⁠wrapper=⁠ argument of redoc() to specify what text in R Markdown files should be captured and restored when de-rendering (in addition to code chunks, inline code, and YAML blocks). make_wrapper() simplifies creation of these wrapper functions and returns a function that can be passed to redoc().

Wrappers included in the package, all of which are used by default, are:

Type of markup	Function	Label	Type
HTML Comments	htmlcommentwrap()	"htmlcomment"	inline
Single-line LaTeX	latexwrap()	"latex"	block
Pandoc citations	citationwrap()	"citation"	inline
Raw Blocks	rawblockwrap()	"rawblock"	block
Raw Spans	rawspanwrap()	"rawspan"	inline

Usage

make_wrapper(label, regex, type = c("block", "inline"))

Arguments

label	the label to use for chunks of this type, e.g., "citation", "table". These should be unique for each type of wrapper used. redoc() will throw an error otherwise.
regex	A regular expression that identifies the text to be wrapped and restored, including all delimiters. It will search in a single string with line breaks. ICU regular expressions are used. The (?s) flag is recommended for multi-line expressions.
type	whether the text should be treated as inline or block text. Inlines are wrapped in span elements and blocks are wrapped in divs. These are treated differently in several ways, especially when restoring text in dedoc().

Details

Some captured text can not be selected by regular expressions, in which case custom functions can be provided to parse out the relevant text. See the vignette "Developing with redoc" for more detail.

Value

A function of class redoc_wrapper

Examples

rmarkdown::render(
    redoc_example_rmd(),
    output_format = redoc(
                      wrappers = list(
                        htmlcommentwrap,
                        latexwrap)))

# This is how each of these functions are defined in the redoc package
htmlcommentwrap <- make_wrapper(
    label = "htmlcomment",
    regex = "(?s)<!--.*?-->",
    type = "inline")

latexwrap <- make_wrapper(
    label = "latex",
    regex = "(?<=[\n\r])\\\\\\w+.*?(?=[\n\r])",
    type = "block")

rawblockwrap <- make_wrapper(
    label = "rawblock",
    regex = "(?s)```\\{=\\w+\\}.*?```\\h*",
    type = "block")

rawspanwrap <- make_wrapper(
    label = "rawspan",
    regex = "(?s)`[^`]`\\{=\\w+?\\}",
    type = "inline")

citationwrap <- make_wrapper(
    label = "citation",
    regex = "(?:@\\w+|\\[.*?-?@\\w+.*?\\](?!\\[\\(\\{))",
    type = "inline")

---

Convert a document to Pandoc's abstract syntax tree format

Description

This is a convenience function for testing and development.

Usage

pandoc_ast(file, from = NULL, tolist = TRUE)

Arguments

file	the file to convert using pandoc.
from	the format to convert from. If NULL (default) File type will be auto-detected by extension. .Rmd files will be treated as .md.
tolist	whether to return the AST as an R list. If FALSE, will return length-1 character vector of raw JSON.

Value

A list containing the structured document

Examples

ast <- pandoc_ast(redoc_example_docx())

---

R Markdown format for Reversible Reproducible Word Documents

Description

Format for converting from R Markdown to a Microsoft Word Document that can be reversed using dedoc() after editing in Word.

Usage

redoc(
  highlight_outputs = FALSE,
  wrap = getOption("redoc.wrap", 80),
  margins = NULL,
  line_numbers = NULL,
  comment_author = NULL,
  keep_md = FALSE,
  wrappers = list(htmlcommentwrap, latexwrap, rawblockwrap, rawspanwrap, cmwrap,
    citationwrap),
  diagnostics = TRUE,
  ...
)

Arguments

highlight_outputs	whether to highlight outputs from chunks and inline code in the final document
wrap	when round-tripping the document, at what width to wrap the markdown output? Set the default with "redoc.wrap" in options(). See dedoc().
margins	page margin size. Can be a single value or a named vector with values, top, bottom, left, right, gutter, header, and footer. If NULL defaults to the reference document.
line_numbers	either TRUE or list with any of the arguments start, by, restart, and distance
comment_author	The name to attribute any CriticMarkup tracked changes to. Defaults to whoami::fullname().
keep_md	whether to keep the intermediate markdown document
wrappers	a list of wrapper functions to capture text to protect when rendering and de-rendering. See make_wrapper().
diagnostics	Whether to embed diagnostic information in the output file. If TRUE, this will save session information and the current pandoc and (if used) RStudio versions inside the Word document for later bug-checking.
...	other parameters passed to rmarkdown::word_document()

---

Compare changes in an edited redoc Word Document against the original

Description

redoc_diff() produces a diff object comparing the current contents of a Word document originally generated by redoc() to the original R markdown file used to create it.

Usage

redoc_diff(
  docx,
  target = "original",
  current = "current",
  track_changes = "comments_only",
  block_missing = "comment",
  inline_missing = "omit",
  wrap = getOption("redoc.wrap", 80),
  mode = "sidebyside",
  context = "auto",
  tar.banner = NULL,
  cur.banner = NULL,
  ...
)

Arguments

docx	Path to an MS Word .docx file originally generated with redoc() and since edited.
target, current	Which versions of the document to compare. One of "original", "roundtrip", or "current".
track_changes, block_missing, inline_missing	Arguments passed to dedoc() to determine how to handle edits in the Word document.
wrap	Width to wrap text lines when converting from docx to markdown. If NULL, no wrapping. Set the default with "redoc.wrap" in options().
mode, context, tar.banner, cur.banner, ...	Arguments passed to diffobj::diffFile() to customize printing of the diff.

Details

When an .docx file is created with redoc(), it internally stores the original R Markdown file as well as a version that is round-tripped to .docx and back. redoc_diff() de-renders the current .docx to R Markdown (with dedoc()) and compares against these versions.

Value

A Diff object, which will be displayed in the RStudio Viewer, a browser, or the console, depending on the context.

---

Files for examples and testing

Description

Files for examples and testing

Usage

redoc_example_rmd()

redoc_example_docx()

redoc_example_edited_docx()

Examples

redoc_example_rmd()
redoc_example_docx()
redoc_example_edited_docx()

---

Extract the Rmd used to to produce a Reversible Word Doc

Description

Documents produced with redoc() store an copy of the original .Rmd files used to produce them. This is useful for diffing against the version created with dedoc(), especially if tracked changes have not been used.

Usage

redoc_extract_rmd(
  docx,
  type = c("original", "roundtrip"),
  dir = ".",
  to = NULL,
  overwrite = FALSE
)

Arguments

docx	A path to a word file or a an rdocx object created with officer::read_docx().
type	One of "original" or "roundtrip". "original" extracts the exact document originally knit. "roundtrip" (default) extracts a document that has been converted to Word and back with no edits in between. The latter should be more useful for comparing against edits, as line-wrapping and placement of no-output chunks should match.
dir	The directory to write the '.Rmd“ to. Defaults to current working directory
to	the filename to write the resulting .Rmd file. The default is to use the the original name with either .orignal.Rmd or roundtrip.Rmd extensions.
overwrite	whether to overwrite existing files

Value

The path to the extracted .Rmd

Examples

redoc_extract_rmd(redoc_example_docx(), dir = tempdir())

---

RStudio Addin Functions

Description

These functions act on the RStudio text editor and can be used via the Addins menu or the R console. rountrip_active_file() ("Render and Update") knits the current file using redoc() replaces the text with text that has been round-tripped to Word and back. This helps eliminate small formatting differences.

The ⁠dedoc_*⁠ functions de-render Word documents (using dedoc()), and place the results in the current or new file. By default, they will also display a diff (generated via redoc_diff()) of edits in the word file compared to its original version a compilation time. If called without an input file, they will prompt for file selection via the RStudio GUI.

Usage

roundtrip_active_file()

dedoc_to_active_file(docx = NULL, showdiff = TRUE)

dedoc_to_new_file(docx = NULL, showdiff = TRUE)

Arguments

docx	The input Word file, originally generated by redoc()
showdiff	Display a diff of the current version of the document against the rendered version?

---