[PATCH][doc] clarify order of backslash and prompt expansion in print -P

[PATCH][doc] clarify order of backslash and prompt expansion in print -P

[Stephane Chazelas]

Also remind that you don't need to escape the backslashes if
using print -rP as I've seem people going through all the
trouble of doing that escaping when they could just have use -r.

diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo
index 909012c8e..5b31bcd6c 100644
--- a/Doc/Zsh/prompt.yo
+++ b/Doc/Zsh/prompt.yo
@@ -3,8 +3,11 @@ chapter(Prompt Expansion)
 sect(Expansion of Prompt Sequences)
 cindex(prompt expansion)
 cindex(expansion, prompt)
-Prompt sequences undergo a special form of expansion.  This type of expansion
-is also available using the tt(-P) option to the tt(print) builtin.
+Prompt sequences undergo a special form of expansion.  This type of
+expansion is also available using the tt(-P) option to the tt(print)
+builtin, performed there em(after) backslash expansion unless used in
+combination with the tt(-r) option to disable the latter or tt(-f) to
+specify a format string.
 
 pindex(PROMPT_SUBST, use of)
 If the tt(PROMPT_SUBST) option is set, the prompt string is first subjected to
@@ -358,10 +361,12 @@ For example, if the current directory is `tt(/home/pike)',
 the prompt `tt(%8<..<%/)' will expand to `tt(..e/pike)'.
 In this string, the terminating character (`tt(<)', `tt(>)' or `tt(])'),
 or in fact any character, may be quoted by a preceding `tt(\)'; note
-when using tt(print -P), however, that this must be doubled as the
-string is also subject to standard tt(print) processing, in addition
-to any backslashes removed by a double quoted string:  the worst case
-is therefore `tt(print -P "%<\\\\<<...")'.
+when using tt(print -P) without tt(-r)/tt(-f), however, that this must
+be doubled as the string is also subject to standard tt(print)
+processing, in addition to any backslashes removed by a double quoted
+string:  the worst case is therefore `tt(print -P "%<\\\\<<...")' to
+escape the `tt(<)' and achieve the same as `tt(print -rP '%2<\<<...')'
+or `tt(print -Pf '%s\n' '%2<\<<...')'.
 
 If the var(string) is longer than the specified truncation length,
 it will appear in full, completely replacing the truncated string.

Re: [PATCH][doc] clarify order of backslash and prompt expansion in print -P

[Bart Schaefer]

On Fri, Jul 28, 2023 at 2:47 AM Stephane Chazelas <stephane@chazelas.org> wrote:
>
> Also remind that you don't need to escape the backslashes if
> using print -rP

This is a good idea but I think the attempt to describe it could be clearer.

> +Prompt sequences undergo a special form of expansion.  This type of
> +expansion is also available using the tt(-P) option to the tt(print)
> +builtin, performed there em(after) backslash expansion unless used in
> +combination with the tt(-r) option

The "unless" here could be read as  "available unless used with -r"
rather than the intended "after backslash unless used".  I'd reverse
the order:

... builtin.  Unless used in combination with tt(-r) for raw output or
tt(-f) to specify a format string, backslash expansion occurs first.