evil-tex

evil toolbox for LaTeX editing. Provides many text objects fully utilizing evil-surround, some useful movements, and keymaps for quickly entering environments or cdlatex-like accents. And useful toggles.

Heavily inspired by vimtex; successor of evil-latex-textobjects.

Table of Contents

Incomplete Showcase

| marks point.

\ti|lde{h} → cic (change inside command) → \tilde{|}

\tilde{h|} → cscc bar (change surrounding command to =bar=) → \bar{h}

\dv|{} → cscc pdv (change surrounding command to =pdv=) → \pdv{}

\eps|ilon → cscc mu (change surrounding command to =mu=) → \mu

\(\sum_{i=1}^{n} i^2|\) → cim (change inner math) → \(|\)

\(\sum_{i=1}^{n} i^2|\) → mtm (toggle surrounding math) → \[\sum_{i=1}^{n} i^2|\]

\[a|^2\] → csmeA (change surrounding math to environment =align*=) → \begin{align*}\n a^2 \n\end{align}

(\mu|_\nu) → csddP (change surrounding delimiter to =\left(=) → \left(\mu|_\nu\right)

Installation

This package can be installed from MELPA, or by cloning it and putting it in the load path. For ease of use, hook it to LaTeX-mode by adding the following to your configuration:

(add-hook 'LaTeX-mode-hook #'evil-tex-mode)

This package requires evil, auctex, and Emacs 25.1+.

If you are using Doom Emacs, you can just enable latex and (evil +everywhere) in your init.el.

Interaction with other packages

evil-tex does not require, but supports evil-surround (using version 1.1.1 or newer is preferred, to leverage #165). evil-embrace is also supported, in the sense that it is told to overlook the bindings.

evil-tex also supports which-key to show the keys in keymaps. Likewise, the toggles under ts play well with evil-snipe as expected.

Overview

Text Objects

This package defines a number of text objects:

The full text object definitions are as follows:

   \foobar{barbaz}     \foobar{barbaz}    \foobar     \foobar    \foobar{}     \foobar{}
   └─────────────┘             └────┘     └─────┘            ┆   └───────┘             ┆
          ac                     ic         ac      ic (empty)      ac            ic (empty)

  ┌\begin{foobar}     \begin{foobar}
  │                  ┌
ae│ baz            ie│ baz
  │                  └
  └\end{foobar}       \end{foobar}

  \(foobar\)    \(foobar\)    \[foobar\]    \[foobar\]
  └────────┘      └────┘      └────────┘      └────┘
      am            im            am            im

  (foobar)    (foobar)    \left(foobar\right)    \left(foobar\right)  \Bigl(foobar\Bigr)    \Bigl(foobar\Bigr)
  └──────┘     └────┘     └─────────────────┘          └────┘         └────────────────┘          └────┘
     ad          id               ad                     id                   ad                    id

   ┌\section{foo}          \section{foo}
   │                      ┌
 aS│ baz                iS│ baz
   │\subsection*{}        │\subsection*{}
   └ qux                  └ qux
    \chapter*{bar}        \chapter*{bar}

   a^{foo}    a^{foo}    a^b    a^b    a^\bar    a^\bar
    └────┘       └─┘      └╵      ╵     └───┘      └──┘ 
      a^          i^      a^      i^     a^         i^
      
   & foobar &    & foobar &    & foobar \\    & foobar \\    
   └───────┘      └──────┘     └───────┘       └──────┘
       aT            iT            aT             iT

The diagram rendering might bug out on mobile.

Notes

• The section objects extends up to the next \section{} type command of equal or higher rank to the one closest to the point from above, and does not distinguish between named and unnamed sections.
• aT will always only contain the left delimiter, unless it is the first cell of its line, then it will only contain the right delimiter.

Toggles

There are a few operations one might want to toggle between frequently, without pressing too many keys. To this end we provide a few toggles, bound by default to mt* (for ”magnificent toggle”), as you have 25 other marks to choose from.

For vimtex users, or people who have something against the letter s, we also provide the ability to map the toggles to ts instead of mt e.g. instead of mtd toggling delimiters, tsd will. See configuration. The toggles are:

Misc.

Command Argument Movement

The binding M-n is provided for cd-latex TAB-like brace movement, useful for quick navigation in marco arguments without going to normal mode.

\bar{h|} → M-n → \bar{h}|

\frac{a|}{} → M-n → \frac{a}{|}

\frac{a|}{b} → M-n → \frac{a}{b|}

\frac{a}{b|} → M-n → \frac{a}{b}|

Section Jumping

]​] and [​[ jump between section headings (\section, \subsection*, etc).

Configuration

Custom env and accent surround insertions

Should be done by using evil-tex-bind-to-(env|cdlatex-accents|delim)-map. example, to add a quote environment and have a default [!ht] position for figures:

(evil-tex-bind-to-env-map '(("q" . "quote")
                            ("f" "\\begin{figure}[!ht]" . "\\end{figure}")))

Same for evil-tex-bind-to-cdlatex-accents-map and evil-tex-bind-to-delim-map

(evil-tex-bind-to-cdlatex-accents-map '(("b" . "fbox")))
(evil-tex-bind-to-delim-keymap '(("h" "\\huge(" . "\\huge)")))

Same for evil-tex-user-delim-map-generator-alist. For the complete format take a look at the documentation of evil-tex-bind-to-env-map.

Custom Toggles

Just bind your function to evil-tex-toggle-map, its a normal keymap. Nothing fancy here.

User Options

• By default, the newline proceeding \begin{...} and preceding \end{...} is selected as part of the delimiter. This way, when doing cie you’re placed on a separate line, and surrounding with envs would force separate lines for \begin, inner text, and \end. To disable this newline behaviour, set evil-tex-select-newlines-with-envs to nil.

• Similarly, empty environments are inserted (using surround) with newlines by default. This way, when doing ysiwee, the environment is inserted above and below the word. To disable this and have it surround the text object in the same line, set evil-tex-select-newlines-in-envs to nil. Note that this will not insert newlines environment name changes such as cseea even if they were already there.
• The toggle bindings are set by default to mt. To turn this off and regain the invaluable t mark, set evil-tex-toggle-override-m to nil.
• In order to use ts for toggle bindings, set evil-tex-toggle-override-t to t. This will overide the standard t motion, and will rob you of the ability to move to one character before s (although you can always do fsh).

Acknowledgements

We would like to thank @lervag for writing the excellent vimtex vim plugin, which was the main thing we missed about vim. We would also like to thank @hpdeifel for writing evil-latex-textobjects, which laid the groundwork for this package and helped us get started with elisp. Lastly, we would like to thank @hlissner helping us with a particulary tricky bit of elisp, and also writing Doom Emacs without which this plugin would probably not exist.

Appendix

Keymaps

Environment keymap

Giving a prefix argument would prompt for options.

cdlatex accent keymap

See cdlatex. “style?” implies that the braces come before the macro, e.g {\displaystyle ...}

Delimiter keymap