--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/emerge.txt	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,786 @@
+
+This is the documentation for version 5 of "emerge.el", an Emacs
+package that allows you to combine two versions of a file by
+selecting, for each place where they differ, which version of the
+difference you prefer.  It is similar to Sun's "filemerge".
+
+Written by Dale R. Worley <drw@math.mit.edu>.
+
+WARRANTY DISCLAIMER
+
+This software was created by Dale R. Worley and is
+distributed free of charge.  It is placed in the public domain and
+permission is granted to anyone to use, duplicate, modify and redistribute
+it provided that this notice is attached.
+
+Dale R. Worley provides absolutely NO WARRANTY OF ANY KIND
+with respect to this software.  The entire risk as to the quality and
+performance of this software is with the user.  IN NO EVENT WILL DALE
+R. WORLEY BE LIABLE TO ANYONE FOR ANY DAMAGES ARISING OUT THE
+USE OF THIS SOFTWARE, INCLUDING, WITHOUT LIMITATION, DAMAGES RESULTING FROM
+LOST DATA OR LOST PROFITS, OR FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+DAMAGES.
+
+;; LCD Archive Entry:
+;; emerge|Dale R. Worley|drw@math.mit.edu
+;; |File merge documentation
+;; |92-12-11|version 5 gamma|~/packages/emerge.doc.Z
+
+- Changes from version 4 to version 5
+
+Put in improved disclaimer of copyright and warranty.
+
+Document autoload for emerge-execute-line.
+
+Changes to support use with Ange-FTP.
+
+Allow filenames containing shell metacharacters to be handled unscathed.
+
+Certain internal problems were fixed so that bugs in "x s", "x j", and
+"x t" were eliminated.
+
+Non-existent and non-readable file names are rejected, even if Emerge
+is called non-interactively.
+
+Add code to process the local-variables list in newly created merge
+buffers.
+
+Add changes made by David Gudeman to allow the default directory for
+arguments to the emerge-files commands to be the directory of the
+argument of that type to the last emerge-files command.  See "Default
+directories" below.
+
+Add emerge-process-line command to allow semi-automatic batching of
+merges.
+
+Add David Gudeman's facility for merging RCS revisions of a file.
+
+Add a few hooks to make customization easier.
+
+Still no Epoch support in this version, though.  Talk to Dan Pierson
+<pierson@xenna.encore.com> or check epoch-emerge-patch.el in the Emacs
+Lisp Directory if you want Epoch support.
+
+And the document still isn't in TeXinfo format.
+
+- Changes from version 3 to version 4
+
+More configuration variables are marked as user options.
+
+Code is included for an improved version of make-auto-save-file-name
+which eliminates many problems with the default version.  See the
+documentation of emerge-make-auto-save-file-name to see how to
+activate it.
+
+Emerge now works with Gnu diff3, which can produce the groups of lines
+from the various files in the order 1, 2, 3 or 1, 3, 2.
+
+Add "x f" command to show what files or buffers are being operated on.
+
+The merge buffer now starts read-only, which being in fast mode it
+should be.
+
+When merging buffers, Emerge writes their contents into temporary
+files in the directory $TMPDIR (if it is defined), or /tmp by default.
+
+Add "x j" command to join two differences.
+
+Add "x s" command to split a difference into two differences.
+
+Add emerge-version variable and function to report the version of Emerge
+being run.
+
+Add "x t" command to trim unchanged lines off top and bottom of
+difference region.
+
+Add "x d", "x a", and "x b" commands to locate the differences at or
+near a given location in one of the buffers.
+
+Emerge no longer tries to copy the minor modes from the A buffer to
+the merge buffer, only the major mode.
+
+The programs executed to find the differences between versions of the file
+are no longer controlled by emerge-diff/diff3-command, but rather by:
+  emerge-diff-program	      
+    Variable: *Name of the program which compares two files.
+  emerge-diff3-program	      
+    Variable: *Name of the program which compares an ancestor file
+    (first argument) and two variant files (second and third arguments).
+  emerge-diff-options	      
+    Variable: *Options to be passed to emerge-diff/diff3-program.
+
+The names of the files are expanded (see expand-file-name) before being
+passed to emerge-diff/diff3-program, so diff need not invoked under a shell
+that understands '~', for instance.
+
+If the diff/diff3 program reports errors, the user is notified and the
+errors are displayed.
+
+The command "0j" can be used to suppress the flags from showing in the
+buffers.
+
+A discussion of the effect of the merge flags on indentation of code
+has been added to the documentation.
+
+If kill-fix.el is loaded, Emerge control variables now have their
+'preserved' property set, so setting the major mode in the merge
+buffer doesn't destroy Emerge's state.
+
+Add "x c", "x C", and "x x" commands to allow the A and B versions to be
+combined into #ifdef - #endif forms.
+
+Replaced calls of "ding" to calls of "error" where appropriate.
+
+Add "x m" command to allow major mode of merge buffer to be changed.
+
+Add "x 1" command to shrink the merge window to one line.
+
+Add emerge-startup-hooks to allow customization.
+
+Fixed a bug that is activated when a remote merge request is made when
+the minibuffer window is selected.
+
+- Changes from version 2 to version 3
+
+The directory into which temporary files are written is now controlled
+by a user option (emerge-temp-file-prefix).
+
+The A and B versions of the difference can be loaded into the kill
+ring with the "c a" and "c b" commands.
+
+The A and B versions of the difference can be inserted into the merge
+buffer with the "i a" and "i b" commands.
+
+The difference region of the merge buffer can be surrounded by the
+point and mark with the "m" command.
+
+The three windows can be scrolled together with the "^", "v", "<",
+">", and "|" commands.
+
+The "s s" and "s a" commands report the state of the option in the
+echo area.  Similarly, the "f" and "e" commands report what they do in
+the echo area.
+
+The "q" command has been revamped, and its behavior is now controlled
+by the manner in which Emerge is started.  In particular, if you wish
+to write the merge buffer into a file upon exiting, invoke
+emerge-files[-with-ancestor] with a prefix argument, and it will
+prompt you for the file name.  Then exiting will write the merge
+buffer to the file, unless "q" is given a prefix argument.
+
+The "i a" and "i b" commands now work in fast mode.
+
+The modifications that Emerge makes to save-buffer and write-file are
+described.
+
+Emerge now handles merging narrowed buffers correctly.
+
+Emerge now isn't fooled when the buffer visiting a file is not the
+same as the file on disk.
+
+- Starting
+
+To start Emerge, you must run one of four commands:
+
+	emerge-files
+	emerge-files-with-ancestor
+	emerge-buffers
+	emerge-buffers-with-ancestor
+
+The "files" versions prompt you for two file names (the "A" and "B"
+files), the "buffers" versions prompt you for two buffer names (the
+"A" and "B" buffers).  Emerge then runs a "diff" of the two entities
+(emerge-buffers writes the buffers into temporary files for input to
+diff) and digests the output to form a list of the differences between
+the two files.  Then three buffers are set up: two containing the
+entities (emerge-files does a find-file (C-x C-f) on the files to get
+them into buffers), and one, the "merge buffer", which contains the
+working copy of the merged file that you are constructing.  The three
+buffers are put up in a nice three-window display, showing the A and B
+buffers in the upper half and the merge buffer in the lower half.
+
+The versions of the command that say "with-ancestor" ask for a third
+name, that of an entity which is a common ancestor from which the
+versions being merged were derived.  These commands use "diff3" to
+compare all three versions.  If one version of a difference agrees
+with the ancestor, then it is presumed that the other version is the
+"correct" version, and is said to be "preferred".
+
+(Note that if you use emerge-files, Emerge attempts to make sure that
+file on disk and the file in the buffer are the same.  If the file on
+disk has been changed, Emerge offers to revert the buffer.  If the
+buffer has been modified, Emerge offers to save the buffer.  If the
+user declines the offer, or if the file on disk and the buffer have
+both been modified, Emerge aborts with an error message.  Emerge is
+careful to widen the buffers containing the files if they have been
+narrowed.  If you use emerge-buffers, the buffers are not widened --
+only the visible portion is used.)
+
+During the merge, the A and B buffers are read-only, so you don't
+damage them.  (This is because the A and B versions of the differences
+are extracted from these buffers.)  When you quit the merge, the
+read-only/read-write status and modified flag on the A and B buffers
+are restored.  In addition, auto-saving of the A and B buffers is
+suppressed during the merge.  This is because Emerge modifies the A
+and B buffers to point out the text of the differences, and it would
+be useless to save these changes.  (Just before suppressing
+auto-saving, Emerge forces an auto-save.)
+
+If you give a prefix argument to emerge-files or
+emerge-files-with-ancestor, it prompts you for another file name,
+which is the file into which the merged file is to be written when you
+exit Emerge.  The output file name defaults to the A file name.  If
+you successfully quit Emerge, the merge buffer will be written to the
+output file, and the buffers for the A, B, and ancestor buffers will
+be deleted (if they exist and are not modified).  If you abort Emerge,
+the merge buffer will not be written and the buffers will not be
+deleted.
+
+You can have any number of merges going at once -- just don't use any
+one buffer as input to more than one merge at once, since that will
+cause the read-only/modified/auto-save status save-and-restore to
+screw up.
+
+Beware that when Emerge starts up, it does a diff or diff3 of the
+files, which can take many minutes for long files with many
+differences.  Emacs can't do anything else until diff finishes.
+
+If diff or diff3 produces error messages, Emerge will beep and display
+the error messages instead of the merge buffer.  There will be a
+message in the echo area giving the name of the merge buffer.  Note
+that this is really just an informational message -- you still have
+switch to the merge buffer and abort the merge to restore the
+conditions before you ran Emerge.  (Emerge considers any output line
+that does not match the regexp emerge-diff/diff3-ok-lines to be an
+error message.)
+
+After the merge has been set up, Emerge runs the hooks in
+emerge-startup-hooks.
+
+The major mode of the merge buffer is set from the major mode of the A
+file or buffer.  You should not use the major-mode-setting commands
+(like c-mode or lisp-mode) to alter the major mode of the merge
+buffer, since they damage the state information of the merge.
+(Emerge's information is maintained as local variables of the merge
+buffer.)  You can use the "x m" command to change the major mode of
+the merge buffer safely.
+
+- Default directories
+
+If the variable emerge-default-last-directories is not set, the
+default directory for all filename arguments to the emerge-files
+commands is the default directory of the current buffer, like any
+other Emacs command.  This can be inconvenient if you are merging
+files in two different directories, since you cannot arrange for the
+default directories for all of the various arguments to be the
+directories you want.
+
+The default directories for filename arguments can be changed by
+setting the variable emerge-default-last-directories.  When it is set,
+the default directory for each filename argument is the directory of
+the previous argument of that type.  Thus, when merging files in two
+directories, the full filenames need only be entered for the first
+emerge-files command; the arugments to later emerge-files commands
+will default to the same directories as the first one.
+
+In this mode of operation, when the default directory for a filename
+argument is not the same as the directory of the file given as the A
+file, the argument acquires a default filename which is the filename
+of the A file appended to the default directory for the argument.
+This simplifies the usual case when several sets of files with
+corresponding names in different directories are being merged.
+
+- Merging
+
+Once you have started the merge, you manipulate the merge buffer with
+special commands issued in the merge buffer.  You may also edit the
+buffer with ordinary Emacs commands.  Emerge keeps track of each
+difference between the A and B buffers and the corresponding section
+of the merge buffer.  Initially, all differences show the A version,
+except those for which B is preferred (because A agrees with the
+ancestor), which show the B version.  Emerge always has its attention
+focused on one particular difference, which is marked off in the three
+buffers by "vvvvvvvvvvvvvvvvvvvv" above and "^^^^^^^^^^^^^^^^^^^^"
+below.  The number of the difference is shown in the mode line.  If
+you are positioned before the first difference (that's where you
+start) or after the last difference, it displays as "diff 0 of nnn" or
+"diff nnn+1 of nnn".
+
+A merge buffer can be in two modes: "fast" mode and "edit" mode.  In
+fast mode, emerge commands are single characters, and ordinary Emacs
+commands are disabled.  This makes Emerge operations fast, but
+prevents you from doing more than selecing the A or the B version of
+differences.  In edit mode, all emerge commands must be prefixed with
+C-c, and all (non-conflicting) Emacs commands are available.  This
+allows editing the merge buffer, but slows down Emerge operations.
+Edit and fast modes are indicated by "F" and "E" in the minor modes in
+the mode line.
+
+The Emerge commands are:
+
+	p	go to the previous difference
+	n	go to the next difference
+	a	select the A version of this difference
+	b	select the B version of this difference
+	j	go to a particular difference (prefix argument
+		specifies which difference) (0j suppresses display of
+		the flags)
+	q	quit - finish the merge*
+	f	go into fast mode
+	e	go into edit mode
+	s a	set/clear auto-advance mode*
+	s s	set/clear skip-prefers mode*
+	l	recenter (C-l) all three windows*
+	- and 0 through 9
+		prefix numeric arguments
+	d a	select the A version as the default from here down in
+		the merge buffer*
+	d b	select the B version as the default from here down in
+		the merge buffer*
+	c a	copy the A version of the difference into the kill
+		ring
+	c b	copy the B version of the difference into the kill
+		ring
+	i a	insert the A version of the difference at the point
+	i b	insert the B version of the difference at the point
+	m	put the point and mark around the difference region
+	^	scroll-down (like M-v) the three windows*
+	v	scroll-up (like C-v) the three windows*
+	<	scroll-left (like C-x <) the three windows*
+	>	scroll-right (like C-x >) the three windows*
+	|	reset horizontal scroll on the three windows*
+	x 1	shrink the merge window to one line (use C-u l to restore it
+		to full size)
+	x a	find the difference containing a location in the A buffer*
+	x b	find the difference containing a location in the B buffer*
+	x c	combine the two versions of this difference*
+	x C	combine the two versions of this difference, using a
+		register's value as the template*
+	x d	find the difference containing a location in the merge buffer*
+	x f	show the files/buffers Emerge is operating on in Help window
+		(use C-u l to restore windows)
+	x j	join this difference with the following one
+		(C-u x j joins this difference with the previous one)
+	x l	show line numbers of points in A, B, and merge buffers
+	x m	change major mode of merge buffer*
+	x s	split this difference into two differences
+		(first position the point in all three buffers to the places
+		to split the difference)
+	x t	trim identical lines off top and bottom of difference
+		(such lines occur when the A and B versions are
+		identical but differ from the ancestor version)
+	x x	set the template for the x c command*
+
+* - more details on these commands are given below
+
+The variable emerge-version gives the version number of Emerge.  The
+emerge-version function displays emerge-version (when called
+interactively) or returns it (when called from a program).
+
+- Differences and their states
+
+A difference can have one of seven states:
+
+A:  the difference is showing the A version.
+
+B:  the difference is showing the B version.
+
+default-A and default-B: the difference is showing the A or B state,
+but has never been selected by the user.  All differences start in the
+default-A state (and thus the merge buffer is a copy of the A buffer),
+except those for which one buffer or another is preferred.  When the
+user selects the difference, it changes to the A or B state.
+
+prefer-A and prefer-B: the difference is showing the A or B state.  In
+addition, the other buffer (that is, for prefer-A, the B buffer; for
+prefer-B, the A buffer) agrees with the ancestor buffer.  Thus,
+presumably, the displayed version is the correct one.  The "a" and "b"
+commands override these states, and turn them into the A and B states.
+
+combined: the difference is showing a combination of the A and B
+states that was constructed by the "x c" or "x C" commands.  Since
+this state is neither the A or B states, the "a" and "b" commands
+won't alter the difference unless they are given a prefix argument.
+
+The state of the currently selected difference is shown in the mode
+line of the merge window:
+
+	state		display
+
+	A		A
+	B		B
+	prefer-A	A*
+	prefer-B	B*
+	combined	comb
+
+- Select default commands (d a and d b)
+
+The "d a" and "d b" commands change all default-A's to default-B's (or
+vice-versa) from the selected difference on down to the end of the
+file to default-A or default-B, respectively.  But remember, any
+difference that you have ever selected isn't in the default-A or
+default-B state, so it will never be affected by "d a" or "d b".  This
+leads to the unexpected result that "d a" or "d b" never affects the
+difference selected at the moment, but prevents differences that you
+have already looked at from changing unexpectedly.
+
+If you work your way down from the top of the file, using "d a" and
+"d b" at judicious points, you can effectivly make the A version the
+default for some sections of the merge buffer and the B version the
+default for others.
+
+Giving the "d a" or "d b" command a prefix argument causes it to change
+differences from the current point down that are in the B state (for d
+a) or A state (for "d b") as well.  (Thus, the selected difference may
+be changed also.)  Differences for which there is a preference will
+not be affected.  (Selecting a difference won't erase its preference.)
+
+- Exiting (q)
+
+The quit command finishes the merge session by restoring the state of
+the A and B buffers and removing the markers around the currently
+selected difference.  It also disables the Emerge commands in the
+merge buffer, since executing them later could damage the contents of
+the various buffers.
+
+The action of "q" depends on how Emerge was started and whether "q"
+was given a prefix argument.  If there was no prefix argument, it is
+considered a "successful" finish.  If there was a prefix argument, it
+is considered an "unsuccessful" finish.  In either case, you are asked
+to cofirm the exit, and the confirmation message tells which sort of
+exit you are confirming.
+
+If Emerge was started by some other process, success/failure is
+reported to the caller.
+
+If Emerge was started with emerge-files or emerge-files-with-ancestor,
+if a prefix argument was given to that command, then you specified a
+file into which the merge is to be written.  A successful exit writes
+the merge into the output file and then kills the A, B, and ancestor
+buffers (so they aren't lying around to confuse you, since they
+probably all have similar names).
+
+- Auto-advance mode (s a)
+
+If auto-advance mode is set, the "a" and "b" commands perform an "n"
+(select next difference) afterward.  When auto-advance mode is set,
+it is indicated by "A" in the minor modes in the mode line.
+"s a" with a positive argument sets auto-advance, with a non-positive
+argument clears it, and with no argument toggles it.
+
+- Skip-prefers mode (s s)
+
+If skip-prefers mode is set, the "n" and "p" commands skip over
+differences with states prefer-A and prefer-B.  Thus you will only see
+differences for which one version isn't presumed "correct".  When
+skip-prefers mode is set, it is indicated by "S" in the minor modes in
+the mode line.  "s s" with a positive argument sets auto-advance, with
+a non-positive argument clears it, and with no argument toggles it.
+
+- Recenter (l)
+
+The Emerge "l" command causes the selected difference to be brought
+into view in the three windows, or at least, whichever of the three
+merge buffers are visible at the moment.  If a prefix argument is
+given, then the original three-window display is set up before the
+difference texts are shown.
+
+- Scrolling the text (^, v, <, >, and |)
+
+Emerge has several commands which scroll all three windows by the same
+amount, thus allowing you to easily compare the versions of the text.
+The commands are "^" (scroll-up), "v" (scroll-down), "<"
+(scroll-left), ">" (scroll-right), and "|" (reset horizontal
+scrolling).  (Remember that Emacs names scrolling commands by the
+motion of the text with respect to the window, so C-v is called
+"scroll-up".)
+
+If these commands (except "|") are given an argument, that is the
+number of lines or characters by which the windows are scrolled.
+Otherwise, the amount of motion is computed based on the dimensions of
+the merge buffer window -- the height of the merge buffer window
+(minus next-screen-context-lines), or half the width of the merge
+buffer window.  (The A and B version windows are assumed to be as high
+as the merge window, but half as wide.)  If the argument is just `C-u
+-', then the scrolling is half the default amount.
+
+- Finding the difference at or near a location (x d, x a, and x b)
+
+The "x d" command selects the difference containing the current point
+in the merge buffer.  If there is no difference containing the point,
+an error is given.  An argument can be given to the command to change
+this behavior: if the argument is positive (e.g., C-u), the next
+following difference is selected; if the argument is negative (e.g.,
+C-u -), the previous difference is selected.
+
+The "x a" and "x b" commands select the difference containing the
+current point in the A and B buffers, respectively.  Otherwise, they
+act like the "x d" command.  Note that although the point used in the
+commands is not the merge buffer point, the commands can only be
+issued in the merge buffer, because it is the only buffer with the
+Emerge keymap.
+
+- Combining the two versions (x c, x C, and x x)
+
+Sometimes one wants to combine the two versions of a difference.  For
+instance, when merging two versions of a program, one wants to make
+something like this:
+
+	#ifdef NEW
+		...new version of code...
+	#else /* NEW */
+		...old version of code...
+	#endif /* NEW */
+
+The "x c" command will make such a combined version.  (Note that any
+combined version is not the same as either the A or B versions, and so
+the "a" and "b" commands will refuse to alter it unless they are given
+a prefix argument.)  The combination is made under control of a
+template, which is a character string with the following
+interpolations:
+
+	%a	the A version of the difference
+	%b	the B version of the difference
+	%%	the character '%'
+
+Thus, the template used above is 
+
+	#ifdef NEW\n%b#else /* NEW */\n%a#endif /* NEW */\n
+
+(using \n here to represent newlines).  The template is stored in the
+variable emerge-combine-versions-template, and its initial value is
+the one given above.  The template can be set (from the current
+region) by the "x x" command.  (Be careful to get the newlines in the
+template in the right places!)  ("x x" was chosen by analogy with "C-x
+x".)  ("x x" is only available in the merge buffer, of course.
+Elsewhere, M-x emerge-set-combine-versions-template can be used.)  If
+"x x" is given a prefix argument, emerge-combine-versions-template is
+localized in the merge buffer before its value is set, so the "x x"
+command's effect (and the effect of any later "x x" command in the
+merge buffer) is only on the merge buffer.
+
+The "x C" command is like "x c", but it prompts for a character
+which is the register whose value is to be used as the template.
+This allows one to use multiple templates conveniently.
+
+- Changing the major mode of the edit buffer (x m)
+
+The "x m" command prompts for the name of a major-mode-setting command
+(such as "c-mode" or "emacs-lisp-mode") and executes it.  Ordinarily,
+major-mode-setting commands change the mode line and local keymap, so
+the "x m" command then resets the Emerge mode line and the fast or
+edit mode local keymap, as appropriate.
+
+If you have already changed the major mode of the merge buffer and
+lost the Emerge keymap, you can use M-x emerge-set-merge-mode to
+execute this command.
+
+Beware that "x m" accepts any command name, not just
+major-mode-setting commands.
+
+In order to use "x m", the kill-fix.el package of improvements to the
+kill-all-local-variables function must be installed.  It can be
+obtained from the Emacs Lisp archives by anonymous FTP from file
+/pub/gnu/emacs/elisp-archive/as-is/kill-fix.el.Z on
+archive.cis.ohio-state.edu.
+
+- Writing the merge buffer manually
+
+Emerge places a wrapper (emerge-query-and-call) on the key bindings of
+save-buffer (usually "C-x C-s") and write-file (usually "C-x C-w"), in
+order to protect the user from writing out the merge before it is
+finished.  Emerge-query-and-call asks the user if he is sure he wants
+to write out the incomplete merge.  If he answers yes, the buffer is
+written out.  The flags are suppressed while the write is being done.
+As a result of this, the displayed portions of the buffers are
+recentered (equivalent to "l").
+
+- Running Emerge standalone
+
+If you invoke emacs with the following arguments, you can execute
+Emerge as a standalone program:
+
+	emacs -l emerge -f emerge-files-command file-a file-b file-out
+
+	emacs -l emerge -f emerge-files-with-ancestor-command
+		file-a file-b file-ancestor file-out
+
+When the user gives the "q" (quit) command, Emerge will write out the
+merge buffer in file-out and terminate Emacs.  If a prefix argument is
+given, Emacs will terminate with an unsuccessful return code (1), if
+not, it will terminate with a successful return code (0).
+
+- Invoking Emerge remotely
+
+If you use the Emacs client/server code that supports remote
+execution, then you can invoke Emerge remotely by executing one of the
+Lisp calls:
+
+	(emerge-files-remote "file A" "file B" "output file")
+
+	(emerge-files-with-ancestor-remote "file A" "file B"
+		"ancestor file" "output file")
+
+Returning a successful/unsuccessful return code is not yet supported
+by the Emacs client/server code.
+
+Beware that in systems of networked workstations, even though all user
+directories are shared between all the workstations, the /tmp
+directory on each workstation is not shared, so writing files into
+/tmp and then remotely invoking Emerge is not likely to work.
+
+- Effect of merge flags on indenting code
+
+The presence of the flags confuses the indentation code of C and
+Emacs-Lisp modes.  Starting the flag strings
+(emerge-{before,after}-flag) with '#' (for C) or ';' (for Lisp)
+prevents the indentation code from noticing the flags.  Remember to
+change the flag strings before loading Emerge, or to execute
+emerge-new-flags after changing them.  But never change the flag
+strings while a merge is being performed.
+
+- Autoloading
+
+The following autoloads will make all top-level Emerge files
+autoloading.  Make sure that "emerge" is in a directory on load-path.
+
+(autoload 'emerge-files "emerge"
+	  "Run Emerge on two files."
+	  t)
+(autoload 'emerge-files-with-ancestor "emerge"
+	  "Run Emerge on two files, giving another file as the ancestor."
+	  t)
+(autoload 'emerge-buffers "emerge"
+	  "Run Emerge on two buffers."
+	  t)
+(autoload 'emerge-buffers-with-ancestor "emerge"
+	  "Run Emerge on two buffers, giving another buffer as the ancestor."
+	  t)
+(autoload 'emerge-files-command "emerge")
+(autoload 'emerge-files-with-ancestor-command "emerge")
+(autoload 'emerge-files-remote "emerge")
+(autoload 'emerge-files-with-ancestor-remote "emerge")
+(autoload 'emerge-revisions "emerge"
+	  "Emerge two RCS revisions of a file."
+	  t)
+(autoload 'emerge-revisions-with-ancestor
+	  "Emerge two RCS revisions of a file, giving another revision as
+the ancestor."
+	  t)
+
+(autoload 'emerge-execute-line "emerge"
+  "Process the current line.  Based on entries found, call emerge correctly
+on the files files listed."
+	t)
+
+- Use with Ange-FTP
+
+The Ange-FTP package allows Emacs to access files using FTP much as if
+they are local files.  However, diff/diff3 cannot access non-local
+files, and so Emerge needs to provide additional support if non-local
+files are being used.  Emerge uses the function emerge-remote-file-p
+to test a file name to see whether that file name can be given
+directly to diff/diff3.  If not, Emerge saves the file contents into a
+temporary file, and gives the temporary file name to diff/diff3.  The
+temporary file is deleted after diff/diff3 is done running.
+
+The function emerge-remote-file-p by default causes temporary files to
+be generated only for files read using Ange-FTP (which are
+distinguished via the variable ange-ftp-path-format).  If Ange-FTP is
+not loaded, it causes no temporary files to be generated.  The
+function emerge-remote-file-p can be modified for customization.
+
+- Filenames containing shell metacharacters
+
+Emerge handles filenames containing shell metacharacters by quoting
+them with \ before passing them to the shell.  This is normally not a
+problem, except that Emacs auto-save files begin with #, which is
+normally used to start comments.  Which characters are considered
+metacharacters is governed by the variable emerge-metachars, whose
+default value is suitable when the shell is sh, csh, or compatible
+shells.
+
+- Local variables lists
+
+Normally, Emerge ignores any local-variables list that is created in
+the merge buffer.  However, sometimes it may be useful to have a
+local-variables list processed.  This can be done manually by
+executing the function "(hack-local-variables)".  If the variable
+emerge-process-local-variables is true, when Emerge is started it
+will process any local variables list in the newly-created merge
+buffer.  (If the merge has an ancestor, the selecting of default
+versions of differences is done before the local variables list is
+processed.)
+
+- Semi-automatic batching of merges
+
+If you have a large number of merges to execute, the function
+emerge-execute-line can reduce the amount of work.  To use it, create
+a buffer containing lines that describe the merges to be done.  Each
+line describes a single merge by means of fields of the form:
+
+	A=file1
+	B=file2
+	ancestor=file3
+	output=file4
+
+The fields are seperated by whitespace, and the filenames given should
+be absolute, not relative.  The buffer's contents can be generated by
+a program and read in as a file, or they can be generated by an Emacs
+function.  (See the sample function emerge-merge-directories, which
+produces specifications to merge the entire contents of two
+directories, possibly with an ancestor directory and an output
+directory.)
+
+If you position the cursor on one line of the buffer and execute
+emerge-execute-line, the information on that line will be read and an
+appropriate merge will be started.  When the merge is finished (or
+aborted), the original buffer will be displayed again, with the cursor
+at the beginning of the next line, ready for the next invocation of
+emerge-execute-line.  In this way, it is easy to start a sequence of
+merges that are described by a buffer of specifications.
+
+To perform a two-way merge, provide an "A" and a "B" field.  To
+perform a merge with an ancestor file, provide "A", "B", and
+"ancestor" fields.  In either case, if an "output" field is provided,
+the results of a successful merge will be written into the designated
+file, just as if a prefix argument had been given to the Emerge
+command.
+
+In addition, emerge-process-line attempts to handle situations where
+one of the "A" or "B" fields are missing, showing that one version or
+another of the file does not exist.  (In all cases, files that are
+specified in the "A", "B", or "ancestor" fields must exist.
+Non-existent files are specified by omitting the appropriate field.)
+The principles governing these cases are: (1) If no "output" file is
+specified, it is an error.  (2) If an "output" file is specified, then
+the "A" or "B" file (whichever is present) is copied into the output
+file.  (3) If an "ancestor" file is given, it is assumed that the file
+in question has been deleted in one or another of the versions, and so
+should be deleted from the "merged" version of the files.  Case (3) is
+sufficiently dangerous that it is only activated if the variable
+emerge-execute-line-deletions is set; otherwise case (3) will be
+handled as case (2), that is, the one existing version will be copied
+to the output file.
+
+In all cases, the goal is to simplify the usual case of "merging two
+directories that contain two versions of a system of software".
+
+- Merging RCS versions of a file
+
+You can merge RCS versions of a file using the commands
+emerge-revisions and emerge-revisions-with-ancestor.  For both
+commands, all of the input files are RCS versions of one base file,
+which are checked out automatically.  If you provide a prefix
+argument, upon successful completion the merged file is checked in.
+
+- Use with Lucid Emacs
+
+Under Lucid Emacs, Emerge highlights the selected difference rather
+that bordering it with character flags.  This is probably more
+natural, but it has the problem that insertions made at the very ends
+of the difference may go either inside or outside of the difference,
+at Emacs' discretion.  The Lucid features should be disablable by
+setting emerge-lucid-p to nil, but that variable is also used to
+activate workarounds to bugs in Lucid Emacs, so the user shouldn't
+change its value.