unposted: force latest version of files from vendor to main branch

1 files changed, 46 insertions, 3 deletions

diff --git a/Doc/Zsh/mod_files.yo b/Doc/Zsh/mod_files.yo
index 541ebb4a9..db45923c7 100644
--- a/Doc/Zsh/mod_files.yo
+++ b/Doc/Zsh/mod_files.yo
@@ -1,9 +1,52 @@
-texinode(The files Module)(The sched Module)(The example Module)(Zsh Modules)
-sect(The files Module)
+COMMENT(!MOD!zsh/files
+Some basic file manipulation commands as builtins.
+!MOD!)
 cindex(files, manipulating)
-The tt(files) module makes some standard commands available as builtins:
+The tt(zsh/files) module makes some standard commands available as builtins:
 
 startitem()
+findex(chgrp)
+item(tt(chgrp) [ tt(-Rs) ] var(group) var(filename) ...)(
+Changes group of files specified.  This is equivalent to tt(chown) with
+a var(user-spec) argument of `tt(:)var(group)'.
+)
+findex(chown)
+item(tt(chown) [ tt(-Rs) ] var(user-spec) var(filename) ...)(
+Changes ownership and group of files specified.
+
+The var(user-spec) can be in four forms:
+
+startsitem()
+sitem(var(user))(change owner to var(user); do not change group)
+sitem(var(user)tt(::))(change owner to var(user); do not change group)
+sitem(var(user)tt(:))(change owner to var(user); change group to var(user)'s primary group)
+sitem(var(user)tt(:)var(group))(change owner to var(user); change group to var(group))
+sitem(tt(:)var(group))(do not change owner; change group to var(group))
+endsitem()
+
+In each case, the `tt(:)' may instead be a `tt(.)'.  The rule is that
+if there is a `tt(:)' then the separator is `tt(:)', otherwise
+if there is a `tt(.)' then the separator is `tt(.)', otherwise
+there is no separator.
+
+Each of var(user) and var(group) may be either a username (or group name, as
+appropriate) or a decimal user ID (group ID).  Interpretation as a name
+takes precedence, if there is an all-numeric username (or group name).
+
+The tt(-R) option causes tt(chown) to recursively descend into directories,
+changing the ownership of all files in the directory after
+changing the ownership of the directory itself.
+
+The tt(-s) option is a zsh extension to tt(chown) functionality.  It enables
+paranoid behaviour, intended to avoid security problems involving
+a tt(chown) being tricked into affecting files other than the ones
+intended.  It will refuse to follow symbolic links, so that (for example)
+``tt(chown luser /tmp/foo/passwd)'' can't accidentally chown tt(/etc/passwd)
+if tt(/tmp/foo) happens to be a link to tt(/etc).  It will also check
+where it is after leaving directories, so that a recursive chown of
+a deep directory tree can't end up recursively chowning tt(/usr) as
+a result of directories being moved up the tree.
+)
 findex(ln)
 xitem(tt(ln) [ tt(-dfis) ] var(filename) var(dest))
 item(tt(ln) [ tt(-dfis) ] var(filename) ... var(dir))(