LaTeX: improved i18n support and documentation (#14204)
* LaTeX: improved i18n support and documentation
- Added a new layer config variable `latex-build-engine`, a thin wrapper of
`TeX-engine`:
- For better support of non-european character set rendering, `xetex` is
chosen when it's found on PATH, and when eithe `chinese` or `japanese`
layer is enabled
- Added a new layer config variable `latex-enable-preview`:
- When non-nil, `auto-revert-mode` is added to `doc-view-mode-hook`
- Previously this is described in documentation but requires users to set it
manually
- Documentation:
- Added a section that lists are layer config variables
- Improved all documentation examples, s.t. they are valid elisp forms to be
evaluated directly
- Improved the section on backend:
- Emphsized that LSP layer is always preferred
- Provided information on installing the language server
- Added the default value for layer config variable, `latex-nofil-env`
* minor edits
- Updated CHANGELOG.develop
- Renamed `latex-enable-preview` to `latex-refresh-preview`
- Replaced a fuzzy intra-link in documentation with a proper link
Co-authored-by: Lucius Hu <lebensterben@users.noreply.github.com>
This commit is contained in:
Lucius Hu
GitHub
parent
c0f61fa035
commit
2d1d338f46
4 changed files with 146 additions and 56 deletions
|
|
@ -2543,6 +2543,10 @@ files (thanks to Daniel Nicolai)
|
|||
- Added ConTeXt mode to the key bindings (thanks to ft)
|
||||
- Fixed ~SPC m ;~ binding (thanks to Tianshu Wang)
|
||||
- Fix jump handlers setup and use dumb-jump as default (thanks to Matt Kramer)
|
||||
- Added layer variable =latex-build-engine= to provide better i18n support (thanks
|
||||
to Lucius Hu)
|
||||
- Added layer variable =latex-refresh-preview= to refresh the preview buffer when
|
||||
compiled PDF is changed (thanks to Lucius Hu)
|
||||
**** Lua
|
||||
- Added support for auto-completion with =company= (thanks to halfcrazy)
|
||||
- Added support for =LSP= (EmmyLua-LS-all) (thanks to Lin.Sun)
|
||||
|
|
|
|||
|
|
@ -10,11 +10,13 @@
|
|||
- [[#bibtex][BibTeX]]
|
||||
- [[#install][Install]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#variables][Variables]]
|
||||
- [[#choosing-a-backend][Choosing a backend]]
|
||||
- [[#company-auctex][Company-auctex]]
|
||||
- [[#lsp][LSP]]
|
||||
- [[#company-auctex][Company-auctex]]
|
||||
- [[#previewing][Previewing]]
|
||||
- [[#build-command][Build command]]
|
||||
- [[#tex-engine][TeX Engine]]
|
||||
- [[#auto-fill][Auto-fill]]
|
||||
- [[#folding][Folding]]
|
||||
- [[#magic-latex-buffer][Magic latex buffer]]
|
||||
|
|
@ -42,91 +44,155 @@ 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.
|
||||
Most layer configurations can be done by setting layer variables in your
|
||||
dotfile. Some however require adding lines to your user-config.
|
||||
|
||||
** 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 |
|
||||
|
||||
** 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.
|
||||
This is the default backend if =LSP= layer is enabled.
|
||||
It provides proper IDE support and is recommended over =company-auctex=.
|
||||
|
||||
To set explicitly do the following in your dotfile:
|
||||
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
|
||||
(latex :variables
|
||||
latex-backend 'lsp)
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((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=.
|
||||
*** Company-auctex
|
||||
This would be the backend if =LSP= layer is not enabled, and =latex-backend= is
|
||||
not set.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
** 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=:
|
||||
=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
|
||||
(add-hook 'doc-view-mode-hook 'auto-revert-mode)
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((latex :variables latex-refresh-preview t)))
|
||||
#+END_SRC
|
||||
|
||||
Then when you open up a compiled PDF, the preview will update automatically when
|
||||
you recompile.
|
||||
=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 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.
|
||||
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
|
||||
dotspacemacs-configuration-layers '(
|
||||
(latex :variables latex-build-command "LaTeX"))
|
||||
(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-alise=. 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
|
||||
|
||||
If you predominantly works 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
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: auto-fill
|
||||
:END:
|
||||
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))
|
||||
(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
|
||||
dotspacemacs-configuration-layers '(
|
||||
(latex :variables latex-enable-folding t))
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((latex :variables latex-enable-folding t)))
|
||||
#+END_SRC
|
||||
|
||||
** Magic latex buffer
|
||||
|
|
@ -134,8 +200,8 @@ 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))
|
||||
(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
|
||||
|
|
|
|||
|
|
@ -19,9 +19,28 @@
|
|||
;; ...but AUCTeX runs LaTeX-mode-hook rather than latex-mode-hook, so:
|
||||
(add-hook 'LaTeX-mode-hook #'spacemacs//init-jump-handlers-latex-mode)
|
||||
|
||||
(defvar latex-backend nil
|
||||
"The backend to use for IDE features.
|
||||
Possible values are `lsp' and `company-auctex'.
|
||||
If `nil' then 'company-auctex` is the default backend unless `lsp' layer is used")
|
||||
|
||||
(defvar latex-build-command (if (executable-find "latexmk") "LatexMk" "LaTeX")
|
||||
"The default command to use with `SPC m b'")
|
||||
|
||||
(defvar latex-build-engine (if (and (executable-find "xetex")
|
||||
(or (configuration-layer/layer-used-p 'chinese)
|
||||
(configuration-layer/layer-used-p 'japanese)))
|
||||
'xetex
|
||||
'default)
|
||||
"The default TeX engine to use with `SPC m b'. It's set to `xetex' when `xetex' is found on PATH
|
||||
and either `chinese' layer or `japanese' layer is in use.
|
||||
|
||||
Allowed values are defined in `TeX-engine-alist'. The default allowed values are:
|
||||
* `default'
|
||||
* `luatex'
|
||||
* `omega'
|
||||
* `xetex'")
|
||||
|
||||
(defvar latex-enable-auto-fill t
|
||||
"Whether to use auto-fill-mode or not in tex files.")
|
||||
|
||||
|
|
@ -42,7 +61,5 @@
|
|||
"tikzpicture")
|
||||
"List of environment names in which `auto-fill-mode' will be inhibited.")
|
||||
|
||||
(defvar latex-backend nil
|
||||
"The backend to use for IDE features.
|
||||
Possible values are `lsp' and `company-auctex'.
|
||||
If `nil' then 'company-auctex` is the default backend unless `lsp' layer is used")
|
||||
(defvar latex-refresh-preview nil
|
||||
"Whether non-nil, refresh the preview buffer when file changes.")
|
||||
|
|
|
|||
|
|
@ -39,6 +39,7 @@
|
|||
:init
|
||||
(progn
|
||||
(setq TeX-command-default latex-build-command
|
||||
TeX-engine latex-build-engine
|
||||
TeX-auto-save t
|
||||
TeX-parse-self t
|
||||
TeX-syntactic-comment t
|
||||
|
|
@ -53,7 +54,9 @@
|
|||
(add-hook 'LaTeX-mode-hook 'LaTeX-math-mode)
|
||||
(add-hook 'LaTeX-mode-hook 'TeX-source-correlate-mode)
|
||||
(add-hook 'LaTeX-mode-hook 'TeX-PDF-mode)
|
||||
(add-hook 'LaTeX-mode-hook #'spacemacs//latex-setup-backend))
|
||||
(add-hook 'LaTeX-mode-hook #'spacemacs//latex-setup-backend)
|
||||
(when latex-refresh-preview
|
||||
(add-hook 'doc-view-mode-hook 'auto-revert-mode)))
|
||||
:config
|
||||
(progn
|
||||
;; Key bindings for plain TeX
|
||||
|
|
|
|||
Reference in a new issue