spacemacs/layers/+lang/latex

LaTeX layer

• Description
  • Features:
• BibTeX
• Install
• Configuration
  • Variables
  • Choosing a backend
    • LSP
    • Company-auctex
  • PDF viewer
  • Previewing
  • Build command
  • TeX Engine
  • Auto-fill
  • Folding
  • Magic latex buffer
• Key bindings
  • Folding
  • RefTeX

Description

This layer adds support for LaTeX files with AucTeX.

Features:

• Auto-build with auctex-latexmk
• Syntax highlighting
• Auto-completion
• Tags navigation on % with evil-matchit
• Labels, references, citations and index entries management with RefTeX

BibTeX

For more extensive support of BibTeX files than RefTeX provides, have a look at the BibTeX layer.

Install

To use this configuration layer, add it to your ~/.spacemacs. You will need to add latex to the existing dotspacemacs-configuration-layers list in this file.

Configuration

Most layer configurations can be done by setting layer variables in your dotfile. Some however require adding lines to your user-config. If the pdf layer is used, then the layer automatically configures pdf-tools as the 'output-pdf' viewer, see #pdf-viewer.

Variables

A number of configuration variables have been exposed via the layer config.el. Sensible defaults have been provided, however they may all be overridden in your .spacemacs.

Variable Name	Default	Description
latex-backend	nil	Use LSP backend, unless it's `company-auctex` or LSP layer isn't enabled
latex-build-command	'latexmk if it's found	Default command to use with SPC m b
latex-build-engine	'xetex if it's found and chinese / japanese layer is enabled	Default TeX engine to use with SPC m b
latex-enable-auto-fill	t	When non-nil, enable auto-fill-mode
latex-enable-folding	nil	When non-nil, enable TeX-fold-mode
latex-enable-magic	nil	When non-nil, enable magic symbols
latex-nofill-env	See details below	A list of LaTeX environment name where auto-fill-mode is disabled
latex-refresh-preview	nil	When non-nil, enable refresh preview buffer when file changes
latex-view-with-pdf-tools	t if pdf layer is installed, else nil	When non-nil, use pdf-tools for viewing output pdf files
latex-view-pdf-in-split-window	nil setting is neglected if latex-view-with-pdf-tools is nil	When non-nil, open pdf-tools in split window (when using TeX-view command)

Choosing a backend

This layer provides two alternative backends to choose from.

LSP

This is the default backend if LSP layer is enabled. It provides proper IDE support and is recommended over company-auctex.

Currently, the LaTeX LSP backend depends on TexLab. You may built it from source, install it in your package manager, or get the pre-compiled binaries. You also need to enable LSP layer in your ~/.spacemacs.

To explicitly choose LSP backend for LaTeX layer, add the following:

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-backend 'lsp)))

Company-auctex

This would be the backend if LSP layer is not enabled, and latex-backend is not set.

This mode only provides very limited IDE capabilities and only recommended best for infrequent LaTeX editing needs.

To explicitly choose company-auctex as the backend, set the following in your ~/.spacemacs:

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-backend 'company-auctex)))

When company-auctex is chosen as the backend, it uses company-math for the completion of math symbols. company-math displays a unicode representation of symbols proposed for completion. It is supposed to have a better coverage of latex symbols than the default counter-part in company-auctex. If you prefer to use company-auctex for math symbols completion set the following in your ~/.spacemacs:

  (setq-default dotspacemacs-configuration-layers
                '((latex :packages (not company-math))))

PDF viewer

If the pdf layer is used, then the layer automatically configures pdf-tools as the 'output-pdf' viewer, see #pdf-viewer. To additionally make pdf-tools open in a split window, set the layer variable latex-view-pdf-in-split-window to t.

If, despite using the pdf layer, you prefer to use another pdf viewer to preview the output pdf's, set the layer variable latex-view-with-pdf-tools to nil.

Previewing

LaTex layer support full-document previews and inline preview (via SPC m p).

To update the preview buffer whenever the compiled PDF file changes, set latex-refresh-preview to t in your ~/.spacemacs:

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-refresh-preview t)))

TexLab also supports more sophisticated previewing setup, which is documented here.

Build command

A build command can be specified via the layer variable latex-build-command. This variable can be set to any of the entities in TeX-command-list, including any custom entries you may have added there.

If latexmk is found on your system PATH, LatexMk will be chosen as your latex-build-command, unless if it's not set.

To use the regular AucTeX command, set latex-build-command to LaTeX as shown below.

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-build-command "LaTeX")))

TeX Engine

auctex and auctex-latexmk have default rules to determine build command and build options according to the buffer-local variable TeX-engine.

It should be one of the symbol defined in TeX-engine-alist. The default valid symbols are:

• default
• luatex
• omega
• xetex

An appropriate TeX-engine is required for high-quality typesetting in certain languages. For convenience, xetex is chosen when it's found on PATH and when either chinese or japanese layer is enabled.

You can choose the engine on a per file basis, by setting file-local variable. For example, you can append these code to the end of a .tex file:

  %%% Local Variables:
  %%% TeX-engine: xetex
  %%% End:

Should you use AUCTeX's keystroke C-c C-c for compilation instead of Spacemacs' SPC m b, the minibuffer will still show LaTeX as compilation command, however xetex will be used on the background and no specific Xe(La)TeX command is needed. Likewise for the other engines.

If you predominantly work with one specific engine, you can set it as a layer variable.

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-build-engine 'xetex)))

More information on TeX engine and languages support can be found in auctex manual page.

Auto-fill

To disable auto-fill (which is on by default) set the variable latex-enable-auto-fill to nil.

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-enable-auto-fill nil)))

The variable latex-nofill-env provides the list of environment names where auto-fill-mode will be inhibited. By default it includes:

• "equation"
• "equation*"
• "align"
• "align*"
• "tabular"
• "tabular*"
• "tabu"
• "tabu*"
• "tikzpicture"

Folding

Enable folding of text by setting latex-enable-folding to t. Default value is nil.

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-enable-folding t)))

Magic latex buffer

To enable "magic" symbols in latex buffers, set the variable latex-enable-magic to t.

  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-enable-magic t)))

The precise effect of this feature can be modified by adjusting the following variables:

• magic-latex-enable-block-highlight: show font properties like \large (default t).
• magic-latex-enable-block-align: reflect block alignment such as \center (default nil).
• magic-latex-enable-pretty-symbols: substitute symbols in place of code, e.g. greek letters (default t).
• magic-latex-enable-suscript: show subscripts and superscripts (default t).
• magic-latex-enable-inline-image: show images inline (default nil).

By default, the underlying latex code is echoed in the echo area.

Key bindings

Key binding	Description
SPC m -	recenter output buffer
SPC m ,	TeX command on master file
SPC m .	mark LaTeX environment
SPC m *	mark LaTeX section
SPC m %	comment or uncomment a paragraph
SPC m ;	comment or uncomment a region
SPC m a or with LSP SPC m a u	run all commands (compile and open viewer)
SPC m b or with LSP SPC m c	build the document (compile)
SPC m c or with LSP SPC m i c	close LaTeX environment
SPC m i c or with LSP SPC m i C	insert cite key
SPC m e or with LSP SPC m i e	insert LaTeX environment
SPC m i i	insert \item
SPC m k	kill TeX job
SPC m l	recenter output buffer
SPC m m	insert LaTeX macro
SPC m n	goto next error
SPC m N	goto previous error
SPC m s	insert LaTeX section
SPC m v	view output
SPC m h d	TeX documentation, can be very slow
SPC m f e	fill LaTeX environment
SPC m f p	fill LaTeX paragraph
SPC m f r	fill LaTeX region
SPC m f s	fill LaTeX section
SPC m p r	preview region
SPC m p b	preview buffer
SPC m p d	preview document
SPC m p e	preview environment
SPC m p s	preview section
SPC m p p	preview at point
SPC m p f	cache preamble for preview
SPC m p c	clear previews
SPC m v	view
SPC m x b	make font bold
SPC m x B	make font medium weight
SPC m x c	make font monospaced (for code)
SPC m x e	make font emphasised
SPC m x i	make font italic
SPC m x o	make font oblique
SPC m x r	remove font properties
SPC m x f a	use calligraphic font
SPC m x f c	use small-caps font
SPC m x f f	use sans serif font
SPC m x f n	use normal font
SPC m x f r	use serif font
SPC m x f u	use upright font

Folding

Available only when latex-enable-folding is non nil.

Key binding	Description
SPC m z =	fold TeX math
SPC m z b	fold TeX buffer
SPC m z e	fold TeX environment
SPC m z m	fold TeX macro
SPC m z r	fold TeX region

RefTeX

Key binding	Description
SPC m r c or with LSP SPC m R c	reftex-citation
SPC m r g or with LSP SPC m R g	reftex-grep-document
SPC m r i or with LSP SPC m R i	reftex-index-selection-or-word
SPC m r I or with LSP SPC m R I	reftex-display-index
SPC m r TAB or with LSP SPC m R TAB	reftex-index
SPC m r l or with LSP SPC m R l	reftex-label
SPC m r p or with LSP SPC m R p	reftex-index-phrase-selection-or-word
SPC m r P or with LSP SPC m R P	reftex-index-visit-phrases-buffer
SPC m r r or with LSP SPC m R r	reftex-reference
SPC m r s or with LSP SPC m R s	reftex-search-document
SPC m r t or with LSP SPC m R t	reftex-toc
SPC m r T or with LSP SPC m R T	reftex-toc-recenter
SPC m r v or with LSP SPC m R v	reftex-view-crossref