Re: [PATCH v2] POSIX ACL support

[Eli Zaretskii <eliz@gnu.org>]

> From: Romain Francoise <romain@orebokech.com>
> Date: Sun, 02 Dec 2012 21:04:19 +0100
> 
> This is another iteration with the following changes:
> - C-level functions renamed to `file-acl' and `set-file-acl' in hope that
>   they can be used with non-POSIX ACL implementations; conversely the
>   parts of the implementation that are POSIX ACL specific are now inside
>   HAVE_POSIX_ACL
> - the additional argument to `copy-file' has been dropped, the existing
>   argument `preserve-selinux-context' has been turned into a more generic
>   `preserve-extended-attributes' argument which does both SELinux and ACL
> - new functions `file-extended-attributes' and `set-file-extended-attributes'
>   have been added to make the implementation cleaner in files.el, handling
>   both SELinux context and ACL entries (do they need to be documented in
>   the Elisp manual?)
> 
> Tested again on GNU/Linux with libacl, and FreeBSD.
> 
> Comments welcome!

Thanks.

> +@cindex ACL entries

Suggest an additional entry "@cindex access control list" here.

> +  If Emacs has been compiled with ACL 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.  For the function @code{set-file-acl}, see @ref{Changing
> +Files}.

We don't mention "ACL" or explain it anywhere else in the manual.  So
this acronym should be explained here, and its first use should use
@dfn, as we do with any new terminology.

> +DEFUN ("file-acl", Ffile_acl, Sfile_acl, 1, 1, 0,
> +       doc: /* Return ACL entries of file named FILENAME, as a string.
> +Return nil if file does not exist or is not accessible, or if Emacs was
> +not compiled with ACL support.  */)

The last sentence of the doc string is inaccurate, because remote
files are supported even if Emacs was not built with ACL support.

> +DEFUN ("set-file-acl", Fset_file_acl, Sset_file_acl,
> +       2, 2, 0,
> +       doc: /* Set ACL of file named FILENAME to ACL-STRING.
> +ACL-STRING should contain the textual representation of the ACL
> +entries in a format suitable for the platform.
> +
> +This function does nothing if Emacs was not compiled with ACL
> +support.  */)

Same here.