Undocument the details of the string returned by file-acl.

 doc/lispref/files.texi (File Attributes, Changing Files): Remove the details
 about the text returned by file-acl.  Instead, just document that
 it is an opaque string meant to be used by set-file-acl.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 8158a282a5cc4eb1f8e3ab7168bc9f7fc36950c0..d3182e9bf3743d07dbb1b1b41704a51f7fcf755e 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-12-22  Eli Zaretskii  <eliz@gnu.org>
+
+       * files.texi (File Attributes, Changing Files): Remove the details
+       about the text returned by file-acl.  Instead, just document that
+       it is an opaque string meant to be used by set-file-acl.
+
 2012-12-21  Chong Yidong  <cyd@gnu.org>
 
        * modes.texi (Auto Major Mode): Fix typo (Bug#13230).

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 07709d4c392d6564c790a87d2230e2027e4d32b0..fe9b126d4a23c07e88c66328b9dad138c8ba9d86 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1356,31 +1356,17 @@ support, then the return value is @code{(nil nil nil nil)}.
 @cindex ACL entries
   If Emacs has been compiled with @dfn{ACL} (access control list)
 support, you can use the function @code{file-acl} to retrieve a file's
-ACL entries.  The format is platform-specific; on GNU/Linux and BSD,
-Emacs uses the POSIX ACL interface, while on MS-Windows Emacs emulates
-the POSIX ACL interface with native file security APIs.  For the
-function @code{set-file-acl}, see @ref{Changing Files}.
+ACL entries.  The interface implementation is platform-specific; on
+GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on
+MS-Windows Emacs emulates the POSIX ACL interface with native file
+security APIs.
 
 @defun file-acl filename
-This function returns the ACL entries of the file @var{filename}.
-The return value is a string containing the textual representation of
-the ACL entries.  On Posix hosts, it looks like this:
-
-@example
-@group
-user::rw-
-group::r--
-group:gnu:rwx
-mask::rwx
-other::r--
-@end group
-@end example
-
-@cindex security descriptor, file
-@cindex SDDL, MS-Windows
-On MS-Windows, the return value is a textual description of the file's
-@dfn{security descriptor} in @acronym{SDDL}, the @dfn{Security
-Descriptor Definition Language}.
+This function returns the ACL entries of the file @var{filename}.  The
+return value is a platform-dependent string containing the textual
+representation of the ACL entries.  Don't use it for anything except
+passing it to the @code{set-file-acl} function (@pxref{Changing Files,
+set-file-acl}).
 
 If the file does not exist or is inaccessible, or if Emacs was unable to
 determine the ACL entries, then the return value is @code{nil}.  The
@@ -1726,8 +1712,8 @@ SELinux support.
 This function sets the ACL entries of the file @var{filename} to
 @var{acl-string}.  @xref{File Attributes}, for a brief description of
 ACLs.  The @var{acl-string} argument should be a string containing the
-textual representation of the desired ACL entries in the format
-appropriate for the ACL interface being used.
+textual representation of the desired ACL entries as returned by
+@code{file-acl} (@pxref{File Attributes, file-acl}).
 @end defun
 
 @node File Names