doc: add a RATIONALE section to the man page.

diff --git a/doc/man/apply-default-acl.1 b/doc/man/apply-default-acl.1
index 42233f1f7bd219b573a682ea41dbfa435408ac28..2c30862f921b66659692c726ae6b3743f5d4642e 100644 (file)
--- a/doc/man/apply-default-acl.1
+++ b/doc/man/apply-default-acl.1
@@ -12,15 +12,40 @@ apply-default-acl \- Apply default POSIX ACLs to files and directories.
 .P
 If the directory containing \fIpath\fR has a default ACL, the ACL on
 \fIpath\fR is replaced with that default. Neither symbolic nor hard
-links are followed; symbolic links are ignored in all path components
-to avoid a dangerous race condition.
+links are followed; symbolic links are ignored in all \fIpath\fR
+components to avoid a dangerous race condition.
 .P
 A heuristic is used to determine whether or not the execute bits are
 removed from \fIpath\fR. If \fIpath\fR is a directory or if some user
-or group has \fBeffective\fR execute permissions on \fIpath\fR, then
-the execute bits will be left alone. Otherwise, they will be
-removed. In effect we pretend that the \fBx\fR permission acts like
-the \fBX\fR (note the case difference) permission of \fBsetfacl\fR.
+or group can execute \fIpath\fR, then the execute bits are left alone.
+Otherwise, they are removed. In effect, we pretend that the \fBx\fR
+permission in the parent's default ACL acts like the \fBX\fR (note the
+case difference) permission used by \fBsetfacl\fR.
+
+.SH RATIONALE
+
+.P
+Why would you need this? When you change the default ACL on a
+directory, it doesn't affect any of the files in that directory. So,
+if change the default ACL on a directory to allow group-read access,
+then you still have to manually allow group-read access on every file
+in that directory. That wouldn't be so bad, except that you need to do
+it recursively, and the \fBsetfacl\fR command is different for files
+and directories. Instead, once you've set the default ACL, you can use
+apply-default-acl to \(dqreset\(dq the permissions on everything in
+the directory. The differences between files and directories are
+handled for you.
+.P
+Another reason is that several common utilities like \fBcp\fR and
+\fBtar\fR will call \fBchmod\fR on the files that they create without
+regard for your default ACLs. When those utilities try to preserve
+group permissions, they are actually affecting your ACL mask, and this
+can prevent your default permissions from taking effect. For example,
+if you \fBcp\fR a file that is not group-writable into a directory
+that has a default ACL, the effective write permissions will all be
+masked when \fBcp\fR clears the group-write (that is, the mask-write)
+bit. Calling apply-default-acl on the files created by these utilities
+fixes the permissions.
 
 .SH OPTIONS
 .IP \fB\-\-recursive\fR,\ \fB\-r\fR