* README file for `wdiff'			allout -*- outline -*-

  Here is version 0.5g of Free `wdiff', which offers a few programs
  complementing `diff' utilities.  Glance through this `README' file
  before starting configuration.  Make sure you read files `ABOUT-NLS'
  and `INSTALL' if you are not familiar with them already.

  The canonical distribution point for this version is either:

     http://www.iro.umontreal.ca/contrib/wdiff/wdiff-0.5g.tar.gz
     ftp://ftp.iro.umontreal.ca/pub/contrib/pinard/wdiff/wdiff-0.5g.tar.gz

  yet the second URL (the FTP one) might disappear one day.  GNU mirrors
  usually hold a copy of non-pretest releases, the canonical distribution
  point for the last such release is:

     ftp://ftp.gnu.org/pub/gnu/wdiff/wdiff-0.5.tar.gz

.* Introduction
   ------------

. + Presentation

    `wdiff', which gave its name to the package, is a front-end to GNU
    `diff'.  It compares two files, finding which words have been deleted or
    added to the first in order to create the second.  It has many output
    formats and interacts well with terminals and pagers (notably with
    `less').  `wdiff' is particularly useful when two texts differ only by
    a few words and paragraphs have been refilled.  `mdiff' studies one
    or many input files altogether, and discovers blocks of lines which
    repeat at more than one place.  This program is still very experimental.
    Even if much development is needed, it is quite useful as it stands.

    Both have been written by Franois Pinard.  These are evolving programs,
    and specifications might change in future releases.

    The `unify' program converts between context diffs to unified diffs,
    and vice-versa.  Some people just prefer one format and despise the
    other, it is a religious issue.  This program brings peace back on earth.
    It has been contributed by Wayne Davison, from Borland.

    Look further down for a mini-FAQ about `wdiff'.

. + See files

	ABOUT-NLS   how to customise this program to your language
	BACKLOG     summary of pending mail and articles
	COPYING     copying conditions
	INSTALL     compilation and installation instructions
	NEWS        major changes in the current release
	THANKS      partial list of contributors

. + Configure options

    Besides those configure options documented in files `INSTALL' and
    `ABOUT-NLS', one extra option may be accepted after `./configure':

.  - `--with-dmalloc'

     to trigger a debugging feature for looking at memory management
     problems, it pre-requires Gray Watson's package, which is available as
     `ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz'.

. + Maintenance tools

    For comprehensive modifications to `wdiff, you might need tools beyond
    those used in simple installations.  If not done already, get:

	ftp://ftp.cygnus.com/pub/home/drepper/gettext-0.10.35.tar.gz
	ftp://ftp.seindal.dk/pub/rene/gnu/m4-1.4l.tar.gz
	ftp://ftp.gnu.org/pub/gnu/perl/perl-5.003.tar.gz
	ftp://ftp.gnu.org/pub/gnu/autoconf/autoconf-2.12.tar.gz  + PATCHES-AC
	ftp://ftp.cygnus.com/pub/tromey/automake-1.3b.tar.gz
	ftp://ftp.gnu.org/pub/gnu/tar/tar-1.12.tar.gz

    Do not forget applying the `PATCHES-AC' file (beware: it is not official)
    appropriately.  Make sure GNU `m4' is fully installed before you start
    installing Autoconf.  Have Perl installed before Automake.

. + Mailing lists and collaboration

    If you feel like receiving releases and pretest announcements for the
    `wdiff' package, send a message to mailto:majordomo@iro.umontreal.ca
    having, in its body, a line saying:

	subscribe wdiff-announce

    If you rather want to participate actively in discussions, pretesting
    and development for `wdiff', do just as above, but this time, use:

	subscribe wdiff-forum

    Look into http://www.iro.umontreal.ca/contrib/wdiff/ for various
    releases, pretests, and related files.  In particular, subdirectory
    `dist/' contains a weekly mirror of the current unpackaged work files,
    while subdirectory `rmail/' contains saved or pending correspondence.

    Please do _not_ widely redistribute releases having a letter after
    the version numbers, as these are meant for pretesting only, and might
    not be stable enough for other usages.

. + Report addresses

    Send bug reports to `wdiff-bugs@iro.umontreal.ca'.  A bug report is
    an adequate description of the problem: your input, what you expected,
    what you got, and why this is wrong.  Diffs are welcome, but they only
    describe a solution, from which the problem might be uneasy to infer.
    If needed, submit actual data files with your report.  Small data
    files are preferred.  Big files may sometimes be necessary, but do
    not send them on the mailing list; rather take special arrangement
    with the maintainer.

    Your feedback will help us to make a better and more portable package.
    Consider documentation errors as bugs, and report them as such.  If you
    develop anything pertaining to `wdiff' or have suggestions, let us know
    and share your findings by writing at `wdiff-forum@iro.umontreal.ca'.

.* Installation hints
   ------------------

   Here are a few hints which might help installing `wdiff' on some systems.
   Most may be applied by temporary presetting environment variables while
   calling `./configure'.  File `INSTALL' explains this.

. + This program does not require termcap, but takes advantage of it
    when it is available.  You may want to get and install GNU termcap
    first from ftp://gnu.org/pub/gnu/termcap/termcap-1.2.tar.gz, or better.

. + If you have termcap emulation routines in libcurses.a and you do not
    have libtermcap.a, and until I find a way to do better, please use:

	LIBS=-lcurses ./configure

. + If you have both more and less and you prefer more over less, then
    prefix the call to configure with your pager selection, as in:

	PAGER=more ./configure

. + There is a simple minded change bars producer in `wdiff', which is
    not installed by default, nor documented.  If you nevertheles want
    it, one way to get it is requesting, at configure time:

	./configure --enable-cbars

.* Frequently Asked Questions (mini-FAQ)

. + Q: How is `wdiff' different from `diff -w'?

    `wdiff' finds word differences, ignoring spaces, tabs and newlines,
    while `diff -w' finds *line* differences, ignoring spaces and tabs.
    Also, each program uses its own output format.

. + Q: Why not simply apply `diff' to files split one word per line?

    You like the way `wdiff' formats its output.  And it's speedier too.

. + Q: Why calling an external `diff'?  Could not `diff' be built in `wdiff'?

    It's not fruitful to rewrite another `diff'.  I'd rather see `wdiff'
    integrated in GNU `diff' than the other way around.  When `wdiff'
    will have matured enough, it *might* be integrated into GNU `diff'
    distribution, or in GNU `diff' itself.

    Many user requests for additions to `wdiff' have been postponed until
    `wdiff' is integrated in `diff'.  However, for the time being, the
    integration project has been put on the back burner.

. + Q: How about `spiff' by Dan Nachbar <nachbar@bellcore.com>?

    `spiff' is far more general than `wdiff'.  On the other end, `wdiff'
    is a lot faster, needs almost no memory, and can afford handling big
    files in reasonnable time.  Despite its lack of generality, `wdiff'
    does one of the most usual jobs, so it is quite useful after all.
    I might try retrofitting some of `spiff' features into `wdiff', but
    not on short term.

. + Q: How do I get to `wdiff' documentation?

    There are many ways:

    1) Calling just `wdiff', without arguments, will summarize its usage.

    2) You can look at the file `wdiff.info' using any ASCII editor,
    or even print the file as is.

    3) If properly installed, you may browse `wdiff.info' from inside GNU
    Emacs by typing the command:

	C-u M-x info RET wdiff.info RET   .

    4) With the standalone Info reader, use `info -f wdiff.info'.
    You can find the standalone info reader in file texinfo-3.?.tar.gz
    in /pub/gnu/texinfo from gnu.org: just unpack it and look into the
    C subdirectory.

    5) If you have TeX, execute the command `make dvi' then process and
    print `wdiff.dvi' the usual way.

. + Q: Can we use `wdiff' from within GNU Emacs?

    Of course.  You might be loosing some output features.  James Ganong
    <jeg@ced.berkeley.edu> wrote `collatew.el', generalizing the Emacs
    LISP compare-windows function in the spirit of `wdiff'.

. + Q: How much memory `wdiff' exactly needs?

    `wdiff' uses a fixed amount of memory.  Long lines or long files are
    no handicap.  All the true work is done by `diff' under the scene,
    and `diff' needs memory itself.  GNU `diff' swallows both files in
    memory first.

. + Q: What are those uninstalled `mdiff' and `wdiff2' programs?

    Programs `mdiff' and `wdiff2' (to replace `wdiff'?) are alpha software:
    see file `README-mdiff' for more details.  These are compiled just
    to discover portability problems, and they do not get installed.
    The `mdiff' checks are currently inhibited in the validation suite,
    as they would likely fail.  The `cbars' script is not installed either.
