NetNews Usenet Archive 1992 #31/NN_1992_31.iso/spool/alt/sources/2886

Internet Message Format | 1992-12-25 | 42.8 KB

Path: sparky!uunet!zaphod.mps.ohio-state.edu!cs.utexas.edu!torn!utgpu!attcan!sobeco!philmtl!altitude!matrox!IRO.UMontreal.CA!pinard
From: [e-mail] (Francois Pinard)
Newsgroups: alt.sources
Subject: wdiff - Patch 4, Part (3/3) - brings 0.03 to 0.04
Message-ID: <[e-mail]>
Date: 24 Dec 92 05:37:22 GMT
Sender: [e-mail]
Distribution: alt
Organization: Universite' de Montre'al
Lines: 1002

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is x.03 (part 3 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file Patch4 continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 3; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping Patch4'
else
echo 'x - continuing file Patch4'
sed 's/^X//' << 'SHAR_EOF' >> 'Patch4' &&
X
X    Permission is granted to make and distribute verbatim copies of this
X manual provided the copyright notice and this permission notice are
X@@ -24,9 +24,9 @@
X
X File: wdiff.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
X
X-   This file documents the the `wdiff' command, which compares two
X-files, finding which words have been deleted or added to the first for
X-getting the second.
X+   This file documents the `wdiff' command, as of release 0.04.  This
X+command compares two files, finding which words have been deleted or
X+added to the first for getting the second.
X
X * Menu:
X
X@@ -33,9 +33,10 @@
X * Copying::            How you can copy and share `wdiff'.
X * Overview::                    Preliminary information.
X * Invoking wdiff::              How to run `wdiff'.
X-* Examples::            How some people used `wdiff'.
X-* Problems::                    Reporting bugs.
X+* Examples::                    Actual examples of `wdiff' usage.
X
X+ -- The Detailed Node Listing --
X+
X
X File: wdiff.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top
X
X@@ -410,20 +411,24 @@
X a word per word basis.  A word is anything between whitespace. This is
X useful for comparing two texts in which a few words have been changed
X and for which paragraphs have been refilled.  It works by creating two
X-temporary files, one word per line, then execute `diff' on these.  It
X-collects the `diff' output and uses it to produce a nicer display of
X-word differences in the original files.
X+temporary files, one word per line, and then executes `diff' on these
X+files.  It collects the `diff' output and uses it to produce a nicer
X+display of word differences between the original files.
X
X    Ideally, `wdiff' should avoid calling `diff' and do all the work
X-internally, being more polished and speedy.  However, I loathe
X-replicating `diff' algorithm and effort elsewhere, instead of improving
X-`diff' itself.  It would be more sensible to integrate `wdiff' in
X-`diff' than the other way around.  I did it this way only because I had
X-a sudden and urgent need for it, and it would have taken more time to
X-do it correctly into GNU `diff'.  Your advices or opinions about this
X-are welcome.
X-
X-   `wdiff' was written by Francois Pinard.
X+internally, allowing it to be faster and more polished.  However, I
X+loathe replicating the `diff' algorithm and development effort, instead
X+of improving `diff' itself.  It would be more sensible to integrate
X+`wdiff' into `diff' than the other way around.  I did it this way only
X+because I had a sudden and urgent need for it, and it would have taken
X+too much time to integrate it correctly into GNU `diff'.  Your advice
X+or opinions about this are welcome.
X+
X+   `wdiff' was written by Francois Pinard. Please report bugs to
X+`[e-mail]'. Include the version number, which you
X+can find by running `wdiff --version'.  Include in your message
X+sufficient input to reproduce the problem and also, the output you
X+expected.
X
X
X File: wdiff.info,  Node: Invoking wdiff,  Next: Examples,  Prev: Overview,  Up: Top
X@@ -433,20 +438,19 @@
X
X    The format for running the `wdiff' program is:
X
X-     wdiff OPTION ... FILE_1 FILE_2
X+     wdiff OPTION ... OLD_FILE NEW_FILE
X
X-   `wdiff' will compare files FILE_1 and FILE_2, considering FILE_1 as
X-the old version of the text and FILE_2 as the new version of the same
X-text, and produce an annotated copy of FILE_2 on standard output.
X-
X-   `wdiff' will exit with a status of 0 if no difference were found,
X-with a status of 1 if any difference was found or with a status of 2 for
X-any other kind of reason of error.
X-
X-   Usually, underlining is used to mark deleted words, while bolding or
X-reverse video is used to makr added words; this is adjustable in many
X-ways.  `wdiff' supports the following options:
X+   `wdiff' compares files OLD_FILE and NEW_FILE and produces an
X+annotated copy of NEW_FILE on standard output. `wdiff' will exit with a
X+status of 0 if no differences were found, a status of 1 if any
X+differences were found, or a status of 2 for any error.
X+
X+   In this documentation, "deleted text" refers to text in OLD_FILE
X+which is not in NEW_FILE, while "inserted text" refers to text on
X+NEW_FILE which is not in OLD_FILE.
X
X+   `wdiff' supports the following command line options:
X+
X `--help'
X `-h'
X      Print an informative help message describing the options.
X@@ -457,130 +461,218 @@
X
X `--no-deleted'
X `-1'
X-     Avoid producing deleted words on the output.  If none of `-1' and
X-     `-2' is selected, it might happen that the right margin will be
X-     exceeded for some lines, respective to the original formatting.
X+     Avoid producing deleted words on the output.  If neither `-1' or
X+     `-2' is selected, the original right margin may be exceeded for
X+     some lines.
X
X `--no-inserted'
X `-2'
X-     Avoid producing inserted words on the output.  If none of `-1' and
X-     `-2' is selected, it might happen that the right margin will be
X-     exceeded for some lines, respective to the original formatting.
X+     Avoid producing inserted words on the output.  When this flag is
X+     given, the whitespace in the output is taken from OLD_FILE instead
X+     of NEW_FILE.  If neither `-1' or `-2' is selected, the original
X+     right margin may be exceeded for some lines.
X
X `--no-common'
X `-3'
X      Avoid producing common words on the output.  When this option is
X-     not selected, common words and whitespace are taken from FILE_2.
X-     When selected, differences are segregated from one other by lines
X-     containing only a few dashes.  Moreover, if this option is
X-     selected at the same time `-1' or `-2' is, then all of the output,
X-     if any, would have the same kind of emphasis; `wdiff' rather
X-     selects to do no emphasis at all.  Finally, if this option is not
X-     selected, but both `-1' and `-2' are, sections of common words
X-     between differences are segregated from one other by lines
X-     containing only a few dashes.
X+     not selected, common words and whitespace are taken from NEW_FILE,
X+     unless option `-2' is given, in which case common words and
X+     whitespace are rather taken from OLD_FILE.  When selected,
X+     differences are separated from one another by lines of dashes.
X+     Moreover, if this option is selected at the same time as `-1' or
X+     `-2', then none of the output will have any emphasis, i.e. no bold
X+     or underlining.  Finally, if this option is not selected, but both
X+     `-1' and `-2' are, then sections of common words between
X+     differences are segregated by lines of dashes.
X+
X+`--statistics'
X+`-s'
X+     On completion, for each file, the total number of words, the
X+     number of common words between the files, the number of words
X+     deleted or inserted and the number of words that have changed is
X+     output.  (A changed word is one that has been replaced or is part
X+     of a replacement.)  Except for the total number of words, all of
X+     the numbers are followed by a percentage relative to the total
X+     number of words in the file.
X+
X+`--auto-pager'
X+`-a'
X+     Some initiatives which were previously automatically taken in
X+     previous versions of `wdiff' are now put under the control of this
X+     option. By using it, a pager is interposed whenever the `wdiff'
X+     output is directed to the user's terminal.  Without this option,
X+     no pager will be called, the user is then responsible for
X+     explicitly piping `wdiff' output into a pager, if required.
X+
X+     The pager is selected by the value of the `PAGER' environment
X+     variable when `wdiff' is run.  If `PAGER' is not defined at run
X+     time, then a default pager, selected at installation time, will be
X+     used instead.  A defined but empty value of `PAGER' means no pager
X+     at all.
X+
X+     When a pager is interposed through the use of this option, one of
X+     the options `-l' or `-t' is also selected, depending on whether
X+     the string `less' appears in the pager's name or not.
X+
X+     It is often useful to define `wdiff' as an alias for `wdiff -a'.
X+     However, this *hides* the normal `wdiff' behaviour.  The default
X+     behaviour may be restored simply by piping the output from `wdiff'
X+     through `cat'.  This dissociates the output from the user's
X+     terminal.
X
X `--printer'
X `-p'
X-     Use overstriking to emphasize parts of output.  Each character of
X-     the deleted words is underlined by writing an underscore `_' first,
X-     than a backspace and the letter to be underlined.  Each character
X-     of the added words are bolded by writing them twice, with a
X-     backspace in between.  This option is not selected by default.
X+     Use over-striking to emphasize parts of the output.  Each
X+     character of the deleted text is underlined by writing an
X+     underscore `_' first, then a backspace and then the letter to be
X+     underlined.  Each character of the inserted text is emboldened by
X+     writing it twice, with a backspace in between.  This option is not
X+     selected by default.
X+
X+`--less-mode'
X+`-l'
X+     Use over-striking to emphasize parts of output.  This option works
X+     as option `-p', but also over-strikes whitespace associated with
X+     inserted text.  `less' shows such whitespace using reverse video.
X+     This option is not selected by default.  However, it is
X+     automatically turned on whenever `wdiff' launches the pager
X+     `less'.  See option `-a'.
X
X-`--statistics'
X-`-s'
X-     At end of program, tell for each file the total number of words,
X-     how many words were common between files, how many were deleted or
X-     inserted and, finally, how many have changed (a changed word has
X-     been replaced or is part of a replacement).  Save for the total
X-     number of words itself, numbers are followed by a percentage
X-     relative to the total number of words for the file.
X+     This option is commonly used in conjunction with `less':
X+
X+          wdiff -l OLD_FILE NEW_FILE | less
X
X `--terminal'
X `-t'
X-     Force the production of `termcap' strings for emphasizing parts of
X+     Force the production of `termcap' strings for emphasising parts of
X      output, even if the standard output is not associated with a
X-     terminal. The `TERM' environment variable should still contain the
X-     name of a valid `termcap' entry, however.  This option is
X-     automatically selected whenever the standard output is associated
X-     with a terminal.  If you ever need to deselect this option while
X-     still getting the output to the terminal, simply pipe the output
X-     of `wdiff' through `cat' as in:
X-
X-          wdiff FILE_1 FILE_2 | cat
X-
X-`--start-delete'
X-`-w'
X-     Use the following argument as the "start delete" string.  This
X-     string would be output prior to any sequence of deleted text, to
X-     mark where it starts.  By default, there is no start delete string
X-     unless there is no other means of distinguishing where such text
X-     starts; in which case the start delete string is `[-'.
X-
X-`--end-delete'
X-`-x'
X-     Use the following argument as the "end delete" string.  This string
X-     would be output after any sequence of deleted text, to mark where
X-     it ends.  By default, there is no end delete string unless there
X-     is no other means of distinguishing where such text ends; in which
X-     case the end delete string is `-]'.
X-
X-`--start-insert'
X-`-y'
X-     Use the following argument as the "start insert" string.  This
X-     string would be output prior to any sequence of inserted text, to
X-     mark where it starts.  By default, there is no start insert string
X-     unless there is no other means of distinguishing where such text
X-     starts; in which case the start insert string is `{+'.
X-
X-`--end-insert'
X-`-z'
X-     Use the following argument as the "end insert" string.  This string
X-     would be output after any sequence of inserted text, to mark where
X-     it ends.  By default, there is no end insert string unless there
X-     is no other means of distinguishing where such text ends; in which
X-     case the end insert string is `+}'.
X-
X-   If your system has the program `less' or else, the program `more',
X-and if the output of `wdiff' is directly associated to a terminal, the
X-program will then automatically pipe its output through one of these
X-pagers.  The `PAGER' environment variable, if set, overrides the
X-built-in selection of a pager.  When a pager is selected, the `-t'
X-option is forced so the pager will still display the emphasized parts
X-of the text.  However, in the special case `wdiff' is paging to the
X-`less' program, the `-p' option is forced instead of the `-t' option,
X-taking advantage of the fact that `less' recognizes overstrike
X-sequences and renders them appropriately on the user screen.
X-
X-   On a final note, options `-p', `-t', `-[1234]' are not mutually
X-exclusive.  If you use many of them, you will merely accumulate the
X-effect of each.
X+     terminal. The `TERM' environment variable must contain the name of
X+     a valid `termcap' entry.  If the terminal description permits,
X+     underlining is used for marking deleted text, while bold or
X+     reverse video is used for marking inserted text.  This option is
X+     not selected by default. However, it is automatically turned on
X+     whenever `wdiff' launches a pager, and it is known that the pager
X+     is *not* `less'.  See option `-a'.
X+
X+     This option is commonly used when `wdiff' output is not redirected,
X+     but sent directly to the user terminal, as in:
X+
X+          wdiff -t OLD_FILE NEW_FILE
X+
X+     A common kludge uses `wdiff' together with the pager `more', as in:
X+
X+          wdiff -t OLD_FILE NEW_FILE | more
X+
X+     However, some versions of `more' use `termcap' emphasis for their
X+     own purposes, so strange interactions are possible.
X+
X+`--start-delete ARGUMENT'
X+`-w ARGUMENT'
X+     Use ARGUMENT as the "start delete" string.  This string will be
X+     output prior to any sequence of deleted text, to mark where it
X+     starts.  By default, no start delete string is used unless there
X+     is no other means of distinguishing where such text starts; in
X+     this case the default start delete string is `[-'.
X+
X+`--end-delete ARGUMENT'
X+`-x ARGUMENT'
X+     Use ARGUMENT as the "end delete" string.  This string will be
X+     output after any sequence of deleted text, to mark where it ends.
X+     By default, no end delete string is used unless there is no other
X+     means of distinguishing where such text ends; in this case the
X+     default end delete string is `-]'.
X+
X+`--start-insert ARGUMENT'
X+`-y ARGUMENT'
X+     Use ARGUMENT as the "start insert" string.  This string will be
X+     output prior to any sequence of inserted text, to mark where it
X+     starts.  By default, no start insert string is used unless there
X+     is no other means of distinguishing where such text starts; in
X+     this case the default start insert string is `{+'.
X+
X+`--end-insert ARGUMENT'
X+`-z ARGUMENT'
X+     Use ARGUMENT as the "end insert" string.  This string will be
X+     output after any sequence of inserted text, to mark where it ends.
X+      By default, no end insert string is used unless there is no other
X+     means of distinguishing where such text ends; in this case the
X+     default end insert string is `+}'.
X+
X+`--avoid-wraps'
X+`-n'
X+     Avoid spanning the end of line while showing deleted or inserted
X+     text. Any single fragment of deleted or inserted text spanning
X+     many lines will be considered as being made up of many smaller
X+     fragments not containing a newline.  So deleted text, for example,
X+     will have an end delete string at the end of each line, just
X+     before the new line, and a start delete string at the beginning of
X+     the next line.  A long paragraph of inserted text will have each
X+     line bracketed between start insert and end insert strings.  This
X+     behaviour is not selected by default.
X+
X+   Note that options `-p', `-t', and `-[wxyz]' are not mutually
X+exclusive.  If you use a combination of them, you will merely
X+accumulate the effect of each.  Option `-l' is a variant of option `-p'.
X
X
X-File: wdiff.info,  Node: Examples,  Next: Problems,  Prev: Invoking wdiff,  Up: Top
X+File: wdiff.info,  Node: Examples,  Prev: Invoking wdiff,  Up: Top
X+
X+Actual examples of `wdiff' usage
X+********************************
X+
X+   This section presents a few examples of usage, most of them have been
X+contributed by `wdiff' users.
X+
X+   * Change bars example.
X+
X+     This example comes from a discussion with Joe Wells,
X+     `[e-mail]'.
X+
X+     The following command produces a copy of NEW_FILE, shifted right
X+     one space to accommodate change bars since the last revision,
X+     ignoring those changes coming only from paragraph refilling.  Any
X+     line with new or changed text will get a `|' in column 1.
X+     However, deleted text is not shown nor marked.
X
X-How some people used `wdiff'
X-****************************
X+          wdiff -1n OLD_FILE NEW_FILE |
X+            sed -e 's/^/  /;/{+/s/^ /|/;s/{+//g;s/+}//g'
X
X-   This section will contain user-contributed examples.
X+     Here is how it works.  Word differences are found, paying
X+     attention only to additions, as requested by option `-1'.  For
X+     bigger changes which span line boundaries, the insert bracket
X+     strings are repeated on each output line, as requested by option
X+     `-n'.  This output is then reformatted with a `sed' script which
X+     shifts the text right two columns, turns the initial space into a
X+     bar only if there is some new text on that line, then removes all
X+     insert bracket strings.
X
X+   * `LaTeX' example.
X+
X+     This example has been provided by Steve Fisk,
X+     `[e-mail]'.
X+
X+     The following uses LaTeX to put deleted text in boxes, and new text
X+     in double boxes:
X+
X+          wdiff -w "\fbox{" -x "}" -y "\fbox{\fbox{" -z "}}" ...
X+
X+     works nicely.
X+
X    * `troff' example.
X
X-     By Paul Fox, `[e-mail]'.
X+     This example comes from Paul Fox, `[e-mail]'.
X
X      Using `wdiff', with some `troff'-specific delimiters gives *much*
X-     better output.  The delimeters I used (extra shell-quoting removed
X-     for clarity) :
X+     better output.  The delimiters I used:
X
X-          wdiff -d -1\s-5 -2\s0 -3\fB -4\fP
X+          wdiff -w'\s-5' -x'\s0' -y'\fB' -z'\fP' ...
X
X      This makes the pointsize of deletions 5 points smaller than
X      normal, and emboldens insertions.  Fantastic!
X
X-     I experimented with
X+     I experimented with:
X
X-          wdiff -d -1\fI -2\fP -3\fB -4\fP
X+          wdiff -w'\fI' -x'\fP' -y'\fB' -z'\fP'
X
X      since that's more like the defaults you use for
X      terminals/printers, but since I actually use italics for emphasis
X@@ -588,35 +680,13 @@
X
X      I tried it on code, and it works surprisingly well there, too...
X
X-
X-File: wdiff.info,  Node: Problems,  Prev: Examples,  Up: Top
X-
X-Reporting Bugs
X-**************
X-
X-   If you find a bug in `wdiff', please send electronic mail to
X-`[e-mail]'.  Include the version number, which you can
X-find by running `wdiff --version'.  Include in your message sufficient
X-input to reproduce the problem and also, the output you expected.
X-
X-   Here are some received, unprocessed suggestions.
X-
X-   * Make an MSDOS port.
X-
X-   * Select by options exactly what is whitespace.
X-
X-   * Have a `wpatch' program.  I do not see good ways of doing this.
X-     Any ideas?  Suggested by Zhuo Zang <[e-mail]>, August
X-     13'th, 1992.
X-
X
X
X Tag Table:
X-Node: Top963
X-Node: Copying1458
X-Node: Overview20609
X-Node: Invoking wdiff21716
X-Node: Examples27422
X-Node: Problems28343
X+Node: Top968
X+Node: Copying1494
X+Node: Overview20645
X+Node: Invoking wdiff22032
X+Node: Examples29912
X
X End Tag Table
X--- wdiff-0.03/wdiff.texi    Tue Aug 18 06:31:08 1992
X+++ wdiff-0.04/wdiff.texi    Wed Dec 23 17:38:43 1992
X@@ -7,11 +7,11 @@
X @c %**end of header
X
X @ifinfo
X-This file documents the the @code{wdiff} command, which compares two
X+This file documents the @code{wdiff} command, which compares two
X files, finding which words have been deleted or added to the first
X for getting the second.
X
X-Copyright (C) 1992 Free Software Foundation, Inc.
X+Copyright (C) 1992 by the Free Software Foundation, Inc.
X
X Permission is granted to make and distribute verbatim copies of
X this manual provided the copyright notice and this permission notice
X@@ -38,8 +38,8 @@
X @titlepage
X @title wdiff
X @subtitle The word difference finder
X-@subtitle Edition 1.0, for wdiff Version 1.0
X-@subtitle June 1992
X+@subtitle Edition 0.04, for wdiff Version 0.04
X+@subtitle November 1992
X @author by Francois Pinard
X
X @page
X@@ -64,9 +64,9 @@
X @node Top, Copying, (dir), (dir)
X
X @ifinfo
X-This file documents the the @code{wdiff} command, which compares two
X-files, finding which words have been deleted or added to the first for
X-getting the second.
X+This file documents the @code{wdiff} command, as of release 0.04.  This
X+command compares two files, finding which words have been deleted or
X+added to the first for getting the second.
X @end ifinfo
X
X @menu
X@@ -73,8 +73,9 @@
X * Copying::            How you can copy and share @code{wdiff}.
X * Overview::                    Preliminary information.
X * Invoking wdiff::              How to run @code{wdiff}.
X-* Examples::            How some people used @code{wdiff}.
X-* Problems::                    Reporting bugs.
X+* Examples::                    Actual examples of @code{wdiff} usage.
X+
X+ --- The Detailed Node Listing ---
X @end menu
X
X @node Copying, Overview, Top, Top
X@@ -87,21 +88,26 @@
X files on a word per word basis.  A word is anything between whitespace.
X This is useful for comparing two texts in which a few words have been
X changed and for which paragraphs have been refilled.  It works by
X-creating two temporary files, one word per line, then execute
X-@code{diff} on these.  It collects the @code{diff} output and uses it to
X-produce a nicer display of word differences in the original files.
X+creating two temporary files, one word per line, and then executes
X+@code{diff} on these files.  It collects the @code{diff} output and uses
X+it to produce a nicer display of word differences between the original
X+files.
X
X Ideally, @code{wdiff} should avoid calling @code{diff} and do all the
X-work internally, being more polished and speedy.  However, I loathe
X-replicating @code{diff} algorithm and effort elsewhere, instead of
X-improving @code{diff} itself.  It would be more sensible to integrate
X-@code{wdiff} in @code{diff} than the other way around.  I did it this
X-way only because I had a sudden and urgent need for it, and it would
X-have taken more time to do it correctly into GNU @code{diff}.  Your
X-advices or opinions about this are welcome.
X+work internally, allowing it to be faster and more polished.  However, I
X+loathe replicating the @code{diff} algorithm and development effort,
X+instead of improving @code{diff} itself.  It would be more sensible to
X+integrate @code{wdiff} into @code{diff} than the other way around.  I
X+did it this way only because I had a sudden and urgent need for it, and
X+it would have taken too much time to integrate it correctly into GNU
X+@code{diff}.  Your advice or opinions about this are welcome.
X
X @code{wdiff} was written by Francois Pinard.
X @c *** Comment placer la ce'dille?
X+Please report bugs to @w{@file{bug-gnu-utils@@prep.ai.mit.edu}}.
X+Include the version number, which you can find by running @w{@samp{wdiff
X+--version}}.  Include in your message sufficient input to reproduce the
X+problem and also, the output you expected.
X
X @node Invoking wdiff, Examples, Overview, Top
X @chapter Invoking @code{wdiff}
X@@ -109,21 +115,20 @@
X The format for running the @code{wdiff} program is:
X
X @example
X-wdiff @var{option} @dots{} @var{file_1} @var{file_2}
X+wdiff @var{option} @dots{} @var{old_file} @var{new_file}
X @end example
X
X-@code{wdiff} will compare files @var{file_1} and @var{file_2},
X-considering @var{file_1} as the old version of the text and @var{file_2}
X-as the new version of the same text, and produce an annotated copy of
X-@var{file_2} on standard output.
X-
X-@code{wdiff} will exit with a status of 0 if no difference were found,
X-with a status of 1 if any difference was found or with a status of 2 for
X-any other kind of reason of error.
X-
X-Usually, underlining is used to mark deleted words, while bolding or
X-reverse video is used to makr added words; this is adjustable in many
X-ways.  @code{wdiff} supports the following options:
X+@code{wdiff} compares files @var{old_file} and @var{new_file} and
X+produces an annotated copy of @var{new_file} on standard output.
X+@code{wdiff} will exit with a status of 0 if no differences were found,
X+a status of 1 if any differences were found, or a status of 2 for any
X+error.
X+
X+In this documentation, @dfn{deleted text} refers to text in
X+@var{old_file} which is not in @var{new_file}, while @dfn{inserted text}
X+refers to text on @var{new_file} which is not in @var{old_file}.
X+
X+@code{wdiff} supports the following command line options:
X
X @table @samp
X @item --help
X@@ -136,135 +141,229 @@
X
X @item --no-deleted
X @itemx -1
X-Avoid producing deleted words on the output.  If none of @samp{-1} and
X-@samp{-2} is selected, it might happen that the right margin will be
X-exceeded for some lines, respective to the original formatting.
X+Avoid producing deleted words on the output.  If neither @samp{-1} or
X+@samp{-2} is selected, the original right margin may be exceeded for
X+some lines.
X
X @item --no-inserted
X @itemx -2
X-Avoid producing inserted words on the output.  If none of @samp{-1} and
X-@samp{-2} is selected, it might happen that the right margin will be
X-exceeded for some lines, respective to the original formatting.
X+Avoid producing inserted words on the output.  When this flag is given,
X+the whitespace in the output is taken from @var{old_file} instead of
X+@var{new_file}.  If neither @samp{-1} or @samp{-2} is selected, the
X+original right margin may be exceeded for some lines.
X
X @item --no-common
X @itemx -3
X Avoid producing common words on the output.  When this option is not
X-selected, common words and whitespace are taken from @var{file_2}.  When
X-selected, differences are segregated from one other by lines containing
X-only a few dashes.  Moreover, if this option is selected at the same
X-time @samp{-1} or @samp{-2} is, then all of the output, if any, would
X-have the same kind of emphasis; @code{wdiff} rather selects to do no
X-emphasis at all.  Finally, if this option is not selected, but both
X-@samp{-1} and @samp{-2} are, sections of common words between
X-differences are segregated from one other by lines containing only a few
X-dashes.
X+selected, common words and whitespace are taken from @var{new_file},
X+unless option @samp{-2} is given, in which case common words and
X+whitespace are rather taken from @var{old_file}.  When selected,
X+differences are separated from one another by lines of dashes.
X+Moreover, if this option is selected at the same time as @samp{-1} or
X+@samp{-2}, then none of the output will have any emphasis, i.e. no bold
X+or underlining.  Finally, if this option is not selected, but both
X+@samp{-1} and @samp{-2} are, then sections of common words between
X+differences are segregated by lines of dashes.
X+
X+@item --statistics
X+@itemx -s
X+On completion, for each file, the total number of words, the number of
X+common words between the files, the number of words deleted or inserted
X+and the number of words that have changed is output.  (A changed word is
X+one that has been replaced or is part of a replacement.)  Except for the
X+total number of words, all of the numbers are followed by a percentage
X+relative to the total number of words in the file.
X+
X+@item --auto-pager
X+@itemx -a
X+Some initiatives which were previously automatically taken in previous
X+versions of @code{wdiff} are now put under the control of this option.
X+By using it, a pager is interposed whenever the @code{wdiff} output is
X+directed to the user's terminal.  Without this option, no pager will be
X+called, the user is then responsible for explicitly piping @code{wdiff}
X+output into a pager, if required.
X+
X+The pager is selected by the value of the @code{PAGER} environment
X+variable when @code{wdiff} is run.  If @code{PAGER} is not defined at
X+run time, then a default pager, selected at installation time, will be
X+used instead.  A defined but empty value of @code{PAGER} means no pager
X+at all.
X+
X+When a pager is interposed through the use of this option,
X+one of the options @samp{-l} or @samp{-t} is also selected, depending on
X+whether the string @samp{less} appears in the pager's name or not.
X+
X+It is often useful to define @samp{wdiff} as an alias for @samp{wdiff
X+-a}.  However, this @emph{hides} the normal @code{wdiff} behaviour.  The
X+default behaviour may be restored simply by piping the output from
X+@code{wdiff} through @code{cat}.  This dissociates the output from the
X+user's terminal.
X
X @item --printer
X @itemx -p
X-Use overstriking to emphasize parts of output.  Each character of the
X-deleted words is underlined by writing an underscore @samp{_} first,
X-than a backspace and the letter to be underlined.  Each character of the
X-added words are bolded by writing them twice, with a backspace in
X+Use over-striking to emphasize parts of the output.  Each character of the
X+deleted text is underlined by writing an underscore @samp{_} first,
X+then a backspace and then the letter to be underlined.  Each character of the
X+inserted text is emboldened by writing it twice, with a backspace in
X between.  This option is not selected by default.
X
X-@item --statistics
X-@item -s
X-At end of program, tell for each file the total number of words, how
X-many words were common between files, how many were deleted or inserted
X-and, finally, how many have changed (a changed word has been replaced or
X-is part of a replacement).  Save for the total number of words itself,
X-numbers are followed by a percentage relative to the total number of
X-words for the file.
X+@item --less-mode
X+@itemx -l
X+Use over-striking to emphasize parts of output.  This option works as
X+option @code{-p}, but also over-strikes whitespace associated with
X+inserted text.  @code{less} shows such whitespace using reverse video.
X+This option is not selected by default.  However, it is automatically
X+turned on whenever @code{wdiff} launches the pager @code{less}.  See
X+option @samp{-a}.
X+
X+This option is commonly used in conjunction with @code{less}:
X+
X+@example
X+wdiff -l @var{old_file} @var{new_file} | less
X+@end example
X
X @item --terminal
X @itemx -t
X-Force the production of @code{termcap} strings for emphasizing parts of
X+Force the production of @code{termcap} strings for emphasising parts of
X output, even if the standard output is not associated with a terminal.
X-The @samp{TERM} environment variable should still contain the name of a
X-valid @code{termcap} entry, however.  This option is automatically
X-selected whenever the standard output is associated with a terminal.  If
X-you ever need to deselect this option while still getting the output to
X-the terminal, simply pipe the output of @code{wdiff} through @code{cat}
X+The @samp{TERM} environment variable must contain the name of a valid
X+@code{termcap} entry.  If the terminal description permits, underlining
X+is used for marking deleted text, while bold or reverse video is used
X+for marking inserted text.  This option is not selected by default.
X+However, it is automatically turned on whenever @code{wdiff} launches a
X+pager, and it is known that the pager is @emph{not} @code{less}.  See
X+option @samp{-a}.
X+
X+This option is commonly used when @code{wdiff} output is not redirected,
X+but sent directly to the user terminal, as in:
X+
X+@example
X+wdiff -t @var{old_file} @var{new_file}
X+@end example
X+
X+A common kludge uses @code{wdiff} together with the pager @code{more},
X as in:
X
X @example
X-wdiff @var{file_1} @var{file_2} | cat
X+wdiff -t @var{old_file} @var{new_file} | more
X @end example
X
X-@item --start-delete
X-@item -w
X-Use the following argument as the @dfn{start delete} string.  This
X-string would be output prior to any sequence of deleted text, to mark
X-where it starts.  By default, there is no start delete string unless
X-there is no other means of distinguishing where such text starts; in
X-which case the start delete string is @samp{[-}.
X-
X-@item --end-delete
X-@item -x
X-Use the following argument as the @dfn{end delete} string.  This string
X-would be output after any sequence of deleted text, to mark where it
X-ends.  By default, there is no end delete string unless there is no
X-other means of distinguishing where such text ends; in which case the
X-end delete string is @samp{-]}.
X-
X-@item --start-insert
X-@item -y
X-Use the following argument as the @dfn{start insert} string.  This
X-string would be output prior to any sequence of inserted text, to mark
X-where it starts.  By default, there is no start insert string unless
X-there is no other means of distinguishing where such text starts; in
X-which case the start insert string is @samp{@{+}.
X-
X-@item --end-insert
X-@item -z
X-Use the following argument as the @dfn{end insert} string.  This string
X-would be output after any sequence of inserted text, to mark where it
X-ends.  By default, there is no end insert string unless there is no
X-other means of distinguishing where such text ends; in which case the
X-end insert string is @samp{+@}}.
X+However, some versions of @code{more} use @code{termcap} emphasis for
X+their own purposes, so strange interactions are possible.
X+
X+@item --start-delete @var{argument}
X+@itemx -w @var{argument}
X+Use @var{argument} as the @dfn{start delete} string.  This string will
X+be output prior to any sequence of deleted text, to mark where it
X+starts.  By default, no start delete string is used unless there is no
X+other means of distinguishing where such text starts; in this case the
X+default start delete string is @samp{[-}.
X+
X+@item --end-delete @var{argument}
X+@itemx -x @var{argument}
X+Use @var{argument} as the @dfn{end delete} string.  This string will be
X+output after any sequence of deleted text, to mark where it ends.  By
X+default, no end delete string is used unless there is no other means of
X+distinguishing where such text ends; in this case the default end delete
X+string is @samp{-]}.
X+
X+@item --start-insert @var{argument}
X+@itemx -y @var{argument}
X+Use @var{argument} as the @dfn{start insert} string.  This string will
X+be output prior to any sequence of inserted text, to mark where it
X+starts.  By default, no start insert string is used unless there is no
X+other means of distinguishing where such text starts; in this case the
X+default start insert string is @samp{@{+}.
X+
X+@item --end-insert @var{argument}
X+@itemx -z @var{argument}
X+Use @var{argument} as the @dfn{end insert} string.  This string will be
X+output after any sequence of inserted text, to mark where it ends.  By
X+default, no end insert string is used unless there is no other means of
X+distinguishing where such text ends; in this case the default end insert
X+string is @samp{+@}}.
X+
X+@item --avoid-wraps
X+@itemx -n
X+Avoid spanning the end of line while showing deleted or inserted text.
X+Any single fragment of deleted or inserted text spanning many lines will
X+be considered as being made up of many smaller fragments not containing
X+a newline.  So deleted text, for example, will have an end delete string
X+at the end of each line, just before the new line, and a start delete
X+string at the beginning of the next line.  A long paragraph of inserted
X+text will have each line bracketed between start insert and end insert
X+strings.  This behaviour is not selected by default.
X @end table
X
X-If your system has the program @code{less} or else, the program
X-@code{more}, and if the output of @code{wdiff} is directly associated to
X-a terminal, the program will then automatically pipe its output through
X-one of these pagers.  The @samp{PAGER} environment variable, if set,
X-overrides the built-in selection of a pager.  When a pager is selected,
X-the @samp{-t} option is forced so the pager will still display the
X-emphasized parts of the text.  However, in the special case @code{wdiff}
X-is paging to the @code{less} program, the @samp{-p} option is forced
X-instead of the @samp{-t} option, taking advantage of the fact that
X-@code{less} recognizes overstrike sequences and renders them
X-appropriately on the user screen.
X-
X-On a final note, options @samp{-p}, @samp{-t}, @samp{-[1234]} are not
X-mutually exclusive.  If you use many of them, you will merely accumulate
X-the effect of each.
X+Note that options @samp{-p}, @samp{-t}, and @samp{-[wxyz]} are not
X+mutually exclusive.  If you use a combination of them, you will merely
X+accumulate the effect of each.  Option @samp{-l} is a variant of option
X+@samp{-p}.
X
X-@node Examples, Problems, Invoking wdiff, Top
X-@chapter How some people used @code{wdiff}
X+@node Examples,  , Invoking wdiff, Top
X+@chapter Actual examples of @code{wdiff} usage
X
X-This section will contain user-contributed examples.
X+This section presents a few examples of usage, most of them have been
X+contributed by @code{wdiff} users.
X
X @itemize @bullet
X+@item Change bars example.
X+
X+This example comes from a discussion with Joe Wells,
X+@samp{jbw@@cs.bu.edu}.
X+
X+The following command produces a copy of @var{new_file}, shifted right
X+one space to accommodate change bars since the last revision, ignoring
X+those changes coming only from paragraph refilling.  Any line with new
X+or changed text will get a @samp{|} in column 1.  However, deleted text
X+is not shown nor marked.
X+
X+@example
X+wdiff -1n @var{old_file} @var{new_file} |
X+  sed -e 's/^/  /;/@{+/s/^ /|/;s/@{+//g;s/+@}//g'
X+@end example
X+
X+Here is how it works.  Word differences are found, paying attention only
X+to additions, as requested by option @samp{-1}.  For bigger changes
X+which span line boundaries, the insert bracket strings are repeated on
X+each output line, as requested by option @samp{-n}.  This output is then
X+reformatted with a @code{sed} script which shifts the text right two
X+columns, turns the initial space into a bar only if there is some new
X+text on that line, then removes all insert bracket strings.
X+
X+@item @code{La@TeX{}} example.
X+
X+This example has been provided by Steve Fisk,
X+@samp{fisk@@polar.bowdoin.edu}.
X+
X+The following uses La@TeX{} to put deleted text in boxes, and new text
X+in double boxes:
X+
X+@example
X+wdiff -w "\fbox@{" -x "@}" -y "\fbox@{\fbox@{" -z "@}@}" @dots{}
X+@end example
X+
X+@noindent
X+works nicely.
X+
X @item @code{troff} example.
X
X-By Paul Fox, @samp{pgf@@cayman.com}.
X+This example comes from Paul Fox, @samp{pgf@@cayman.com}.
X
X Using @code{wdiff}, with some @code{troff}-specific delimiters gives
X-@emph{much} better output.  The delimeters I used (extra shell-quoting
X-removed for clarity) :
X+@emph{much} better output.  The delimiters I used:
X
X @example
X-wdiff -d -1\s-5 -2\s0 -3\fB -4\fP
X+wdiff -w'\s-5' -x'\s0' -y'\fB' -z'\fP' @dots{}
X @end example
X
X This makes the pointsize of deletions 5 points smaller than normal, and
X emboldens insertions.  Fantastic!
X
X-I experimented with
X+I experimented with:
X
X @example
X-wdiff -d -1\fI -2\fP -3\fB -4\fP
X+wdiff -w'\fI' -x'\fP' -y'\fB' -z'\fP'
X @end example
X
X since that's more like the defaults you use for terminals/printers, but
X@@ -273,30 +372,6 @@
X
X I tried it on code, and it works surprisingly well there, too...
X
X-@end itemize
X-
X-@node Problems,  , Examples, Top
X-@chapter Reporting Bugs
X-
X-If you find a bug in @code{wdiff}, please send electronic mail to
X-@w{@samp{pinard@@iro.umontreal.ca}}.  Include the version number, which
X-you can find by running @w{@samp{wdiff --version}}.  Include in your
X-message sufficient input to reproduce the problem and also, the output
X-you expected.
X-
X-Here are some received, unprocessed suggestions.
X-
X-@itemize @bullet
X-@item
X-Make an MSDOS port.
X-
X-@item
X-Select by options exactly what is whitespace.
X-
X-@item
X-Have a @code{wpatch} program.  I do not see good ways of doing this.
X-Any ideas?  Suggested by Zhuo Zang <zzang@@stat.ufl.edu>, August 13'th,
X-1992.
X @end itemize
X
X @bye
X--- wdiff-0.03/writepipe.c    Mon Aug 17 14:19:38 1992
X+++ wdiff-0.04/writepipe.c    Sat Dec  5 18:47:48 1992
X@@ -20,6 +20,10 @@
X #include <stdio.h>
X #include <varargs.h>
X
X+#if defined (HAVE_UNISTD_H)
X+#include <unistd.h>
X+#endif
X+
X /* Open a pipe to write to a program without intermediary sh.
X    Checks PATH.
X    Sample use:
X@@ -38,7 +42,7 @@
X
X   /* Copy arguments into `args'. */
X   va_start (ap);
X-  while (args[argno++] = va_arg (ap, char *))
X+  while ((args[argno++] = va_arg (ap, char *)) != NULL)
X     /* Do nothing. */ ;
X   va_end (ap);
X
X@@ -49,9 +53,12 @@
X     {
X     case 0:            /* Child.  Read from pipe. */
X       close (fds[1]);        /* Not needed. */
X-      close (0);        /* We don't want the old stdin. */
X-      dup (fds[0]);        /* Guaranteed to dup to 0 (stdin). */
X-      close (fds[0]);        /* No longer needed. */
X+      if (fds[0] != 0)        /* Redirect 0 (stdin) only if needed.  */
X+    {
X+      close (0);        /* We don't want the old stdin. */
X+      dup (fds[0]);        /* Guaranteed to dup to 0 (stdin). */
X+      close (fds[0]);    /* No longer needed. */
X+    }
X       execvp (args[0], args);
X       _exit (2);        /* 2 for `cmp'. */
X     case -1:            /* Error. */
SHAR_EOF
echo 'File Patch4 is complete' &&
chmod 0640 Patch4 ||
echo 'restore of Patch4 failed'
Wc_c="`wc -c < 'Patch4'`"
test 137819 -eq "$Wc_c" ||
    echo 'Patch4: original size 137819, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
rm -f _shar_seq_.tmp
echo You have unpacked the last part
exit 0
--
Franc,ois Pinard       ``Happy GNU Year!''      [e-mail]
[phone]                                   ...!uunet!iros1!pinard
About the League for Programming Freedom?  Email me or [e-mail]