.\" Generated by manscript from dwdiff.1.txt
.TH "DWDIFF" "1" "2018/12/03" "$VERSION$" "Delimited word diff program"
.hw /usr/share/doc/dwdiff-$VERSION$ http://os.ghalkes.nl/dwdiff.html
.SH NAME
dwdiff \- a delimited word diff program
.SH SYNOPSIS
\fBdwdiff\fR [\fIOPTIONS\fR] \fIOLD FILE\fR \fINEW FILE\fR
.br
\fBdwdiff\fR [\fIOPTIONS\fR] \fB\-\-diff\-input\fR [\fIDIFF FILE\fR]
.SH DESCRIPTION
\fBdwdiff\fR is a \fBdiff\fR program that operates at the word level instead of the line
level. It is different from \fBwdiff\fR in that it allows the user to specify what
should be considered whitespace, and in that it takes an optional list of
characters that should be considered delimiters. Delimiters are single
characters that are treated as if they are words, even when there is no
whitespace separating them from preceding words or delimiters. \fBdwdiff\fR is mostly
command-line compatible with \fBwdiff\fR. Only the \-\-autopager, \-\-terminal and
\-\-avoid\-wraps options are not supported.
.PP
The default output from \fBdwdiff\fR is the new text, with the deleted and inserted
parts annotated with markers. Command line options are available to change both
what is printed, and the markers.
.SH OPTIONS
\fBdwdiff\fR accepts the following options (Note that all strings will first be
escape expanded. All standard \\-escapes are supported, as well as \\u and \\U
Unicode escapes):
.PP
.TP
\fB\-h\fR, \fB\-\-help\fR
Display a short help message.
.TP
\fB\-v\fR, \fB\-\-version\fR
Print version and copyright information.
.TP
\fB\-d\fR \fIdelimiters\fR, \fB\-\-delimiters\fR=\fIdelimiters\fR
Specify a list of characters to be used as delimiters. The default is empty.
.TP
\fB\-P\fR, \fB\-\-punctuation\fR
Use punctuation characters as delimiters. The exact set of punctuation
characters depends on the current locale.
.TP
\fB\-W\fR \fIwhitespace\fR, \fB\-\-white\-space\fR=\fIwhitespace\fR
Specify a list of characters to be used as whitespace. The default set of
whitespace characters depends on the current locale.
.TP
\fB\-u\fR, \fB\-\-diff\-input\fR
Interpret the input as the output from \fBdiff\fR in the Unified Diff format
(usually produced by \fBdiff \-u\fR). In this case only one input file is
allowed. This option allows reformating diff output with \fBdwdiff\fR, and is
useful for example to post-process the output of \fBsvn diff\fR.
.TP
\fB\-1\fR, \fB\-\-no\-deleted\fR
Suppress printing of words deleted from the first file.
.TP
\fB\-2\fR, \fB\-\-no\-inserted\fR
Suppress printing of words inserted in the second file.
.TP
\fB\-3\fR, \fB\-\-no\-common\fR
Suppress printing of words common to both files.
.TP
\fB\-L\fR[\fIwidth\fR], \fB\-\-line\-numbers\fR[=\fIwidth\fR]
Show line numbers at the start of each line. The line numbers displayed are
the line number in the old file and the line number in the new file
respectively. The optional \fIwidth\fR argument is the minimum number of
positions per line number.
.TP
\fB\-C\fR\fInum\fR, \fB\-\-context\fR=\fInum\fR
Show \fInum\fR lines of context before and after each changes. A line
with only \-\- is printed between blocks of changes.
.TP
\fB\-s\fR, \fB\-\-statistics\fR
Print statistics when done. The numbers printed include the number of words
from in both files, the number of deleted words, the number of
inserted words, and the number of changed words. The number of changed words
is counted as the number of words that are removed from the first file, and
the number of words that replace them from the second file. All of these
numbers are also expressed as a percentage of the total number of words in the
file the words came from.
.TP
\fB\-i\fR, \fB\-\-ignore\-case\fR
Ignore differences in case when comparing words. This option is only
available if the diff program that is called provides it.
.TP
\fB\-I\fR, \fB\-\-ignore\-formatting\fR
Ignore differences in formatting of characters. This option switches to using
the Unicode compatibility decomposition instead of the canonical decomposition.
The compatibility decomposition discards formatting information. For example,
the ligature fi will be decomposed into two separate characters for the
purposes of comparison. However, also super- and subscript will be regarded
equal as well as different rotations of the same character.
.TP
\fB\-c\fR[\fIspec\fR], \fB\-\-color\fR[=\fIspec\fR]
Color mode. The optional \fIspec\fR can be used to customize the colors.
\fIspec\fR consists of [\fIdelete\fR],[\fIinsert\fR]. If either is
omited it will be set to its default color (bright red or bright green
respectively). Both parts of the \fIspec\fR consist of
[\fIforeground\fR][:\fIbackground\fR]. To obtain a list of permissible
color names, use the word ``list'' as \fIspec\fR. Alternatively, you can
specify any escape sequence to set attributes as a color by prepending
\fIe:\fR.
.IP
The standard markers for the begin and end of deleted and inserted text are
suppressed, but any markers specified on the command line will still be
printed.
.TP
\fB\-l\fR, \fB\-\-less\-mode\fR
As \-p but also overstrike deleted whitespace.
.TP
\fB\-p\fR, \fB\-\-printer\fR
Use overstriking with an underscore and bold text to emphasize changes. This
is implemented by first printing the underscore or a duplicate of the
character to be printed, followed by a backspace, followed by the character.
On regular terminals you won't see any effect. The \fBless\fR(1) command will
however show underlined and bold text.
.IP
The standard markers for the begin and end of deleted and inserted text are
suppressed, but any markers specified on the command line will still be
printed.
.TP
\fB\-m\fR\fInum\fR, \fB\-\-match\-context\fR=\fInum\fR
Use \fInum\fR words of context before and after words for matching. Words in
the old text will then only match words in the new text if words surrounding
them are also equal. This improves the output for \fBdwdiff\fR for large changes
with frequently occurring words. However, using context requires more disk
space and more processing time. The default value is 1. Set this option to 0
to revert to the pre 1.5 behavior.
.TP
\fB\-\-aggregate\-changes\fR
Allow multiple close changes to be treated as one change, if context words are
used (see \fB\-\-match\-context\fR). This option reduces the processing time as the
changes reported by the \fBdiff\fR program are not post-processed to give more
precise results.
.TP
\fB\-A\fR \fIalgorithm\fR, \fB\-\-algorithm\fR=\fIalgorithm\fR
Select the algorithm to be used for determining differences. There are three
possible values for \fIalgorithm\fR: \fIbest\fR, which tries to find the minimal set
of changes, \fInormal\fR, which trades some optimality for speed, and \fIfast\fR,
which assumes that the input is large and contains few changes. By default
the \fInormal\fR algorithm is used.
.TP
\fB\-S\fR[\fImarker\fR], \fB\-\-paragraph\-separator\fR[=\fImarker\fR]
Show insertion or deletion of blocks of lines with only whitespace characters.
A special marker is inserted into the output to indicate these blocks. The
default marker is \-\-.
.TP
\fB\-\-wdiff\-output\fR
Create \fBwdiff\fR compatible output. The \fBdwdiff\fR program uses a different output
algorithm, which provides a more intuitive output.
.TP
\fB\-w\fR \fIstring\fR, \fB\-\-start\-delete\fR=\fIstring\fR
Specify a string to mark begin of deleted text. The default is [\-.
.TP
\fB\-x\fR \fIstring\fR, \fB\-\-stop\-delete\fR=\fIstring\fR
Specify a string to mark end of deleted text. The default is \-].
.TP
\fB\-y\fR \fIstring\fR, \fB\-\-start\-insert\fR=\fIstring\fR
Specify a string to mark begin of inserted text. The default is {+.
.TP
\fB\-z\fR \fIstring\fR, \fB\-\-stop\-insert\fR=\fIstring\fR
Specify a string to mark end of inserted text. The default is +}.
.TP
\fB\-R\fR, \fB\-\-repeat\-markers\fR
Repeat the begin and end markers at the start and end of line if a change
crosses a newline.
.TP
\fB\-\-profile\fR=\fIname\fR
Load the profile with name \fIname\fR from the \fB.dwdiffrc\fR file in the user's home
directory. Only the last profile named is actually read, unless it is followed
by a \fB\-\-no\-profile\fR option. By default the profile named \fIdefault\fR is read.
.TP
\fB\-\-no\-profile\fR
Disable reading of profiles, unless followed by another \fB\-\-profile\fR option.
This also disables reading the \fIdefault\fR profile.
.PP
A single dash (\-) as a file can be used to denote standard input. Only one
file can be read from standard input. To stop \fBdwdiff\fR from interpreting
file names that start with a dash as options, one can specify a double dash
(\-\-) after which \fBdwdiff\fR will interpret any following arguments as files
to read.
.PP
The exit status of \fBdwdiff\fR indicates the result of the comparison: 0 if the files
are the same, 1 if the files are different. Should an error occur, \fBdwdiff\fR will
exit with status 2.
.SH PROFILES
Since version 2.1.0, \fBdwdiff\fR allows users to create profiles. A profile is a set
of options that can be loaded using the \fB\-\-profile\fR option. Profiles are
specified in the \fB.dwdiffrc\fR in the user's home directory. The format of
the \fB.dwdiffrc\fR file is as follows:
.PP
A line contains either a profile header (a text enclosed in []) or a long option
name without leading dashes, optionally followed by it's argument. Arguments are
stripped of whitespace surrounding it. If an argument starts and ends with
matching double or single quotes, these are removed as well. Comments can be
included by starting a line with a hash mark (#).
.PP
If no profile is specified, the profile named \fIdefault\fR will be loaded, unless
the \fB\-\-no\-profile\fR option is specified. Here is an example \fB.dwdiffrc\fR:
.PP
.po +5
[default]
.br
color red,blue
.br
punctuation
.PP
[html]
.br
start-delete <span style="color=red">
.br
stop-delete </span>
.br
start-insert <span style="color=green">
.br
stop-insert </span>
.PP
[space-only]
.br
# Use only a space as whitespace.
.br
white-space " "
.br
.po
.SH BUGS
If you think you have found a bug, please check that you are using the latest
version of \fBdwdiff\fR <http://os.ghalkes.nl/dwdiff.html>. When reporting
bugs, please include a minimal example that demonstrates the problem.
.SH AUTHOR
G.P. Halkes <dwdiff@ghalkes.nl>
.SH COPYRIGHT
Copyright \(co 2006\-2017 G.P. Halkes and others
.br
\fBdwdiff\fR is licensed under the GNU General Public License version 3.
.br
For more details on the license, see the file COPYING in the documentation
directory. On Un*x systems this is usually /usr/share/doc/dwdiff-$VERSION$.
.SH SEE\ ALSO
\fBdwfilter\fR(1), \fBwdiff\fR(1), \fBdiff\fR(1)