-
Notifications
You must be signed in to change notification settings - Fork 27
/
README.Rmd
169 lines (112 loc) · 6.2 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
[](https://github.com/davidgohel/officedown/actions)
[](https://CRAN.R-project.org/package=officedown)
> `{officedown}` is bringing some [officer](https://cran.r-project.org/package=officer) features into R markdown documents.
## Overview
### Word
The package facilitates the formatting of Microsoft Word documents produced by R
Markdown documents by providing a range of features:
<a href="https://github.com/davidgohel/officedown"><img src="man/figures/logo.png" alt="officedown logo" align="right" /></a>
* Compatibility with the functions of the package `officer` for the
production of "runs" and "blocks" of content (text formatting, landscape mode,
tables of contents, etc.).
You can add a column break in a two-column section, you can easily color a chunk
of text, you can add tables of contents at any place in the document and also
add a list of figures or list of tables.
* Ability to use the table styles and list styles defined in the "reference_docx"
which serves as a template for the pandoc document.
With rmarkdown, you can reuse all paragraph styles. With `{officedown}`, you can
also reuse table and list styles. These features are based on the use of Word
templates (`reference_docx`). It is recommended to learn how "Word styles" work
for paragraphs, tables and lists if you never really used Word styles.
> These styles are to be defined in a Word document that serves as a template.
> You must first create a Word document (or edit an existing Word document),
> adjust the styles and save it. This document which serves as a vehicle for the
> defined styles will be used by R Markdown, the argument `reference_docx` must
> be filled in with the file path.
* The replacement of captions (tables, figures and standard identifiers) by
captions containing a Word bookmark that can be used for cross-referencing.
Also the replacement of cross-references by cross-references using fields calculated
by Word. The syntax conforms to the bookdown cross-reference definition.
The package transforms some specific knitr codes into references
calculated by Word, it applies to:
* cross-references with bookdown syntax
* table and image captions
* title identifiers
> It is then easy to copy and paste the content into another document
without losing the reference numbers. Captions are also auto-numbered by Word.
* Full support for flextable output, including with outputs containing
images and links.
The package enable knitting flextable outputs with images or plots in
cells without using `{officer}`. Insertion of images in `{flextable}`
is not supported with `rmarkdown::word_document` but is possible by
using `officedown::rdocx_document`.
### PowerPoint
The package also enhances PowerPoint productions with R Markdown by providing a
mechanism for placing results according to the slide template contained in the
PowerPoint document used as "reference_doc". It becomes easy to add several
contents in the same slide.
The package also offers the possibility to transform your graphic instructions
into editable vector graphics (with the rvg package) by simply wrapping your
call into a call to function `dml`.
## Resources
The help pages are in a bookdown located at:
https://ardata-fr.github.io/officeverse/
Manuals are available at:
https://davidgohel.github.io/officedown/.
## Questions and Issues
Github issues are closed, instead use https://github.com/davidgohel/officedown/discussions
PLEASE, read the help pages before asking questions or declaring
issues. If you do post:
- Provide the code that is producing the error, it has to be a minimal reproducible example.
Stackoverflow is providing good explanations about it: https://stackoverflow.com/help/mcve. You can use package `reprex` to help you: https://reprex.tidyverse.org/. The most popular R stackoverflow question is about the subject: https://stackoverflow.com/questions/5963269/how-to-make-a-great-r-reproducible-example.
- Provide the results of R command `sessionInfo()`. It had to be executed after you loaded the packages used by your example. This will let me know what is your version of R and what are the versions of the packages you used in your example.
- Do not cross post
## Installation
You can install `{officedown}` from github with:
```{r eval = FALSE}
remotes::install_github("davidgohel/officedown")
```
Supported formats require some minimum [pandoc](https://pandoc.org/installing.html) versions:
| R Markdown output | pandoc version |
|---------------------:|:--------------:|
| Microsoft Word | >= 2.0 |
| Microsoft PowerPoint | >= 2.4 |
## Getting started
### rdocx_document
use RStudio Menu to create a document from `{officedown}` template.
It creates an R markdown document, parameter `output` is set to
`officedown::rdocx_document`. Note that package `{officedown}` need
to be loaded in the Rmd.
## Word Features illustration
A bookdown is available in the package and can be used as a demo.
```{r}
dir <- system.file(package = "officedown", "examples", "bookdown")
file.copy(dir, getwd(), recursive = TRUE, overwrite = TRUE)
# rmarkdown::render_site("bookdown")
fs::dir_tree("bookdown", recurse = TRUE)
```
```{r include=FALSE}
# remotes::install_github("ardata-fr/doconv")
rmarkdown::render_site("bookdown")
z <- doconv::to_miniature("bookdown/_book/bookdown.docx", use_docx2pdf = TRUE,
row = c(1, 1, 2, 2, 3, 0, 4, 0, 5, 5, 6), width = 850,
fileout = "man/figures/README-bookdown.png")
unlink("bookdown", recursive = TRUE, force = TRUE)
```
You should see the following document:
