path: root/doc/ShowTrailingWhitespace.txt
diff options
Diffstat (limited to 'doc/ShowTrailingWhitespace.txt')
1 files changed, 162 insertions, 0 deletions
diff --git a/doc/ShowTrailingWhitespace.txt b/doc/ShowTrailingWhitespace.txt
new file mode 100644
index 0000000..9d3f861
--- /dev/null
+++ b/doc/ShowTrailingWhitespace.txt
@@ -0,0 +1,162 @@
+*ShowTrailingWhitespace.txt* Detect unwanted whitespace at the end of lines.
+ *ShowTrailingWhitespace.vim*
+description |ShowTrailingWhitespace-description|
+usage |ShowTrailingWhitespace-usage|
+installation |ShowTrailingWhitespace-installation|
+configuration |ShowTrailingWhitespace-configuration|
+integration |ShowTrailingWhitespace-integration|
+limitations |ShowTrailingWhitespace-limitations|
+known problems |ShowTrailingWhitespace-known-problems|
+todo |ShowTrailingWhitespace-todo|
+history |ShowTrailingWhitespace-history|
+DESCRIPTION *ShowTrailingWhitespace-description*
+This plugin highlights whitespace at the end of each line (except when typing
+at the end of a line). It uses the matchadd()-function, therefore doesn't
+interfere with syntax highlighting and leaves the |:match| command for other
+Highlighting can be switched on/off globally and for individual buffers. The
+plugin comes with exceptions for certain filetypes, where certain lines can /
+must include trailing whitespace; additional patterns can be configured.
+There are already a number of plugins for this purpose, most based on this
+However, most of them use the older :match command and are not as flexible.
+- smartmatcheol.vim (vimscript #2635) highlights based on file extension or
+ name.
+- trailing-whitespace (vimscript #3201) uses :match.
+- bad-whitespace (vimscript #3735) uses :match, allows on/off/toggling via
+ commands.
+- Trailer Trash (vimscript #3938) uses :match.
+- DynamicSigns (vimscript #3965) can show whitespace errors (also mixed
+ indent) in the sign column.
+Many plugins also come with a command to strip off the trailing whitespace;
+this plugin separates this into the companion |DeleteTrailingWhitespace.vim|
+plugin (vimscript #0000), which can even remove the trailing whitespace
+automatically on each write.
+To quickly locate the occurrences of trailing whitespace, you can use the
+companion |JumpToTrailingWhitespace.vim| plugin (vimscript #0000).
+USAGE *ShowTrailingWhitespace-usage*
+By default, trailing whitespace is highlighted in all Vim buffers. Some users
+may want to selectively enable / disable this for certain filetypes, or files
+in a particular directory hierarchy, or toggle this on demand. Since it's
+difficult to accommodate all these demands with short and easy mappings and
+commands, this plugin does not define any of them, and leaves it to you to
+tailor the plugin to your needs. See |ShowTrailingWhitespace-configuration|
+INSTALLATION *ShowTrailingWhitespace-installation*
+This script is packaged as a |vimball|. If you have the "gunzip" decompressor
+in your PATH, simply edit the *.vba.gz package in Vim; otherwise, decompress
+the archive first, e.g. using WinZip. Inside Vim, install by sourcing the
+vimball or via the |:UseVimball| command. >
+ vim ShowTrailingWhitespace.vba.gz
+ :so %
+To uninstall, use the |:RmVimball| command.
+DEPENDENCIES *ShowTrailingWhitespace-dependencies*
+- Requires Vim 7.1 with "matchadd()", or Vim 7.2 or higher.
+CONFIGURATION *ShowTrailingWhitespace-configuration*
+For a permanent configuration, put the following commands into your |vimrc|:
+ *ShowTrailingWhitespace-colors*
+To change the highlighting colors: >
+ highlight ShowTrailingWhitespace Error ctermbg=Red guibg=Red
+ *g:ShowTrailingWhitespace*
+By default, highlighting is enabled for all buffers, and you can (selectively)
+disable it. To work from the opposite premise, launch Vim with highlighting
+disabled: >
+ let g:ShowTrailingWhitespace = 0
+ *g:ShowTrailingWhitespace_FilterFunc*
+In addition to toggling the highlighting on/off via
+|g:ShowTrailingWhitespace|, the decision can also be influenced by buffer
+settings or the environment. By default, buffers that are not persisted to
+disk (unless they are scratch buffers) or not modifiable (like user interface
+windows from various plugins) are skipped. You can disable this filtering: >
+ let g:ShowTrailingWhitespace_FilterFunc = ''
+or install your own custom filter function instead: >
+ let g:ShowTrailingWhitespace_FilterFunc = function('MyFunc')
+ *ShowTrailingWhitespace-commands*
+Highlighting can be enabled / disabled globally and for individual buffers.
+Analog to the |:set| and |:setlocal| commands, you can define the following
+commands: >
+ command! -bar ShowTrailingWhitespaceOn call ShowTrailingWhitespace#Set(1,1)
+ command! -bar ShowTrailingWhitespaceOff call ShowTrailingWhitespace#Set(0,1)
+ command! -bar ShowTrailingWhitespaceBufferOn call ShowTrailingWhitespace#Set(1,0)
+ command! -bar ShowTrailingWhitespaceBufferOff call ShowTrailingWhitespace#Set(0,0)
+To set the local highlighting back to its global value (like :set {option}<
+does), the following command can be defined: >
+ command! -bar ShowTrailingWhitespaceBufferClear call ShowTrailingWhitespace#Reset()
+ *ShowTrailingWhitespace-mappings*
+You can also define a quick mapping to toggle the highlighting (here, locally;
+for global toggling use ShowTrailingWhitespace#Toggle(1): >
+ nnoremap <silent> <Leader>t$ :<C-u>call ShowTrailingWhitespace#Toggle(0)<Bar>echo (ShowTrailingWhitespace#IsSet() ? 'Show trailing whitespace' : 'Not showing trailing whitespace')<CR>
+ *ShowTrailingWhitespace-exceptions*
+For some filetypes, in certain places, trailing whitespace is part of the
+syntax or even mandatory. If you don't want to be bothered by these showing up
+as false positives, you can augment the regular expression so that these
+places do not match. The ShowTrailingWhitespace#SetLocalExtraPattern()
+function takes a regular expression that is prepended to the pattern for the
+trailing whitespace. For a certain filetype, this is best set in a file
+ ftplugin/{filetype}_ShowTrailingWhitespace.vim
+INTEGRATION *ShowTrailingWhitespace-integration*
+ *ShowTrailingWhitespace-functions*
+The ShowTrailingWhitespace#IsSet() function can be used to query the on/off
+status for the current buffer, e.g. for use in the |statusline|.
+To obtain the pattern for matching trailing whitespace, including any
+|ShowTrailingWhitespace-exceptions|, you can use the function
+LIMITATIONS *ShowTrailingWhitespace-limitations*
+KNOWN PROBLEMS *ShowTrailingWhitespace-known-problems*
+TODO *ShowTrailingWhitespace-todo*
+IDEAS *ShowTrailingWhitespace-ideas*
+HISTORY *ShowTrailingWhitespace-history*
+1.00 16-Mar-2012
+First published version.
+0.01 25-Feb-2012
+Started development.
+Copyright: (C) 2012 Ingo Karkat
+The VIM LICENSE applies to this script; see |copyright|.
+Maintainer: Ingo Karkat <>
+ vim:tw=78:ts=8:ft=help:norl: