2015-12-02 14:23:39 +00:00
#+TITLE : LaTeX layer
2015-06-10 16:44:30 +00:00
2019-05-07 08:21:07 +00:00
#+TAGS : dsl|layer|markup|programming
2019-05-05 17:26:40 +00:00
2015-06-10 16:44:30 +00:00
[[file:img/latex.png ]]
2019-05-07 20:05:06 +00:00
* Table of Contents :TOC_5_gh:noexport:
2017-05-22 14:16:12 +00:00
- [[#description ][Description ]]
2017-08-06 02:14:10 +00:00
- [[#features ][Features: ]]
2019-04-21 20:04:25 +00:00
- [[#bibtex ][BibTeX ]]
2017-05-22 14:16:12 +00:00
- [[#install ][Install ]]
2020-10-27 21:48:22 +00:00
- [[#configuration ][Configuration ]]
2020-12-13 09:33:04 +00:00
- [[#variables ][Variables ]]
2020-10-27 21:48:22 +00:00
- [[#choosing-a-backend ][Choosing a backend ]]
- [[#lsp ][LSP ]]
2020-12-13 09:33:04 +00:00
- [[#company-auctex ][Company-auctex ]]
2021-08-31 20:55:56 +00:00
- [[#pdf-viewer ][PDF viewer ]]
2017-05-22 14:16:12 +00:00
- [[#previewing ][Previewing ]]
- [[#build-command ][Build command ]]
2020-12-13 09:33:04 +00:00
- [[#tex-engine ][TeX Engine ]]
2017-05-22 14:16:12 +00:00
- [[#auto-fill ][Auto-fill ]]
- [[#folding ][Folding ]]
2015-12-11 22:14:56 +00:00
- [[#magic-latex-buffer ][Magic latex buffer ]]
2018-10-23 14:18:21 +00:00
- [[#key-bindings ][Key bindings ]]
2017-05-22 14:16:12 +00:00
- [[#folding-1 ][Folding ]]
- [[#reftex ][RefTeX ]]
2015-06-10 16:44:30 +00:00
* Description
This layer adds support for LaTeX files with [[https://savannah.gnu.org/projects/auctex/ ][AucTeX ]].
2017-08-06 02:14:10 +00:00
** Features:
2015-08-11 11:46:59 +00:00
- Auto-build with [[https://github.com/tom-tan/auctex-latexmk/ ][auctex-latexmk ]]
2020-10-27 21:48:22 +00:00
- Syntax highlighting
- Auto-completion
2015-06-10 21:16:01 +00:00
- 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 ]]
2015-06-10 16:44:30 +00:00
2019-04-21 19:00:24 +00:00
* BibTeX
2016-04-17 02:32:11 +00:00
For more extensive support of BibTeX files than RefTeX provides, have a look at
2017-08-18 19:07:43 +00:00
the [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Blang/bibtex/README.org ][BibTeX layer ]].
2016-04-17 02:32:11 +00:00
2015-06-10 16:44:30 +00:00
* Install
2016-01-06 05:21:55 +00:00
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.
2015-06-10 16:44:30 +00:00
2020-10-27 21:48:22 +00:00
* Configuration
2020-12-13 09:33:04 +00:00
Most layer configurations can be done by setting layer variables in your
2021-08-31 20:55:56 +00:00
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 ]].
2020-12-13 09:33:04 +00:00
** 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.
2021-08-31 20:55:56 +00:00
| 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 |
| ~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) |
2020-10-27 21:48:22 +00:00
** Choosing a backend
2021-08-31 20:55:56 +00:00
This layer provides two alternative backends to choose from.
2020-10-27 21:48:22 +00:00
2020-12-13 09:33:04 +00:00
*** 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:
2020-10-27 21:48:22 +00:00
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-backend 'lsp)))
2020-10-27 21:48:22 +00:00
#+END_SRC
2020-12-13 09:33:04 +00:00
*** 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.
2020-10-27 21:48:22 +00:00
2020-12-13 09:33:04 +00:00
To explicitly choose =company-auctex= as the backend, set the following in your
=~/.spacemacs= :
2020-10-27 21:48:22 +00:00
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-backend 'company-auctex)))
2020-10-27 21:48:22 +00:00
#+END_SRC
2020-12-23 12:52:32 +00:00
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= :
2021-01-10 20:07:24 +00:00
#+BEGIN_SRC emacs-lisp
2020-12-23 12:52:32 +00:00
(setq-default dotspacemacs-configuration-layers
2021-01-10 20:07:24 +00:00
'((latex :packages (not company-math))))
#+END_SRC
2020-12-23 12:52:32 +00:00
2021-08-31 20:55:56 +00:00
** 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= .
2015-06-10 16:44:30 +00:00
** Previewing
2020-12-13 09:33:04 +00:00
=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= :
2015-06-10 16:44:30 +00:00
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-refresh-preview t)))
2015-06-10 16:44:30 +00:00
#+END_SRC
2020-12-13 09:33:04 +00:00
=TexLab= also supports more sophisticated previewing setup, which is documented
[[https://texlab.netlify.app/docs/installation/previewing ][here ]].
2015-06-10 16:44:30 +00:00
** Build command
2015-08-11 11:46:59 +00:00
A build command can be specified via the layer variable =latex-build-command= .
2020-12-13 09:33:04 +00:00
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.
2015-06-10 16:44:30 +00:00
2020-12-13 09:33:04 +00:00
To use the regular =AucTeX= command, set =latex-build-command= to =LaTeX= as
shown below.
2015-06-10 16:44:30 +00:00
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-build-command "LaTeX")))
2015-06-10 16:44:30 +00:00
#+END_SRC
2020-12-13 09:33:04 +00:00
** TeX Engine
=auctex= and =auctex-latexmk= have default rules to determine build command
and build options according to the buffer-local variable =TeX-engine= .
2021-08-22 18:22:31 +00:00
It should be one of the symbol defined in =TeX-engine-alist= . The default valid
2020-12-13 09:33:04 +00:00
symbols are:
2021-08-22 18:22:31 +00:00
- ~default~
- ~luatex~
- ~omega~
- ~xetex~
2020-12-13 09:33:04 +00:00
An appropriate =TeX-engine= is required for high-quality typesetting in certain
2021-08-22 18:22:31 +00:00
languages. For convenience, ~xetex~ is chosen when it's found on PATH and when
2020-12-13 09:33:04 +00:00
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
2020-12-13 10:32:28 +00:00
%%% Local Variables:
2021-08-22 18:22:31 +00:00
%%% TeX-engine: xetex
2020-12-13 10:32:28 +00:00
%%% End:
2020-12-13 09:33:04 +00:00
#+END_SRC
2021-08-22 18:22:31 +00:00
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
2020-12-13 09:33:04 +00:00
variable.
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-build-engine 'xetex)))
2020-12-13 09:33:04 +00:00
#+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 ]].
2015-06-10 16:44:30 +00:00
** Auto-fill
2016-11-27 16:58:39 +00:00
To disable auto-fill (which is on by default) set the variable
=latex-enable-auto-fill= to =nil= .
2015-06-10 16:44:30 +00:00
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-enable-auto-fill nil)))
2015-06-10 16:44:30 +00:00
#+END_SRC
2020-12-13 09:33:04 +00:00
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"
2016-01-04 04:51:19 +00:00
** Folding
Enable folding of text by setting =latex-enable-folding= to =t= . Default value
is nil.
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-enable-folding t)))
2016-01-04 04:51:19 +00:00
#+END_SRC
2015-12-11 22:14:56 +00:00
** Magic latex buffer
2019-05-26 20:58:52 +00:00
To enable "magic" symbols in latex buffers, set the variable
2015-12-11 22:14:56 +00:00
=latex-enable-magic= to =t= .
#+BEGIN_SRC emacs-lisp
2020-12-13 10:32:28 +00:00
(setq-default dotspacemacs-configuration-layers
'((latex :variables latex-enable-magic t)))
2015-12-11 22:14:56 +00:00
#+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.
2018-10-23 14:18:21 +00:00
* Key bindings
2016-04-17 02:32:11 +00:00
2021-05-09 20:37:02 +00:00
| 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 |
2015-06-10 16:44:30 +00:00
2016-01-04 04:51:19 +00:00
** Folding
2016-04-28 17:33:59 +00:00
Available only when =latex-enable-folding= is non nil.
2016-01-04 04:51:19 +00:00
2018-12-05 03:03:03 +00:00
| Key binding | Description |
2016-01-04 04:51:19 +00:00
|-------------+----------------------|
| ~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 |
2015-06-10 16:44:30 +00:00
** RefTeX
2020-10-27 21:48:22 +00:00
| 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 |