1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/output.R
3\name{knit}
4\alias{knit}
5\alias{purl}
6\title{Knit a document}
7\usage{
8knit(
9  input,
10  output = NULL,
11  tangle = FALSE,
12  text = NULL,
13  quiet = FALSE,
14  envir = parent.frame(),
15  encoding = "UTF-8"
16)
17
18purl(..., documentation = 1L)
19}
20\arguments{
21\item{input}{Path to the input file.}
22
23\item{output}{Path to the output file for \code{knit()}. If \code{NULL}, this
24function will try to guess a default, which will be under the current
25working directory.}
26
27\item{tangle}{Boolean; whether to tangle the R code from the input file (like
28\code{utils::\link{Stangle}}).}
29
30\item{text}{A character vector. This is an alternative way to provide the
31input file.}
32
33\item{quiet}{Boolean; suppress the progress bar and messages?}
34
35\item{envir}{Environment in which code chunks are to be evaluated, for
36example, \code{\link{parent.frame}()}, \code{\link{new.env}()}, or
37\code{\link{globalenv}()}).}
38
39\item{encoding}{Encoding of the input file; always assumed to be UTF-8 (i.e.,
40this argument is effectively ignored).}
41
42\item{...}{arguments passed to \code{\link{knit}()} from \code{purl()}}
43
44\item{documentation}{An integer specifying the level of documentation to add to
45the tangled script. \code{0} means to output pure code, discarding all text chunks);
46\code{1} (the default) means to add the chunk headers to the code; \code{2} means to
47add all text chunks to code as roxygen comments.}
48}
49\value{
50The compiled document is written into the output file, and the path
51  of the output file is returned. If the \code{text} argument is not
52  \code{NULL}, the compiled output is returned as a character vector. In
53  other words, if you provide a file input, you get an output filename; if
54  you provide a character vector input, you get a character vector output.
55}
56\description{
57This function takes an input file, extracts the R code in it according to a
58list of patterns, evaluates the code and writes the output in another file.
59It can also tangle R source code from the input document (\code{purl()} is a
60wrapper to \code{knit(..., tangle = TRUE)}). The \code{knitr.purl.inline}
61option can be used to also tangle the code of inline expressions (disabled by
62default).
63}
64\details{
65For most of the time, it is not necessary to set any options outside the
66input document; in other words, a single call like
67\code{knit('my_input.Rnw')} is usually enough. This function will try to
68determine many internal settings automatically. For the sake of
69reproducibility, it is better practice to include the options inside the
70input document (to be self-contained), instead of setting them before
71knitting the document.
72
73First the filename of the output document is determined in this way:
74\file{foo.Rnw} generates \file{foo.tex}, and other filename extensions like
75\file{.Rtex}, \file{.Rhtml} (\file{.Rhtm}) and \file{.Rmd}
76(\file{.Rmarkdown}) will generate \file{.tex}, \file{.html} and \file{.md}
77respectively. For other types of files, if the filename contains
78\samp{_knit_}, this part will be removed in the output file, e.g.,
79\file{foo_knit_.html} creates the output \file{foo.html}; if \samp{_knit_} is
80not found in the filename, \file{foo.ext} will produce \file{foo.txt} if
81\code{ext} is not \code{txt}, otherwise the output is \file{foo-out.txt}. If
82\code{tangle = TRUE}, \file{foo.ext} generates an R script \file{foo.R}.
83
84We need a set of syntax to identify special markups for R code chunks and R
85options, etc. The syntax is defined in a pattern list. All built-in pattern
86lists can be found in \code{all_patterns} (call it \code{apat}). First
87\pkg{knitr} will try to decide the pattern list based on the filename
88extension of the input document, e.g. \samp{Rnw} files use the list
89\code{apat$rnw}, \samp{tex} uses the list \code{apat$tex}, \samp{brew} uses
90\code{apat$brew} and HTML files use \code{apat$html}; for unkown extensions,
91the content of the input document is matched against all pattern lists to
92automatically determine which pattern list is being used. You can also
93manually set the pattern list using the \code{\link{knit_patterns}} object or
94the \code{\link{pat_rnw}} series functions in advance and \pkg{knitr} will
95respect the setting.
96
97According to the output format (\code{opts_knit$get('out.format')}), a set of
98output hooks will be set to mark up results from R (see
99\code{\link{render_latex}}). The output format can be LaTeX, Sweave and HTML,
100etc. The output hooks decide how to mark up the results (you can customize
101the hooks).
102
103The name \code{knit} comes from its counterpart \samp{weave} (as in Sweave),
104and the name \code{purl} (as \samp{tangle} in Stangle) comes from a knitting
105method `knit one, purl one'.
106
107If the input document has child documents, they will also be compiled
108recursively. See \code{\link{knit_child}}.
109
110See the package website and manuals in the references to know more about
111\pkg{knitr}, including the full documentation of chunk options and demos,
112etc.
113}
114\note{
115The working directory when evaluating R code chunks is the directory of
116  the input document by default, so if the R code involves external files
117  (like \code{read.table()}), it is better to put these files under the same
118  directory of the input document so that we can use relative paths. However,
119  it is possible to change this directory with the package option
120  \code{\link{opts_knit}$set(root.dir = ...)} so all paths in code chunks are
121  relative to this \code{root.dir}. It is not recommended to change the
122  working directory via \code{\link{setwd}()} in a code chunk, because it may
123  lead to terrible consequences (e.g. figure and cache files may be written
124  to wrong places). If you do use \code{setwd()}, please note that
125  \pkg{knitr} will always restore the working directory to the original one.
126  Whenever you feel confused, print \code{getwd()} in a code chunk to see
127  what the working directory really is.
128
129  If the \code{output} argument is a file path, it is strongly recommended to
130  be in the current working directory (e.g. \file{foo.tex} instead of
131  \file{somewhere/foo.tex}), especially when the output has external
132  dependencies such as figure files. If you want to write the output to a
133  different directory, it is recommended to set the working directory to that
134  directory before you knit a document. For example, if the source document
135  is \file{foo.Rmd} and the expected output is \file{out/foo.md}, you can
136  write \code{setwd('out/'); knit('../foo.Rmd')} instead of
137  \code{knit('foo.Rmd', 'out/foo.md')}.
138
139  N.B. There is no guarantee that the R script generated by \code{purl()} can
140  reproduce the computation done in \code{knit()}. The \code{knit()} process
141  can be fairly complicated (special values for chunk options, custom chunk
142  hooks, computing engines besides R, and the \code{envir} argument, etc). If
143  you want to reproduce the computation in a report generated by
144  \code{knit()}, be sure to use \code{knit()}, instead of merely executing
145  the R script generated by \code{purl()}. This seems to be obvious, but some
146  people
147  \href{https://stat.ethz.ch/pipermail/r-devel/2014-May/069113.html}{do not
148  get it}.
149}
150\examples{
151library(knitr)
152(f = system.file("examples", "knitr-minimal.Rnw", package = "knitr"))
153knit(f)  # compile to tex
154
155purl(f)  # tangle R code
156purl(f, documentation = 0)  # extract R code only
157purl(f, documentation = 2)  # also include documentation
158
159unlink(c("knitr-minimal.tex", "knitr-minimal.R", "figure"), recursive = TRUE)
160}
161\references{
162Package homepage: \url{https://yihui.org/knitr/}. The \pkg{knitr}
163  \href{https://yihui.org/knitr/demo/manual/}{main manual}: and
164  \href{https://yihui.org/knitr/demo/graphics/}{graphics manual}.
165
166  See \code{citation('knitr')} for the citation information.
167}
168