czm-tex-ref.el: Interface for LaTeX labels/citations

Overview

This package provides functions for inserting labels/references/citations in a LaTeX buffer. For example, here’s how it looks when I decide that I want to number some equation and refer to it:

This packages differs from the standard package for doing so, reftex, in that

• label and reference features are combined into a single function,
• selection is previewed using consult,
• it works in non-file buffers, where reftex does not, and
• it is less feature-complete than reftex in a couple ways.

Configuration

This package requires AUCTeX and czm-tex-util.el, so install those first.

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-tex-ref
  :custom
  (czm-tex-ref-master-bib-file "~/doit/refs.bib")
  (czm-tex-ref-rearrange-bib-entries t)
  :bind
  (:map LaTeX-mode-map
	("C-c 9" . czm-tex-ref-label)
	("C-c 0" . czm-tex-ref-bib)))

Modify suitably:

• Replace the key binds with whatever you prefer.
• Replace “~/doit/refs.bib” with the path to the .bib file containing all your references. If you don’t use such a “master” .bib file, then delete that line; czm-tex-ref will then search through the first file encountered in any “\bibliography{…}” command found in your TeX buffer.
• The customization option czm-tex-ref-rearrange-bib-entries t means that czm-tex-ref will rearrange your .bib file by moving selected entries to the top, so that it becomes easy to repeatedly cite “popular” references. If you wish to disable this behavior, change t to nil.
• If you work exclusively in file buffers and want to use reftex to select label captions, then add the following under :custom:

  (czm-tex-ref-insert-label-function #'reftex-label)
      

  Or customize this to whatever you’d like; the default option czm-tex-ref-insert-label inserts a time-stamped label in base 36, as in the GIF above.

Usage

References and labels

The reader might be familiar with reftex, which provides two basic functions for working with labels: reftex-label to insert labels, and reftex-reference to insert references to labels.

In czm-tex-ref, the label and reference features are combined into a single function, czm-tex-ref-label. This uses consult to select a line in the current buffer that either contains a label, or where it makes sense to insert one. In the latter case, a new label is inserted at the appropriate position. In either case, a reference to the label is copied to the kill ring.

To illustrate, compare how you would insert a reference to an unlabelled equation that occurred at some earlier point in your document. In reftex, you would

• navigate to the equation,
• run refex-label C-c ( to insert a label,
• navigate back to where you want to reference it, and
• run reftex-reference C-c ) to select the equation that you just labelled.

In czm-tex-ref, you instead

• run czm-tex-ref-label,
• select the equation that you want to reference using consult, and
• yank (C-y) the reference.

The latter workflow feels much quicker and more fluid to me.

Citations

reftex provides one basic function for inserting citations, reftex-citation. The function czm-tex-ref-bib is analogous, but with two differences:

1. It uses consult to select the citation to insert.
2. It has been designed to work also in non-file buffers (e.g., indirect org-mode source blocks), and for this reason, is a bit less feature-complete than reftex-citation:
   • It doesn’t work with \bibitem entries.
   • It doesn’t support multiple .bib files.

This isn’t much of a problem for me, since I keep all my references in one .bib file.

Related packages

There is a work in progress called consult-reftex that provides a “two method” interface, closer to that of reftex, for labels and references, also using consult.