Permalink
Browse files

Provide \CRANpkg macro in Rd.sty, and use in the vignettes.

git-svn-id: https://svn.r-project.org/R/trunk@57949 00db46b3-68df-0310-9c12-caf00c1e9a41
  • Loading branch information...
1 parent 6e89b2f commit 84d8ef48fd138ccf4fea2eda89cd6b32c68fe108 hornik committed Dec 21, 2011
@@ -357,6 +357,11 @@
\ifthenelse{\boolean{Rd@use@hyper}}
{\newcommand{\methaliasA}[3]{\hypertarget{Rfn.#3}{\relax}}}
{\newcommand{\methaliasA}[3]{}}
+
+\ifthenelse{\boolean{Rd@use@hyper}}
+{\newcommand{\CRANpkg}[1]{\href{http://CRAN.R-project.org/package=#1}{\pkg{#1}}}}
+{\newcommand{\CRANpkg}[1]{\pkg{#1}}}
+
\newcommand{\HeaderA}[3]{%
\vneed{1ex}
\markboth{#1}{#1}
@@ -1,14 +1,16 @@
\documentclass[a4paper]{article}
-%\VignetteIndexEntry{Display Lists in grid}
-%\VignettePackage{grid}
-%\VignetteDepends{graphics}
-%\VignetteDepends{gridBase}
-\newcommand{\code}[1]{\texttt{#1}}
-\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
+
+\usepackage{Rd}
+
+% \VignetteIndexEntry{Display Lists in grid}
+% \VignettePackage{grid}
+% \VignetteDepends{graphics}
+% \VignetteDepends{gridBase}
+
\newcommand{\grid}{\pkg{grid}}
-\newcommand{\gridBase}{\pkg{gridBase}}
-\newcommand{\lattice}{\pkg{lattice}}
-\newcommand{\R}{{\sffamily R}}
+\newcommand{\gridBase}{\CRANpkg{gridBase}}
+\newcommand{\lattice}{\CRANpkg{lattice}}
+
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
@@ -152,8 +154,8 @@ set of base pie charts within \grid{} viewports within a base plot.
In this case, I can produce all of the grobs required in the normal
manner -- their locations and sizes are not based on special
calculations\footnote{The example is wrapped inside a check for
- whether the \pkg{gridBase} package is installed so that the code
- will still ``run'' on systems without \pkg{gridBase}.}.
+ whether the \CRANpkg{gridBase} package is installed so that the code
+ will still ``run'' on systems without \CRANpkg{gridBase}.}.
<<results=hide>>=
x <- c(0.88, 1.00, 0.67, 0.34)
@@ -1,16 +1,17 @@
\documentclass[a4paper]{article}
-%\VignetteIndexEntry{Introduction to grid}
-%\VignettePackage{grid}
-%\VignetteDepends{lattice}
+\usepackage{Rd}
+
+% \VignetteIndexEntry{Introduction to grid}
+% \VignettePackage{grid}
+% \VignetteDepends{lattice}
% Definitions
-\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\slan}{{\sffamily S}}
\newcommand{\rlan}{{\sffamily R}}
-\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
\newcommand{\grid}{\pkg{grid}}
-\newcommand{\lattice}{\pkg{lattice}}
+\newcommand{\lattice}{\CRANpkg{lattice}}
+
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
@@ -35,11 +36,11 @@ options(width = 60)
of control and flexibility in the appearance and arrangement of
graphical output. \grid{} does not provide high-level functions which
create complete plots. What it does provide is a basis for developing
-such high-level functions (e.g., the \lattice{} and \pkg{ggplot2}
+such high-level functions (e.g., the \lattice{} and \CRANpkg{ggplot2}
packages), the facilities for customising and manipulating \lattice{}
output, the ability to produce high-level plots or non-statistical
images from scratch, and the ability to add sophisticated annotations
-to the output from base graphics functions (see the \pkg{gridBase}
+to the output from base graphics functions (see the \CRANpkg{gridBase}
package).
This document provides an introduction to the fundamental concepts
@@ -83,9 +84,10 @@ grid.show.viewport(viewport(x = 0.5, y = 0.5, width = 0.5, height = 0.25,
\includegraphics[width=3.5in, height=3.5in]{grid-viewport}
}
\end{center}
-\caption{\label{figure:viewport}
- A diagram of a simple \grid{} viewport (produced using the
-\code{grid.show.viewport() } function.}
+\caption{
+ \label{figure:viewport}
+ A diagram of a simple \grid{} viewport (produced using the
+ \protect\code{grid.show.viewport()} function.}
\end{figure}
The object returned by the \code{viewport()} function is only a
@@ -522,7 +524,7 @@ popViewport(2)
}
\end{center}
\caption{\label{figure:simpleplot}
- The grid equivalent of \code{plot(1:10)}.}
+ The grid equivalent of \protect\code{plot(1:10)}.}
\end{figure}
Now consider a more complex example, where we create a barplot
@@ -1,14 +1,16 @@
\documentclass[a4paper]{article}
-%\VignetteIndexEntry{Working with grid grobs}
-%\VignettePackage{grid}
-\newcommand{\code}[1]{\texttt{#1}}
-\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
+
+\usepackage{Rd}
+
+% \VignetteIndexEntry{Working with grid grobs}
+% \VignettePackage{grid}
+
\newcommand{\grid}{\pkg{grid}}
\newcommand{\grob}{\code{grob}}
\newcommand{\gTree}{\code{gTree}}
\newcommand{\gPath}{\code{gPath}}
-\newcommand{\lattice}{\pkg{lattice}}
-\newcommand{\R}{{\sffamily R}}
+\newcommand{\lattice}{\CRANpkg{lattice}}
+
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
@@ -1,10 +1,12 @@
\documentclass[a4paper]{article}
-%\VignetteIndexEntry{Working with viewports}
-\newcommand{\code}[1]{\texttt{#1}}
-\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
+
+\usepackage{Rd}
+
+% \VignetteIndexEntry{Working with viewports}
+
\newcommand{\grid}{\pkg{grid}}
-\newcommand{\lattice}{\pkg{lattice}}
-\newcommand{\R}{{\sffamily R}}
+\newcommand{\lattice}{\CRANpkg{lattice}}
+
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
@@ -33,8 +33,8 @@ pdftitle={Package `parallel'}% Could also have pdfusetitle
\section{Introduction}
Package \pkg{parallel} was first included in \R{} 2.14.0. It builds
-on the work done for CRAN packages \pkg{multicore} \citep{multicore}
-and \pkg{snow} \citep{snow} and provides drop-in replacements for most
+on the work done for CRAN packages \CRANpkg{multicore} \citep{multicore}
+and \CRANpkg{snow} \citep{snow} and provides drop-in replacements for most
of the functionality of those packages, with integrated handling of
random-number generation.
@@ -95,7 +95,7 @@ processes. They can be created in one of three ways:
and Mac OS X may expect pop-up dialog boxes from the firewall asking
if an \R{} process should accept incoming connections.
- Following \pkg{snow}, a pool of worker processes listening
+ Following \CRANpkg{snow}, a pool of worker processes listening
\emph{via} sockets for commands from the master is called a
`cluster' of nodes.
@@ -108,7 +108,7 @@ processes. They can be created in one of three ways:
reasonable OS) share memory pages with the master until modified so
forking is very fast.
- The use of forking was pioneered by package \pkg{multicore}.
+ The use of forking was pioneered by package \CRANpkg{multicore}.
Note that as it does share the complete process, it also shares any
GUI elements, for example an \R{} console and on-screen devices.
@@ -120,28 +120,28 @@ processes. They can be created in one of three ways:
There needs to be a way to communicate between master and worker.
Once again there are several possibilities since master and workers
- share memory. In \pkg{multicore} the initial fork sends an \R{}
+ share memory. In \CRANpkg{multicore} the initial fork sends an \R{}
expression to be evaluated to the worker, and the master process
opens a pipe for reading that is used by the worker to return the
results. Both that and creating a cluster of nodes communicating
\emph{via} sockets are supported in package \pkg{parallel}.
\item Using OS-level facilities to set up a means to send tasks to
other members of a group of machines. There are several ways to do
- that, and for example package \pkg{snow} can make use of PVM
+ that, and for example package \CRANpkg{snow} can make use of PVM
(`parallel virtual machine') and MPI (`message passing interface')
- using \R{} packages \pkg{rpvm} and \pkg{Rmpi} respectively.
+ using \R{} packages \CRANpkg{rpvm} and \CRANpkg{Rmpi} respectively.
Communication overheads can dominate computation times in this
approach, so it is most often used on tightly-coupled networks of
computers with high-speed interconnects.
- CRAN packages following this approach include \pkg{GridR} (using
- Condor or Globus) and \pkg{Rsge} (using SGE, currently called
+ CRAN packages following this approach include \CRANpkg{GridR} (using
+ Condor or Globus) and \CRANpkg{Rsge} (using SGE, currently called
`Oracle Grid Engine').
It will not be considered further in this vignette, but those parts
- of \pkg{parallel} which provide \pkg{snow}-like functions will
- accept \pkg{snow} clusters including MPI clusters (and although PVM
+ of \pkg{parallel} which provide \CRANpkg{snow}-like functions will
+ accept \CRANpkg{snow} clusters including MPI clusters (and although PVM
and NWS clusters have not been tested, they should also work).
\end{enumerate}
@@ -185,7 +185,7 @@ the user may be running many \R{} processes simultaneously, and those
processes may themselves be using multiple threads through a
multi-threaded BLAS, compiled code using OpenMP or other low-level
forms of parallelism. We have even seen instances of
-\pkg{multicore}'s \code{mclapply} being called
+\CRANpkg{multicore}'s \code{mclapply} being called
recursively,\footnote{\code{parallel::mclapply} detects this and runs
nested calls serially.} generating $2n + n^2$ processes on a machine
estimated to have $n = 16$ cores.
@@ -206,8 +206,8 @@ number of physical CPU packages.
\section{Analogues of apply functions}
-By far the most common direct applications of packages \pkg{multicore}
-and \pkg{snow} have been to provide parallelized replacements of
+By far the most common direct applications of packages \CRANpkg{multicore}
+and \CRANpkg{snow} have been to provide parallelized replacements of
\code{lapply}, \code{sapply}, \code{apply} and related functions.
As analogues of \code{lapply} there are
@@ -236,9 +236,9 @@ For matrices there are the rarely used \code{parApply} and
\section{SNOW Clusters}
-The package contains a slightly revised copy of much of \pkg{snow},
+The package contains a slightly revised copy of much of \CRANpkg{snow},
and the functions it contains can also be used with clusters created
-by \pkg{snow}.
+by \CRANpkg{snow}.
Two functions are provided to create SNOW clusters,
\code{makePSOCKcluster} (a streamlined version of
@@ -290,18 +290,18 @@ information in the shape of extra arguments.
\section{Forking}
-Except on Windows, the package contains a copy of \pkg{multicore}:
+Except on Windows, the package contains a copy of \CRANpkg{multicore}:
there a few names with the added prefix \code{mc}, e.g.{}
-\code{mccollect} and \code{mcparallel}. (Package \pkg{multicore} used
+\code{mccollect} and \code{mcparallel}. (Package \CRANpkg{multicore} used
these names, but also the versions without the prefix which are too
-easily masked: e.g.{} package \pkg{lattice} has a function
+easily masked: e.g.{} package \CRANpkg{lattice} has a function
\code{parallel}.)
-The low-level functions from \pkg{multicore} are provided but not
+The low-level functions from \CRANpkg{multicore} are provided but not
exported from the namespace.
There are high-level functions \code{mclapply} and \code{pvec}: unlike
-the versions in \pkg{multicore} these default to 2 cores, but this can
+the versions in \CRANpkg{multicore} these default to 2 cores, but this can
be controlled by setting \code{options("mc.cores")}, and that takes
its default from environment variable \code{MC\_CORES} when the
package is loaded. (Setting this to \code{1} inhibits parallel
@@ -340,7 +340,7 @@ numbers: the processes/threads which run separate parts of the
computation need to run independent (and preferably reproducible)
random-number streams. One way to avoid any difficulties is (where
possible) to do all the randomization in the master process: this is
-done where possible in package \pkg{boot} (version 1.3-1 and later).
+done where possible in package \CRANpkg{boot} (version 1.3-1 and later).
When an \R{} process is started up it takes the random-number seed
from the object \code{.Random.seed} in a saved workspace or constructs
@@ -407,11 +407,11 @@ Apart from \emph{streams} ($2^{127}$ steps apart), there is the concept of
\code{nextRNGSubStream} advances to the next substream.
A direct \R{} interface to the (clunkier) original C implementation is
-available in CRAN package \pkg{rlecuyer} \citep{rlecuyer}. That works
+available in CRAN package \CRANpkg{rlecuyer} \citep{rlecuyer}. That works
with named streams, each of which have three 6-element seeds
associated with them. This can easily be emulated in \R{} by storing
\code{.Random.seed} at suitable times. There is another interface
-using S4 classes in package \pkg{rstream} \citep{rstream}.
+using S4 classes in package \CRANpkg{rstream} \citep{rstream}.
\section{Load balancing}
@@ -461,7 +461,7 @@ the workers start with a different \R{} environment from the one
current on the master).
An example of providing access to both approaches as well as serial
-code is package \pkg{boot}, version \code{1.3-3} or later.
+code is package \CRANpkg{boot}, version \code{1.3-3} or later.
\section{Extended examples}
@@ -480,7 +480,7 @@ some actually are computer-intensive.
\subsection{Bootstrapping}
-Package \pkg{boot} \citep{boot} is support software for the monograph
+Package \CRANpkg{boot} \citep{boot} is support software for the monograph
by \citet{Davison.Hinkley.97}. Bootstrapping is often used as an
example of easy parallelization, and some methods of producing
confidence intervals require many thousands of bootstrap samples.
@@ -489,7 +489,7 @@ within its main functions, but we illustrate how to use the original
(serial) functions in parallel computations.
We consider two examples using the \code{cd4} dataset from package
-\pkg{boot} where the interest is in the correlation between before and
+\CRANpkg{boot} where the interest is in the correlation between before and
after measurements. The first is a straight simulation, often called
a \emph{parametric bootstrap}. The non-parallel form is
<<>>=
@@ -712,34 +712,34 @@ while(length(done) < length(pkgs)) {
\section{Differences from earlier versions}
-The support of parallel RNG differs from \pkg{snow}: \pkg{multicore}
+The support of parallel RNG differs from \CRANpkg{snow}: \CRANpkg{multicore}
had no support.
\subsection{Differences from multicore}
-\pkg{multicore} had quite elaborate code to inhibit the Aqua event
+\CRANpkg{multicore} had quite elaborate code to inhibit the Aqua event
loop for \command{R.app} and the event loop for the \code{quartz}
graphics device. This has been replaced by recording a flag in the
\R{} executable for a child process.
The version of \code{detectCores} here is biased towards the number of
physical CPUs. This was occasioned by serious problems on Sparc Solaris
-where \pkg{multicore} defaulted to a silly number of processes.
+where \CRANpkg{multicore} defaulted to a silly number of processes.
Functions \code{fork} and \code{kill} have \code{mc} prefixes and are
not exported. This avoids confusion with other packages (such as
-package \pkg{fork}), and note that \code{mckill} is not as general as
+package \CRANpkg{fork}), and note that \code{mckill} is not as general as
\code{tools::pskill}.
Aliased functions \code{collect} and \code{parallel} are no longer provided.
\subsection{Differences from snow}
-\pkg{snow} set a timeout that exceeded the maximum value required by
+\CRANpkg{snow} set a timeout that exceeded the maximum value required by
POSIX, and did not provide a means to set the timeout on the workers.
This resulted in process interlocks on Solaris.
-\code{makeCluster} creates PVM, MPI or NWS clusters by calling \pkg{snow}.
+\code{makeCluster} creates PVM, MPI or NWS clusters by calling \CRANpkg{snow}.
\code{makePSOCKcluster} has been streamlined, as package \pkg{parallel} is in
a known location on all systems, and \command{Rscript} is these days
@@ -777,18 +777,18 @@ R CMD Sweave file.Rnw
\subsection{Can I use Sweave for OpenOffice files?}
- Yes, package \pkg{odfWeave} provides functions for using Sweave in
+ Yes, package \CRANpkg{odfWeave} provides functions for using Sweave in
combination with OpenOffice Writer rather than \LaTeX.
\subsection{Can I use Sweave for HTML files?}
- Yes, package \pkg{R2HTML} provides a driver for using Sweave in
+ Yes, package \CRANpkg{R2HTML} provides a driver for using Sweave in
combination with HTML rather than \LaTeX.
\subsection{After loading package \pkg{R2HTML} Sweave doesn't
work properly!}
- Package \pkg{R2HTML} registers an Sweave driver for HTML files
+ Package \CRANpkg{R2HTML} registers an Sweave driver for HTML files
using the same file extensions as the default \texttt{noweb}
syntax, and after that its syntax is on the search list before the
default syntax. Using
@@ -799,9 +799,7 @@ or calling Sweave like
\begin{verbatim}
Sweave(..., syntax = "SweaveSyntaxNoweb")
\end{verbatim}
-ensures the default syntax even after loading package \pkg{R2HTML}.
-
-
+ensures the default syntax even after loading package \CRANpkg{R2HTML}.
\end{document}

0 comments on commit 84d8ef4

Please sign in to comment.