Improved --acls, --xattrs, and --fake-super.

rsync.yo

@@ -884,12 +884,20 @@ quote(itemization(
 If bf(--perms) is enabled, this option is ignored.
 
 dit(bf(-A, --acls)) This option causes rsync to update the destination
-ACLs to be the same as the source ACLs.  This nonstandard option only
-works if the remote rsync also supports it.  bf(--acls) implies bf(--perms).
+ACLs to be the same as the source ACLs.
+The option also implies bf(--perms).
+
+The source and destination systems must have compatible ACL entries for this
+option to work properly.  See the bf(--fake-super) option for a way to backup
+and restore ACLs that are not compatible.
 
 dit(bf(-X, --xattrs)) This option causes rsync to update the remote
-extended attributes to be the same as the local ones.  This will work
-only if the remote machine's rsync also supports this option.
+extended attributes to be the same as the local ones.
+
+For systems that support extended-attribute namespaces, a copy being done by a
+super-user copies all namespaces except system.*.  A normal user only copies
+the user.* namespace.  To be able to backup and restore non-user namespaces as
+a normal user, see the bf(--fake-super) option.
 
 dit(bf(--chmod)) This option tells rsync to apply one or more
 comma-separated "chmod" strings to the permission of the files in the
@@ -914,8 +922,8 @@ dit(bf(-o, --owner)) This option causes rsync to set the owner of the
 destination file to be the same as the source file, but only if the
 receiving rsync is being run as the super-user (see also the bf(--super)
 and bf(--fake-super) options).
-Without this option, the owner is set to the invoking user on the
-receiving side.
+Without this option, the owner of new and/or transferred files are set to
+the invoking user on the receiving side.
 
 The preservation of ownership will associate matching names by default, but
 may fall back to using the ID number in some circumstances (see also the
@@ -967,14 +975,19 @@ being running as the super-user.  To turn off super-user activities, the
 super-user can use bf(--no-super).
 
 dit(bf(--fake-super)) When this option is enabled, rsync simulates
-super-user activities by saving/restoring the privileged attributes via a
-special extended attribute that is attached to each file (as needed).  This
+super-user activities by saving/restoring the privileged attributes via
+special extended attributes that are attached to each file (as needed).  This
 includes the file's owner and group (if it is not the default), the file's
 device info (device & special files are created as empty text files), and
 any permission bits that we won't allow to be set on the real file (e.g.
 the real file gets u-s,g-s,o-t for safety) or that would limit the owner's
 access (since the real super-user can always access/change a file, the
 files we create can always be accessed/changed by the creating user).
+This option also handles ACLs (if bf(--acls) was specified) and non-user
+extended attributes (if bf(--xattrs) was specified).
+
+This is a good way to backup data withou using a super-user, and to store
+ACLs from incompatible systems.
 
 The bf(--fake-super) option only affects the side where the option is used.
 To affect the remote side of a remote-shell connection, specify an rsync
@@ -984,10 +997,9 @@ quote(tt(  rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
 
 Since there is only one "side" in a local copy, this option affects both
 the sending and recieving of files.  You'll need to specify a copy using
-"localhost" if you need to avoid this.  Note, however, that it is always
-safe to copy from some non-fake-super files into some fake-super files
-using a local bf(--fake-super) command because the non-fake source files
-will just have their normal attributes.
+"localhost" if you need to avoid this, possibly using the "lsh" shell
+script (from the support directory) as a substitute for an actual remote
+shell (see bf(--rsh)).
 
 This option is overridden by both bf(--super) and bf(--no-super).