In charlotte-ngs/rmddochelper:

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
#knitr::knit_hooks$set(odg_conv = rmddochelper::odg_convert_hook)

Disclaimer

This vignette describes the search for and the design for an easy to use functionality to include ODG-formatted graphics objects into an Rmarkdown (Rmd) document. We assume that the graphics object is stored in a file which is termed from here on as the odg-file. The odg-file cannot directly be included into the Rmd-document, but it is converted into a format such as pdf or png, that can then be included as graphics in an Rmd-document.

Introduction

One basic requirement of authors for a writing-tool is the ability to include graphics into a document. The technical details of how that is done depends on the document authoring system that is used.

WYSIWYG

Most such systems have their own graphics functionality included. Alternatively it is also possible to prepare the graphics in a specialized program, and then include the graphics via drag-and-drop into the document or some menu-based functionality for graphics inclusion can be used.

Markup

LaTeX: According to lshort there are some packages to produce graphics directly in the LaTeX-source document. Graphics can also be produced outside of LaTeX and can then be included into the document using the function \includegraphics.

HTML: In HTML documents, graphics are produced in a separate program and are included using the <img src>-tag.

Markdown

Similarly to the markup languages, markdown defines a set of instruction statements encoded with special symbols that are used for formatting the output. The design goal of markdown was to reduce the amount of instruction symbols compared to the text by a significant amount. There are several flavors of markdown languages. The one used in this project is called Rmarkdown (Rmd). Rmd allows to include chunks of R-code which will be processed by specialized R-packages to first produce an ordinary markdown format and then produce output-formats such as pdf, html or MS-Word. The final conversion step is done using the famous document conversion system called pandoc.

Methods

For Rmd-source documents, graphics objects can be included using the function include_graphics() from the R-package knitr. This function allows to include graphics objects in popular formats such as pdf or png. This is the reason why, this package (rmddochelper) uses this function.

Deprecated legacy functions

This package rmddochelper has already an existing method of creating an odg-graphic using the function create_odg_graphic(). This function is called not from within a document, but outside of the document in a separate R-console (e.g. in RStudio). This function is rather complicated to use, because it offers many parameters. A first approach might very well be to simplify this function. This is postponed to a later point in time, in favor of building a function for a smoother workflow which is described below.

New Proposed Workflow

In the process of writing a document, an author decides to include a diagram, a figure or a drawing into that document. The diagram, figure, drawing or whatever else, the author wants to include into his or her document is from now on called a graphical object. What is important at this point is that the graphical object (be it a diagram, a figure, a drawing or something else) that should be included, is to be produced or generated by a software program or tool outside of the ordinary text-authoring system.

Creation

The way of creating a graphical object proposed here, uses the notebook-type features of R-code chunks in Rmd-documents when edited with RStudio. These features allow for the execution of a given R-statement inside of a R-code chunk without rendering the whole Rmd-source document. A graphics object can be produced by calling an R-function which might be named rmddochelper::use_odg_graphic inside an R-code-chunk such as shown below.

knitr::opts_chunk$set(eval = FALSE)

 ```r
 rmddochelper::use_odg_graphic(ps_path = "my_first_graphic.odg")
 ```

The only important thing here is that the label of the R-code-chunk is the same as the basename of the argument ps_path without file-extension. This is later used by the hook-function that will convert the odg-graphics object into the formats that can be included into the document.

When executing the function rmddochelper::use_odg_graphic() inside the R-code-chunk, an odg-file is created in the directory that is specified by the argument ps_path . The above shown function is supposed to work like the devtools::use_* class of functions. An important pre-requisite of the shown function is that we have a tool available to create a graphical object in an odg-format. One example of such a tool is LibreOffice Draw.

Inclusion

In most cases the original version of the graphical object is in a format that cannot directly be included in a document like an Rmd-document. Hence it needs to be converted into a usable format such as pdf or png. In the case of odg graphics produced with LibreOffice Draw, we can use the functionality of LibreOffice to do the format conversion. After the format conversion, we need to insert the R-code chunk that includes the graphical object into the Rmd-source document. This chunk looks as follows

 ```r
 knitr::include_graphics(path = "./my_first_graphic.png")
 ```

Between the creation of the odg-graphics object and the inclusion of the graphics file into the Rmd-document, the graphics object must be converted form odg to png or pdf. This conversion can either be done manually from In the end this chunk will consist of several parts. One part is the statement that calls the knitr::include_graphics() function. This function call gets the converted graphic file as argument. Furthermore, it is required that the chunk label has the same name as the included graphic file without extension. This requirement comes from the automated format conversion.

Format conversion

The format conversion is best done in a knitr-hook function. A good reference to knitr-hook function is given on https://yihui.name/knitr/hooks/.

Old Legacy Stuff below

The question is how we can decide the location of this rmd-document. One possibility is to use the rprojroot package. The function thisfile() returns the absolute path to this rmd-document as shown below.

this_rmd_rprojroot <- rprojroot::thisfile()
cat("This file is: ", this_rmd, "\n")

But the solution with rprojroot works only when the rmd-document is transformed using knitr because the determination of the path to the current rmd-source document is based on functionality in knitr. Hence when trying to run a chunk inside this document interactively as in a notebook, the solution using rprojroot does not work.

Depending on the parent directory of this rmd-document, we want to place the created odg-graphic in a different place. In case this rmd-source document is placed in a separate subdirectory called rmd, we put all odg-graphics under ../odg. Otherwise, the odg-graphic is just put in a subdirectory called odg.

par_dir <- basename(dirname(this_rmd))
cat("Parent directory: ", par_dir, "\n")
# determine odg_dir
get_odg_dir4this_rmd <- function(ps_this_rmd){
  # determine parent directory of ps_this_file
  s_parent_dir <- dirname(ps_this_rmd)
  s_base_parent_dir <- basename(s_parent_dir)
  s_odg_parent_dir <- s_parent_dir
  if (s_base_parent_dir == "rmd") 
    s_odg_parent_dir <- dirname(s_parent_dir)
  return(file.path(s_odg_parent_dir, "odg"))

}
# output
cat("Current odg_dir: ", get_odg_dir4this_rmd(ps_this_rmd = this_rmd))
cat("Test odg_dir: ", get_odg_dir4this_rmd(ps_this_rmd = file.path(dirname(this_rmd), "rmd", basename(this_rmd))))

At this point we are ready to place the created odg-graphic in an automatically determined subdirectory. This subdirectory is determined using the function get_odg_dir4this_rmd(). The call to the cration function would then be

s_odg_dir <- get_odg_dir4this_rmd(ps_this_rmd = this_rmd)
s_odg_file <- file.path(s_odg_dir, "my_second_odg.odg")
rmddochelper::use_odg_graphic(ps_odg_file = s_odg_file)