1
###########################################################################/**
2
# @RdocFunction buildVignette
3
#
4
# @title "Builds a vignette"
5
#
6
# \description{
7
#  @get "title" into a PDF or a HTML file.
8
# }
9
#
10
# @synopsis
11
#
12
# \arguments{
13
#   \item{file}{A character string specifying the vignette source file.}
14
#   \item{dir}{A character string specifying the working directory.}
15
#   \item{latex}{A logical specifying whether a TeX produced by weave
16
#     should be compiled by \link{texi2pdf} or not.}
17
#   \item{tangle}{A logical specifying whether tangle should be run or not.}
18
#   \item{quiet}{A logical specifying whether weave, \link{texi2pdf}, and
19
#     tangle should be run in quiet mode or not.}
20
#   \item{clean}{Remove all files generated by the build, even if there
21
#     were copies there before.}
22
#   \item{engine}{An optional @character string specifying the vignette
23
#     engine to use for building the vignette.  If not specified, it will
24
#     be inferred from the \code{\\VignetteEngine\{\}} markup in the
25
#     vignette.  If that is not specified, the \code{"utils::Sweave"}
26
#     engine will be used.}
27
#   \item{buildPkg}{An optional @character string specifying the vignette
28
#     package to use, if the vignette engine does not specify one.}
29
#   \item{...}{Additional arguments passed to weave and tangle.}
30
# }
31
#
32
# \value{
33
#   Returns the filename to the final vignette (PDF or HTML) product.
34
#   If \code{latex = FALSE}, it may be a TeX file.
35
# }
36
#
37
# @author "HB"
38
#
39
# \seealso{
40
#   Since R devel (to become 3.1.0) r63076 (2013-06-27), there is
41
#   \code{buildVignette()} in the \pkg{tools} package.
42
# }
43
#
44
# @keyword documentation
45
# @keyword file
46
# @keyword IO
47
# @keyword internal
48
#*/###########################################################################
49
buildVignette <- function(file, dir = ".", latex = TRUE, tangle = TRUE, quiet = TRUE, clean = TRUE, engine=NULL, buildPkg=NULL, ...) {
50 0
    if (getRversion() >= "3.1.0") {
51 0
      .Defunct(new="tools::buildVignette")
52
    }
53

54
    ### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
55
    ### BEGIN: Workaround until buildVignette() is in the 'tools' package.
56
    ### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
57 0
    .get_vignette_metadata <- import_tools(".get_vignette_metadata")
58 0
    vignette_is_tex <- import_tools("vignette_is_tex")
59 0
    find_vignette_product <- import_tools("find_vignette_product")
60
    
61
    ## vignetteEngine() is exported in tools (>= 3.0.0)
62 0
    if (getRversion() < "3.0.0") {
63 0
      vignetteEngine <- import_tools("vignetteEngine")
64
    }
65

66 0
    list.files <- function(..., no..=FALSE) {
67 0
      res <- base::list.files(...)
68 0
      if (no..) res <- setdiff(res, c(".", ".."))
69 0
      res
70
    }
71
    ### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
72
    ### END: Workaround until buildVignette() is in the 'tools' package.
73
    ### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
74

75 0
    if (!file_test("-f", file))
76 0
        stop("No such file: ", file)
77

78 0
    if (!file_test("-d", dir))
79 0
        stop("Cannot set working directory. No such directory: ", dir)
80

81 0
    if (is.null(engine)) {
82
      # Infer vignette engine from vignette content
83 0
      lines <- readLines(file, warn=FALSE)
84 0
      engine <- .get_vignette_metadata(lines, "Engine")
85 0
      if (length(engine) == 0L)
86 0
          engine <- "utils::Sweave"
87
    }
88

89
    # Is vignette builder package specified in engine name?
90 0
    parts <- strsplit(engine, split="::", fixed=TRUE)[[1L]]
91 0
    if (length(parts) == 2L)
92 0
        buildPkg <- c(parts[1L], buildPkg)
93

94
    # Load vignette builder package(s), iff specified
95
    # HB: Should this be done by vignetteEngine()?
96 0
    if (length(buildPkg) > 0L)
97 0
        for (pkg in buildPkg)
98 0
            loadNamespace(pkg)
99

100
    # Get the vignette engine
101 0
    engine <- vignetteEngine(engine, package=buildPkg)
102

103
    # Infer the vignette name
104 0
    names <- sapply(engine$pattern, FUN = sub, "", file)
105 0
    name <- basename(names[(names != file)][1L])
106

107
    # A non-matching filename?
108 0
    if (is.na(name))
109 0
        stop("The vignette filename ", sQuote(file), " does not match any of the ", sQuote(paste(engine$package, engine$name, sep="::")), " engine's filename patterns (", paste(sQuote(engine$pattern), collapse=", "), ")")
110

111
    # Set working directory temporarily
112 0
    if (dir != ".") {
113 0
      file <- file_path_as_absolute(file)
114 0
      wd <- getwd()
115 0
      if (is.null(wd))
116 0
          stop("current working directory cannot be ascertained")
117 0
      setwd(dir)
118 0
      on.exit({
119 0
          setwd(wd)
120
      })
121
    }
122

123
    # Record existing files
124 0
    origfiles <- list.files(all.files = TRUE)
125 0
    if (clean) {
126 0
        file.create(".build.timestamp")
127
    }
128

129
    # Sweave
130 0
    engine$weave(file, quiet = quiet, ...)
131 0
    setwd(dir)  # In case weave/vignette changed it
132 0
    output <- find_vignette_product(name, by = "weave", engine = engine)
133

134
    # Compile TeX to PDF?
135 0
    if(latex && vignette_is_tex(output)) {
136 0
        texi2pdf(file = output, clean = FALSE, quiet = quiet)
137 0
        final <- find_vignette_product(name, by = "texi2pdf", engine = engine)
138
    } else
139 0
        final <- output
140

141
    # Tangle
142 0
    if (tangle) {
143 0
        engine$tangle(file, quiet = quiet, ...)
144 0
        setwd(dir)  # In case tangle changed it
145 0
        sources <- find_vignette_product(name, by = "tangle", main = FALSE, engine = engine)
146
    } else
147 0
        sources <- NULL
148

149
    # Cleanup
150
    # NOTE: TeX file is useful for visually impared, cf. JR. Godfrey,
151
    #       'Statistical Software from a Blind Person's Perspective',
152
    #       The R Journal, 2013 (to appear).
153 0
    keep <- c(output, sources, final)[-1L]
154 0
    if (clean) {
155 0
        f <- setdiff(list.files(all.files = TRUE, no.. = TRUE), keep)
156 0
        newer <- file_test("-nt", f, ".build.timestamp")
157
        ## some packages create directories
158 0
        unlink(f[newer], recursive = TRUE)
159
    }
160 0
    f <- setdiff(list.files(all.files = TRUE, no.. = TRUE), c(keep, origfiles))
161 0
    f <- f[file_test("-f", f)]
162 0
    file.remove(f)
163

164 0
    final
165
} # buildVignette()

Read our documentation on viewing source code .

Loading