forked from davidgohel/officer
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
151 lines (97 loc) · 5.8 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
---
title: "officer R package"
output:
github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
message = FALSE,
collapse = TRUE,
comment = "#>"
)
```
The officer package lets R users manipulate Word (`.docx`) and
PowerPoint (`*.pptx`) documents. In short, one can add images,
tables and text into documents from R. An initial document can
be provided; contents, styles and properties of the original
document will then be available.
<img src="https://www.ardata.fr/img/hexbin/officer.svg" width = "15%"/>
> Make corporate reporting with minimum hassle
[](https://travis-ci.org/davidgohel/officer)
[](https://ci.appveyor.com/project/davidgohel/officer/branch/master)
[](https://CRAN.R-project.org/package=officer)
[](https://codecov.io/gh/davidgohel/officer)
## Word documents
The `read_docx()` function will read an initial Word document (an
empty one by default) and lets you modify its content later.
The package provides functions to add R outputs into a Word document:
* images: produce your plot in png or emf files and add them into the document,
as a whole paragraph or inside a paragraph.
* tables: add data.frames as tables, format is defined by the associated Word table style.
* text: add text as paragraphs or inside an existing paragraph, format is defined by the associated Word paragraph and text styles.
* field codes: add Word field codes inside paragraphs. Field codes is an old
feature of MS Word to create calculated elements such as tables of contents,
automatic numbering and hyperlinks.
In a Word document, one can use cursor functions to reach the
beginning or end of a document, or a particular paragraph containing a
given text. This *cursor* concept has been implemented to make the
post processing of files easier.
File generation is performed with the `print` function.
### import Word document in a data.frame
The function `docx_summary()` reads and imports content of a Word
document into a data.frame. The function handles paragraphs,
tables and section breaks.
## PowerPoint documents
The function `read_pptx()` will read an initial PowerPoint document
(an empty one by default) and let you modify its content later.
The package provides functions to add R outputs into existing or new PowerPoint slides:
* images: produce your plot in png or emf files and add them in a slide.
* tables: add data.frames as tables, format is defined by the associated PowerPoint table style.
* text: add text as paragraphs or inside an existing paragraph, format is defined in the corresponding layout of the slide.
In a PowerPoint document, one can set a slide as selected and reach a particular shape (and remove it or add text).
File generation is performed with the `print()` function.
### import PowerPoint document in a data.frame
The `pptx_summary()` function reads and imports content of a PowerPoint
document into a tibble object. The function handles paragraphs, tables and images.
## Extensions
### Tables and package `flextable`
The package [flextable](https://github.com/davidgohel/flextable) brings a full API to produce nice tables and use them with `officer`. Tables can be written in
PowerPoint documents and Word documents. An option is available to render
flextables in rmarkdown (HTML and Word outputs).
### Vector graphics with package `rvg`
The package [rvg](https://github.com/davidgohel/rvg) brings an API to produce nice vector graphics that can be embedded in PowerPoint documents or Excel workbooks with `officer`.
### Native office charts with package `mschart`
The package [mschart](https://github.com/ardata-fr/mschart) combined with `officer` can
produce native office charts in PowerPoint and Word documents.
## Installation
You can get the development version from GitHub:
```{r eval = FALSE}
devtools::install_github("davidgohel/officer")
```
Or the latest version on CRAN:
```{r eval = FALSE}
install.packages("officer")
```
## Resources
### Online documentation
The help pages are located at https://davidgohel.github.io/officer/.
### Getting help
If you have questions about how to use the package,
[visit Stack Overflow's `officer` tag](http://stackoverflow.com/questions/tagged/officer)
and post your question there. I usually read them and answer when possible.
## Contributing to the package
### Code of Conduct
Anyone getting involved in this package agrees to our [Code of Conduct](https://github.com/davidgohel/officer/blob/master/CONDUCT.md).
### Bug reports
When you file a [bug report](https://github.com/davidgohel/officer/issues), please spend some time making it easy for me to follow and reproduce. The more time you spend on making the bug report coherent, the more time I can dedicate to investigate the bug as opposed to the bug report.
### Contributing to the package development
A great way to start is to contribute an example or improve the documentation.
If you want to submit a Pull Request to integrate functions of yours, please provide:
* the new function(s) with code and roxygen tags (with examples)
* a new section in the appropriate vignette that describes how to use the new function
* add corresponding tests in directory `tests/testthat`.
By using rhub (run `rhub::check_for_cran()`), you will see if everything is ok.
When submitted, the PR will be evaluated automatically on travis and appveyor and you will be able to see if something broke.