diff options
Diffstat (limited to 'doc/ShowTrailingWhitespace.txt')
| -rw-r--r-- | doc/ShowTrailingWhitespace.txt | 162 |
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. + + SHOW TRAILING WHITESPACE by Ingo Karkat + *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 +uses. +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. + +RELATED WORKS * + +There are already a number of plugins for this purpose, most based on this +VimTip: + http://vim.wikia.com/wiki/Highlight_unwanted_spaces +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| +below. + +============================================================================== +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 +ShowTrailingWhitespace#Pattern(0). + +============================================================================== +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 <ingo@karkat.de> +============================================================================== + vim:tw=78:ts=8:ft=help:norl: |