345 lines
17 KiB
Org Mode
345 lines
17 KiB
Org Mode
#+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]]
|
|
- [[#pdf-viewer][PDF viewer]]
|
|
- [[#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]]
|
|
- [[#evil-tex][evil-tex]]
|
|
|
|
* 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]]
|
|
- LaTeX-specific text objects and much more with [[https://github.com/iyefrat/evil-tex][evil-tex]]
|
|
|
|
* 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. 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 [[#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-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
|
|
[[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
|
|
|
|
** 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=:
|
|
|
|
#+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-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:
|
|
|
|
#+BEGIN_SRC tex
|
|
%%% Local Variables:
|
|
%%% TeX-engine: xetex
|
|
%%% End:
|
|
#+END_SRC
|
|
|
|
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.
|
|
|
|
#+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 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 |
|
|
|
|
** evil-tex
|
|
See the [[https://github.com/iyefrat/evil-tex/blob/master/README.org][evil-tex documentation]] for more comprehensive explanation of text
|
|
objects it provides and its other features, including its integration with
|
|
~evil-surround~.
|
|
|
|
| Key binding | Description |
|
|
|-------------+-----------------------------------------------------|
|
|
| ~]]~ / ~[[~ | jump between section headings |
|
|
| ~M-n~ | Move between braces, similar to ~TAB~ in ~cd-latex~ |
|
|
| ~SPC m q~ | Prefix for [[https://github.com/iyefrat/evil-tex#toggles][evil-tex toggle commands]] |
|
|
|
|
In order to [[https://github.com/iyefrat/evil-tex#user-options][preserve both the precious ~t~ mark and the indispensable ~ts~
|
|
motion]], the [[https://github.com/iyefrat/evil-tex/blob/master/README.org#toggles][evil-tex "magnificent toggles"]] are bound under ~SPC m q~ rather than
|
|
~mt~ or ~ts~. This binding can be remembered with mnemonic "quite magnificent
|
|
toggle".
|