#+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]]
  - [[#layer][Layer]]
  - [[#auto-completion][Auto-completion]]
  - [[#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]]
- Auto-completion with [[https://github.com/alexeyr/company-auctex][company-auctex]]
- 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
** Layer
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.

** Auto-completion
Add the layer =auto-completion= to the variable
=dotspacemacs-configuration-layers= of your dotfile =~/.spacemacs=.

** 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 enable auto-fill set the variable =latex-enable-auto-fill= to =t=.

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 t))
#+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~     | run all commands (compile and open viewer) |
| ~SPC m b~     | build                                      |
| ~SPC m c~     | close LaTeX environment                    |
| ~SPC m 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 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~   | reftex-citation                       |
| ~SPC m r g~   | reftex-grep-document                  |
| ~SPC m r i~   | reftex-index-selection-or-word        |
| ~SPC m r I~   | reftex-display-index                  |
| ~SPC m r TAB~ | reftex-index                          |
| ~SPC m r l~   | reftex-label                          |
| ~SPC m r p~   | reftex-index-phrase-selection-or-word |
| ~SPC m r P~   | reftex-index-visit-phrases-buffer     |
| ~SPC m r r~   | reftex-reference                      |
| ~SPC m r s~   | reftex-search-document                |
| ~SPC m r t~   | reftex-toc                            |
| ~SPC m r T~   | reftex-toc-recenter                   |
| ~SPC m r v~   | reftex-view-crossref                  |