czm-preview.el: Extensions for preview.el

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 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”).

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.

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.

Tips for snappier previews

• dvi files generate faster than pdf, so I recommend 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) \"}\""))))
      

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.