% Created 2018-08-04 Sat 21:26
% 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:orgf333d2b}

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
\pkg{Rdpack} builds on it to print a snippet of R code and the results of its evaluation, similarly to
console output but the code is not prefixed and the results are prefixed with comment
symbols.
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}
The argument of \texttt{\textbackslash{}printExample} must be on a single line with released versions of R\footnote{This limitation has been lifted in R-devel starting from June 2018 but obviously this
is currently of little help for production packages.}. 

\texttt{\textbackslash{}printExample} is typically placed in section Details of an object's documentation.

\subsection{Experimental feature}
\label{sec:org8fb81af}

The experimental macro \texttt{\textbackslash{}runExamples} can be used as a replacement of section \texttt{examples}.
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{The macro \texttt{\textbackslash{}runExamples} is fully working but is marked as experimental, since
currently \texttt{R CMD check} gives a warning about unknown \texttt{\textbackslash{}Sexpr} section at top level.
According to the specification of the Rd format (see
\href{https://developer.r-project.org/parseRd.pdf}{Murdoch (2010), p. 4} \texttt{\textbackslash{}Sexpr}'s at top level
are legal.  I need to check with the CRAN team or R devel if such expressions produced by
user macros are excluded on purpose.}.

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

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, 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 code should be on a single line for the reasons explained in the discussion of
\texttt{\textbackslash{}printExample}. 

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:orgfebd2ea}

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).
\end{document}
