6 files changed, 75 insertions, 25 deletions
diff --git a/Doc/Zsh/mod_cap.yo b/Doc/Zsh/mod_cap.yo
index f6513b314..2db811cdc 100644
--- a/Doc/Zsh/mod_cap.yo
+++ b/Doc/Zsh/mod_cap.yo
@@ -1,6 +1,7 @@
-texinode(The cap Module)(The clone Module)()(Zsh Modules)
-sect(The cap Module)
-The tt(cap) module is used for manipulating POSIX.1e (POSIX.6) capability
+COMMENT(!MOD!zsh/cap
+Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.
+!MOD!)
+The tt(zsh/cap) module is used for manipulating POSIX.1e (POSIX.6) capability
 sets.  If the operating system does not support this interface, the
 builtins defined by this module will do nothing.
 The builtins in this module are:
diff --git a/Doc/Zsh/mod_complete.yo b/Doc/Zsh/mod_complete.yo
index 558bbc4ae..e1c377666 100644
--- a/Doc/Zsh/mod_complete.yo
+++ b/Doc/Zsh/mod_complete.yo
@@ -1,6 +1,7 @@
-texinode(The complete Module)(The compctl Module)(The clone Module)(Zsh Modules)
-sect(The complete Module)
-The tt(compctl) module makes available several builtin commands which
+COMMENT(!MOD!zsh/complete
+The basic completion code.
+!MOD!)
+The tt(zsh/complete) module makes available several builtin commands which
 can be used in user-defined completion widgets, see
 ifzman(zmanref(zshcompwid))\
 ifnzman(noderef(Completion Widgets))\
diff --git a/Doc/Zsh/mod_example.yo b/Doc/Zsh/mod_example.yo
index 5339253d9..af6d53b88 100644
--- a/Doc/Zsh/mod_example.yo
+++ b/Doc/Zsh/mod_example.yo
@@ -1,6 +1,7 @@
-texinode(The example Module)(The files Module)(The deltochar Module)(Zsh Modules)
-sect(The example Module)
-The tt(example) module makes available one builtin command:
+COMMENT(!MOD!zsh/example
+An example of how to write a module.
+!MOD!)
+The tt(zsh/example) module makes available one builtin command:
 
 startitem()
 findex(example)
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))(
diff --git a/Doc/Zsh/mod_mapfile.yo b/Doc/Zsh/mod_mapfile.yo
index 6d0475711..496d8a915 100644
--- a/Doc/Zsh/mod_mapfile.yo
+++ b/Doc/Zsh/mod_mapfile.yo
@@ -1,7 +1,8 @@
-texinode(The mapfile Module)(The parameter Module)(The files Module)(Zsh Modules)
-sect(The mapfile Module)
+COMMENT(!MOD!zsh/mapfile
+Access to external files via a special associative array.
+!MOD!)
 cindex(parameter, file access via)
-The tt(mapfile) module provides one special associative array parameter of
+The tt(zsh/mapfile) module provides one special associative array parameter of
 the same name.
 
 startitem()
@@ -34,11 +35,13 @@ handled, zsh's internal memory management may be arbitrarily baroque.  Thus
 it should not automatically be assumed that use of tt(mapfile) represents a
 gain in efficiency over use of other mechanisms.  Note in particular that
 the whole contents of the file will always reside physically in memory when
-accessed (possibly multiple times, due to standard parameter subsitution
-operations).
+accessed (possibly multiple times, due to standard parameter substitution
+operations).  In particular, this means handling of sufficiently long files
+(greater than the machine's swap space, or than the range of the pointer
+type) will be incorrect.
 
 No errors are printed or flagged for non-existent, unreadable, or
-unwriteable files, as the parameter mechanism is too low in the shell
+unwritable files, as the parameter mechanism is too low in the shell
 execution hierarchy to make this convenient.
 
 It is unfortunate that the mechanism for loading modules does not yet allow
diff --git a/Doc/Zsh/mod_zleparameter.yo b/Doc/Zsh/mod_zleparameter.yo
index cf79668e4..03d504724 100644
--- a/Doc/Zsh/mod_zleparameter.yo
+++ b/Doc/Zsh/mod_zleparameter.yo
@@ -1,19 +1,20 @@
-texinode(The zleparameter Module)()(The zle Module)(Zsh Modules)
-sect(The zleparameter Module)
+COMMENT(!MOD!zsh/zleparameter
+Access to internals of the Zsh Line Editor via parameters.
+!MOD!)
 cindex(parameters, special)
-The tt(zleparameter) module defines two special parameters that can be 
+The tt(zsh/zleparameter) module defines two special parameters that can be 
 used to access internal information of the Zsh Line Editor (see
 ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
 ).
 
 startitem()
-vindex(zlekeymaps)
-item(tt(zlekeymaps))(
+vindex(keymaps)
+item(tt(keymaps))(
 This array contains the names of the keymaps currently defined.
 )
-vindex(zlewidgets)
-item(tt(zlewidgets))(
+vindex(widgets)
+item(tt(widgets))(
 This associative array contains one entry per widget defined. The name 
 of the widget is the key and the value gives information about the
 widget. It is either the string `tt(builtin)' for builtin widgets, a