*diffchar.txt*  Highlight the exact differences, based on characters and words
>
  ____   _  ____  ____  _____  _   _  _____  ____   
 |    | | ||    ||    ||     || | | ||  _  ||  _ |  
 |  _  || ||  __||  __||     || | | || | | || | ||  
 | | | || || |__ | |__ |   __|| |_| || |_| || |_||_ 
 | |_| || ||  __||  __||  |   |     ||     ||  __  |
 |     || || |   | |   |  |__ |  _  ||  _  || |  | |
 |____| |_||_|   |_|   |_____||_| |_||_| |_||_|  |_|
<
Last Change:	2019/08/28
Version:	8.6
Author:		Rick Howe <rdcxy754@ybb.ne.jp>
Copyright:	(c) 2014-2019 by Rick Howe

-----------------------------------------------------------------------------
INTRODUCTION                                           *diffchar*

This plugin has been developed in order to make diff mode more useful. Vim
highlights all the text in between the first and last different characters on
a changed line. But this plugin will find the exact differences between them,
character by character - so called DiffChar.

For example, in diff mode: ([|hl-DiffText|], <|hl-DiffAdd|>)
>
    (window A) The [quick brown fox jumps over the lazy] dog.
    (window B) The [lazy fox jumps over the quick brown] dog.
<
this plugin will exactly show the changed and added units:
>
    (window A) The [quick] <brown >fox jumps over the [lazy] dog.
    (window B) The [lazy] fox jumps over the [quick] <brown >dog.
<
This plugin will synchronously show/reset the highlights of the exact
differences as soon as the diff mode begins/ends since a |g:DiffModeSync| is
enabled as a default. And the exact differences will be kept updated while
editing.

You can use `:SDChar` and `:RDChar` commands to manually show and reset the
highlights on all or some of lines. To toggle the highlights, use `:TDChar`
command.

This plugin shows the differences based on a |g:DiffUnit|. Its default is
'Word1' and it handles a \w\+ word and a \W character as a difference unit.
There are other types of word provided and you can also set 'Char' to compare
character by character.

In diff mode, the corresponding changed lines are compared between two
windows. You can set a matching color to a |g:DiffColors| to make it easy to
find the corresponding units between two windows. As a default, all the
changed units are highlighted with |hl-DiffText|. In addition, |hl-DiffAdd| is
always used for the added units and both the previous and next character of
the deleted units are shown in bold/underline.

When the diff mode begins, this plugin detects the limited number of the
|hl-DiffChange| lines, specified by a |g:DiffMaxLines|, in the current visible
and upper/lower lines of the window. Whenever a cursor is moved onto another
line and then the window is scrolled up or down, it dynamically detects the
|hl-DiffChange| lines again. Which means, independently of the file size, the
number of lines to be detected and then the time consumed are always constant.
You can specify a positive value as the actual number of |hl-DiffChange|
lines. The height of the current window is used instead if its value is less
than it. A negative value is also allowed as multiples of the window height.
If 0 is specified, it disables and statically detects all |hl-DiffChange|
lines once the diff mode begins. Its default is -3 and detects three times as
many lines as the window height.

While showing the exact differences, when the cursor is moved on a difference
unit, you can see its corresponding unit with |hl-Cursor| in another window,
based on |g:DiffPairVisible|. In addition, the corresponding unit is echoed in
the command line or displayed in a popup-window just below the cursor
position, if you change its default. And if |g:DiffPairVisible| is enabled, a
balloon window is appeared to display the corresponding unit where the mouse
is pointing.

You can use `]b` or `]e` to jump cursor to start or end position of the next
difference unit, and `[b` or `[e` to the start or end position of the previous
unit. Those keymaps are configurable in your vimrc and so on.

Like line-based `:diffget`/`:diffput` and `do`/`dp` vim commands, you can use
`<Leader>g` and `<Leader>p` commands in normal mode to get and put each
difference unit, where the cursor is on, between 2 buffers and undo its
difference.

In order to check the actual differences in a line, you can use `:EDChar`
command and echo the lines for range. A changed, added, and deleted unit is
shown as [-...-][+...+], [+...+], and [-...-] respectively, while showing its
highlight. If a strike highlighting is available such as on GUI and some
terminal, the deleted unit is highlighted with the strike instead and [+, +],
[-, and -] are eliminated. This command tries to shorten some equivalent units
and show ... instead, if the line is too long to fit on the command line.
The line number is shown if 'number' or 'relativenumber' option is set in the
window. When [!] is used, nothing is shorten and all lines are displayed.

This plugin has been using "An O(NP) Sequence Comparison Algorithm" developed
by S.Wu, et al., which always finds an optimum sequence. But if there are many
lines to be detected, it takes time to complete the diff tracing. To make it
more efficient, this plugin tries to use the external diff command if
available.

This plugin works on each tab page individually. You can use a tab page
variable (t:), instead of a global one (g:), to specify different options on
each tab page. Note that this plugin can not handle more than two diff mode
windows in a tab page. If it would happen, to prevent any trouble, all
highlighted DiffChar units are to be reset in the tab page.

This plugin has been always positively supporting mulltibyte characters.

-----------------------------------------------------------------------------
COMMANDS                                               *diffchar-commands*

:[range]SDChar
    Show the highlights of difference units for [range]

