redoc

# redoc
## Reversible R Markdown/MS Word documents
### Alan Yeung | Analyst | BBV/STI
### 26 March 2019

---

# Introduction: The Problem Scenario

- You are working on a collaborative project within a multidisciplinary team.

- You have produced analyses in `R` and written up a document using `RMarkdown`.

- You choose to output to MS Word and share the document.

- A collaborator tells you your work is rubbish and returns the document full of tracked changes and comments.

- You need to make revisions but tracked changes and comments cannot be pulled into `RMarkdown`.

---

![redoc Tweet](images/redoc_tweet.png)

---
class: inverse, middle, center

# Example: nps_report_20161216.docx

---

# redoc

- [`redoc`](https://noamross.github.io/redoc) is an experimental package created by Noam Ross to enable a two-way `RMarkdown` ⟷ Microsoft Word workflow.

- **Package is in the very early stages and still buggy. It needs a lot of work** (if interested, you can [contribute](https://github.com/noamross/redoc/blob/master/.github/CONTRIBUTING.md)).

- Uses [lua filters](https://pandoc.org/lua-filters.html) so **needs Pandoc v2 (comes with RStudio 1.2)**

Install with

```r
source("https://install-github.me/noamross/redoc")
```

- Provides new output format: `rdocx_reversible()`.

```yaml
---
output:
  redoc::rdocx_reversible:
    keep_md: TRUE
    highlight_outputs: TRUE
---
```

- Word files created with `redoc` can be reverted back to `.Rmd`, even if they have been edited.

- Tracked changes and comments added using [Critic Markup](http://criticmarkup.com/spec.php#thebasicsyntax).

- **VERY COOL** but quite complex behind the scenes.

---
# Critic Markup: The 5 Types

`{++ ++}`

`{++added in words appear here++}`

**Deletion**

`{-- --}`

`{--deleted words appear here--}`

**Substitution**

`{~~ ~> ~~}`

`{~~sabstatute~>substitute~~}`
]

`{>> <<}`

`{>>This is terrible!<<}`

**Highlight (for comments)**

`{== ==}``{>> <<}`

`{==You said==}``{>>Like<<}`
]

---
class: inverse, middle

1. Create `rdocx_reversible()` file1 using basic `RMarkdown` template.
2. Insert tracked changes and comments to Word `redoc` file.
3. Use `undoc()` to retrieve `.Rmd` file in different ways.

.footnote[
[1] **Buggy**: For some reason, the `.Rmd` needs at least one addition **{++ ++}**, one subtraction **{-- --}** and one comment **{>> <<}** to knit properly.
]

---
# Some Concluding Thoughts

- `redoc` is probably too buggy to use in it's current state.

- Lacks some features, e.g. tools to bring in all changes as critic markup and then review within `RStudio`.

- If you do want to use it, couple of strategies that may work reasonably well:

- Use tracked changes that are very likely to be **all** accepted (or rejected I suppose!). **OR**

- Bring in all changes to the `.Rmd` and use the search function within RStudio to find different types of changes.

---

# **Thanks, Any Questions?**

# Alan Yeung (alan.yeung **at** nhs **dot** net)