spacemacs/layers/+lang/latex/README.org

#+TITLE: LaTeX layer

#+TAGS: dsl|layer|markup|programming

[[file:img/latex.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#bibtex][BibTeX]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#variables][Variables]]
  - [[#choosing-a-backend][Choosing a backend]]
    - [[#lsp][LSP]]
    - [[#company-auctex][Company-auctex]]
  - [[#previewing][Previewing]]
  - [[#build-command][Build command]]
  - [[#tex-engine][TeX Engine]]
  - [[#auto-fill][Auto-fill]]
  - [[#folding][Folding]]
  - [[#magic-latex-buffer][Magic latex buffer]]
- [[#key-bindings][Key bindings]]
  - [[#folding-1][Folding]]
  - [[#reftex][RefTeX]]

* Description
This layer adds support for LaTeX files with [[https://savannah.gnu.org/projects/auctex/][AucTeX]].

** Features:
- Auto-build with [[https://github.com/tom-tan/auctex-latexmk/][auctex-latexmk]]
- Syntax highlighting
- Auto-completion
- Tags navigation on ~%~ with [[https://github.com/redguardtoo/evil-matchit][evil-matchit]]
- Labels, references, citations and index entries management with [[http://www.gnu.org/software/emacs/manual/html_node/reftex/index.html][RefTeX]]

* BibTeX
For more extensive support of BibTeX files than RefTeX provides, have a look at
the [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Blang/bibtex/README.org][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.

** 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 [[#auto-fill][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              |

** 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
[[https://github.com/latex-lsp/texlab/releases][pre-compiled binaries]]. You also need to enable =LSP= layer in your
=~/.spacemacs=.

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-backend 'lsp)))
#+END_SRC

*** 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=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-backend 'company-auctex)))
#+END_SRC

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=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :packages (not company-math))))
#+END_SRC

** 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=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-refresh-preview t)))
#+END_SRC

=TexLab= also supports more sophisticated previewing setup, which is documented
[[https://texlab.netlify.app/docs/installation/previewing][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.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-build-command "LaTeX")))
#+END_SRC

** 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-alise=. 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:

#+BEGIN_SRC tex
  %%% Local Variables:
  %%% TeX-engine: 'xetex
  %%% End:
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-build-engine 'xetex)))
#+END_SRC

More information on TeX engine and languages support can be found in =auctex=
[[https://www.gnu.org/software/auctex/manual/auctex/Internationalization.html#Internationalization][manual page]].

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-enable-auto-fill nil)))
#+END_SRC

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.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-enable-folding t)))
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((latex :variables latex-enable-magic t)))
#+END_SRC

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 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                  |