:[range]RDChar
    Reset the highlights of difference units for [range]

:[range]TDChar
    Toggle to show/reset the highlights for [range]

:[range]EDChar[!]
    Echo the line for [range], by showing each corresponding unit together
    in `[+...+]`/`[-...-]` or strike highlighting. Some equivalent units may be
    shown as `...`. The line number is shown if 'number' or 'relativenumber'
    option is set in the window. When [!] is used, all lines and all units
    are displayed.

-----------------------------------------------------------------------------
KEYMAPS                                                *diffchar-keymaps*

<Plug>JumpDiffCharPrevStart (default: `[b`)
    Jump cursor to the start position of the previous difference unit

<Plug>JumpDiffCharNextStart (default: `]b`)
    Jump cursor to the start position of the next difference unit

<Plug>JumpDiffCharPrevEnd (default: `[e`)
    Jump cursor to the end position of the previous difference unit

<Plug>JumpDiffCharNextEnd (default: `]e`)
    Jump cursor to the end position of the next difference unit

<Plug>GetDiffCharPair (default: `<Leader>g`)
    Get a corresponding difference unit from another buffer to undo difference

<Plug>PutDiffCharPair (default: `<Leader>p`)
    Put a corresponding difference unit to another buffer to undo difference

-----------------------------------------------------------------------------
OPTIONS                                                *diffchar-options*

|g:DiffUnit|, |t:DiffUnit|
    Type of difference unit
    'Char'   : any single character
    'Word1'  : \w\+ word and any \W single character (default)
    'Word2'  : non-space and space words
    'Word3'  : \< or \> character class boundaries
    'CSV(,)' : separated by characters such as ',', ';', and '\t'

|g:DiffColors|, |t:DiffColors|
    Matching colors for changed units (always |hl-DiffAdd| for added units)
    0   : always |hl-DiffText| (default)
    1   : 4 colors in fixed order
    2   : 8 colors in fixed order
    3   : 16 colors in fixed order
    100 : all colors defined in highlight option in dynamic random order

|g:DiffPairVisible|, |t:DiffPairVisible|
    Make a corresponding unit visible when cursor is moved onto a diff unit
    0 : disable
    1 : highlight with |hl-Cursor| (default)
    2 : highlight with |hl-Cursor| + echo in the command line
    3 : highlight with |hl-Cursor| + popup-window at the cursor position

|g:DiffModeSync|, |t:DiffModeSync|
    Synchronously show/reset/update with diff mode
    0 : disable
    1 : enable (default)

|g:DiffMaxLines|, |t:DiffMaxLines|
    A maximum number of |hl-DiffChange| lines to be dynamically detected
    -n : multiples of the window height (default as -3)
    n  : the actual number of lines
    0  : disable (detect all |hl-DiffChange| lines once diff mode begins)

-----------------------------------------------------------------------------
CHANGE HISTORY                                         *diffchar-history*

Update : 8.6
* Enhanced |g:DiffPairVisible| option to show a corresponding diff unit as a
  popup-window just below the cursor position (available on patch-8.1.1391).
  And changed its default as 1 (diff unit highlighting only).
* Fixed not to stop monitoring the changes of text and 'diffopt' option,
  even if there is no |hl-DiffChange| line, when |g:DiffModeSync| option is
  enabled.

Update : 8.5
* Enhanced to show a balloon on GUI and display a corresponding diff unit,
  where the mouse is pointing, if |g:DiffPairVisible| option is enabled
  (patch-8.1.647 is required to correctly display multibyte characters).
* Fixed to correctly handle |hl-DiffChange| lines while editing.

Update : 8.4
* Extended |g:DiffMaxLines| option to allow a negative value as multiples of
  the window height and changed its default as -3.
* Fixed to reset all highlighted DiffChar units when more than two windows
  become diff mode in a tab page.
* Deleted |g:DiffSplitTime| option.

Update : 8.3
* Fixed not to detect more |hl-DiffChange| lines than |g:DiffMaxLines| option.

Update : 8.2
* Fixed to correctly update the highlighted DiffChar units while editing when
  a new internal diff is not specified in 'diffopt' option (patch-8.1.360).

Update : 8.1
* Fixed to properly detect |hl-DiffChange| lines even when all visible lines
  of current window are in a closed fold if a |g:DiffMaxLines| option is
  enabled.

Update : 8.0
* Introduced a |g:DiffMaxLines| option to dynamically detect a limited number
  of |hl-DiffChange| lines, when the diff mode begins and whenever a cursor is
  moved onto an undetected line. It enables to always take a minimum constant
  time, independently of the file size.
* Enhanced to check a new DiffUpdated event (patch-8.1.397) to follow diff
  updates and some changes of 'diffopt' option.
* Enhanced to support new iwhiteall and iwhiteeol of 'diffopt' option
  (patch-8.1.360).
* Removed |g:DiffUpdate| option and merged it into |g:DiffModeSync|.
* Removed keymap for <F7> and <F8>, which toggle to show/reset the highlights.
* Changed to work in diff mode, not in non-diff mode.
* Removed a support for vim version 7.x.
* Changed not to set 'diffexpr' option when a new internal diff is specified
  in 'diffopt' (patch-8.1.360).

 vim:tw=78:ts=8:ft=help:norl:
