# WordR Package

#### 2022-06-30

WordR package enables creating MS Word files (.docx) from given MS Word template. It can evaluate inline R code, insert tables and plots. WordR package is technically a wrapper around a powerful package officer.

# Motivation

R language has many ways for producing state-of-the-art reports. For example rmarkdown or Sweave packages are very effective in preparing reports in PDF format or R2wd for creating a MS Word report from scratch. However, such techniques has some drawbacks:

• For nontechnical person it is very difficult to prepare the source (template) file.
• It is not conveniently possible to further edit the resulting report (if rendered into e.g. PDF).
• Formatting possibilities with rmarkdown or R2wd are limited and with Sweave complicated (LateX knowledge required).

On the other hand, WordR package, enables

• preparation of the source file in MS Word, with all the bells and whistles it offers (and drawbacks!),
• result is also editable MS Word document,
• such document can be later saved as PDF from MS Word if needed.

To conclude, WordR package is useful, for example, when you need to

• periodically prepare static report and/or
• want non-technical people (who can use MS Word but not R) to be able to prepare majority of the template and/or
• want the resulting report being editable, for example, for adding additional custom interpretation, based on the current results, without need to change the input template.

# How to use the WordR package

All examples, and instructions given in this document applies to MS Word 2013. No major differences are expected to other versions (as of 2017).

## Template preparation

First we need to create a template (.docx) file. Such file may contain any formatting MS Word allows. Apart from that, the template may contain two other things:

• inline R code
• bookmarks for inserting Tables or Plots

Examples can be found in the examples folder of the package.

### Creating inline R code

This functionality enables including simple R expression(s) in the Word document, which is evaluated during file rendering. The result of the expression need to be a string of length one (or something coercible to character(1)). Line breaks cannot be inserted in this way. Because of used workflow, each R inline expression need to be a separate paragraph. However, MS Word offers a way how to do an inline paragraph. Steps for creating an inline expression:

• Open MS Word, create a new file or open an existing one
• locate the cursor on the place where you want to have the R expression
• insert style separator by pressing Ctrl+Alt+Enter (it is preferable to have formatting symbols visible by clicking the “new line” sign button on Home>Paragraph panel in MS Word)
• type r expression, where expression is R expression like 1+1.
• insert style separator again
• if you want the result to be in non-default format, insert cursor into the inline code area and select the desired format from Styles menu. (Do not select the r code as that would change the style for the text not the whole r inline code paragraph)

As a result you should see something like this:

Example can be seen in file examples/templates/template1.docx.

#### Troubleshooting the inline code

• How to insert corect (straight) quotes (' or "): MS Word is, by default (maybe depends on local settings), changing the quotes to ‘Smart quotes’. You can change it the MS Word settings under Proofing > AutoCorrect Options > Autoformat as you type... You can de-select Straight Quotes as Smart Quotes and that should revert the quotes to being straight. Or when typing, right after you type a quote, if Word turns it into a “smart quote,” immediately press Ctrl-Z.
• The expression does not evaluate as expected: Just try to evaluate it in the environment where you are running the renderInlineCode function, and make sure its output is character of length one.
• The output is not in desired style: insert cursor into the inline code paragraph and select the desired style from Styles menu in MS Word.

### Inserting bookmarks for Plots or Tables

Example and more info about bookmarks in MS Word can be seen in file examples/templates/templateFT.docx

To render a table on a given place, just insert a bookmark with name t_XYZ where XYZ will be a name of a flextable (flextable::flextable) table.

To render a plot on a given place, just insert a bookmark with name p_XYZ where XYZ will be a name of plot function.

## Template rendering

Functions for rendering the MS Word file are the main content of the WordR package. Typical rendering R script contains following steps:

• calculation of the outputs - tables, plots and values for inline expressions
• running renderInlineCode on the prepared template file
• running body_add_flextables on the file resulting from previous step
• running addPlots on the file resulting from previous step

Alternatively, from v0.3.3 renderAll function is available, which is a wrapper around those three rendering functions.

Examples can be seen in examples/examples.R.