Customizing LaTeX Options in the RStudio IDE

Avatar
Posit Support
Follow

Customizing LaTeX Options

Overview

The Compile PDF command in the RStudio IDE typesets the current TeX or Rnw source file into a PDF. There are a number of options you can specify to control this process, the most important of which is which LaTeX program you want to use for typesetting.

The RStudio IDE is compatible with both the pdfLaTeX and XeLaTeX typesetting engines. You can also specify a custom LaTeX program by setting the RSTUDIO_PDFLATEX environment variable (see below for more details).

The default LaTeX program is pdfLaTeX and you won't normally need to change this unless you require specific features or capabilities offered by XeLaTeX.

Setting Global Defaults

You can set the global default program for LaTeX typesetting from within the Authoring section of the Options dialog. Setting this option has the following effects:

  1. It determines the program used for LaTeX typesetting when you are not within a project.
  2. It is used to initialize the program used for LaTeX typesetting for newly created projects.

Note that changing the global default will not change the default for previously created projects. The section below includes information on setting per-project defaults.

Setting Project Defaults

RStudio projects have an option to indicate which program should be used for LaTeX typesetting when they are active. This option is initialized based on the global default and can be changed using the Authoring section of the Project Options dialog:

If you have a project containing TeX or Rnw files that need to be typeset using more than one method the following section describes how to set the typesetting program on a per-file basis

Setting the LaTeX Program for a File

You can also specify the program to be used for LaTeX typesetting on per-file basis. You may want to do this either to override the global or project-level default, or if you want to share the file and ensure that the correct typesetting program is used on other systems.

To specify the LaTeX typesetting for a file, you add a specially formatted TeX comment at the beginning of your file. For example, to specify that you want the current file processing using XeLaTeX, you would use the following code

% !TeX program = XeLaTeX

To specify pdfLaTeX you would use:

% !TeX program = pdfLaTeX

Note that these directives are based on the syntax used by TeXworks for the same purpose, so if you edit files in both RStudio and TeXworks they will both respect the specified program. For compatibility with TeXShop RStudio also respects the use of 'TS-program' (rather than 'program') as a keyword, for example: !TeX TS-program = XeLaTeX.

Specifying a Custom LaTeX Program

If you want to specify a custom LaTeX program you can do so by setting the RSTUDIO_PDFLATEX environment variable. Note that this will override any current global or per-project LaTeX program options, however will not override a per-file setting.

If you specify a custom LaTeX program please note the following:

  • The environment variable must be set before you try to weave the document.
  • RStudio will pass the -file-line-error (or -c-style-errors for MikTeX) option to indicate that it wants errors formatted with C style file and line information.
  • RStudio will pass the -synctec=-1 option to indicate that it wants a synctec file created (to enable direct navigation between the editor and PDF preview).
  • RStudio will pass the -shell-escape (or -enable-write18 for MikTeX) option if shell escape commands are enabled (see below for details).
  • If the LaTeX program you specify is not known to work correctly when invoked from within texi2dvi, you may wish to disable the use of texi2dvi (see below for details).

Additional LaTeX Options

The following additional LaTeX options can also be configured from within the Authoring section of the Options dialog:

  • Clean auxiliary output after compile — Running the LaTeX program produces various intermediate files (e.g. 'target.out', 'target.aux'). Enabling this option causes these files to be automatically removed after the compile. Note that log files ('target.blg' and 'target.log') are also cleaned up, however they are preserved if errors occur during compilation.
  • Enable shell escape commands — Enable execution of shell commands using \write18 by passing the -shell-escape option to the LaTeX program. This option is disabled by default because allowing documents to execute embedded shell commands may pose a security risk.
  • Insert numbered sections and subsections — Specifies that sections and sub-sections inserted using the Format menu should include numbering (if this option is not enabled then sections will be inserted as \section*).
 

Related Topics

Comments