src/library/tools/man/texi2dvi.Rd

% File src/library/tools/man/texi2dvi.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{texi2dvi}
\alias{texi2dvi}
\alias{texi2pdf}
\title{Compile LaTeX Files}
\description{
  Run \code{latex}/\code{pdflatex}, \code{makeindex} and \code{bibtex}
  until all cross-references are resolved to create a dvi or a PDF file.
}
\usage{
texi2dvi(file, pdf = FALSE, clean = FALSE, quiet = TRUE,
         texi2dvi = getOption("texi2dvi"),
         texinputs = NULL, index = TRUE)

texi2pdf(file, clean = FALSE, quiet = TRUE,
         texi2dvi = getOption("texi2dvi"),
         texinputs = NULL, index = TRUE)
}
\arguments{
  \item{file}{character string.  Name of the LaTeX source file.}
  \item{pdf}{logical.  If \code{TRUE}, a PDF file is produced instead of
    the default dvi file (\code{texi2dvi} command line option \option{--pdf}).}
  \item{clean}{logical.  If \code{TRUE}, all auxiliary files created
    during the conversion are removed.}
  \item{quiet}{logical.  No output unless an error occurs.}
  \item{texi2dvi}{character string (or \code{NULL}).  Script or program
    used to compile a TeX file to dvi or PDF. The default (selected
    by \code{""} or \code{"texi2dvi"} or \code{NULL}) is to look
    for a program or script named \file{texi2dvi} on the path and
    otherwise emulate the script with \code{system2} calls (which
    can be selected by the value \code{"emulation"}).  See also
    \sQuote{Details}.} 
  \item{texinputs}{\code{NULL} or a character vector of paths to add to
    the LaTeX and bibtex input search paths.}
  \item{index}{logical: should indices be prepared?}
}
\details{
  \code{texi2pdf} is a wrapper for the common case of
  \code{texi2dvi(pdf = TRUE)}.

  Despite the name, this is used in \R to compile LaTeX files,
  specifically those generated from vignettes and by the
  \code{\link{Rd2pdf}} script (used for package reference manuals).  It
  ensures that the \file{\var{\link{R_HOME}}/share/texmf} directory is
  in the \env{TEXINPUTS} path, so \R style files such as \file{Sweave}
  and \file{Rd} will be found.  The TeX search path used is first the
  existing \env{TEXINPUTS} setting (or the current directory if unset),
  then elements of argument \code{texinputs}, then
  \file{\var{R_HOME}/share/texmf} and finally the default path.
  Analogous changes are made to \env{BIBINPUTS} and \env{BSTINPUTS}
  settings.

#ifdef unix
  The default option for \code{texi2dvi} is set from environment variable
  \env{R_TEXI2DVICMD}, and the default for that is set from environment
  variable \env{TEXI2DVI} or if that is unset, from a value chosen when
  \R is configured.
  
  %% issues included not re-running latex in texinfo 6.1 and bashisms in
  %% the /bin/sh script in <= 6.0.
  A shell script \command{texi2dvi} is part of GNU's \pkg{texinfo}.
  Several issues have been seen with released versions, so if yours does
  not work correctly try \env{R_TEXI2DVICMD=emulation}.
#endif

#ifdef windows
  On Windows the option \code{"texi2dvi"} is normally unset.  The MiKTeX
  command \command{texify.exe} is a suitable choice for \code{texi2dvi},
  and is tried as from \R 3.2.3 if the argument is blank or \code{NULL}
  and a program or script \code{texi2dvi} is not found.

  MiKTeX had a \code{texi2dvi} executable until Sept 2015, but no other
  Windows TeX installation that we know of does, so emulation is used on
  e.g.\sspace{}TeXLive installations on Windows.
#endif

  Occasionally indices contain special characters which cause indexing
  to fail (particularly when using the \samp{hyperref} LaTeX package)
  even on valid input.  The argument \code{index = FALSE} is provided to
  allow package manuals to be made when this happens: it uses emulation.
}

\note{
  %% configure just looks for a texi2dvi command and does not check its
  %% version.  Howvever, it is normally distributed with texinfo, and
  %% that is checked to be >= 5.1.
  %% The macOS distribution by default installs /usr/local/bin/texi2dvi,
  %% but that is optional and macOS has /usr/bin/texi2dvi stuck at 4.8.
  There are various versions of the \command{texi2dvi} script on
  Unix-alikes and quite a number of bugs have been seen, some of which
  this \R wrapper works around.

  One that was present with \command{texi2dvi} version \code{4.8} (as
  supplied by macOS) is that it will not work correctly for paths which
  contain spaces, nor if the absolute path to a file would contain
  spaces.

  The three possible approaches all have their quirks.  For example the
  Unix-alike \code{texi2dvi} script removes ancillary files that already
  exist but the other two approaches do not (and may get confused by
  such files).
  
  Where supported (\command{texi2dvi} 5.0 and later;
  \command{texify.exe} from MiKTeX), option \option{--max-iterations=20}
  is used to avoid infinite retries.
  
  The emulation mode supports \code{quiet = TRUE} from \R 3.2.3 only.
  Currently \code{clean = TRUE} only cleans up in this mode if the
  conversion was successful---this gives users a chance to examine log
  files in the event of error.
  
  All the approaches should respect the values of environment variables
  \env{LATEX}, \env{PDFLATEX}, \env{MAKEINDEX} and \env{BIBTEX} for the
  full paths to the corresponding commands.
}
\value{
  Invisible \code{NULL}.  Used for the side effect of creating a dvi or
  PDF file in the current working directory (and maybe other files,
  especially if \code{clean = FALSE}).
}
\author{
  Originally Achim Zeileis but largely rewritten by R-core.
}
\keyword{utilities}