Fix for batch mode (was Re: batch mode maintainability)

[Jos Backus]

On Thu, Jan 24, 2002 at 06:19:56PM -0801, Jos Backus wrote:
> OK, I may need help with the markup part though, so I'll post a rough draft
> here first.

Here's my first attempt at improving the documentation of the batch mode
feature.  This is the manpage only; I'll attempt to update the yodl file once
everybody is satisfied with the wording, but I have no way to check it.

When people are happy with the docs I'll resubmit my batchmode cleanup patch.

Comments/suggestions welcome.

Index: rsync.1
===================================================================
RCS file: /cvsroot/rsync/rsync.1,v
retrieving revision 1.108
diff -u -r1.108 rsync.1
--- rsync.1	29 Jan 2002 21:52:56 -0000	1.108
+++ rsync.1	31 Jan 2002 01:51:16 -0000
@@ -306,8 +306,8 @@
      --log-format=FORMAT     log file transfers using specified format
      --password-file=FILE    get password from FILE
      --bwlimit=KBPS          limit I/O bandwidth, KBytes per second
-     --read-batch=FILE       read batch file
-     --write-batch           write batch file
+     --write-batch=PREFIX    write batch fileset starting with PREFIX
+     --read-batch=PREFIX     read batch fileset starting with PREFIX
  -h, --help                  show this help screen
 
 
@@ -801,12 +801,13 @@
 result is an average transfer rate equalling the specified limit\&. A value
 of zero specifies no limit\&.
 .IP 
-.IP "\fB--read-batch\fP" 
-Apply a previously generated change batch\&.
-.IP 
-.IP "\fB--write-batch\fP" 
-Generate a set of files that can be transferred
-as a batch update\&.
+.IP "\fB--write-batch=PREFIX\fP" 
+Generate a set of files that can be transferred as a batch update\&. Each
+filename in the set starts with \fBPREFIX\fP.
+.IP 
+.IP "\fB--read-batch=PREFIX\fP" 
+Apply a previously generated change batch, using the fileset whose filenames
+start with \fBPREFIX\fP\&.
 .IP 
 .PP 
 .SH "EXCLUDE PATTERNS" 
@@ -913,29 +914,50 @@
 \fBNote:\fP Batch mode should be considered experimental in this version
 of rsync\&.  The interface or behaviour may change before it stabilizes\&.
 .PP 
-The following call generates 4 files that encapsulate the information
-for synchronizing the contents of \fBtarget_dir\fP with the updates found in
-\fBsrc_dir\fP
-.PP 
+Batch mode adds the ability to generate control information which describes
+the changes that need to be made in order to turn a source directory tree into
+a target directory tree. This control information is stored in 4 files which
+have a common, user-defined prefix:
+.PP
+.IP o 
+<prefix>\fB.rsync_argvs\fP command-line arguments
+.IP o 
+<prefix>\fB.rsync_flist\fP rsync internal file metadata
+.IP o 
+<prefix>\fB.rsync_csums\fP rsync checksums
+.IP o 
+<prefix>\fB.rsync_delta\fP data blocks for file update & change
+.PP
+This control information can be used to update an identical source directory
+tree (on another system perhaps) to the state of the target directory tree.
+.PP
+Example:
+.PP
 .RS 
-$ rsync --write-batch [other rsync options here] \e
+$ rsync --write-batch=some_update [other rsync options] \e
 .br 
-/somewhere/src_dir /somewhere/target_dir
+/this/src_dir /this/target_dir
 .RE 
+.RS 
+$ rsync --read-batch=some_update [other rsync options] \e
+.br 
+/that/target_dir
+.RE 
+.PP
+Note that in addition to creating the batch control files, the write-batch
+option also makes the target directory tree identical to the source directory
+tree.
+.PP 
+Batch mode is useful when applying the same set of updates to many identical
+systems. Generating the batch control files once saves having to perform the
+file status, checksum and data block generation more than once when updating
+multiple source directory trees. Multicast transport protocols can be used to
+transfer the control files, instead of sending the same data to every host.
+.PP
+\fBCaveat\fP: The -z/--compress option does not work in batch mode.
 .PP 
-The generated files are labeled with a common timestamp:
-.PP 
-.IP o 
-\fBrsync_argvs\&.<timestamp>\fP command-line arguments
-.IP o 
-\fBrsync_flist\&.<timestamp>\fP rsync internal file metadata
-.IP o 
-\fBrsync_csums\&.<timestamp>\fP rsync checksums
-.IP o 
-\fBrsync_delta\&.<timestamp>\fP data blocks for file update & change
-.PP 
-See \fBhttp://www\&.ils\&.unc\&.edu/i2dsi/unc_rsync+\&.html\fP for papers and technical
-reports\&.
+See \fBhttp://www\&.ils\&.unc\&.edu/i2dsi/unc_rsync+\&.html\fP for papers and
+technical reports\&.
 .PP 
 .SH "SYMBOLIC LINKS" 
 .PP 
-- 
Jos Backus                 _/  _/_/_/        Santa Clara, CA
                          _/  _/   _/
                         _/  _/_/_/             
                    _/  _/  _/    _/
josb at cncdsl.com     _/_/   _/_/_/            use Std::Disclaimer;