| % File src/library/utils/man/vignette.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2016 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{vignette} |
| \title{View, List or Get R Source of Package Vignettes} |
| \alias{vignette} |
| \alias{edit.vignette} |
| \alias{print.vignette} |
| \alias{vignettes} % to link to from e.g. grid-package.Rd |
| %% \alias{getRcode} |
| %% \alias{getRcode.vignette}%hidden |
| \description{ |
| View a specified package vignette, or list the available ones; |
| display it rendered in a viewer, and get or edit its \R source file. |
| } |
| \usage{ |
| vignette(topic, package = NULL, lib.loc = NULL, all = TRUE) |
| |
| \S3method{print}{vignette}(x, \dots) |
| \S3method{edit}{vignette}(name, \dots) |
| %% \S3method{getRcode}{vignette}(x, strict=TRUE, \dots) |
| } |
| \arguments{ |
| \item{topic}{a character string giving the (base) name of the vignette |
| to view. If omitted, all vignettes from all installed packages are |
| listed.} |
| \item{package}{a character vector with the names of packages to |
| search through, or \code{NULL} in which \sQuote{all} packages (as |
| defined by argument \code{all}) are searched.} |
| \item{lib.loc}{a character vector of directory names of \R libraries, |
| or \code{NULL}. The default value of \code{NULL} corresponds to all |
| libraries currently known.} |
| \item{all}{logical; if \code{TRUE} search all available packages in |
| the library trees specified by \code{lib.loc}, and if \code{FALSE}, |
| search only attached packages.} |
| \item{x, name}{object of class \code{vignette}.} |
| \item{\dots}{ignored by the \code{print} method, passed on to |
| \code{\link{file.edit}} by the \code{edit} method.} |
| } |
| \details{ |
| Function \code{vignette} returns an object of the same class, the |
| print method opens a viewer for it. |
| |
| On Unix-alikes, |
| The program specified by the \code{pdfviewer} option is used for |
| viewing PDF versions of vignettes. |
| |
| If several vignettes have PDF/HTML versions with base name identical |
| to \code{topic}, the first one found is used. |
| |
| If no topics are given, all available vignettes are listed. The |
| corresponding information is returned in an object of class |
| \code{"packageIQR"}. |
| |
| %% \code{getRcode(x)} gets the (full path) file name of the \R code |
| %% extracted from the vignette, and the \code{edit} method that \R code |
| %% to a temporary file and opens the file in an editor (see |
| %% \code{\link{edit}}). This makes it very easy to execute the commands |
| %% line by line, modify them in any way you want to help you test |
| %% variants, etc. |
| } |
| \seealso{ |
| \code{\link{browseVignettes}} for an HTML-based vignette browser; |
| \code{\link{RShowDoc}(<basename>, package = "<pkg>")} displays a |
| \dQuote{rendered} vignette (pdf or html). |
| } |
| \examples{ |
| ## List vignettes from all *attached* packages |
| vignette(all = FALSE) |
| |
| ## List vignettes from all *installed* packages (can take a long time!): |
| vignette(all = TRUE) |
| |
| ## The grid intro vignette -- open it |
| \dontrun{vignette("grid") # calling print()} |
| ## The same (conditional on existence of the vignettte). |
| ## Note that 'package = *' is much faster in the case of many installed packages: |
| if(!is.null(v1 <- vignette("grid", package="grid"))) { |
| \dontrun{v1 # calling print(.)} |
| str(v1) |
| ## Now let us have a closer look at the code |
| %% print(utils:::getRcode(v1)) # the R file name |
| %% if(interactive()) # "display" it |
| %% file.show(utils:::getRcode(v1)) |
| %% ## or even more interactively: |
| \dontrun{edit(v1) # e.g., to send lines ...} |
| }# if( has vignette "installed") |
| ## A package can have more than one vignette (package grid has several): |
| vignette(package = "grid") |
| if(interactive()) { |
| ## vignette("rotated") |
| ## The same, but without searching for it: |
| vignette("rotated", package = "grid") |
| } |
| } |
| \keyword{documentation} |