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
|
<%@meta language="R-vignette" content="--------------------------------
DIRECTIVES FOR R:
%\VignetteIndexEntry{R packages: Vignettes prior to R 3.0.0}
%\VignetteAuthor{Henrik Bengtsson}
%\VignetteKeyword{R}
%\VignetteKeyword{package}
%\VignetteKeyword{vignette}
%\VignetteKeyword{RSP}
%\VignetteEngine{R.rsp::rsp}
%\VignetteTangle{FALSE}
--------------------------------------------------------------------"%>
<% t0 <- Sys.time() %>
<%
R.rsp <- R.oo::Package("R.rsp");
%>
\documentclass[12pt]{article}
\usepackage{xspace}
\usepackage{alltt}
% Adjust margins
\addtolength{\oddsidemargin}{-0.5in}
\addtolength{\evensidemargin}{-0.5in}
\addtolength{\textwidth}{1in}
\addtolength{\topmargin}{-0.5in}
\addtolength{\textheight}{1in}
% Drop PTEX metadata (for reproducbility)
\pdfsuppressptexinfo=-1
\newcommand{\keywords}[1]{\footnotesize{\textbf{Keywords: }#1}\xspace}
\newcommand{\pkg}[1]{\textsl{#1}\xspace}
\newcommand{\file}[1]{\textsl{#1}\xspace}
\newcommand{\code}[1]{\texttt{#1}\xspace}
\newcommand{\bs}{$\backslash$}
\newenvironment{rspVerbatim}{\vspace{-\parskip}\begin{alltt}\color{blue}}{\end{alltt}}
\newenvironment{escapeRspVerbatim}{\vspace{-\parskip}\begin{alltt}}{\end{alltt}}
\title{<%@meta name="title"%>}
\author{<%@meta name="author"%>}
\date{<%=format(as.Date(R.rsp$date), format="%B %d, %Y")%>}
\begin{document}
\maketitle
<%-------------------------------------------------------------------
INTRODUCTION
-------------------------------------------------------------------%>
\section*{Introduction}
When building an R package, Sweave/LaTeX vignettes are recognized by R, compiled into PDFs, which are listed along with their source in the R help system, e.g. \code{help.start()}. These package vignettes are also being listed online on the CRAN and Bioconductor package pages. As of R~v3.0.0, it is straighforward to also include vignettes of other type, include RSP-embedded vignettes.
For legacy versions of R prior to R v3.0.0 (released April 2013), some efforts have to be made to build and incorporate non-Sweave vignettes. This document describes how to include RSP and other non-Sweave vignettes in R packages in a way that is fully compatible with legacy and more recent versions of R. By following these instructions, the exact same package setup can be used regardless of R version and they work for any type of R vignettes, e.g. RSP, knitr and noweb.
<%-------------------------------------------------------------------
HOW TO
-------------------------------------------------------------------%>
\section*{How to}
We assume that you are already familiar with how to use non-Sweave vignettes in R for R v3.0.0 and later. If not, please see other \pkg{R.rsp} vignettes on this topic as well as 'Writing R Extensions' part of the built-in R documention. This document explains the \emph{additional steps} needed in order to for non-Sweave vignettes work also in version prior to R~v3.0.0.
More precisely, the following three files need to be available "as is" in the \file{vignettes/} directory of the package:
\begin{enumerate}
\item \file{dummy.Rnw}: A "dummy" Sweave vignette file triggering R's vignette installation procedures, and
\item \file{Makefile}: A file with instructions emulating the post-3.0.0 R vignette mechanisms, and
\item \file{.install\_extras}: A file specifying which (source and generated output) vignette files to \emph{install}\footnote{The term \emph{install} is used for vignettes to make it explicit that the orignal source files are located in \file{vignettes/}, but when compiled are copied together with the output files to \file{inst/doc/} of the built package. Directory \file{vignettes/} is \emph{not} installed to, and therefore not available in, the built package.}.
\end{enumerate}
These files can be copied from the \pkg{R.rsp} package (see Appendix for their content) to the new package's \file{vignettes/} directory using:
\begin{verbatim}
filenames <- c("dummy.Rnw", "Makefile", ".install_extras")
<% pathMk <- file.path("doc", "templates", fsep="/"); %>
pathS <- system.file("<%=pathMk%>", package="R.rsp")
pathD <- "vignettes"
dir.create(pathD)
pathnamesS <- file.path(pathS, gsub("^[.]", ",", filenames))
pathnamesD <- file.path(pathD, filenames)
file.copy(pathnamesS, to=pathnamesD)
\end{verbatim}
Neither of these files need to be edited\footnote{The reason for the \code{gsub()} renaming is because R does not allow the last file to installed starting with a period. Instead with use a comma as a workaround.}. Note that the Makefile and the functions it utilizes are independent of the RSP markup language why it can also be used for other vignette formats as well.
The use of custom \file{vignettes/Makefile} and \file{vignettes/.install\_extras} files is described in Section `Writing package vignettes' of `Writing R Extensions'.
\subsection*{Improved HTML overview of vignettes}
By default, the R HTML help system will list links to the PDF and the Sweave source of the vignettes. This means that also the dummy Rnw stub needed will also be listed. As explained in `Writing R Extensions', it is possible to override this by providing a custom \file{vignettes/index.html} file. It can be tedious the manually edit the \file{index.html} file. For this reason, if the \file{index.html} file is missing, then the above \file{Makefile} automatically builds one (using RSP-embedded HTML) and populates it with the PDF and source files available according to what the vignette files specify (see also the Appendix).
<%-------------------------------------------------------------------
APPENDIX
-------------------------------------------------------------------%>
\clearpage
\section*{Appendix}
\subsection*{The generic Makefile file}
The customized and generic \file{Makefile} that builds non-Sweave vignettes and any missing \file{index.html} file is available in \pkg{R.rsp} package directory \file{<%=pathMk%>/}. This \file{Makefile} should be copied ``as is'' to \file{vignettes/} of your package. Its content is:
{\scriptsize\begin{verbatim}
<%=
pathname <- system.file(pathMk, "Makefile", package="R.rsp");
bfr <- readLines(pathname, warn=FALSE);
rr <- grep("^# HISTORY", bfr);
if (length(rr) > 0) {
bfr <- bfr[1:(rr-2L)];
}
bfr <- gsub("\t", " ", bfr, fixed=TRUE);
paste(bfr, collapse="\n");
%>
\end{verbatim}}
\subsection*{The generic .install\_extras file}
The \file{vignettes/.install\_extras} file controls which source and output vignette files should be installed and therefore be copied to the \file{inst/doc/} directory of the built package. The generic \file{.install\_extras} file, available in \pkg{R.rsp} package directory \file{<%=pathMk%>/}, contains:
{\scriptsize\begin{verbatim}
<%=
pathname <- system.file(pathMk, ",install_extras", package="R.rsp");
bfr <- readLines(pathname, warn=FALSE);
rr <- grep("^# HISTORY", bfr);
if (length(rr) > 0) {
bfr <- bfr[1:(rr-2L)];
}
bfr <- gsub("\t", " ", bfr, fixed=TRUE);
paste(bfr, collapse="\n");
%>
\end{verbatim}}
\subsection*{The "trigger" dummy.Rnw file}
The "dummy" Sweave source file \file{dummy.Rnw} file available by in \pkg{R.rsp} package directory \file{<%=pathMk%>/}, which triggers R's vignette installation mechanism to process the \file{vignettes/Makefile}, contains:
{\scriptsize\begin{verbatim}
<%=
pathname <- system.file(pathMk, "dummy.Rnw", package="R.rsp");
bfr <- readLines(pathname, warn=FALSE);
rr <- grep("^# HISTORY", bfr);
if (length(rr) > 0) {
bfr <- bfr[1:(rr-2L)];
}
bfr <- gsub("\t", " ", bfr, fixed=TRUE);
paste(bfr, collapse="\n");
%>
\end{verbatim}}
\subsection*{Session information}
<%=toLatex(sessionInfo())%>
This report was automatically generated using \code{rfile()} of the R.rsp package.
\end{document}
|
