# thomasjo/atom-latex

Compile LaTeX or knitr documents from within Atom
JavaScript Shell Perl CSS
Latest commit bd601d2 Apr 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Apr 9, 2019
keymaps Oct 3, 2016
lib Dec 5, 2018
resources Oct 25, 2016
script Mar 28, 2018
spec Mar 29, 2018
styles Jun 13, 2017
.appveyor.yml Mar 21, 2017
.gitattributes Oct 25, 2016
.gitignore Mar 6, 2014
.travis.yml Jun 24, 2017
CHANGELOG.md Apr 4, 2018
CONTRIBUTING.md Jul 8, 2016
package.json Dec 5, 2018

# LaTeX package

Compile LaTeX, knitr, literate Agda, literate Haskell, or Pweave documents from within Atom.

## Installing

Use the Atom package manager and search for "latex", or run `apm install latex` from the command line.

## Prerequisites

### TeX distribution

A reasonably up-to-date and working TeX distribution is required. The only officially supported distributions are TeX Live, and MiKTeX. Although, the latter is not as well tested and supported as TeX Live, hence using TeX Live is highly recommended.

You need to ensure that the package can find your TeX distribution's binaries; by default the package uses your `PATH` environment variable, as well as the following search paths on Linux and macOS

1. `/usr/texbin`
2. `/Library/TeX/texbin`

and on Windows it uses

1. `%SystemDrive%\texlive\2017\bin\win32`
2. `%SystemDrive%\texlive\2016\bin\win32`
3. `%SystemDrive%\texlive\2015\bin\win32`
4. `%ProgramFiles%\MiKTeX 2.9\miktex\bin\x64`
5. `%ProgramFiles(x86)%\MiKTeX 2.9\miktex\bin`

If your TeX distribution's binaries are not installed in one of those locations or discoverable via the `PATH` environment variable, you will need to help the package find the binaries. This can be done by setting the TeX Path configuration option to point to the folder containing the binaries, either in the settings view, or directly in your `config.cson` file. See Configuration for further details regarding the settings of this package.

### Syntax Highlighting

In order for this package to behave as expected, your Atom environment must contain a package that provides a LaTeX grammar. We suggest language-latex, but other valid options might exist. Additional syntax packages may be required to build document types other than LaTeX. For more details see Builder Capabilities below.

### Builder Selection

The `latex` package provides access to two automatic builders for LaTeX and knitr documents. By default the package will use `latexmk` for LaTeX documents and an included builder to prepare knitr documents for `latexmk`. In this case an up to date installation of `latexmk` is required. If you're using TeX Live then you need only insure that `latexmk` is installed and up to date using the appropriate package manager. If you're using MikTeX then see how to use `latexmk` with MiKTeX.

The JavaScript based DiCy builder may also be used for all documents by selecting the `Use DiCy` option in the settings page. DiCy will be installed automatically and so no further action is required for either TeX Live or MiKTeX.

### Builder Capabilities

Document types other than LaTeX documents may be processed by this package. The availability and behavior of this feature depends upon the specific builder selected. The following table details the different types of documents that may be processed by each builder and any additional syntax package requirements.

Document Type latexmk based Builder DiCy Builder Required Language Packages
LaTeX Yes Yes language-latex
knitr Yes Yes language-r and language-knitr
literate Agda No preprocessing Yes language-agda
Pweave No Yes language-weave

## Usage

The `latex:build` command can be invoked from the LaTex menu or by pressing the default keybind ctrl-alt-b while in a LaTex or knitr file. Log messages and any other messages from the build may be seen in the LaTeX log panel accessible from the status bar.

The `latex` package supports other commands as detailed in the table below.

Command Keybinding Use
`latex:build` ctrl-alt-b Build LaTeX/knitr file and open result.
`latex:rebuild` None Force a rebuild of LaTeX/knitr file.
`latex:clean` ctrl-alt-c Cleanup files after a build.
`latex:kill` None Terminate currently running build. Also available from status indicator.
`latex:sync` ctrl-alt-s Use SyncTeX forward if possible from the current cursor position.
`latex:sync-log` None Display and highlight log messages from the current cursor position.
`latex:check-runtime` None Check for the existence of `latexmk`, `Rscript` and PDF/PS/DVI viewers.

### Overriding Build Settings

Many of the build settings in the settings page of the `latex` package can be overridden on a per file basis. One way to override specific build settings is to use "magic" TeX comments in the form of `% !TEX <name> = <value>`. Another way is to use a YAML formatted file with the same name as your root LaTeX file, but with an extension of `.yaml`. The settings and values that can overridden via either method are listed in the table below. If multiple setting names are listed then the first is preferred and following names are available for compatibility. More details can found at Overridding Build Settings.

Name Value Use
`cleanPatterns` comma separated patterns, e.g. `**/*.blg, foo` Specify patterns to use for `latex:clean`
`enableSynctex` `yes`, `no`, `true` or `false` Override SyncTeX setting
`enableExtendedBuildMode` `yes`, `no`, `true` or `false` Override extended build mode setting
`enableShellEscape` `yes`, `no`, `true` or `false` Override shell escape setting
`engine` or `program` `pdflatex`, `lualatex`, etc. Override the LaTeX engine to use for build.
`moveResultToSourceDirectory` `yes`, `no`, `true` or `false` Override move result to source directory setting
`outputFormat` or `format` `dvi`, `ps` or `pdf` Override the output format
`jobNames`, `jobnames` or `jobname` comma separated names, e.g. `foo, bar` Control the number and names of build jobs. Only a single name can be used for `jobname`.
`outputDirectory` or `output_directory` directory path, e.g. `build` Specify the output directory that should be used.
`producer` `dvipdf`, `dvipdfmx`, `xdvipdfmx` or `ps2pdf` Override the PDF producer
`root` file path, e.g. `../file.tex` Specify the root file that should be built. Only available via "magic" TeX comments.

There are additional settings that may be configured for the DiCy builder that may not be accessible from this package's setting page, but can be set via a YAML options file or TeX magic comments. For more details please see Options and Configuration in the DiCy documentation.

### PDF/DVI/PS Viewers

The `latex` package currently supports Atril, Evince, Okular, pdf-view, Preview, Skim, Sumatra PDF, Windows shell open, xdg-open, Xreader and Zathura as PDF/DVI/PS viewers. This includes support for cursor synchronization via SyncTeX if possible. Specific features of each of the viewers is detailed at Supported Viewers.

## Development status

Please note that this package is in a beta state. It is stable, but lacks some important features.

Any and all help is greatly appreciated!

NOTE: `latexmk` does not support file paths containing special characters such as `~`. To partially circumvent this, add `useRelativePaths: true` to your config file like so

```# config.cson
"*":
latex:
useRelativePaths: true```

When set, this package will use a relative path in place of an absolute one. This will allow `latexmk` to compile projects stored in directories that contain special characters. Note that the project itself must not contain special characters in its directory or file names.

This feature has not been fully tested yet, and there are no guarantees it will work in all cases. Please raise an issue if you find a case where it fails.

You can’t perform that action at this time.