073fe39b38
This commit makes the latex layer automatically configure pdf-tools as latex pdf-viewer if the pdf layer is installed. Additionally it adds a layer variable to configure pdf-tools to open in a split-window. (Strangely, finding out how to achieve that is far from trivial, and also not easy to google, because many hits do not provide the "correct" answer (see the typical example [here](https://emacs.stackexchange.com/questions/28056/spacemacs-latex-how-to-make-view-command-tile-vertically-with-emacs-window)). Update layers/+lang/latex/funcs.el Co-authored-by: Lucius Hu <1222865+lebensterben@users.noreply.github.com>
328 lines
16 KiB
Org Mode
328 lines
16 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]]
|
||
|
||
* 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. 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-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 |
|