Documentation fixes based on mail from Edward Welbourne, and an

attempted explanation of rsync's symbolic-link handling.

rsync.yo

@@ -19,7 +19,7 @@ manpagedescription()
 
 rsync is a program that behaves in much the same way that rcp does,
 but has many more options and uses the rsync remote-update protocol to
-greatly speedup file transfers when the destination file already
+greatly speed up file transfers when the destination file already
 exists.
 
 The rsync remote-update protocol allows rsync to transfer just the
@@ -81,7 +81,7 @@ Once installed you can use rsync to any machine that you can use rsh
 to.  rsync uses rsh for its communications, unless both the source and
 destination are local.
 
-You can also specify an alternative to rsh, by either using the -e
+You can also specify an alternative to rsh, either by using the -e
 command line option, or by setting the RSYNC_RSH environment variable.
 
 One common substitute is to use ssh, which offers a high degree of
@@ -139,10 +139,10 @@ It is also possible to use rsync without using rsh or ssh as the
 transport. In this case you will connect to a remote rsync server
 running on TCP port 873. 
 
-You may establish the connetcion via a web proxy by setting the
+You may establish the connection via a web proxy by setting the
 environment variable RSYNC_PROXY to a hostname:port pair pointing to
-your web proxy. Note that your web proxy must allow proxying to port
-873, this must be configured in your proxy servers ruleset.
+your web proxy.  Note that your web proxy's configuration must allow
+proxying to port 873.
 
 Using rsync in this way is the same as using it with rsh or ssh except
 that:
@@ -226,8 +226,8 @@ verb(
      --backup-dir            make backups into this directory
      --suffix=SUFFIX         override backup suffix
  -u, --update                update only (don't overwrite newer files)
- -l, --links                 preserve soft links
- -L, --copy-links            treat soft links like regular files
+ -l, --links                 copy symlinks as symlinks
+ -L, --copy-links            copy the referent of symlinks
      --copy-unsafe-links     copy links outside the source tree
      --safe-links            ignore links outside the destination tree
  -H, --hard-links            preserve hard links
@@ -378,17 +378,16 @@ dit(bf(-u, --update)) This forces rsync to skip any files for which the
 destination file already exists and has a date later than the source
 file.
 
-dit(bf(-l, --links)) This tells rsync to recreate symbolic links on the
-remote system  to  be the same as the local system. Without this
-option, all symbolic links are skipped.
+dit(bf(-l, --links)) When symlinks are encountered, recreate the
+symlink on the destination.
 
-dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just
-like ordinary files.
+dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
+they point to is copied, rather than the symlink.
 
-dit(bf(--copy-unsafe-links)) This tells rsync to treat symbolic links that
-point outside the source tree like ordinary files.  Absolute symlinks are
-also treated like ordinary files, and so are any symlinks in the source
-path itself when --relative is used.
+dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
+symbolic links that point outside the source tree.  Absolute symlinks
+are also treated like ordinary files, and so are any symlinks in the
+source path itself when --relative is used.
 
 dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
 which point outside the destination tree. All absolute symlinks are
@@ -414,16 +413,15 @@ the source and target are on the local machine.
 dit(bf(-p, --perms)) This option causes rsync to update the remote
 permissions to be the same as the local permissions.
 
-dit(bf(-o, --owner)) This option causes rsync to update the  remote  owner
-of the  file to be the same as the local owner. This is only available
-to the super-user.  Note that if the source system is a daemon using chroot,
-the --numeric-ids option is implied because the source system cannot get
-access to the usernames.
+dit(bf(-o, --owner)) This option causes rsync to set the owner of the
+destination file to be the same as the source file.  On most systems,
+only the super-user can set file ownership.  
 
-dit(bf(-g, --group)) This option causes rsync to update the  remote  group
-of the file to be the same as the local group.  If the receving system is
-not running as the super-user, only groups that the receiver is a member of
-will be preserved (by group name, not group id number).
+dit(bf(-g, --group)) This option causes rsync to set the group of the
+destination file to be the same as the source file.  If the receiving
+program is not running as the super-user, only groups that the
+receiver is a member of will be preserved (by group name, not group id
+number).
 
 dit(bf(-D, --devices)) This option causes rsync to transfer character and
 block device information to the remote system to recreate these
@@ -551,8 +549,9 @@ quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
 then files listed in a $HOME/.cvsignore are added to the list and any
 files listed in the CVSIGNORE environment variable (space delimited).
 
-Finally in each directory any files listed in the .cvsignore file in
-that directory are added to the list.
+Finally, any file is ignored if it is in the same directory as a
+.cvsignore file and matches one of the patterns listed therein.  See
+the bf(cvs(1)) manual for more information.
 
 dit(bf(--csum-length=LENGTH)) By default the primary checksum used in
 rsync is a very strong 16 byte MD4 checksum. In most cases you will
@@ -609,21 +608,24 @@ what ownership to give files. The special uid 0 and the special group
 0 are never mapped via user/group names even if the --numeric-ids
 option is not specified.
 
-If the source system is a daemon using chroot, or if a user or group name
-does not exist on the destination system, then the numeric id from the
-source system is used instead.
+If the source system is a daemon using chroot, or if a user or group
+name does not exist on the destination system, then the numeric id
+from the source system is used instead.
 
 dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
 timeout in seconds. If no data is transferred for the specified time
 then rsync will exit. The default is 0, which means no timeout.
 
-dit(bf(--daemon)) This tells rsync that it is to run as a rsync
-daemon. If standard input is a socket then rsync will assume that it
-is being run via inetd, otherwise it will detach from the current
-terminal and become a background daemon. The daemon will read the
-config file (/etc/rsyncd.conf) on each connect made by a client and
-respond to requests accordingly. See the rsyncd.conf(5) man page for more
-details. 
+dit(bf(--daemon)) This tells rsync that it is to run as a daemon.  The
+daemon may be accessed using the bf(host::module) or
+bf(rsync://host/module/) syntax.
+
+If standard input is a socket then rsync will assume that it is being
+run via inetd, otherwise it will detach from the current terminal and
+become a background daemon.  The daemon will read the config file
+(/etc/rsyncd.conf) on each connect made by a client and respond to
+requests accordingly.  See the rsyncd.conf(5) man page for more
+details.
 
 dit(bf(--no-detach)) When running as a daemon, this option instructs
 rsync to not detach itself and become a background process.  This
@@ -706,7 +708,7 @@ manpagesection(EXCLUDE PATTERNS)
 The exclude and include patterns specified to rsync allow for flexible
 selection of which files to transfer and which files to skip.
 
-rsync builds a ordered list of include/exclude options as specified on
+rsync builds an ordered list of include/exclude options as specified on
 the command line. When a filename is encountered, rsync checks the
 name against each exclude/include pattern in turn. The first matching
 pattern is acted on. If it is an exclude pattern, then that file is
@@ -759,7 +761,7 @@ itemize(
   part of an include option. The "- " part is discarded before matching.
 
   it() if the pattern is a single exclamation mark ! then the current
-  exclude list is reset, removing all previous exclude patterns.
+  include/exclude list is reset, removing all previously defined patterns.
 )
 
 The +/- rules are most useful in exclude lists, allowing you to have a
@@ -812,6 +814,29 @@ it() bf(rsync_delta.<timestamp>) data blocks for file update & change
 See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
 reports.
 
+manpagesection(SYMBOLIC LINKS)
+
+Three basic behaviours 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 ommitted altogether.
+
 manpagesection(DIAGNOSTICS)
 
 rsync occasionally produces error messages that may seem a little