[PATCH] improve :A docs (was: Re: Next release (5.3))

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Peter Stephenson wrote on Wed, Jul 13, 2016 at 10:32:33 +0100:
> No one can actually point to a specific error case being fixed by the
> change.
> 
> I suggest we focus on improving the documentation of :A, as the current
> ".." behaviour is one thing it *is* clear about so it's a little
> bizarre to change *that*, to point out problems, and decide if we
> actually want a new qualifier, which I think would be fairly
> uncontroversial even if it's not frequently used.

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index c6e7b6f..c5f3c00 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -224,10 +224,15 @@ Note that the transformation takes place even if the file or any
 intervening directories do not exist.
 )
 item(tt(A))(
-As `tt(a)', but also resolve use of symbolic links where possible.
-Note that resolution of `tt(..)' occurs em(before) resolution of symbolic
-links.  This call is equivalent to tt(a) unless your system has the
-tt(realpath) system call (modern systems do).
+Turn a file name into an absolute path as the `tt(a)' modifier does, and
+em(then) pass the result through the tt(realpath+LPAR()3+RPAR()) library
+function to resolve symbolic links.
+
+Note: on systems that do not have a tt(realpath+LPAR()3+RPAR()) library
+function, symbolic links are not resolved, so on those systems `tt(a)' and
+`tt(A)' are equivalent.
+
+Note: tt(foo:A) and tt(realpath+LPAR()foo+RPAR()) are different on some inputs.
 )
 item(tt(c))(
 Resolve a command name into an absolute path by searching the command