Repository files navigation

This module integratesMeow 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, withcursor-blink-mode rather than a shape change to indicate a switch to Insert state;
• A customemacs 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 readMeow’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).

+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; seethe relevant docs.

You will probably want to look at the files responsible for defining the bindings (in this module’sautoload/ 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.

• doom-package:meow

• The localleader bindings are accomplished via a hack.

This module does not have a changelog yet.

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

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

After youdoom sync and restart Emacs, Meow will start in Normal state, so make sure that bindings have been set up; seeModule 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 yourdoom! block to use this one.

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

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

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 describedin Meow’s documentation, when a key other thanx /h /c /m /g is pressed in Keypad state, it is directly looked up in the leader keymap. This module setsdoom-leader-map (bound toC-c by default) as the leader keymap. So, for example,SPC s p producesC-c s p.

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

• doom-leader-code-map is bound tok, asc is taken by Keypad.
• Localleader is bound tol, asm is taken.

In Emacs, the cursor is always considered to be locatedbetween two characters. In Vim, the cursor is always considered to beon top of a character. Evil manages to accomplish the latter behavior, but Meowdoes 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 themeow-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 tonil.

In modes that bind unmodified keys, Meow starts in ‘Motion’ state. The default bindings for Motion state (with+qwerty) bindj andk tonext-line andprevious-line, respectively; andSPC triggers Keypad state. This is only useful in modes where moving over lines is a meaningful concept, andSPC 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), andC-] to switch to Motion state. Once in Motion state, you can useC-] to switch to Meow’s ‘temp Normal’ state if you need more of Meow’s bindings.

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

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

The expansion hints are known to work poorly with variable-width fonts (seethis 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)

Doom’smap! and Meow’smeow-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.

Report an issue?

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 hadthis issue.

Meow’smeow-undo expects the command bound tomeow--kbd-undo (defaultC-/) to behave like Emacs’ built-inundo command. Undo-Fu remaps this command toundo-fu-only-undo, which behaves differently, someow-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:disablet)

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

󱌣 This module has no appendix yet. Write one?