(x_icon_verify): New function.
[bpt/emacs.git] / man / ediff.texi
index 1747a9b..954efe4 100644 (file)
 @synindex pg cp
 @synindex ky cp
 
-@dircategory Emacs
-@direntry
-* Ediff: (ediff).       A visual interface for comparing and merging programs.
-@end direntry
-
 @iftex
 @finalout
 @end iftex
 @c      @smallbook
 @comment %**end of header (This is for running Texinfo on a region.)
 
-@ifinfo
+@copying
 This file documents Ediff, a comprehensive visual interface to Unix diff
 and patch utilities.
 
-Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software
+Foundation, Inc.
 
+@quotation
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
 any later version published by the Free Software Foundation; with no
@@ -48,9 +45,14 @@ This document is part of a collection distributed under the GNU Free
 Documentation License.  If you want to distribute this document
 separately from the collection, you can do so by adding a copy of the
 license to the document, as described in section 6 of the license.
-@end ifinfo
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Ediff: (ediff).       A visual interface for comparing and merging programs.
+@end direntry
 
-@iftex
 @titlepage
 @title Ediff User's Manual
 @sp 4
@@ -62,28 +64,9 @@ license to the document, as described in section 6 of the license.
 @page
 
 @vskip 0pt plus 1filll
-@noindent
-Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU
-Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software.  Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License.  If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+@insertcopying
 @end titlepage
-@page
-@end iftex
+
 
 @node Top, Introduction, (dir), (dir)
 
@@ -262,8 +245,8 @@ utility to change the original files on disk.  This is not that
 dangerous, since you will always have the original contents of the file
 saved in another file that has the extension @file{.orig}.
 Furthermore, if the file is under version control, then you can always back
-out to one of the previous versions (see the section on Version Countrol in
-Emacs manual).
+out to one of the previous versions (see the section on Version Control in
+the Emacs manual).
 
 @code{ediff-patch-file} is careful about versions control: if the file
 to be patched is checked in, then Ediff will offer to check it out, because
@@ -658,7 +641,7 @@ user can always forcefully refine specific difference regions by typing
 @kindex h
 Cycles between full highlighting, the mode where fine differences are not
 highlighted (but computed), and the mode where highlighting is done with
-ASCII strings.  The latter is not really recommended, unless on a dumb TTY.
+@acronym{ASCII} strings.  The latter is not really recommended, unless on a dumb TTY.
 
 @item r
 @kindex r
@@ -894,31 +877,30 @@ what exactly differs inside these chunks.  Since eyeballing large pieces of
 text is contrary to human nature, Ediff has a special command to help
 reduce the risk of developing a cataract.
 
-The above command compares regions within Ediff buffers.  This creates a
-child Ediff session for comparing current Emacs regions in buffers A, B, or
-C as follows:
+In other situations, the currently highlighted region might be big and you
+might want to reconcile of them interactively.
 
-@emph{If you are comparing 2 files or buffers:}
-Ediff would compare current Emacs regions in buffers A and B.
+All of this can be done with the above command, @kbd{=}, which
+compares regions within Ediff buffers.  Typing @kbd{=} creates a
+child Ediff session for comparing regions in buffers A, B, or
+C as follows.
 
-@emph{If you are comparing 3 files or buffers simultaneously:} Ediff would
-compare the current Emacs regions in the buffers of your choice (you will
-be asked which two of the three buffers to use).
+First, you will be asked whether you want to compare the fine differences
+between the currently highlighted buffers on a word-by-word basis. If you
+accept, a child Ediff session will start using the currently highlighted
+regions. Ediff will let you step over the differences word-wise.
 
-@emph{If you are merging files or buffers (with or without ancestor):}
-Ediff would take the current region in the merge buffer and compare
-it to the current region in the buffer of your choice (A or B).
+If you reject the offer, you will be asked to select regions of your choice.
 
-@emph{Note: In all these cases you must first switch to the appropriate
-Emacs buffers and manually set the regions that you want to compare.}
+@emph{If you are comparing 2 files or buffers:}
+Ediff will ask you to select regions in buffers A and B.
 
-Highlighting set by the parent Ediff session is removed, to avoid interference
-with highlighting of the child session.  When done with the child session, type
-@kbd{C-l} in the parent's control panel to restore the original highlighting.
+@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will
+ask you to choose buffers and then select regions inside those buffers.
 
-If you temporarily switch to the parent session, parent highlighting will be
-restored.  If you then come back to the child session, you may want to remove
-parent highlighting, so it won't interfere.  Typing @kbd{h} may help here.
+@emph{If you are merging files or buffers (with or without ancestor):}
+Ediff will ask you to choose which buffer (A or B) to compare with the
+merge buffer and then select regions in those buffers.
 
 @end table
 
@@ -1050,9 +1032,20 @@ memorize them.
 
 In directory comparison or merging, a session group panel displays only the
 files common to all directories involved.  The differences are kept in a
-separate buffer and are conveniently displayed by typing @kbd{D} to the
-corresponding session group panel.  Thus, as an added benefit, Ediff can be
-used to compare the contents of up to three directories.
+separate @emph{directory difference buffer} and are conveniently displayed
+by typing @kbd{D} to the corresponding session group panel.  Thus, as an
+added benefit, Ediff can be used to compare the contents of up to three
+directories.
+
+@cindex Directory difference buffer
+Sometimes it is desirable to copy some files from one directory to another
+without exiting Ediff. The @emph{directory difference buffer}, which is
+displayed by typing @kbd{D} as discussed above, can be used for this
+purpose. If a file is, say, in Ediff's Directory A, but is missing in
+Ediff's Directory B (Ediff will refuse to override existing files), then
+typing @kbd{C} or clicking mouse button 2 over that file (which must be
+displayed in directory difference buffer) will copy that file from
+Directory A to Directory B.
 
 Session records in session group panels are also marked with @kbd{+}, for
 active sessions, and with @kbd{-}, for finished sessions.
@@ -1074,7 +1067,7 @@ the only such group-level operation is the creation of a multi-file patch.
 @vindex ediff-autostore-merges
 For group sessions created to merge files, Ediff can store all merges
 automatically in a directory.  The user is asked to specify such directory
-if the value of @code{ediff-autostore-merges} is non-nil.  If the value is
+if the value of @code{ediff-autostore-merges} is non-@code{nil}.  If the value is
 @code{nil}, nothing is done to the merge buffers---it will be the user's
 responsibility to save them.  If the value is @code{t}, the user will be
 asked where to save the merge buffers in all merge jobs, even those that do
@@ -1565,7 +1558,7 @@ white space and newlines.  This feature can be toggled on/off interactively,
 via the command @kbd{##}.
 @end table
 
-@strong{Note:} In order for this feature to work, auto-refining of
+@strong{Please note:} in order for this feature to work, auto-refining of
 difference regions must be on, since otherwise Ediff won't know if there
 are fine differences between regions.  On devices where Emacs can display
 faces, auto-refining is a default, but it is not turned on by default on
@@ -1700,8 +1693,8 @@ faces, you can modify them when Ediff is being loaded using
               ediff-current-diff-face-B)))
 @end smallexample
 
-@strong{Note:} To set Ediff's faces, use only @code{copy-face} or
-@code{set/make-face-@dots{}} as shown above. Emacs' low-level
+@strong{Please note:} to set Ediff's faces, use only @code{copy-face}
+or @code{set/make-face-@dots{}} as shown above. Emacs' low-level
 face-manipulation functions should be avoided.
 
 @node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization
@@ -2345,11 +2338,11 @@ The second of the data buffers being compared.
 @item ediff-buffer-C
 In three-way comparisons, this is the third buffer being compared.
 In merging, this is the merge buffer.
-In two-way comparison, this variable is nil.
+In two-way comparison, this variable is @code{nil}.
 
 @item ediff-window-A
 The window displaying buffer A.  If buffer A is not visible, this variable
-is nil or it may be a dead window.
+is @code{nil} or it may be a dead window.
 
 @item ediff-window-B
 The window displaying buffer B.
@@ -2358,9 +2351,9 @@ The window displaying buffer B.
 The window displaying buffer C, if any.
 
 @item ediff-control-frame
-A dedicated frame displaying the control buffer, if it exists.
-It is non-nil only if Ediff uses the multiframe display, i.e., when the
-control buffer is in its own frame.
+A dedicated frame displaying the control buffer, if it exists.  It is
+non-@code{nil} only if Ediff uses the multiframe display, i.e., when
+the control buffer is in its own frame.
 @end table
 
 @node Credits, Index, Customization, Top
@@ -2375,9 +2368,9 @@ made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the
 toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@xemacs.org>
 adapted it to the Emacs customization package.
 
-Many people provided help with bug reports, patches, and advice.
+Many people provided help with bug reports, feature suggestions, and advice.
 Without them, Ediff would not be nearly as useful as it is today.
-Here is a full list of contributors (I hope I didn't miss anyone):
+Here is a hopefully full list of contributors:
 
 @example
 Adrian Aichner (aichner@@ecf.teradyne.com),
@@ -2406,6 +2399,7 @@ Boris Goldowsky (boris@@cs.rochester.edu),
 Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),
 Aaron Gross (aaron@@bfr.co.il),
 Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),
+Marcus Harnisch (marcus_harnisch@@mint-tech.com),
 Xiaoli Huang (hxl@@epic.com),
 Andreas Jaeger (aj@@suse.de),
 Lars Magne Ingebrigtsen (larsi@@ifi.uio.no),
@@ -2440,6 +2434,8 @@ Francois Pinard (pinard@@iro.umontreal.ca),
 Tibor Polgar (tlp00@@spg.amdahl.com),
 David Prince (dave0d@@fegs.co.uk),
 Paul Raines (raines@@slac.stanford.edu),
+Stefan Reicher (xsteve@@riic.at),
+Charles Rich (rich@@merl.com),
 Bill Richter (richter@@math.nwu.edu),
 C.S.@: Roberson (roberson@@aur.alcatel.com),
 Kevin Rodgers (kevin.rodgers@@ihs.com),
@@ -2458,6 +2454,7 @@ Peter Stout (Peter_Stout@@cs.cmu.edu),
 Chuck Thompson (cthomp@@cs.uiuc.edu),
 Ray Tomlinson (tomlinso@@bbn.com),
 Raymond Toy (toy@@rtp.ericsson.se),
+Stephen J. Turnbull  (stephen@@xemacs.org),
 Jan Vroonhof (vroonhof@@math.ethz.ch),
 Colin Walters (walters@@cis.ohio-state.edu),
 Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
@@ -2476,3 +2473,7 @@ Eli Zaretskii (eliz@@is.elta.co.il)
 @setchapternewpage odd
 @contents
 @bye
+
+@ignore
+   arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46
+@end ignore