1% File src/library/utils/man/vignette.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2016 R Core Team
4% Distributed under GPL 2 or later
5
6\name{vignette}
7\title{View, List or Get R Source of Package Vignettes}
8\alias{vignette}
9\alias{edit.vignette}
10\alias{print.vignette}
11\alias{vignettes} % to link to from e.g. grid-package.Rd
12%% \alias{getRcode}
13%% \alias{getRcode.vignette}%hidden
14\description{
15  View a specified package vignette, or list the available ones;
16  display it rendered in a viewer, and get or edit its \R source file.
17}
18\usage{
19vignette(topic, package = NULL, lib.loc = NULL, all = TRUE)
20
21\S3method{print}{vignette}(x, \dots)
22\S3method{edit}{vignette}(name, \dots)
23%% \S3method{getRcode}{vignette}(x, strict=TRUE, \dots)
24}
25\arguments{
26  \item{topic}{a character string giving the (base) name of the vignette
27    to view.  If omitted, all vignettes from all installed packages are
28    listed.}
29  \item{package}{a character vector with the names of packages to
30    search through, or \code{NULL} in which \sQuote{all} packages (as
31    defined by argument \code{all}) are searched.}
32  \item{lib.loc}{a character vector of directory names of \R libraries,
33    or \code{NULL}.  The default value of \code{NULL} corresponds to all
34    libraries currently known.}
35  \item{all}{logical; if \code{TRUE} search all available packages in
36    the library trees specified by \code{lib.loc}, and if \code{FALSE},
37    search only attached packages.}
38  \item{x, name}{object of class \code{vignette}.}
39  \item{\dots}{ignored by the \code{print} method, passed on to
40    \code{\link{file.edit}} by the \code{edit} method.}
41}
42\details{
43  Function \code{vignette} returns an object of the same class, the
44  print method opens a viewer for it.
45
46  On Unix-alikes,
47  The program specified by the \code{pdfviewer} option is used for
48  viewing PDF versions of vignettes.
49
50  If several vignettes have PDF/HTML versions with base name identical
51  to \code{topic}, the first one found is used.
52
53  If no topics are given, all available vignettes are listed.  The
54  corresponding information is returned in an object of class
55  \code{"packageIQR"}.
56
57  %% \code{getRcode(x)} gets the (full path) file name of the \R code
58  %% extracted from the vignette, and the \code{edit} method that  \R code
59  %% to a temporary file and opens the file in an editor (see
60  %% \code{\link{edit}}). This makes it very easy to execute the commands
61  %% line by line, modify them in any way you want to help you test
62  %% variants, etc.
63}
64\seealso{
65  \code{\link{browseVignettes}} for an HTML-based vignette browser;
66  \code{\link{RShowDoc}(<basename>, package = "<pkg>")} displays a
67  \dQuote{rendered} vignette (pdf or html).
68}
69\examples{
70## List vignettes from all *attached* packages
71vignette(all = FALSE)
72
73## List vignettes from all *installed* packages (can take a long time!):
74vignette(all = TRUE)
75
76## The grid intro vignette -- open it
77\dontrun{vignette("grid") # calling print()}
78## The same (conditional on existence of the vignettte).
79## Note that 'package = *' is much faster in the case of many installed packages:
80if(!is.null(v1 <- vignette("grid", package="grid"))) {
81\dontrun{v1 # calling print(.)}
82  str(v1)
83  ## Now let us have a closer look at the code
84  %% print(utils:::getRcode(v1)) # the R file name
85  %% if(interactive()) # "display" it
86  %%   file.show(utils:::getRcode(v1))
87  %% ## or even more interactively:
88\dontrun{edit(v1) # e.g., to send lines ...}
89}# if( has vignette "installed")
90## A package can have more than one vignette (package grid has several):
91vignette(package = "grid")
92if(interactive()) {
93   ## vignette("rotated")
94   ## The same, but without searching for it:
95   vignette("rotated", package = "grid")
96}
97}
98\keyword{documentation}
99