Skip to content

Latest commit

 

History

History
144 lines (116 loc) · 6.32 KB

README.md

File metadata and controls

144 lines (116 loc) · 6.32 KB
Raw

accessr

Build status R-CMD-check Coverage Status CRAN_Status_Badge Downloads (monthly) Downloads (total)

Command Line Tools to Produce Accessible Documents using R Markdown

This package provides functions to produce accessible html slides, html, Word and PDF documents from input R markdown files. Accessible PDF files are produced only on a Windows Operating System. One aspect of accessibility is providing headings that are recognised by a screen reader, providing a navigational tool for a blind or partially-sighted person. A main aim is to enable documents of different formats to be produced from a single R markdown source file using one function call. The render() function from the rmarkdown package is used to render R markdown files. A zip file containing multiple files can be produced from one function call. A user-supplied template Word document can be used to determine the formatting of the output Word document. Accessible PDF files are produced from Word documents using OfficeToPDF. A convenience function, install_otp() is provided to install this software. The option to print html output to (non-accessible) PDF files is also available.

Additional features. When the output format is a Word document the function ext_img() enables the knitr chunk options out.width and/or out.height to be used to set the dimensions of a figure (R-generated or external image). Passing (the default) slide_level = 1 to rmd2ioslides() enables the use of the level one header # to separate slides in an ioslides presentation without producing grey segue slides.

The main functions

The main functions are:

  • rmd2word(): create word documents and accessible PDF files.
  • rmd2ioslides(), rmd2slidy(): create ioslides/slidy presentations and perhaps print to (non-accessible) PDF documents.
  • rmd2html(): create html documents and perhaps print to (non-accessible) PDF documents.
  • rmd2many(): create HTML slides, PDF slides, Word and PDF documents from a single R markdown file.

Rmd to Word to PDF

Suppose that in your current working directory you have the R markdown files file1.Rmd and file2.Rmd, a template Word file your_template.docx and that the file OfficeToPDF.exe downloaded from OfficeToPDF releases can be accessed. The following code creates files file1.docx, file2.docx, file1.pdf and file2.pdf in your working directory and, unless you supply zip = FALSE, a zip file accessr_word.zip containing the two PDF files will also be created.

rmd2word(c("file1", "file2"), doc = "your_template.docx")

A path to the Word template document can be provided using the doc argument. If doc is not provided then a default template is used. See ?rmd2word for details. If you include figures then the knitr chunk option fig.alt can be used to set the alternative text. You may find you need to enclose LaTeX maths environments in $$ … $$ when typesetting mathematics.

A path to OfficeToPDF.exe can be provided using an argument dir. If dir is missing then rmd2word will look for OfficeToPDF.exe in the default installation directory dir of install_otp.

Rmd to ioslides

Similarly, the function rmd2ioslides produces HTML ioslides presentations.

rmd2ioslides(c("file1", "file2"))

If the argument pdf = TRUE is supplied then the chrome_print function in the pagedown package is used to produce (non-accessible) PDF files from these slides. This requires a secure internet connection. See ?rmd2ioslides.

rmd2slidy (see slidy presentations) and rmd2html work in a similar way.

A basic example Rmd file

Executing the following code will copy the file example.Rmd to the working directory and create from it output as a Word document, an html document and ioslides and slidy presentations. In the working directory there will also be the files example.docx, example.pdf and example.html. The latter contains the slidy presentation because the final three calls each create example.html, which is overwritten.

rmd_file <- system.file(package = "accessr", "examples", "example.Rmd")
file.copy(from = rmd_file, to = getwd())
rmd2word("example")
rmd2html("example")
rmd2ioslides("example")
rmd2slidy("example")

This example file includes examples of creating figures and tables and notes potential issues with typesetting mathematics when creating Word output. In particular, the knitr chunk options fig.alt and fig.cap can be used to create a separate alternative text and caption for a figure. It also features the use of an input list params of named parameters, with a component hide that can be used to hide selected parts of the output.

Suggested workflow

I have used rmd2ioslides to create HTML lecture presentations and rmd2word to create accessible PDF document versions of these presentations for upload, pre- and post- lecture, to a Virtual Learning Environment (Moodle). The default setting of rmd2many produces these files and Word document with 18pt bold text. The latter may be particularly useful for some students. I use params$hide (see above) to hide selected content from the file that I share with the students prior to the lecture.

Installation

To get the current released version from CRAN:

install.packages("accessr")