doomemacs/modules/lang/latex/README.org

#+title:    :lang latex
#+subtitle: Writing papers in Emacs has never been so fun
#+created:  January 16, 2017
#+since:    1.3

* Description :unfold:
Provide a helping hand when working with LaTeX documents.

- Sane defaults
- Fontification of many popular commands
- Pretty indentation of wrapped lines using the [[doom-package:adaptive-wrap]] package
- Spell checking with [[doom-package:flycheck]]
- Change PDF viewer to Okular or [[doom-package:latex-preview-pane]]
- Bibtex editor
- Autocompletion using [[doom-package:company-mode]]
- Compile your =.tex= code only once using LatexMk

** Maintainers
- [[doom-user:][@tecosaur]]
- [[doom-user:][@ymarco]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +cdlatex ::
  Enable [[doom-package:cdlatex]] for fast math insertion.
- +fold ::
  Use TeX-fold (from [[doom-package:auctex]]) to fold LaTeX macros to unicode, and make folding
  hook-based and less manual.
- +lsp ::
  Enable LSP support in latex buffers. Requires [[doom-module::tools lsp]] and a langserver
  (supports digestif and TexLab).

** Packages
- [[doom-package:adaptive-wrap]]
- [[doom-package:auctex]]
- [[doom-package:cdlatex]] if [[doom-module:+cdlatex]]
- [[doom-package:evil-tex]] if [[doom-module::editor evil +everywhere]]
- [[doom-package:latex-preview-pane]]
- if [[doom-module::completion company]]
  - [[doom-package:company-auctex]]
  - [[doom-package:company-math]]
  - [[doom-package:company-reftex]]

** TODO Hacks
#+begin_quote
 󱌣 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires ghostscript and a latex compiler. These are provided by the
=texlive= bundle, available through many OS package managers.

#+begin_quote
  Ghostscript <= 9.27 is [[/auctex/manual/preview-latex/No-images-are-displayed-with-gs-9_002e27-and-earlier.html][reportedly buggy]] and doesn't work with auctex's math
    previews. (You can check you ghostscript version with ~$ gs --version~.)
    Most package managers already have newer versions, but if not you might have
    to build gs from source.
#+end_quote

** Ubuntu
#+begin_src sh
apt-get install texlive
#+end_src

** Arch Linux
#+begin_src sh
pacman -S texlive-basic texlive-latexrecommended texlive-plaingeneric
#+end_src

** TODO macOS
#+begin_src sh
brew install --cask basictex
# If the above doesn't work, then
brew install --cask mactex  # WARNING: large 4gb download!
#+end_src

#+begin_quote
 󱌣 This has not been verified.
#+end_quote

** NixOS
#+begin_src nix
environment.systemPackages = [ pkgs.texlive.combined.scheme-medium ];
#+end_src

** Formatter

Formatting is handled using the [[doom-module::editor format]] module via [[https://github.com/cmhughes/latexindent.pl][latexindent]].

* TODO Usage
#+begin_quote
 󱌣 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* Configuration
** Specifying the location of a bibtex file & corresponding PDFs
Reftex has a variable that allow you to specify where it should find your
bibliography file(s):
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq reftex-default-bibliography "/your/bib/file.bib")
#+end_src

** Changing the PDFs viewer
This module provides integration for four supported pdf viewers. They are

+ [[https://skim-app.sourceforge.io/][Skim.app]] (MacOS only)
+ Evince
+ Sumatra PDF
+ Zathura
+ Okular
+ pdf-tools (requires [[doom-module::tools pdf]] module)

They are searched for in this order. See ~+latex-viewers~ to change the order,
or remove tools from the search altogether. If you want to exclusively use one
tool, for instance:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq +latex-viewers '(zathura))
#+end_src

If none of these tools are found, ~latex-preview-pane~ (uses ~DocView~ in Emacs)
is used as a fallback. You can use this exclusively by setting ~+latex-viewers~
to ~nil~.

** Using cdlatex's snippets despite having yasnippet
[[doom-package:cdlatex]] has a snippet insertion capability which is disabled in favor of
[[doom-package:yasnippet]] when using [[doom-module::editor snippets]]. If you still wanna use it, simply rebind
the [[kbd:][TAB]] key for cdlatex, which takes care of snippet-related stuff:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(map! :map cdlatex-mode-map
      :i "TAB" #'cdlatex-tab)
#+end_src

This would favor yasnippet's expansion and cursor movement over cdlatex's
expansion and movement, but that shouldn't matter if you're not using yasnippet
in latex buffers.

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote