README.org

:editor meow

Description

This module integrates Meow with Doom Emacs.

The integration consists of:

• A ‘port’ of Doom’s (emacs) leader and localleader bindings to Meow’s Keypad state;
• A cursor configuration that uses the ‘bar’ cursor shape to indicate the way Emacs’ cursor positioning differs from other modal editors, with cursor-blink-mode rather than a shape change to indicate a switch to Insert state;
• A custom emacs Meow state with minimal bindings, intended for modes that use the keys bound in Motion state, and as a means of demonstrating the process of defining a custom state;
• Numerous other tweaks, including to the suggested bindings, to integrate with Doom better.

It is recommended to read Meow’s README prior to trying this module.

Meow is designed as a minimal, dependency-free modal ‘layer’ on top of Emacs, preferring to leverage built-in functionality rather than reinventing the wheel. If it seems to be ‘missing’ a feature present in another modal system, it may be because the equivalent Emacs functionality is considered usable enough not to warrant a Meow-flavored reimplementation. Accordingly, it is suggested to become familiar with Emacs’ basic concepts and features, at least up to the level taught in the Tutorial (M-x help-with-tutorial).

Module flags

+qwerty, +qwertz, +dvorak, +dvp, +colemak

Set up Meow’s suggested bindings for the respective layouts. If you don’t use any of these flags, you will need to set up bindings yourself; see the relevant docs.

You will probably want to look at the files responsible for defining the bindings (in this module’s autoload/ directory) in order to be aware of any tweaks applied by this module. If the reason for a tweak is not documented in its respective file, it probably is in +qwerty.

Packages

• doom-package:meow

Hacks

• The localleader bindings are accomplished via a hack.

Changelog

This module does not have a changelog yet.

Installation

mkdir -p ~/.config/doom/modules/editor # or ~/.doom.d/modules/editor, if your Doom config is in ~/.doom.d
cd $_ # change working directory to the one above
git clone https://github.com/meow-edit/doom-meow meow

Enable this module in your doom! block. (add (meow +your-desired-flags...) after the :editor section in init.el)

After you doom sync and restart Emacs, Meow will start in Normal state, so make sure that bindings have been set up; see Module flags.

The leader and localleader bindings are defined in <a href=”doom-module::config default +bindings”>doom-module::config default +bindings, so that module is required for them to work.

This module will not work smoothly with doom-module::editor evil, doom-module::editor god, or doom-module::editor objed. You must disable those modules in your doom! block to use this one.

Usage

󱌣 This module’s usage documentation is incomplete. Complete it?

Please refer to Meow’s docs for any information not related to Doom or this module.

Leader and localleader integration

This module configures Meow’s Keypad state such that it can be used to access Doom’s leader/localleader bindings, as set up by <a href=”doom-module::config default +bindings”>doom-module::config default +bindings. Note that since this module cannot be used with Evil, you’ll be using Doom’s Emacs leader/localleader bindings (emacsdir:modules/config/default/+emacs-bindings.el), which are not the same as its Evil ones.

As described in Meow’s documentation, when a key other than x / h / c / m / g is pressed in Keypad state, it is directly looked up in the leader keymap. This module sets doom-leader-map (bound to C-c by default) as the leader keymap. So, for example, SPC s p produces C-c s p.

Some tweaks were necessary in order to accomodate the differences of Keypad state -

• doom-leader-code-map is bound to k, as c is taken by Keypad.
• Localleader is bound to l, as m is taken.

Configuration

Cursor

In Emacs, the cursor is always considered to be located between two characters. In Vim, the cursor is always considered to be on top of a character. Evil manages to accomplish the latter behavior, but Meow does not attempt to do so. In order to help Evil/Vim users adjust, this module includes a custom cursor configuration -

• The ‘bar’ cursor shape is used in most cases, as it sits between two characters. You can change this by setting any of the meow-cursor-type-* variables.
• Since we don’t use the block cursor shape to indicate Normal state, we instead blink the cursor to indicate when we’re in Insert state. You can disable this by setting +meow-want-blink-cursor-in-insert to nil.

Disabling bindings for certain modes

In modes that bind unmodified keys, Meow starts in ‘Motion’ state. The default bindings for Motion state (with +qwerty) bind j and k to next-line and previous-line, respectively; and SPC triggers Keypad state. This is only useful in modes where moving over lines is a meaningful concept, and SPC doesn’t have an important binding.

For modes that don’t fit the above description, this module defines a custom ‘Emacs’ state. This state has only two bindings - M-SPC to trigger Keypad (this binding is also added in Insert state), and C-] to switch to Motion state. Once in Motion state, you can use C-] to switch to Meow’s ‘temp Normal’ state if you need more of Meow’s bindings.

For example, to make pdf-view-mode start in Emacs state:

;; in $DOOMDIR/config.el
(add-to-list 'meow-mode-state-list '(pdf-view-mode . emacs))

Disabling expansion hints for some modes

The expansion hints are known to work poorly with variable-width fonts (see this issue). If you encounter this problem, you should disable them for the modes in which you use those fonts -

;; in $DOOMDIR/config.el
;; For example, to disable expansion hints in org-mode -
(add-to-list 'meow-expand-exclude-mode-list 'org-mode)

map! vs meow-define-keys

Doom’s map! and Meow’s meow-define-keys are largely equivalent in terms of functionality. (map! :map meow-normal-state-keymap ...) and (meow-define-keys 'normal ...) (and (meow-normal-define-keys ...)) will do the same thing, as far as this author is aware.

There is one exception - when binding a key to another key, meow-define-keys generates a command to execute that key, and binds to that. map! doesn’t explicitly support binding a key to another key, and when you try it, it binds the key directly without a command wrapping it. This binding seems to get overridden by any command bound to the same key.

Troubleshooting

Report an issue?

Prefix key descriptions in which-key popup

These do not show up properly when Keypad state is used. It is unclear where to look for the source of the problem. The previous module also had this issue.

Undo and doom-package:undo-fu

Meow’s meow-undo expects the command bound to meow--kbd-undo (default C-/) to behave like Emacs’ built-in undo command. Undo-Fu remaps this command to undo-fu-only-undo, which behaves differently, so meow-undo doesn’t work properly. Currently, the only workaround is to stop using Undo-Fu and learn Emacs’ default undo mechanism:

;; In $DOOMDIR/packages.el
(package! undo-fu :disable t)

Frequently asked questions

Mode-specific/state-specific Meow bindings

Unlike Evil, Meow does not directly support keybindings specific to a particular mode or state. For example, there is no (direct) way to make TAB do one thing in org-mode and another in emacs-lisp-mode. This is an intentional limitation; see this issue comment for a discussion, and the recommended way of achieving this kind of functionality.

Appendix

󱌣 This module has no appendix yet. Write one?