Skip to content

Latest commit

 

History

History
142 lines (111 loc) · 7.75 KB

README.org

File metadata and controls

142 lines (111 loc) · 7.75 KB

dynexp.el: Snippets via abbrev-mode

Overview

This package provides completion features that allow for the rapid entry of, e.g., various LaTeX constructs (environments, macros, symbols, subscripts, …). It does so by leveraging Emacs’ familiar abbrev mechanism, extending it with a simple markup language (<+++>, <++>) and a suite of post-processing functions. This approach differs from that of popular packages such as CDLaTeX and YASnippet (or the built-in Skeleton language and Tempo mode), which introduce their own expansion systems.

Configuration

This package requires AUCTeX (to carry out the macro folding), so install that first.

Either download this repository and install using M-x package-install-file, or install using your preferred package manager. For the built-in package manager, you can do this by adding the following to your init file:

(unless (package-installed-p 'dynexp)
  (package-vc-install "https://github.com/ultronozm/dynexp.el"))

Then add the following to your init file (after the relevant configuration for AUCTeX):

(use-package dynexp
  :after latex
  :hook (LaTeX-mode . dynexp-latex-setup)
  :bind
  (:map LaTeX-mode-map
        ("SPC" . dynexp-space)
        ("TAB" . dynexp-next))
  :config
  (let ((file (expand-file-name
               "lisp/dynexp-abbrev.el"
               (file-name-directory (locate-library "dynexp")))))
      (quietly-read-abbrev-file file)))

You might wish to copy the “dynexp-abbrev.el” file provided by the package to your preferred location (so that you can modify it without your changes being overwritten by updates to this package). In that case, you should replace the :config part of the above with (quietly-read-abbrev-file "~/path/to/dynexp/lisp/dynexp-abbrev.el").

Usage

This package makes use of Emacs’s built-in abbrevs feature, which expands words, called abbrevs, into some different text, called the expansion of the abbrev. Quoting from this most recent link:

For example, you might define foo as an abbrev expanding to find outer otter. Then you could insert find outer otter into the buffer by typing f o o SPC.

To each abbrev, one can attach a hook function, which is called, with no arguments, after the abbrev is replaced by its expansion; see this part of the elisp manual for details.

The main export of this package is a certain abbrev hook function dynexp that postprocesses the expansion. We illustrate with three examples.

  1. I use “bthm” as an abbrev for theorem environments. When I type “bthm” in a LaTeX buffer followed by SPC (bound to dynexp-space), it expands to the following abbrev: 
    \begin{theorem}
<+++>
\end{theorem}<++>"

    The function dynexp postprocesses this expansion, transforming it into the following:

    \begin{theorem}
  _
\end{theorem}<++>"

    The underscore _ indicates where the cursor is positioned. When I’m done writing the contents of the theorem, I hit TAB (bound to dynexp-next), which moves the cursor just beyond the theorem environment, like so:

    \begin{theorem}
  (Contents of my cool theorem.)
\end{theorem}_
  2. The abbrev “zx” (easy to type on my keyboard) expands to 
    $<+++>$<++>

    which dynexp postprocesses to

    $_$<++>

    After typing some inline math, I hit TAB to move the cursor just beyond the second dollar delimiter:

    $x=y$_
  3. The abbrev “mx3p” expands to 
    \begin{pmatrix}
<+++> & <++> & <++> \\
<++> & <++> & <++> \\
<++> & <++> & <++> \\
\end{pmatrix}<++>

    which dynexp postprocesses to

    \begin{pmatrix}
_ & <++> & <++> \\
<++> & <++> & <++> \\
<++> & <++> & <++> \\
\end{pmatrix}<++>

    I can then fill in the matrix one entry at a time, using TAB to navigate.

The recipe is likely clear:

  • <+++> is where the cursor should be positioned after the expansion, and
  • <++> is left intact by the expansion, but used to denote “positions of interest” that are “eaten up” by dynexp-next.

There are a few variants of the hook function dynexp, e.g., dynexp-fold, which expands the abbreviation template and applies TeX-fold-region to it.

The package file lisp/dynexp-abbrevs.el contains a few thousand abbrevs that I’ve accumulated over the years. As a base, I started with FasTeX (http://www.cds.caltech.edu/~fastex/fastex.html), specifically, the FasTeX shortcuts for Emacs released by Ari Stern.

You can create new expansion templates by modifying lisp/dynexp-abbrevs.el. It’s often convenient to mimic an existing expansion template.

Usage

With dynexp-auto-expand-mode enabled and dynexp-auto-expand-list configured, simply type any abbrev included in the list. It will expand automatically when you finish typing it, saving you the extra step of pressing SPC.

Additional features

Viewing and Managing Abbrevs

There are several ways to see and manage the available abbrevs:

  1. M-x list-abbrevs: This command displays all currently active abbrevs. You can use Emacs’ built-in search features like isearch (C-s) or occur (M-s o) to find specific abbrevs within this list (see the Incremental Search documentation).
  2. M-x edit-abbrevs: This opens an editable buffer where you can modify existing abbrevs or add new ones.
  3. M-x consult-abbrev: If you have the consult-abbrev package installed, this command provides a more interactive way to browse and search through your abbrevs. It offers live preview of expansions and is particularly useful for quickly recalling which abbrev expands to a given LaTeX construction.
  4. Directly editing dynexp-abbrev.el: For more extensive changes or additions, you can edit the dynexp-abbrev.el file directly. This is especially useful when adding new expansion templates or modifying existing ones.

Remember that changes made through edit-abbrevs or by directly editing dynexp-abbrev.el won’t take effect until you reload the abbrevs file or restart Emacs.

Auto-expansion

This package now includes an auto-expansion feature that allows certain abbrevs to be expanded automatically without the need to press SPC. This may be useful for common abbreviations.

Setup

To use this feature:

  1. Enable dynexp-auto-expand-mode in the buffers of interest. For instance, to enable it in your LaTeX buffers, add the following to your init file: 
    (add-hook 'LaTeX-mode-hook 'dynexp-auto-expand-mode)
  2. Customize the dynexp-auto-expand-list variable to include the abbrevs you want to auto-expand. For example: 
    (setq dynexp-auto-expand-list '("zx" "bdp" "bthm"))

    This will cause the abbrevs “zx”, “bdp”, and “bthm” to expand automatically as soon as you finish typing them, without needing to press SPC.