[Emacs-diffs] /srv/bzr/emacs/trunk r111296: Undocument the details of the string returned by file-acl.

[Eli Zaretskii]

------------------------------------------------------------
revno: 111296
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2012-12-22 16:18:11 +0200
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/files.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-12-21 19:32:43 +0000
+++ b/doc/lispref/ChangeLog     2012-12-22 14:18:11 +0000
@@ -1,3 +1,9 @@
+2012-12-22  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * modes.texi (Auto Major Mode): Fix typo (Bug#13230).

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2012-12-19 21:25:58 +0000
+++ b/doc/lispref/files.texi    2012-12-22 14:18:11 +0000
@@ -1356,31 +1356,17 @@
 @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:
-
address@hidden
address@hidden
-user::rw-
-group::r--
-group:gnu:rwx
-mask::rwx
-other::r--
address@hidden group
address@hidden example
-
address@hidden security descriptor, file
address@hidden SDDL, MS-Windows
-On MS-Windows, the return value is a textual description of the file's
address@hidden 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 @@
 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
address@hidden (@pxref{File Attributes, file-acl}).
 @end defun
 
 @node File Names