31592: improve documentary for handling of named directories.

Minor changes of phrasing.

3 files changed, 17 insertions, 12 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 3623f9bb9..8e46a88ee 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -277,7 +277,9 @@ item(tt(-c))(
 clear the directory stack.
 )
 item(tt(-l))(
-print directory names in full instead of using of using tt(~) expressions.
+print directory names in full instead of using of using tt(~) expressions (\
+ifzman(see em(Dynamic) and em(Static named directories) in zmanref(zshexpn))\
+ifnzman(noderef(Filename Expansion))).
 )
 item(tt(-p))(
 print directory entries one per line.
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index e8d1ed297..5ba3e21af 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1708,14 +1708,14 @@ Note that trailing slashes will be removed from the path to the directory
 It is also possible to define directory names using the tt(-d) option to the
 tt(hash) builtin.
 
-In certain circumstances (in prompts, for instance), when the shell
-prints a path, the path is checked to see if it has a named
-directory as its prefix.  If so, then the prefix portion
-is replaced with a `tt(~)' followed by the name of the directory.
-The shortest way of referring to the directory is used,
-with ties broken in favour of using a named directory,
-except when the directory is tt(/) itself.  The parameters tt($PWD) and
-tt($OLDPWD) are never abbreviated in this fashion.
+When the shell prints a path (e.g. when expanding tt(%~) in prompts or when
+printing the directory stack), the path is checked to see if it has a named
+directory as its prefix.  If so, then the prefix portion is replaced with a
+`tt(~)' followed by the name of the directory.
+The shorter of the two ways of referring to the directory is used,
+i.e. either the directory name or the full path; the name is used
+if they are the same length.
+The parameters tt($PWD) and tt($OLDPWD) are never abbreviated in this fashion.
 
 subsect(`=' expansion)
 
diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo
index 8d7979546..eab15d29d 100644
--- a/Doc/Zsh/prompt.yo
+++ b/Doc/Zsh/prompt.yo
@@ -100,10 +100,13 @@ directory to show; zero means the whole path.  A negative integer
 specifies leading components, i.e. tt(%-1d) specifies the first component.
 )
 item(tt(%~))(
-As tt(%d) and tt(%/), but if the current working directory has a named
+As tt(%d) and tt(%/), but if the current working directory starts with
+tt($HOME), that part is replaced by a `tt(~)'. Furthermore, if it has a named
 directory as its prefix, that part is replaced by a `tt(~)' followed by
-the name of the directory.  If it starts with tt($HOME), that part is
-replaced by a `tt(~)'.
+the name of the directory, but only if the result is shorter than
+the full path; 
+ifzman(see em(Dynamic) and em(Static named directories) in zmanref(zshexpn))\
+ifnzman(noderef(Filename Expansion)).
 )
 xitem(tt(%h))
 item(tt(%!))(