% Created 2019-04-14 Sun 17:28
% Intended LaTeX compiler: pdflatex
\documentclass[a4paper,twoside,11pt,nojss,article]{jss}
	       \usepackage[T1]{fontenc}
	       \usepackage[left=2cm,right=2cm,bottom=15mm]{geometry}
	       \usepackage{graphicx,color,alltt}
	       \usepackage[authoryear,round,longnamesfirst]{natbib}
	       \usepackage{hyperref}
                              % \usepackage{Sweave}
\author{Georgi N. Boshnakov}
\Plainauthor{Georgi N. Boshnakov}
\Address{
Georgi N. Boshnakov\\
School of Mathematics\\
The University of Manchester\\
Oxford Road, Manchester M13 9PL, UK\\
URL: \url{http://www.maths.manchester.ac.uk/~gb/}
}
<<echo=FALSE>>=
library(Rdpack)
pd <- packageDescription("Rdpack")
@
\Abstract{
This vignette discusses Rd macros provided by package \pkg{Rdpack} for
inserting evaluated examples and programmatically created figures. These
macros are convenience wrappers around the native capabilities provided
by the Rd parser. The macros work in Rd files and roxygen2 comments.
\par
This vignette is part of package Rdpack, version~\Sexpr{pd$Version}.
}
\Keywords{examples, graphics, figures, Rd, R}
\Plainkeywords{examples, graphics, figures, Rd, R}
\author{Georgi N. Boshnakov}
\date{\today}
\title{Inserting figures and evaluated examples}
\hypersetup{
 pdfauthor={Georgi N. Boshnakov},
 pdftitle={Inserting figures and evaluated examples},
 pdfkeywords={examples, graphics, figures, Rd, R},
 pdfsubject={},
 pdfcreator={Emacs 25.3.1 (Org mode 9.1.6)}, 
 pdflang={English}}
\begin{document}

\maketitle
%\SweaveOpts{engine=R,eps=FALSE}

%\VignetteIndexEntry{Inserting figures and evaluated examples}
%\VignetteDepends{Rdpack}
%\VignetteKeywords{examples, graphics, figures, Rd, R}
%\VignettePackage{Rdpack}


\section{Evaluated examples}
\label{sec:orgf215fe2}

Sometimes the documentation of an object becomes more clear if accompanied by snippets of R
code and their results. 
The standard Rd macro \texttt{\textbackslash{}Sexpr} caters for a number of possibilities to evaluate R code and
insert the results and the code in the documentation. 
The Rd macro \texttt{\textbackslash{}printExample} provided by package
\texttt{"Rdpack"} builds on it to print a snippet of R code and the results of its evaluation. 
For example,
\begin{verbatim}
    \printExample{2+2; a <- 2*3; a}
\end{verbatim}
gives
\begin{verbatim}
    2 + 2
    ##: 4
    a <- 2 * 3
    a
    ##: 6
\end{verbatim}
Note that each command is printed on a separate line even though in this example the source code
is on a single line, separated by semicolons\footnote{The argument of \texttt{\textbackslash{}printExample} needed to be on a single line with versions of R before
\texttt{R-3.6.0}, since the lines after the first were silently ignored, with no errors and no
warnings. This should not be a concern if your package requires \texttt{R >= 3.6.0} anyway or if you
can live with somewhat inferior documentation in older versions or \texttt{R}.}. 
Similarly to \texttt{knitr}, the results are prefixed with comment symbols but the code is not
prefixed with anything.

The help page of \texttt{?Rdpack::promptUsage} contains a number of examples created with
\texttt{\textbackslash{}printExample}. The corresponding Rd file can be obtained from the package tarball or from
\url{https://github.com/GeoBosh/Rdpack/blob/master/man/promptUsage.Rd}. 

\section{Section examples with results}
\label{sec:org80695a1}


The macro \texttt{\textbackslash{}printExample} can be used as many times as needed and is typically placed in
section \emph{Details} of an object's documentation.

In contrast, the macro \texttt{\textbackslash{}runExamples} can be used as a replacement of the whole \texttt{\textbackslash{}examples}
section in the Rd file. The code and its results are printed just as by \texttt{\textbackslash{}printExample}.

For example, if the following code is put at the top level in an Rd file (i.e. not in a
section):
\begin{verbatim}
    \runExamples{2+2; a <- 2*3; a}
\end{verbatim}
then it will be evaluated and replaced by a normal section examples:
\begin{verbatim}
    \examples{
    2 + 2
    ##: 4
    a <- 2 * 3
    a
    ##: 6
    }
\end{verbatim}
This generated examples section is processed by the standard R tools (almost) as if it was
there from the outset. In particular, the examples are run by the R's quality control tools
and tangled along with examples in other documentation files\footnote{In versions of R before 3.6.0, \texttt{R CMD check} used to give warnings about unknown
\texttt{\textbackslash{}Sexpr} section at top level. See also the note about multiline argument for
\texttt{\textbackslash{}printExample}.}. A small example package
using this feature is at \href{https://github.com/GeoBosh/reprexes/tree/master/runExamplesCheck}{runExamplesCheck}.


\section{Creating and including graphs}
\label{sec:orgb3e0ae9}

Figures can be inserted with the help of the standard Rd markup command \texttt{\textbackslash{}figure}. 
The Rd macro \texttt{\textbackslash{}insertFig} provided by package \pkg{Rdpack} takes a snipped of R code,
evaluates it and inserts the plot produced by it (using \texttt{\textbackslash{}figure}).  \texttt{\textbackslash{}insertFig} takes three
arguments: a filename, the package name and the code to evaluate to produce the figure. 
For example,
\begin{verbatim}
    \insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)}
\end{verbatim}
will evaluate the code\footnote{See also the remark about using miltiline code in \texttt{\textbackslash{}printExample}. For figures this is
not a problem at all even in older versions of R, since all preparatory code can be put in a
separate \texttt{\textbackslash{}Sexpr}, and then \texttt{\textbackslash{}insertFig} can be given only the final command producing the graph.}, save the graph in file \texttt{"man/figures/cars.png"} subdirectory of
package \texttt{"mypackage"}, and include the figure using \texttt{\textbackslash{}figure}. 
Subdirectory \texttt{"figures"} is created if it doesn't exist. 
Currently the graphs are saved in \texttt{"png"} format only.


The sister macro \texttt{\textbackslash{}makeFig} creates the graph in exactly the same way as \texttt{\textbackslash{}insertFig} but
does not insert it. This can be done with a separate \texttt{\textbackslash{}figure} command. This can be used if
additional options are desired for different output formats, see the description of \texttt{\textbackslash{}figure} in
"Writing R extensions". 

\subsection{A technical note}
\label{sec:org00b2a6c}

The above description should just work.  This note is for users who wonder about
technicalities.

The R documentation can be built in many ways and as a result the directory
\texttt{"man/figures/"} does not necessarily refer to the developers source package. 
Indeed, when a package is built, R works on a modified and cleaned-up temporary copy of the source
directory, so the figures are created in that copy and then included in the package tarball. 
Similarly during the package check. On the other hand, \texttt{R CMD Rd2pdf} and some other tools
and R functions work directly on the source tree of the package and they will create the
figures there.  

The net effect is that a package tarball always contains freshly generated up-to-date
graphs. Developers who never generate the documentation by other means may not even have the
directory \texttt{man/figures} in the source tree of their package (but it will be present in the
package tarball).

\newpage
\end{document}