242 lines
9.7 KiB
Markdown
242 lines
9.7 KiB
Markdown
#Vim Better Whitespace Plugin
|
|
|
|
This plugin causes all trailing whitespace characters (see [Supported Whitespace Characters](#supported-whitespace-characters) below) to be
|
|
highlighted. Whitespace for the current line will not be highlighted
|
|
while in insert mode. It is possible to disable current line highlighting while in other
|
|
modes as well (see options below). A helper function `:StripWhitespace` is also provided
|
|
to make whitespace cleaning painless.
|
|
|
|
Here is a screenshot of this plugin at work:
|
|
|
|
|
|
##Installation
|
|
There are a few ways you can go about installing this plugin:
|
|
|
|
1. If you have [Vundle](https://github.com/gmarik/Vundle.vim) you can simply add:
|
|
```
|
|
Plugin 'ntpeters/vim-better-whitespace'
|
|
```
|
|
to your `.vimrc` file then run:
|
|
```
|
|
:PluginInstall
|
|
```
|
|
2. If you are using [Pathogen](https://github.com/tpope/vim-pathogen), you can just run the following command:
|
|
```
|
|
git clone git://github.com/ntpeters/vim-better-whitespace.git ~/.vim/bundle/vim-better-whitespace
|
|
```
|
|
3. While this plugin can also be installed by copying its contents into your `~/.vim/` directory, I would highly recommend using one of the above methods as they make managing your Vim plugins painless.
|
|
|
|
##Usage
|
|
Whitespace highlighting is enabled by default, with a highlight color of red.
|
|
|
|
* To set a custom highlight color, just call:
|
|
```
|
|
highlight ExtraWhitespace ctermbg=<desired_color>
|
|
```
|
|
|
|
* To toggle whitespace highlighting on/off, call:
|
|
```
|
|
:ToggleWhitespace
|
|
```
|
|
|
|
* To disable highlighting for the current line in normal mode call:
|
|
```
|
|
:CurrentLineWhitespaceOff <level>
|
|
```
|
|
Where `<level>` is either `hard` or `soft`.
|
|
|
|
* The level `hard` will maintain whitespace highlighting as it is, but may
|
|
cause a slow down in Vim since it uses the CursorMoved event to detect and
|
|
exclude the current line.
|
|
|
|
* The level `soft` will use syntax based highlighting, so there shouldn't be
|
|
a performance hit like with the `hard` option. The drawback is that this
|
|
highlighting will have a lower priority and may be overwritten by higher
|
|
priority highlighting.
|
|
|
|
* To re-enable highlighting for the current line in normal mode:
|
|
```
|
|
:CurrentLineWhitespaceOn
|
|
```
|
|
|
|
* To clean extra whitespace, call:
|
|
```
|
|
:StripWhitespace
|
|
```
|
|
By default this operates on the entire file. To restrict the portion of
|
|
the file that it cleans, either give it a range or select a group of lines
|
|
in visual mode and then execute it.
|
|
|
|
* To enable/disable stripping of extra whitespace on file save, call:
|
|
```
|
|
:ToggleStripWhitespaceOnSave
|
|
```
|
|
This will strip all trailing whitespace everytime you save the file for all file types.
|
|
|
|
* If you want this behaviour by default for all filetypes, add the following to your `~/.vimrc`:
|
|
|
|
```
|
|
autocmd BufEnter * EnableStripWhitespaceOnSave
|
|
```
|
|
|
|
For exceptions of all see ```g:better_whitespace_filetypes_blacklist```.
|
|
|
|
* If you would prefer to only strip whitespace for certain filetypes, add
|
|
the following to your `~/.vimrc`:
|
|
|
|
```
|
|
autocmd FileType <desired_filetypes> autocmd BufEnter <buffer> EnableStripWhitespaceOnSave
|
|
```
|
|
|
|
where `<desired_filetypes>` is a comma separated list of the file types you want
|
|
to be stripped of whitespace on file save ( ie. `javascript,c,cpp,java,html,ruby` )
|
|
Note that `<buffer>` is a keyword here denoting operation on the current buffer and
|
|
should stay just as it appears in the line above.
|
|
|
|
* To disable this plugin for specific file types, add the following to your `~/.vimrc`:
|
|
```
|
|
let g:better_whitespace_filetypes_blacklist=['<filetype1>', '<filetype2>', '<etc>']
|
|
```
|
|
This replaces the filetypes from the default list of blacklisted filetypes. The
|
|
default types that are blacklisted are:
|
|
```
|
|
['diff', 'gitcommit', 'unite', 'qf', 'help', 'markdown']
|
|
```
|
|
If you do not want any of these filetypes unignored, simply include them in the
|
|
blacklist:
|
|
```
|
|
let g:better_whitespace_filetypes_blacklist=['<filetype1>', '<filetype2>', '<etc>',
|
|
'diff', 'gitcommit', 'unite', 'qf', 'help']
|
|
```
|
|
|
|
* To enable verbose output for each command, set verbosity in your `.vimrc`:
|
|
```
|
|
let g:better_whitespace_verbosity=1
|
|
```
|
|
|
|
##Supported Whitespace Characters
|
|
Due to the fact that the built-in whitespace character class for patterns (`\s`)
|
|
only matches against tabs and spaces, this plugin defines its own list of
|
|
horizontal whitepsace characters to match for both highlighting and stripping.
|
|
|
|
This is list should match against all ASCII and Unicode horizontal whitespace
|
|
characters:
|
|
```
|
|
U+0009 TAB
|
|
U+0020 SPACE
|
|
U+00A0 NO-BREAK SPACE
|
|
U+1680 OGHAM SPACE MARK
|
|
U+180E MONGOLIAN VOWEL SEPARATOR
|
|
U+2000 EN QUAD
|
|
U+2001 EM QUAD
|
|
U+2002 EN SPACE
|
|
U+2003 EM SPACE
|
|
U+2004 THREE-PER-EM SPACE
|
|
U+2005 FOUR-PER-EM SPACE
|
|
U+2006 SIX-PER-EM SPACE
|
|
U+2007 FIGURE SPACE
|
|
U+2008 PUNCTUATION SPACE
|
|
U+2009 THIN SPACE
|
|
U+200A HAIR SPACE
|
|
U+200B ZERO WIDTH SPACE
|
|
U+202F NARROW NO-BREAK SPACE
|
|
U+205F MEDIUM MATHEMATICAL SPACE
|
|
U+3000 IDEOGRAPHIC SPACE
|
|
U+FEFF ZERO WIDTH NO-BREAK SPACE
|
|
```
|
|
|
|
A file is provided with samples of each of these characters to check the plugin
|
|
working with them: whitespace_examples.txt
|
|
|
|
If you encounter any additional whitespace characters I have missed here,
|
|
please submit a pull request.
|
|
|
|
##Screenshots
|
|
Here are a couple more screenshots of the plugin at work.
|
|
|
|
This screenshot shows the current line not being highlighted in insert mode:
|
|
|
|
|
|
This screenshot shows the current line not being highlighted in normal mode( `CurrentLineWhitespaceOff hard` ):
|
|
|
|
|
|
This screenshot shows that highlighting works fine for spaces, tabs, and a mixture of both:
|
|
|
|
|
|
##Frequently Asked Questions
|
|
Hopefully some of the most common questions will be answered here. If you still have a question
|
|
that I have failed to address, please open an issue and ask it!
|
|
|
|
**Q: Why is trailing whitespace such a big deal?**
|
|
|
|
A: In most cases it is not a syntactical issue, but rather is a common annoyance among
|
|
programmers.
|
|
|
|
|
|
**Q: Why not just use `listchars` with `SpecialKey` highlighting?**
|
|
|
|
A: I tried using `listchars` to show trail characters with `SpecialKey` highlighting applied.
|
|
Using this method the characters would still show on the current line for me even when the
|
|
`SpecialKey` foreground highlight matched the `CursorLine` background highlight.
|
|
|
|
|
|
**Q: Okay, so `listchars` doesn't do exactly what you want, why not just use a `match` in your `vimrc`?**
|
|
|
|
A: I am using `match` in this plugin, but I've also added a way to exclude the current line in
|
|
insert mode and/or normal mode.
|
|
|
|
|
|
**Q: If you just want to exclude the current line, why not just use syntax-based highlight rather
|
|
than using `match` and `CursorMoved` events?**
|
|
|
|
A: Syntax-based highlighting is an option in this plugin. It is used to omit the current line when
|
|
using `CurrentLineWhitespaceOff soft`. The only issue with this method is that `match` highlighing
|
|
takes higher priorty than syntax highlighting. For example, when using a plugin such as
|
|
[Indent Guides](https://github.com/nathanaelkane/vim-indent-guides), syntax-based highlighting of
|
|
extra whitespace will not highlight additional white space on emtpy lines.
|
|
|
|
|
|
**Q: I already have my own method of removing white space, why is the method used in this plugin better?**
|
|
|
|
A: It may not be, depending on the method you are using. The method used in this plugin strips extra
|
|
white space and then restores the cursor position and last search history.
|
|
|
|
|
|
**Q: Most of this is pretty easy to just add to users' `vimrc` files. Why make it a plugin?**
|
|
|
|
A: It is true that a large part of this is fairly simple to make a part of an individuals
|
|
configuration in their `vimrc`. I wanted to provide something that is easy to setup and use
|
|
for both those new to Vim and others who don't want to mess around setting up this
|
|
functionality in their `vimrc`.
|
|
|
|
**Q: Can you add indentation highlighting for spaces/tabs? Can you add highlighting for other
|
|
types of white space?**
|
|
|
|
A: No, and no. Sorry, but both are outside the scope of this plugin. The purpose of this plugin
|
|
is to provide a better experience for showing and dealing with extra white space. There is
|
|
already an amazing plugin for showing indentation in Vim called [Indent Guides](https://github.com/nathanaelkane/vim-indent-guides).
|
|
For other types of white space highlighting, [listchars](http://vimdoc.sourceforge.net/htmldoc/options.html#'listchars') should be sufficient.
|
|
|
|
**Q: I have a better way to do something in this plugin. OR You're doing something stupid/wrong/bad.**
|
|
|
|
A: If you know of a better way to do something I am attempting in this plugin, or if I am doing
|
|
something improperly/not reccomended then let me know! Please either open an issue informing
|
|
me or make the changes yourself and open a pull request. If I am doing something that is bad
|
|
or can be improved, I more than willing to hear about it!
|
|
|
|
##Promotion
|
|
If you like this plugin, please star it on Github and vote it up at Vim.org!
|
|
|
|
Repository exists at: http://github.com/ntpeters/vim-better-whitespace
|
|
|
|
Plugin also hosted at: http://www.vim.org/scripts/script.php?script_id=4859
|
|
|
|
##Credits
|
|
Originally inspired by: https://github.com/bronson/vim-trailing-whitespace
|
|
|
|
Based on:
|
|
|
|
http://sartak.org/2011/03/end-of-line-whitespace-in-vim.html
|
|
|
|
http://vim.wikia.com/wiki/Highlight_unwanted_spaces
|