Emacs: How to Turn a Minor Mode on/off/toggle?

Perm url with updates: http://xahlee.org/emacs/emacs-tip_mode_on_off_toggle.html

Emacs: How to Turn a Minor Mode on/off/toggle?

Xah Lee, 2010-03-20, 2010-07-11

This page is a short tutorial on how to turn a emacs mode on, off, or toggle.

You know, in emacs, “t” is true, and “nil” is false. So, for example, if you want to turn off a minor mode always, you might put this in your emacs init file:

;; turn off some modes?
(desktop-save-mode nil) ;  WRONG!
(cua-mode nil) ;  WRONG!


Why is it wrong?

Yes, “t” is true and “nil” is false, but for modes, the proper way is to use “1” to turn it on, and “0” to turn it off. Why? Because a mode function isn't designed to take a true or false value as argument. Because, for example, most minor mode need to also act like a toggle. For example, typing “Alt+x auto-fill-mode” will toggle it.

So, the design is that, for minor modes, a positive number is to turn it on, 0 or negative number is to turn it off. To toggle, no argument will do (no argument is equivalent to a argument of “nil”). When you need to be absolutely sure, look up the inline doc of the mode. For example, type “Ctrl+h auto-fill-mode”.

;; turn on
(desktop-save-mode 1) ; correct!

;; turn off
(auto-fill-mode 0) ; correct!

When you put “(auto-fill-mode)” in your emacs init file, usually it still works, because by default it is off, and “(auto-fill-mode)” toggles the state from off to on, so in the end it is still on. But some days or years later when you have added packages or code, things will go south and you'll scratch your head and wonder what's going on.

Now look in your emacs init file and fix them all!


For minor modes, a argument of t will always turn it on, even though this seems to contradict what the inline doc says. For example, here's a quote from auto-fill-mode:

(auto-fill-mode &optional ARG)

Toggle Auto Fill mode.
With ARG, turn Auto Fill mode on if and only if ARG is positive.

As of today (emacs 23.2.x), for most or all minor modes, no arg or a nil arg will toggle the mode.

According to Stefan Monnier (one of the current emacs maintainer) in a post in comp.emacs on 2010-06-16 (Source) , this behavior may change in future emacs because it is too confusing. “t” will always turn it on, “nil” turns it off always. For toggling, i'm guessing there'll be extra function with “toggle” in the name, e.g. toggle-read-only, toggle-case-fold-search, toggle-debug-on-error, toggle-text-mode-auto-fill, toggle-truncate-lines, ...

(thanks to YOO for correcting me about the actual behavior of “(auto-fill-mode t)”.)


Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs