Merge users/9638, and workers/{21986,22118,22165,22360,22365}.

1 files changed, 21 insertions, 9 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 0ae467c42..99b3238bd 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -160,12 +160,22 @@ Change the current directory.  In the first form, change the
 current directory to var(arg), or to the value of tt($HOME) if
 var(arg) is not specified.  If var(arg) is `tt(-)', change to the
 value of tt($OLDPWD), the previous directory.
-Otherwise, if a directory named var(arg) is not found in the current
-directory and var(arg) does not begin with a slash, search each
-component of the shell parameter tt(cdpath).  If no directory is found
-and the option tt(CDABLE_VARS) is set, and a parameter named var(arg)
-exists whose value begins with a slash, treat its value as the
-directory.  In that case, the parameter is added to the named
+
+Otherwise, if var(arg) begins with a slash, attempt to change to the
+director given by var(arg).
+
+If var(arg) does not begin with a slash, the behaviour depends on whether
+the current directory `tt(.)' occurs in the list of directories contained
+in the shell parameter tt(cdpath).  If it does not, first attempt to change
+to the directory var(arg) under the current directory, and if that fails
+but tt(cdpath) is set and contains at least one element attempt to change
+to the directory var(arg) under each component of tt(cdpath) in turn until
+successful.  If `tt(.)' occurs in tt(cdpath), then tt(cdpath) is searched
+strictly in order so that `tt(.)' is only tried at the appropriate point.
+
+If no directory is found, the option tt(CDABLE_VARS) is set, and a
+parameter named var(arg) exists whose value begins with a slash, treat its
+value as the directory.  In that case, the parameter is added to the named
 directory hash table.
 
 The second form of tt(cd) substitutes the string var(new)
@@ -410,7 +420,9 @@ pattern (should be quoted) and only the history events matching this
 pattern will be shown.
 Otherwise the editor program var(ename) is invoked on a file containing
 these history events.  If var(ename) is not given, the value
-of the parameter tt(FCEDIT) is used.  If var(ename) is `tt(-)',
+of the parameter tt(FCEDIT) is used; if that is not set the value of the
+parameter tt(EDITOR) is used; if that is not set a builtin default, usually
+`tt(vi)' is used.  If var(ename) is `tt(-)',
 no editor is invoked.  When editing is complete, the edited
 command is executed.
 
@@ -1200,7 +1212,7 @@ example(trap 'print $LINENO' DEBUG)
 
 will print the line number of a command executed after it has run, while
 
-example(TRAPDEBUG() { print $LINENO; })
+example(TRAPDEBUG+LPAR()RPAR() { print $LINENO; })
 
 will always print the number zero.
 
@@ -1381,7 +1393,7 @@ determines how the function is loaded.
 )
 item(tt(-h))(
 Hide: only useful for special parameters (those marked `<S>' in the table in
-ifzman(zmanref(zshparams))\
+ifzman(zmanref(zshparam))\
 ifnzman(noderef(Parameters Set By The Shell))\
 ), and for local parameters with the same name as a special parameter,
 though harmless for others.  A special parameter with this attribute will