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]]
  - [[#choosing-a-backend][Choosing a backend]]
    - [[#company-auctex][Company-auctex]]
    - [[#lsp][LSP]]
  - [[#previewing][Previewing]]
  - [[#build-command][Build command]]
  - [[#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.

** Choosing a backend
This layer provides two alternative backends to choose from.

*** Company-auctex
This is the default choice if nothing is set and no lsp layer
is loaded in your dotfile. This mode only provides very
limited IDE capabilities. Used best for smaller documents.
To set explicitly set the following in your
dotfile:

#+BEGIN_SRC emacs-lisp
  (latex :variables latex-backend 'company-auctex)
#+END_SRC

*** LSP
For proper IDE support this backend should be used. It is
based on an external server which will be started automatically
by emacs, once a latex file is opened. The key bindings are
the same for all lsp modes so if you are already familiar with
one you should be able to work the same in all modes.

To set explicitly do the following in your dotfile:

#+BEGIN_SRC emacs-lisp
  (latex :variables
  	 latex-backend 'lsp)
#+END_SRC

For this to work you will also need to obtain
the latest version of the lsp server from [[https://github.com/latex-lsp/texlab][here]]
and put it into your =PATH=.

NOTE: Key bindings for LSP are defined in the
LSP layer. Also it is advisable to have a look
at the autocomplete layer for an optimal
intellisense config for LSP.

** Previewing
To perform full-document previews (that is, aside from the inline previewing
under ~SPC m p~), add the following to your =.spacemacs= under
=dotspacemacs/user-config=:

#+BEGIN_SRC emacs-lisp
  (add-hook 'doc-view-mode-hook 'auto-revert-mode)
#+END_SRC

Then when you open up a compiled PDF, the preview will update automatically when
you recompile.

** Build command
A build command can be specified via the layer variable =latex-build-command=.

If =LatexMk= is specified, the appropriate =LatexMk= configuration will be
applied. (the default on systems with =latexmk= in the path) This variable can
be set to any of the entities in =TeX-command-list=, including any custom
entries you may have added there. To use the regular =AucTeX= command set
=latex-build-command= to =LaTeX= as shown below.

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

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

The variable =latex-nofill-env= provide the list of environment names where
=auto-fill-mode= will be inhibited.

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

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

#+BEGIN_SRC emacs-lisp
  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
  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                  |