preview-auto ![Atom Feed](/images/rss.svg)
- Description
- Automatic previews in AUCTeX
- Latest
- preview-auto-0.3.0.20240906.80544.tar (.sig), 2024-Sep-06, 50.0 KiB
- Maintainer
- Paul D. Nelson <nelson.paul.david@gmail.com>
- Website
- https://github.com/ultronozm/preview-auto.el
- Browse ELPA's repository
- CGit or Gitweb
- Badge
To install this package from Emacs, use package-install
or list-packages
.
Full description
1. Overview
The introduction to the preview
manual reads as follows:
Does your neck hurt from turning between previewer windows and the source too often? This AUCTeX component will render your displayed LaTeX equations right into the editing window where they belong.
The purpose of preview-latex is to embed LaTeX environments such as display math or figures into the source buffers and switch conveniently between source and image representation.
AUCTeX provides commands for generating previews in various regions: the current section, the entire document, the marked region, and so on. While these previews generate, you're not supposed to edit while the previews generate, because that can mess up their positioning. A typical workflow is thus to run the command preview-section
(C-c C-p C-s
) every few minutes, during pauses in editing. This introduces a bit of overhead if you prefer to have previews on by default.
This package provides a minor mode, preview-auto-mode
, toggled via the command M-x preview-auto-mode
, the keybinding C-c C-p C-a
, or the Preview
menu. With this minor mode activated, the visible portion of an AUCTeX buffer is continuously previewed. Moreover, previews will automatically abort if you edit in a way that could affect their positioning. Finally, it works in more general situations (e.g., you can use it out-of-the-box to highlight LaTeX in source code comments for other programming languages).
2. Configuration
This package requires AUCTeX, so install that first, and check that the preview-latex feature of AUCTeX works.
Download this repository, install using M-x package-install-file
(or package-vc-install, straight, elpaca, …), and add something like the following to your init file:
(use-package preview-auto)
Customization options can be discovered via M-x customize-group preview-auto
.
2.1. Recommended AUCTeX settings
We recommend the following AUCTeX settings.
(setq preview-locating-previews-message nil) (setq preview-protect-point t) (setq preview-leave-open-previews-visible t)
2.2. Optimization
The following setting makes preview always use DVI's, which generate faster than PDF's:
(setq preview-LaTeX-command-replacements '(preview-LaTeX-disable-pdfoutput))
If you use a package such as hyperref
that works only with PDF's, then you should replace \usepackage{hyperref}
in your TeX file with something like the following:
\usepackage{ifpdf} \ifpdf \usepackage{hyperref} \fi
2.3. Always enable
If you want preview-auto-mode
to activate automatically when you visit a tex file (but not when you visit a bbl file), then use the following config:
(use-package preview-auto :hook (LaTeX-mode . czm-preview-mode-conditionally-enable))
2.4. My setup
I use something like the following use-package
declaration:
(use-package preview-auto :after latex :config (setq preview-protect-point t) (setq preview-locating-previews-message nil) (setq preview-leave-open-previews-visible t) :custom (preview-auto-interval 0.1) (preview-LaTeX-command-replacements '(preview-LaTeX-disable-pdfoutput)))
My precise current setup may be found in the LaTeX part of my config (elpaca
branch).
2.5. Non-file buffers and other modes
This package works fine in non-file buffers running LaTeX-mode
, provided that you set the local variable TeX-master
to the name of a valid tex file containing all the macros that you use. For example, if "~/doit/preview-master.tex" is the name of such a file, and you want to use preview-auto-mode
in indirect org-mode source blocks, just add something like the following to your config:
(defun my/set-TeX-master () (setq TeX-master "~/doit/preview-master.tex")) (advice-add 'org-edit-src-code :after 'my/set-TeX-master)
It also works in buffers running other major modes. (For example, I use it to preview LaTeX in comments in Lean4 files.) Again, you just need to specify a suitable TeX-master. For Lean4, I use something like:
(add-hook 'lean4-mode-hook 'my/set-TeX-master)
The default behavior is that in programming modes, only the comments are searched for latex code. You can customize this via the defcustom preview-auto-check-function
.
2.6. tikzpicture support
According to section B.4.5 of the preview-latex
info manual, support for the tikzpicture environment can be enabled by adding the following lines to your document preamble:
\usepackage[displaymath,sections,graphics,floats,textmath]{preview} \PreviewEnvironment[{[]}]{tikzpicture}
If you want preview-auto-mode
to preview such environments automatically (including when they are not wrapped in some math environment), then you should add "tikzpicture" to the customizable list variable preview-auto--extra-environments
, e.g., by putting
(add-to-list 'preview-auto--extra-environments "tikzpicture")
in your config. I keep this disabled by default because of the extra setup required in the document preamble, without which preview-latex
would return "LaTeX found no preview images" errors.
3. Issues
- Sometimes the preview command run by the timer produces the same error over and over again, effectively locking Emacs. If this happens, you should hold down
C-g
until the timer dies. Then, try usingpreview
"normally" and sort out the erorrs. Finally, togglepreview-auto-mode
. - When the timer provided by
preview-auto
fires, it clears the minibuffer. This is becauseinhibit-message
is used surrounding a call towrite-region
to prevent flooding the minibuffer with "Wrote…" messages, but messages sent underinhibit-message
still clear the minibuffer. This can be a bit annoying if you are looking at the minibuffer for some other reason (e.g., Flymake) while thepreview-auto
timer is firing a bunch. Fixing this would require tweaking AUCTeX's internals a bit. - Very rarely, I've seen some
preview-latex
process (e.g., Ghostscript) gets stuck. The symptom is thatpreview-auto
will not generate anything, even after resetting the mode. You can check if this has happened usingM-: (get-buffer-process (TeX-process-buffer-name (TeX-region-file)))
. The fix is then to navigate to the_region_.tex
buffer and doM-x TeX-kill-job
.
Old versions
preview-auto-0.3.0.20240818.113948.tar.lz | 2024-Aug-18 | 9.59 KiB |
preview-auto-0.3.0.20240629.205058.tar.lz | 2024-Jun-30 | 9.57 KiB |
preview-auto-0.3.0.20240617.174622.tar.lz | 2024-Jun-18 | 9.58 KiB |