Merge pull request #176 from Univers42/docs/issue-134-print-p-preview

docs: clarify print -P prompt preview caveat (#134)

Author: LESdylan

USER_DOC.md

@@ -114,6 +114,12 @@ What is live at every render, and what is not:
 | `$((…))` | yes |
 | `$(…)` and backquotes | **no** — the text stays on screen as written; it would fork on every redraw |
 
+**Preview caveat:** `print -P` formats its expanded input again using zsh's
+prompt escapes. If a variable contains `%` sequences, `print -rP "[${V}]"`
+can interpret them as prompt escapes even though the live prompt leaves the
+expanded value literal. Do not treat `print -P` output as an exact preview of
+variable-backed prompt segments; this mismatch is tracked in [issue #134](https://github.com/Univers42/hellish/issues/134).
+
 For a computed segment, set a variable from a hook and put the variable in
 the prompt. `HELLISH_PRECMD_FUNCS` runs once before each prompt
 (`hellishrc.example`, section 5b):

wiki/interactive.md

@@ -106,8 +106,11 @@ loaded, and a shell run from a checkout loads it with
 
 **PS1 is bilingual.** Both escape languages render in a plain PS1 — paste `%n@%m %~ %#` or
 `\u@\h \w \$` and either works, while `100% `, csh-style `%> ` and the strftime percents inside
-`$(date +%H:%M)` or `\D{%M}` survive literally. `PROMPT` and `print -P` keep exact zsh semantics
-(measured against zsh 5.9), and under `set -o zsh`, PS1 *is* PROMPT, as in zsh.
+`$(date +%H:%M)` or `\D{%M}` survive literally. `PROMPT` keeps exact zsh semantics (measured against zsh 5.9), and under
+`set -o zsh`, PS1 *is* PROMPT, as in zsh. `print -P` uses zsh's prompt
+formatter too, but it can re-interpret percent escapes in expanded variable
+contents; its output is not always an exact preview of the live prompt (issue
+[#134](https://github.com/Univers42/hellish/issues/134)).
 
 **What is live, and what is not.** `$VAR`, `${VAR…}`, `$?` and `$((…))` are expanded every time
 the prompt is drawn. Command substitution is not: `$(…)` and backquotes stay on screen as the