czm-preview.el: Extensions for preview.el

Notice

This package should now be considered deprecated in favor of AUCTeX 14.0.5 and the newer package https://github.com/ultronozm/preview-auto.el, which incorporate all the functionality of this package, but without the hacky :override advice used in its implementation. I’m leaving this one here in case any existing users are happy with it and don’t want to update their configs, etc.

Overview

This package supplies a minor mode czm-preview-mode that augments preview.el (or preview-latex) from AUCTeX. The introduction to the preview.el 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.

This package distills the modifications to my local copy of preview.el accumulated over the years:

1. LaTeX environments are previewed automatically.

   With stock AUCTeX, one manually generates previews in various regions: the current section, the entire document, the marked region, and so on. Also, 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.

   With this package, previews generate automatically in the visible buffer, and editing won’t mess up their positioning. These features are convenient if you’re in the habit of using a TeX buffer like a blackboard, for thinking or collaborating rather than just for publishing.

2. Previews remain visible while you edit them.

   Moreover, they update automatically if you stop typing for a moment. I’ve found this feature useful when revising a paper with remote collaborators, via videoconferencing and screensharing.

3. Previews work in non-file buffers.

   In particular, they work in indirect buffers and indirect org-mode source blocks. You can thus view and edit several parts of a TeX buffer simultaneously, with live previews for each. By contrast, stock AUCTeX previews are restricted to file buffers.

   Incidentally, a minor bug in preview.el (fixed in this package, and now also in pre-release preview.el) makes it impractical to use indirect buffers.

4. Equation numbers are accurately depicted in previews.

   In stock AUCTeX, if you preview a region containing three equation environments, they’ll be numbered (1), (2) and (3), regardless of how they’re numbered in the compiled document.

   This package gives correct equation numbers when visiting a .tex file that has an accompanying .aux file (e.g., generated continuously via latexmk, which I do via czm-tex-compile.el).

   In-buffer numbering for other types of environments (theorems, …) is provided by the package czm-tex-fold.el. When using both packages, “everything” is numbered just like in the compiled document. This is very convenient, e.g., when implementing the suggestions of a collaborator or referee (“fix equation 3.8.1 and Theorem 3.5”). The numbering also comes in handy when searching for references using czm-tex-ref.el, which looks something like this:

   

Some of these features are also available in the package xenops, but they’re implemented differently there: from the ground up, rather than using AUCTeX as a base. Incidentally, I’ve never really gotten the chance to try xenops, which doesn’t seem to work with recent versions of emacs.

Configuration

This package requires AUCTeX and czm-tex-util.el, so install those 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 czm-preview)

That’s the basic setup. We now discuss some mild refinements:

• It is recommended (but not required) that you specify a “master” TeX file containing a minimal preamble. Doing so is necessary to make this package usable in non-file buffers, and can also speed up preview generation.
• You might want the mode to activate automatically whenever you visit a TeX file (but probably not when visiting .bbl files).
• You might want to bind a key that toggles it. (This gives a handy way to restart the mode, which is worth trying if it stops working.)

To implement these refinements, use the following:

(use-package czm-preview
  :after latex
  :bind
  (:map LaTeX-mode-map
	("C-c u" . czm-preview-mode))
  :custom
  (czm-preview-TeX-master "~/doit/preview-master.tex")
  :hook
  (LaTeX-mode . czm-preview-mode-conditionally-enable))

I’ve included my own “preview-master.tex” in the “tex” subfolder of this repository. Feel free to make your own, or edit mine so that it contains whichever macros you use. Then replace “~/doit/preview-master.tex” in the above with the appropriate path.

Note, for instance, that \usepackage{tikzpicture} is commented out in the supplied “preview-master.tex”. I’ve found that tikz slows down preview generation by a couple hundred milliseconds or so; I prefer the snappier feel, and only rarely have the need to preview tikzpictures. If you’re using the czm-preview-TeX-master approach and want tikzpictures enabled with the supplied “preview-master.tex”, you should uncomment the \usepackage{tikzpicture} line. Similar considerations apply to any other macros, of course.

The precise use-package declaration that I use may be found in my config.

Usage

Visit a TeX file, with AUCTeX’s LaTeX-mode as the major-mode. Run M-x czm-preview-mode (unless you are using the refined setup described above, in which case this step is automatic). If you’ve specified czm-preview-TeX-master, then the same should work in any LaTeX-mode buffer.

Issues

• If czm-preview-TeX-master is non-nil and czm-preview-mode is activated, then ordinary LaTeX compilation via C-c C-c probably won’t work correctly. There are at least two workarounds:
  • Disable czm-preview-mode when you compile, then enable it again when you want to generate more previews.
  • (What I do) Avoid compilation via C-c C-c altogether. Instead, have a latexmk process running in the background for each TeX file that you work with. For this, I use czm-tex-compile.el.
• czm-preview-mode adds advice when it is enabled and removes that advice when it is disabled. This is a practical but imperfect way to do things, and can lead to problems: if you disable the mode in one buffer, and then attempt to use the mode in another buffer where you had already enabled it, the advice will not be present. In such situations, you should toggle the mode in the buffer where you’re using it. I rarely disable the mode (e.g., when stitching together multiple math environments in a way that temporarily creates horribly invalid TeX code) and always enable it shortly afterwards, so this issue doesn’t arise.
• If you don’t adopt the czm-preview-TeX-master approach, then you should make sure that TeX-PDF-mode is set to t, for some reason that I can’t remember at the moment.

Tips for snappier previews

• dvi files generate faster than pdf, so I recommend using the czm-preview-TeX-master approach and turning off TeX-PDF-mode, e.g., by adding (setq-default TeX-PDF-mode nil) to your init file.
• I have sometimes found older versions of TeX compilers to be faster than newer ones; it might be useful to experiment. On one computer, I include the following in my init file, which says to generate previews using TeXLive 2020 rather than 2023:

  (with-eval-after-load 'preview
    (let ((tex-dir (when (equal (system-name) "Pauls-MBP-3")
                     "/usr/local/texlive/2020/bin/x86_64-darwin/")))
      (setq preview-LaTeX-command
  	    `(
  	      ,(concat
  	        "%`"
  	        tex-dir
  	        "%l \"\\nonstopmode\\nofiles\\PassOptionsToPackage{")
  	      ("," . preview-required-option-list)
  	      "}{preview}\\AtBeginDocument{\\ifx\\ifPreview\\undefined" preview-default-preamble "\\fi}\"%' \"\\detokenize{\" %(t-filename-only) \"}\""))))
      

• If your tex file sets TeX-master to t as a file local variable (common in AUCTeX) and you activate czm-preview-mode via LaTeX-mode-hook, then the file local variable will set TeX-master to t, while czm-preview-mode requires it to be something else, so previews won’t work. You can fix this issue by turning czm-preview-mode on and off, which will set TeX-master to the correct value.

Caution

This minor mode is implemented in part via :override advice applied to the packages tex.el/preview.el, and so might be incompatible with future versions of those. This is a poor design choice, guided by my practical needs.