orivej/ethan-wspace

ethan-wspace

Presenting, with tongue firmly in cheek: ethan-wspace, the definitive emacs customizations for people who are OCD about whitespace.

It is BSD licensed and currently only 44 kb. You really have no reason not to use it.

Motivation

You may have some opinions about whitespace in your source code. They may even amount to preferences. However, it takes a seriously twisted person to think about whitespace obsessively. I have. Unless you demonstrate that you are OCD enough to think about these things for hours, I will conclude that I know more about these things than you do. And I will be right.

No matter how many opinions you have, I have more. And that makes mine more correct.

So what?

You're probably thinking, "Who cares?" And you'd be right. I sincerely doubt using these customizations will make your life as a programmer even 1% more productive. 1% is nothing. You'd do better to buy a bigger monitor.

So then, why be OCD about whitespace? It boils down to one essential thing: diffs like these.

$ git diff
diff --git a/foo.c b/foo.c
index 7be6eb3..8ba98ba 100644
--- a/foo.c
+++ b/foo.c
@@ -1,6 +1,6 @@
 #include <stdio.h>

-int main(){
+int main(){
   printf("hello world\n");
   return 0;
 }

What's going on in this diff? Take a few minutes to study it and figure out what's going on. What did I change? It doesn't look like I changed anything! But in fact there's a diff, so there must be some change, right?

The answer is that I either introduced or removed whitespace at the end of the line. git diff will highlight, in red, trailing whitespace like this that you added, but not that you took away. (P.S. ReStructuredText is removing the trailing whitespace from the example, but if you look at the rst source you will see that it is there.)

Reviewing diffs with whitespace changes is annoying. Trying to guess what the whitespace changes were, so you can undo the whitespace changes, is downright tedious. Ideally you should never have to do these things.

ethan-wspace can help.

What does it do?

ethan-wspace takes the approach of do no harm. Specifically, when you open a file:

If the whitespace is already clean, ethan-wspace inserts hooks to clean the whitespace before every save.
If the whitespace is not already clean, ethan-wspace highlights errors. It doesn't clean the whitespace without you asking for it, so you don't get spurious whitespace changes in your diffs. It doesn't prevent you from introducing new errors, but hopefully you will be cognizant of the errors in the file.

ethan-wspace recognizes the following categories of whitespace errors:

trailing whitespace at end of line (eol).
no trailing newline (no-nl-eof).
more than one trailing newline (many-nls-eof).
tabs, at all (tabs).

It recognizes these categories independently, and treats each category as clean or not-clean. The goal is always to make your diffs unambiguous. Laudable goal, right?

ethan-wspace also has one other fancy feature. If you are editing some line, and are writing something at the end of it, and have added some spaces, but your cursor is just after those spaces, the spaces aren't considered "trailing" yet. They won't be highlit if you are in highlight-eol-mode. If you are in clean-eol-mode, and you should save the buffer, the spaces will be cleaned, the buffer will be saved, and the spaces will be re-added for your convenience[1]. Similar behavior exists for newlines-at-end-of-file.

[1]	This may have the surprising behavior that your file appears "clean" even though its contents are not exactly what is on disk.

My tabs! Get your hands off my tabs!

It is my opinion (and remember, my opinions are right) that you should never, ever have tabs in your source code, at all. This was once a holy war, but in my experience, pretty much everybody today understands this point and the reasoning behind it. If you disagree, please see Tabs Are Evil on the EmacsWiki.

One notable exception to this situation is if you are unfortunate enough to have to work with Makefiles. In these files, tabs are essential. You can tell ethan-wspace to stop caring about tabs at all in this context using configuration like the following:

(defun makefile-tabs-are-less-evil ()
  (setq ethan-wspace-errors (remove 'tabs ethan-wspace-errors)))
(add-hook 'makefile-mode-hook 'makefile-tabs-are-less-evil)

Perhaps you are one of those bizarre creatures who uses Smart Tabs. In that case, you are even more OCD about whitespace than I am, and in a twisted way I salute you. However, ethan-wspace by default treats tabs as errors, which you might find distracting. In that case, I recommend something like the following:

(set-default 'ethan-wspace-errors (remove 'tabs ethan-wspace-errors))

How to use it

N.B. There's now a recipe for ethan-wspace in el-get! To use it, add something like the following to your el-get-sources:

(:name ethan-wspace
       :after (lambda () (global-ethan-wspace-mode 1)))

If you're not using el-get, you need to manually make sure to add the lisp directory to your load-path, and then (require 'ethan-wspace). In other words, add to your init.el something like the following:

(add-to-list 'load-path (expand-file-name "~/.emacs.d/upstream/ethan-wspace.git/lisp"))
(require 'ethan-wspace)
(global-ethan-wspace-mode 1)

You should also remove any customizations you have made to turn on either show-trailing-whitespace or require-final-newline; we handle those for you. (But note that require-final-newline is turned on by some modes based on the value of mode-require-final-newline, so you may have to turn that off.)

(custom-set-variable
  '(mode-require-final-newline nil))

When you open files (N.B. but not non-file buffers), bad whitespace will be highlit and clean whitespace will be maintained by cleaning just before files are saved. You can switch from one to the other using M-x ethan-wspace-highlight-FOO-mode or M-x ethan-wspace-clean-FOO-mode (each mode disables the other). If you want to clean all kinds of whitespace, you can use M-x ethan-wspace-clean-all, which immediately cleans everything and switches to clean-before-save on all whitespace types.

There's also a mode line "lighter" for ethan-wspace which looks something like ew:mnLt. Lower case letters indicate categories of whitespace which will be cleaned before save; upper case letters indicate categories which are being highlit. You can click on a particular letter to change from one to the other.

You might also want to customize the face used to highlight erroneous whitespace. This is configurable by ethan-wspace-face. A default face is computed based on the background of your frame when ethan-wspace was required (so you might want to make your calls to color-theme first).

Relationship to other emacs things

Most other emacs whitespace customizations (and there are many: see ShowWhiteSpace on the EmacsWiki) focus on showing problematic whitespace. There are also some customizations out there focused on Deleting Whitespace. But there are many and they all have extremely similar names. (ethan-wspace aims to be the most egotistically-named package.) ethan-wspace subsumes most of them, except for whitespace.el to show all whitespace in non-programming contexts, and ws-trim.el which I had never heard of before just now.

whitespace.el and the family of related code that includes visws.el, whitespace-mode.el, show-whitespace-mode.el, and blank-mode.el has many options for making whitespace characters visible, both by faces and by changing their representations in the display table. That seems very useful for editing binary files or other circumstances where you care exactly what whitespace you're looking at, but it isn't really useful for editing source code, where you typically want whitespace to be as clean as possible. I have no idea which of those files is most recent or "best", as I have never used them.
ws-trim.el automatically trims whitespace on edited lines. With a low ws-trim-level it is complementary to ethan-wspace, and may be useful to encourage you to delete whitespace organically. I'd never heard about this package and hopefully ethan-wspace will grow similar functionality soon.
ws-butler automatically trims whitespace on edited lines too, like an improved ws-trim.
Putting delete-trailing-whitespace or nuke-trailing-whitespace in your before-save-hook is now obsolete; these functions are too aggressive and will cause you many spurious whitespace commits.
Standard emacs variables show-trailing-whitespace and require-final-newline are "subsumed" by this mode -- require-final-newline is reimplemented in a more general way, and show-trailing-whitespace is triggered per-buffer by this mode. (show-trailing-whitespace is built into emacs core and seems to be the fastest/most elegant way to highlight trailing whitespace.)
next-line-add-newlines, to add newlines when you move forward lines, still exists and is unchanged. I recommend you set this to nil (if it isn't already -- I think it is nil in all versions since 21.1), but ethan-wspace will still trim unnecessary newlines on each save if there were fewer than two when the buffer was opened.
redspace.el is a small library meant only to highlight trailing whitespace. This is already done by the variable show-trailing-whitespace, which is used internally by ethan-wspace. show-trailing-whitespace has the nice effect that it doesn't highlight trailing whitespace when your cursor is after it -- so you don't see little blinking lights as you type a line of text.
show-wspace.el is a library that has lots of faces to show tabs, trailing whitespace, and "hard spaces". ethan-wspace obsoletes this mode too.

More ranting about Tabs Are Evil

Required reading for this discussion is JWZ's "famous" tabs versus spaces post. He sets out three categories of effect that tabs have, and how to defuse the whole situation.

I have encountered people who prefer tabs because they prefer being able to press backspace and go exactly one level of indentation back. These people are obviously wrong because if you're using a halfway decent editor, it should be capable of indenting CORRECTLY for you automatically (i.e. emacs's TAB behavior), as well as backspacing a whole level in languages where that's useful (i.e. emacs's python-backspace). So this argument just boils down to "I have a crappy text editor."

You may encounter people who say things like, "Tabs are better because they let everybody set their own indentation width." And this is true to a point. If you are one of those people, pop quiz: let's say you use tabs, and prefer them to be four spaces wide. How do you indent the last line of this code?

if __name__ == '__main__':
    main.Application(config, sys.argv, time.time(),
                     docutils.parsers.rst.directives.images.Image)

If you said "five tabs, one space" -- you lose. Because then when you move to Jan's machine, where tabs are two spaces, you find:

if __name__ == '__main__':
    main.Application(config, sys.argv, time.time(),
           docutils.parsers.rst.directives.images.Image)

And on Johann's machine, where tabs are eight spaces, you see:

if __name__ == '__main__':
    main.Application(config, sys.argv, time.time(),
                               docutils.parsers.rst.directives.images.Image)

Your beautifully-indented source code has been scattered to the winds. You've just demonstrated that you aren't crazy enough to think about whitespace issues obsessively enough. Rejoice! There is a place for you in normal society.

It's due to code above that truly demented people will suggest using tabs for blocks only and spaces within blocks. I've seen this rule propounded on Reddit, for example. In the above code, that gives you "one tab, seventeen spaces". I've never tried this approach on a real project, for the simple fact that people are lazy and source-code editors are imperfect, and somewhere, somehow, I am certain to come across spaces where there should be tabs, or tabs where there should be spaces. And then I will be furious.

(If I worked on a project with a team of sharpshooter programmers who all agreed on the tabs-for-scope-plus-spaces-for-alignment rule, I'd investigate configuring emacs to do this. But until then I rely on the far easier expedient of just outlawing tabs in source code entirely and consigning them to the dustbin of history.)

orivej / ethan-wspace