Should `highlight_outputs` be TRUE or FALSE by default?

[noamross]

The highlight_outputs argument in redoc() colors parts of the output document that are generated by code. The purpose of this is to signal to collaborators what parts of the document aren't super helpful to edit by hand. However, I'm not sure that I like the way that it looks - it looks odd when interacting with code highlighting and doesn't look right with images. Also, it could confuse collaborators - part of redoc's design philosophy is to minimize cognitive overhead for those editing on the Word side.

Should I change the default for highlight_outputs to FALSE? Or is there some other approach?

I note there may be some ways to lock parts of the word document from editing in the future, but only for chunk-type outputs, not inline text. It will be some time before I get to this, though, if ever.

[MattCowgill]

I'd vote for FALSE, personally

[rmflight]

I am also voting for FALSE, partly because I add the date to my YAML programmatically, and right now the highlighting is breaking the YAML parsing in pandoc

[noamross]

I agree, but can you explain how it is breaking it, or provide a reprex?

[rmflight]

Sure, if the code below is in the yaml header

date: "`r Sys.time()`"

This will get css for highlighting added during knitting, and then pandoc will choke on it. I can make a reprex tomorrow if needed.

[rmflight]

test_doc.docx A true reprex would be:

---
title: "My Title"
author: "Robert M Flight"
date: "`r Sys.Date()`"
output: 
  redoc::redoc
---

```{r setup, echo = FALSE}
knitr::opts_chunk$set(echo = FALSE, warning = FALSE, message = FALSE)
```

This is a simple `redoc` document.

When you knit this from a file.Rmd, there will be: [WARNING] Could not parse YAML metadata at line 9 column 1: :4:20: Expected start of line

And this is what the output docx looks like:

SessionInfo:

R version 3.5.1 (2018-07-02) Platform: x86_64-pc-linux-gnu (64-bit) Running under: Ubuntu 18.04.3 LTS

Matrix products: default BLAS: /software/R-351/lib/R/lib/libRblas.so LAPACK: /software/R-351/lib/R/lib/libRlapack.so

locale: [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
[3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
[5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
[7] LC_PAPER=en_US.UTF-8 LC_NAME=C
[9] LC_ADDRESS=C LC_TELEPHONE=C
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C

attached base packages: [1] stats graphics grDevices utils datasets methods base

loaded via a namespace (and not attached): [1] Rcpp_1.0.2 rstudioapi_0.10 knitr_1.24
[4] xml2_1.2.0 magrittr_1.5 uuid_0.1-2
[7] R6_2.4.0 rlang_0.4.0.9000 stringr_1.4.0
[10] httr_1.4.0 tools_3.5.1 xfun_0.8
[13] htmltools_0.3.6 yaml_2.2.0 digest_0.6.20
[16] crayon_1.3.4 zip_2.0.2 whoami_1.3.0
[19] officer_0.3.4 base64enc_0.1-3 evaluate_0.14
[22] mime_0.7 rmarkdown_1.15 stringi_1.4.3
[25] compiler_3.5.1 diffobj_0.2.2.9003 redoc_0.1.0.9000
[28] jsonlite_1.6

[noamross]

Thanks! Can you attach the docx?

I have a fix on a branch to fix the RPLACEHOLDER - That's "hidden text" in Word, but some people have hidden text turned on (in Preferences > View on my version). Something needs to be there to attach the metadata to internally. The new version will still have hidden text but it will just be a zero-width space.

[rmflight]

Attached above.

[noamross]

I've switched highlight_outputs to FALSE by default.