+In these examples, rsync is used to update /adest/dir/ from /source/dir/
+and the information to repeat this operation is stored in "foo" and
+"foo.sh". The host "remote" is then updated with the batched data going
+into the directory /bdest/dir. The differences between the two examples
+reveals some of the flexibility you have in how you deal with batches:
+
+itemize(
+
+ it() The first example shows that the initial copy doesn't have to be
+ local -- you can push or pull data to/from a remote host using either the
+ remote-shell syntax or rsync daemon syntax, as desired.
+
+ it() The first example uses the created "foo.sh" file to get the right
+ rsync options when running the read-batch command on the remote host.
+
+ it() The second example reads the batch data via standard input so that
+ the batch file doesn't need to be copied to the remote machine first.
+ This example avoids the foo.sh script because it needed to use a modified
+ --read-batch option, but you could edit the script file if you wished to
+ make use of it (just be sure that no other option is trying to use
+ standard input, such as the "--exclude-from=-" option).
+
+)
+
+Caveats:
+
+The read-batch option expects the destination tree that it is updating
+to be identical to the destination tree that was used to create the
+batch update fileset. When a difference between the destination trees
+is encountered the update might be discarded with no error (if the file
+appears to be up-to-date already) or the file-update may be attempted
+and then, if the file fails to verify, the update discarded with an
+error. This means that it should be safe to re-run a read-batch operation
+if the command got interrupted. If you wish to force the batched-update to
+always be attempted regardless of the file's size and date, use the -I
+option (when reading the batch).
+If an error occurs, the destination tree will probably be in a
+partially updated state. In that case, rsync can
+be used in its regular (non-batch) mode of operation to fix up the
+destination tree.
+
+The rsync version used on all destinations must be at least as new as the
+one used to generate the batch file. Rsync will die with an error if the
+protocol version in the batch file is too new for the batch-reading rsync
+to handle.
+
+The --dry-run (-n) option does not work in batch mode and yields a runtime
+error.
+
+When reading a batch file, rsync will force the value of certain options
+to match the data in the batch file if you didn't set them to the same
+as the batch-writing command. Other options can (and should) be changed.
+For instance
+--write-batch changes to --read-batch, --files-from is dropped, and the
+--include/--exclude options are not needed unless --delete is specified
+without --delete-excluded.
+
+The code that creates the BATCH.sh file transforms any include/exclude
+options into a single list that is appended as a "here" document to the
+shell script file. An advanced user can use this to modify the exclude
+list if a change in what gets deleted by --delete is desired. A normal
+user can ignore this detail and just use the shell script as an easy way
+to run the appropriate --read-batch command for the batched data.
+
+The original batch mode in rsync was based on "rsync+", but the latest
+version uses a new implementation.
+
+manpagesection(SYMBOLIC LINKS)
+
+Three basic behaviors are possible when rsync encounters a symbolic
+link in the source directory.
+
+By default, symbolic links are not transferred at all. A message
+"skipping non-regular" file is emitted for any symlinks that exist.
+
+If bf(--links) is specified, then symlinks are recreated with the same
+target on the destination. Note that bf(--archive) implies
+bf(--links).
+
+If bf(--copy-links) is specified, then symlinks are "collapsed" by
+copying their referent, rather than the symlink.
+
+rsync also distinguishes "safe" and "unsafe" symbolic links. An
+example where this might be used is a web site mirror that wishes
+ensure the rsync module they copy does not include symbolic links to
+bf(/etc/passwd) in the public section of the site. Using
+bf(--copy-unsafe-links) will cause any links to be copied as the file
+they point to on the destination. Using bf(--safe-links) will cause
+unsafe links to be omitted altogether.
+
+Symbolic links are considered unsafe if they are absolute symlinks
+(start with bf(/)), empty, or if they contain enough bf("..")
+components to ascend from the directory being copied.
+
+manpagesection(DIAGNOSTICS)
+
+rsync occasionally produces error messages that may seem a little
+cryptic. The one that seems to cause the most confusion is "protocol
+version mismatch - is your shell clean?".
+
+This message is usually caused by your startup scripts or remote shell
+facility producing unwanted garbage on the stream that rsync is using
+for its transport. The way to diagnose this problem is to run your
+remote shell like this:
+
+verb(
+ ssh remotehost /bin/true > out.dat
+)
+
+then look at out.dat. If everything is working correctly then out.dat
+should be a zero length file. If you are getting the above error from
+rsync then you will probably find that out.dat contains some text or
+data. Look at the contents and try to work out what is producing
+it. The most common cause is incorrectly configured shell startup
+scripts (such as .cshrc or .profile) that contain output statements
+for non-interactive logins.
+
+If you are having trouble debugging include and exclude patterns, then
+try specifying the -vv option. At this level of verbosity rsync will
+show why each individual file is included or excluded.
+
+manpagesection(EXIT VALUES)
+
+startdit()
+dit(bf(0)) Success
+dit(bf(1)) Syntax or usage error
+dit(bf(2)) Protocol incompatibility
+dit(bf(3)) Errors selecting input/output files, dirs
+dit(bf(4)) Requested action not supported: an attempt
+was made to manipulate 64-bit files on a platform that cannot support
+them; or an option was specified that is supported by the client and
+not by the server.
+dit(bf(5)) Error starting client-server protocol
+dit(bf(10)) Error in socket I/O
+dit(bf(11)) Error in file I/O
+dit(bf(12)) Error in rsync protocol data stream
+dit(bf(13)) Errors with program diagnostics
+dit(bf(14)) Error in IPC code
+dit(bf(20)) Received SIGUSR1 or SIGINT
+dit(bf(21)) Some error returned by waitpid()
+dit(bf(22)) Error allocating core memory buffers
+dit(bf(23)) Partial transfer due to error
+dit(bf(24)) Partial transfer due to vanished source files
+dit(bf(30)) Timeout in data send/receive
+enddit()
+