Title: | Helper Functions to Install and Maintain TeX Live, and Compile LaTeX Documents |
---|---|
Description: | Helper functions to install and maintain the 'LaTeX' distribution named 'TinyTeX' (<https://yihui.org/tinytex/>), a lightweight, cross-platform, portable, and easy-to-maintain version of 'TeX Live'. This package also contains helper functions to compile 'LaTeX' documents, and install missing 'LaTeX' packages automatically. |
Authors: | Yihui Xie [aut, cre, cph] , Posit Software, PBC [cph, fnd], Christophe Dervieux [ctb] , Devon Ryan [ctb] , Ethan Heinzen [ctb], Fernando Cagua [ctb] |
Maintainer: | Yihui Xie <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.53.3 |
Built: | 2024-10-09 17:15:17 UTC |
Source: | https://github.com/rstudio/tinytex |
If a package has been installed in TinyTeX or TeX Live, the command
tlmgr info PKG
should return PKG
where PKG
is the
package name.
check_installed(pkgs)
check_installed(pkgs)
pkgs |
A character vector of LaTeX package names. |
A logical vector indicating if packages specified in pkgs
are
installed.
This function only works with LaTeX distributions based on TeX Live, such as TinyTeX.
tinytex::check_installed('framed')
tinytex::check_installed('framed')
The function copy_tinytex()
copies the existing TinyTeX installation
to another directory (e.g., a portable device like a USB stick). The function
use_tinytex()
runs tlmgr path add
to add the copy of TinyTeX
in an existing folder to the PATH
variable of the current system, so
that you can use utilities such as tlmgr
and pdflatex
,
etc.
copy_tinytex( from = tinytex_root(), to = select_dir("Select Destination Directory"), move = FALSE ) use_tinytex(from = select_dir("Select TinyTeX Directory"))
copy_tinytex( from = tinytex_root(), to = select_dir("Select Destination Directory"), move = FALSE ) use_tinytex(from = select_dir("Select TinyTeX Directory"))
from |
The root directory of the TinyTeX installation. For
|
to |
The destination directory where you want to make a copy of TinyTeX.
Like |
move |
Whether to use the new copy and delete the original copy of TinyTeX after copying it. |
You can only copy TinyTeX and use it in the same system, e.g., the Windows version of TinyTeX only works on Windows.
The function install_tinytex()
downloads and installs TinyTeX, a
custom LaTeX distribution based on TeX Live. The function
uninstall_tinytex()
removes TinyTeX; reinstall_tinytex()
reinstalls TinyTeX as well as previously installed LaTeX packages by default;
tinytex_root()
returns the root directory of TinyTeX if found.
install_tinytex( force = FALSE, dir = "auto", version = "daily", bundle = "TinyTeX-1", repository = "auto", extra_packages = if (is_tinytex()) tl_pkgs(), add_path = TRUE ) uninstall_tinytex(force = FALSE, dir = tinytex_root()) reinstall_tinytex(packages = TRUE, dir = tinytex_root(), ...) tinytex_root(error = TRUE)
install_tinytex( force = FALSE, dir = "auto", version = "daily", bundle = "TinyTeX-1", repository = "auto", extra_packages = if (is_tinytex()) tl_pkgs(), add_path = TRUE ) uninstall_tinytex(force = FALSE, dir = tinytex_root()) reinstall_tinytex(packages = TRUE, dir = tinytex_root(), ...) tinytex_root(error = TRUE)
force |
Whether to force to install or uninstall TinyTeX. For
|
dir |
The directory to install (should not exist unless |
version |
The version of TinyTeX, e.g., |
bundle |
The bundle name of TinyTeX (which determines the collection of LaTeX packages to install). See https://github.com/rstudio/tinytex-releases#releases for all possible bundles and their meanings. |
repository |
The CTAN repository to set. By default, it is the
repository automatically chosen by |
extra_packages |
A character vector of extra LaTeX packages to be
installed. By default, a vector of all currently installed LaTeX packages
if an existing installation of TinyTeX is found. If you want a fresh
installation, you may use |
add_path |
Whether to run the command |
packages |
Whether to reinstall all currently installed packages. |
... |
Other arguments to be passed to |
error |
Whether to signal an error if TinyTeX is not found. |
If you really want to disable the installation, you may set the
environment variable TINYTEX_PREVENT_INSTALL to true
. Then
install_tinytex()
will fail immediately. This can be useful to
sysadmins who want to prevent the accidental installation of TinyTeX.
Installing TinyTeX requires perl (on Linux, perl-base is insufficient).
See the TinyTeX documentation (https://yihui.org/tinytex/) for the default installation directories on different platforms.
First find the root directory of the installation via
tinytex_root()
. Then check if the directory name is
"tinytex"
(case-insensitive). If not, further check if the first line
of the file ‘texmf-dist/web2c/fmtutil.cnf’ under the directory contains
"TinyTeX"
or ".TinyTeX"
. If the binary version of TinyTeX was
installed, ‘fmtutil.cnf’ should contain a line like ‘Generated by
*/TinyTeX/bin/x86_64-darwin/tlmgr on Thu Sep 17 07:13:28 2020’.
is_tinytex()
is_tinytex()
A logical value indicating if the LaTeX installation is TinyTeX.
tinytex::is_tinytex()
tinytex::is_tinytex()
The function latexmk()
emulates the system command latexmk
(https://ctan.org/pkg/latexmk) to compile a LaTeX document. The
functions pdflatex()
, xelatex()
, and lualatex()
are
wrappers of latexmk(engine =, emulation = TRUE)
.
latexmk( file, engine = c("pdflatex", "xelatex", "lualatex", "latex", "tectonic"), bib_engine = c("bibtex", "biber"), engine_args = NULL, emulation = TRUE, min_times = 1, max_times = 10, install_packages = emulation && tlmgr_writable(), pdf_file = gsub("tex$", "pdf", file), clean = TRUE ) pdflatex(...) xelatex(...) lualatex(...)
latexmk( file, engine = c("pdflatex", "xelatex", "lualatex", "latex", "tectonic"), bib_engine = c("bibtex", "biber"), engine_args = NULL, emulation = TRUE, min_times = 1, max_times = 10, install_packages = emulation && tlmgr_writable(), pdf_file = gsub("tex$", "pdf", file), clean = TRUE ) pdflatex(...) xelatex(...) lualatex(...)
file |
A LaTeX file path. |
engine |
A LaTeX engine (can be set in the global option
|
bib_engine |
A bibliography engine (can be set in the global option
|
engine_args |
Command-line arguments to be passed to |
emulation |
Whether to emulate the executable |
min_times , max_times
|
The minimum and maximum number of times to rerun
the LaTeX engine when using emulation. You can set the global options
|
install_packages |
Whether to automatically install missing LaTeX
packages found by |
pdf_file |
Path to the PDF output file. By default, it is under the same
directory as the input |
clean |
Whether to clean up auxiliary files after compilation (can be
set in the global option |
... |
Arguments to be passed to |
The latexmk
emulation works like this: run the LaTeX engine once
(e.g., pdflatex
), run makeindex
to make the index if
necessary (the ‘*.idx’ file exists), run the bibliography engine
bibtex
or biber
to make the bibliography if necessary
(the ‘*.aux’ or ‘*.bcf’ file exists), and finally run the LaTeX
engine a number of times (the maximum is 10 by default) to resolve all
cross-references.
By default, LaTeX warnings will be converted to R warnings. To suppress these
warnings, set options(tinytex.latexmk.warning = FALSE)
.
If emulation = FALSE
, you need to make sure the executable
latexmk
is available in your system, otherwise latexmk()
will fall back to emulation = TRUE
. You can set the global option
options(tinytex.latexmk.emulation = FALSE)
to always avoid emulation
(i.e., always use the executable latexmk
).
The default command to generate the index (if necessary) is
makeindex
. To change it to a different command (e.g.,
zhmakeindex
), you may set the global option
tinytex.makeindex
. To pass additional command-line arguments to the
command, you may set the global option tinytex.makeindex.args
(e.g.,
options(tinytex.makeindex = 'zhmakeindex', tinytex.makeindex.args =
c('-z', 'pinyin'))
).
If you are using the LaTeX distribution TinyTeX, but its path is not in the
PATH
variable of your operating system, you may set the global option
tinytex.tlmgr.path
to the full path of the executable tlmgr
,
so that latexmk()
knows where to find executables like
pdflatex
. For example, if you are using Windows and your TinyTeX is
on an external drive ‘Z:/’ under the folder ‘TinyTeX’, you may set
options(tinytex.tlmgr.path = "Z:/TinyTeX/bin/windows/tlmgr.bat")
.
Usually you should not need to set this option because TinyTeX can add itself
to the PATH
variable during installation or via
use_tinytex()
. In case both methods fail, you can use this
manual approach.
A character string of the path of the output file (i.e., the value of
the pdf_file
argument).
This is a helper function that combines parse_packages()
and
tlmgr_install()
.
parse_install(...)
parse_install(...)
... |
Arguments passed to |
Analyze the error messages in a LaTeX log file to figure out the names of
missing LaTeX packages that caused the errors. These packages can be
installed via tlmgr_install()
. Searching for missing packages
is based on tlmgr_search()
.
parse_packages( log, text = read_lines(log), files = detect_files(text), quiet = rep(FALSE, 3) )
parse_packages( log, text = read_lines(log), files = detect_files(text), quiet = rep(FALSE, 3) )
log |
Path to the LaTeX log file (typically named ‘*.log’). |
text |
A character vector of the error log (read from the file provided
by the |
files |
A character vector of names of the missing files (automatically
detected from the |
quiet |
Whether to suppress messages when finding packages. It should be
a logical vector of length 3: the first element indicates whether to
suppress the message when no missing LaTeX packages could be detected from
the log, the second element indicate whether to suppress the message when
searching for packages via |
A character vector of LaTeX package names.
R ships a custom texmf tree containing a few LaTeX style and class files,
which are required when compiling R packages manuals (‘Rd.sty’) or
Sweave documents (‘Sweave.sty’). This tree can be found under the
directory file.path(R.home('share'), 'texmf')
. This function can be
used to add/remove R's texmf tree to/from TeX Live via
tlmgr_conf('auxtrees')
.
r_texmf(action = c("add", "remove"), ...)
r_texmf(action = c("add", "remove"), ...)
action |
Add/remove R's texmf tree to/from TeX Live. |
... |
Arguments passed to |
See the tlmgr manual for detailed information about
tlmgr conf auxtrees
. Check out
https://tex.stackexchange.com/q/77720/9128 if you don't know what
texmf
means.
# running the code below will modify your texmf tree; please do not run # unless you know what it means # r_texmf('remove') # r_texmf('add') # all files under R's texmf tree list.files(file.path(R.home('share'), 'texmf'), recursive = TRUE, full.names = TRUE)
# running the code below will modify your texmf tree; please do not run # unless you know what it means # r_texmf('remove') # r_texmf('add') # all files under R's texmf tree list.files(file.path(R.home('share'), 'texmf'), recursive = TRUE, full.names = TRUE)
Calls tlmgr info --list --data name
to obtain the names of all
(installed) TeX Live packages. Platform-specific strings in package names are
removed, e.g., "tex"
is returned for the package
tex.x86_64-darwin.
tl_pkgs(only_installed = TRUE)
tl_pkgs(only_installed = TRUE)
only_installed |
Whether to list installed packages only. |
A character vector of package names.
Use the command tlmgr info --list
to obtain the sizes of LaTeX
packages.
tl_sizes(show_total = TRUE, pkgs = NULL, only_installed = TRUE, field = "size")
tl_sizes(show_total = TRUE, pkgs = NULL, only_installed = TRUE, field = "size")
show_total |
Whether to show the total size. |
pkgs |
A character vector of package names (by default, all packages). |
only_installed |
Whether to list installed packages only. |
field |
A character vector of field names in the package information. See https://www.tug.org/texlive/doc/tlmgr.html#info for more info. |
By default, a data frame of three columns: package
is the
package names, size
is the sizes in bytes, and size_h
is the
human-readable version of sizes. If different field names are provided in
the field
argument, the returned data frame will contain these
columns.
Execute the tlmgr
command to search for LaTeX packages, install
packages, update packages, and so on.
tlmgr(args = character(), usermode = FALSE, ..., .quiet = FALSE) tlmgr_search(what, file = TRUE, all = FALSE, global = TRUE, word = FALSE, ...) tlmgr_install( pkgs = character(), usermode = FALSE, path = !usermode && os != "windows", ... ) tlmgr_remove(pkgs = character(), usermode = FALSE) tlmgr_version(format = c("raw", "string", "list")) tlmgr_update( all = TRUE, self = TRUE, more_args = character(), usermode = FALSE, run_fmtutil = TRUE, delete_tlpdb = getOption("tinytex.delete_tlpdb", FALSE), ... ) tlmgr_path(action = c("add", "remove")) tlmgr_conf(more_args = character(), ...) tlmgr_repo(url = NULL, ...)
tlmgr(args = character(), usermode = FALSE, ..., .quiet = FALSE) tlmgr_search(what, file = TRUE, all = FALSE, global = TRUE, word = FALSE, ...) tlmgr_install( pkgs = character(), usermode = FALSE, path = !usermode && os != "windows", ... ) tlmgr_remove(pkgs = character(), usermode = FALSE) tlmgr_version(format = c("raw", "string", "list")) tlmgr_update( all = TRUE, self = TRUE, more_args = character(), usermode = FALSE, run_fmtutil = TRUE, delete_tlpdb = getOption("tinytex.delete_tlpdb", FALSE), ... ) tlmgr_path(action = c("add", "remove")) tlmgr_conf(more_args = character(), ...) tlmgr_repo(url = NULL, ...)
args |
A character vector of arguments to be passed to the command
|
usermode |
(For expert users only) Whether to use TeX Live's
user mode. If
|
... |
For |
.quiet |
Whether to hide the actual command before executing it. |
what |
A search keyword as a (Perl) regular expression. |
file |
Whether to treat |
all |
For |
global |
Whether to search the online TeX Live Database or locally. |
word |
Whether to restrict the search of package names and descriptions to match only full words. |
pkgs |
A character vector of LaTeX package names. |
path |
Whether to run |
format |
The data format to be returned: |
self |
Whether to update the TeX Live Manager itself. |
more_args |
A character vector of more arguments to be passed to the
command |
run_fmtutil |
Whether to run |
delete_tlpdb |
Whether to delete the ‘texlive.tlpdb.HASH’ files
(where |
action |
On Unix, add/remove symlinks of binaries to/from the system's
|
url |
The URL of the CTAN mirror. If |
The tlmgr()
function is a wrapper of system2('tlmgr')
. All
other tlmgr_*()
functions are based on tlmgr
for specific
tasks. For example, tlmgr_install()
runs the command tlmgr
install
to install LaTeX packages, and tlmgr_update
runs the command
tlmgr update
, etc. Note that tlmgr_repo
runs tlmgr
options repository
to query or set the CTAN repository. Please consult the
tlmgr manual for full details.
The tlmgr manual: https://www.tug.org/texlive/doc/tlmgr.html
# search for a package that contains titling.sty tlmgr_search('titling.sty') # to match titling.sty exactly, add a slash before the keyword, e.g. tlmgr_search('/titling.sty') # use a regular expression if you want to be more precise, e.g. tlmgr_search('/titling\\.sty$') # list all installed LaTeX packages tlmgr(c('info', '--list', '--only-installed', '--data', 'name'))
# search for a package that contains titling.sty tlmgr_search('titling.sty') # to match titling.sty exactly, add a slash before the keyword, e.g. tlmgr_search('/titling.sty') # use a regular expression if you want to be more precise, e.g. tlmgr_search('/titling\\.sty$') # list all installed LaTeX packages tlmgr(c('info', '--list', '--only-installed', '--data', 'name'))