(chmod invocation): Warn about "chmod -w file".

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 7068fc4..8db25a9 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8303,6 +8303,9 @@ recursive directory traversals.
 
 If used, @var{mode} specifies the new permissions.
 For details, see the section on @ref{File permissions}.
+In the extremely rare cases where @var{mode} has leading @samp{-}, a
+portable script should use @option{--} first, e.g., @samp{chmod -- -w
+file}.  Typically, though, @samp{chmod a-w file} is preferable.
 
 The program accepts the following options.  Also see @ref{Common options}.