shape-doctor.py: a path that is not ASCII is printed as that path in every NEXT, keep line and WHY, as itself where the report's encoding writes its bytes and escaped whole where it does not, so a line naming Projets/Équipe or a Latin-1 name runs as printed (#785)

AGENTS.md

@@ -267,8 +267,8 @@ its last line names that directory, the human's to delete once those have run.
    never changes the verdict: it says whether THIS workstation can run the fixes
    the other rows named. Relay a missing prerequisite; `openRepoShape
    --preflight` offers only the `gh` set-up, and the human types that yes.
-7. `--json` is the same report as one object, alone on stdout, each row
-   carrying its `id`, for when you have to act on a row rather than quote it.
+7. `--json` is the same report as one object, alone on stdout, each row with
+   its `id`, to act on a row. A `next` with `$'…'` needs bash or zsh, not `sh`.
 
 ## Updating a project's shape
 

README.md

@@ -159,6 +159,8 @@ typed `yes`, which its preflight cannot take there. Printed commands are quoted
 for a POSIX shell, so paste them into Git Bash. Only `shape-doctor.py`'s lines,
 `setup-project.py`'s family lines and `family.py`'s `NEXT`, `switch -c`, `add`
 and `git rm -r --cached` lines are quoted for PowerShell, on Windows.
+Off Windows, a path `shape-doctor.py` cannot print as itself is written `$'…'`:
+bash, zsh and ksh read that; dash (`/bin/sh` on Debian and Ubuntu) does not.
 
 </details>
 

docs/handbook.html

@@ -472,7 +472,7 @@
 
       <!-- reads README.md § preamble: blob ddadd23a162129f7e64fefce899105661440c05c -->
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <!-- reads README.md § The three legs: blob 4ec313e8424665e41fc92a4147808e0bd4901d78 -->
 
@@ -612,7 +612,7 @@ <h4>The one thing to read before electing it</h4>
 
     <section id="start">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <p class="eyebrow">Setup</p>
       <h2>Start here</h2>
@@ -738,7 +738,9 @@ <h4>The tool offers the rest</h4>
           <code>shape-doctor.py</code>&rsquo;s lines, <code>setup-project.py</code>&rsquo;s family
           lines and <code>family.py</code>&rsquo;s <code>NEXT</code>, <code>switch -c</code>,
           <code>add</code> and <code>git rm -r --cached</code> lines are quoted for PowerShell, on
-          Windows.</p>
+          Windows. Off Windows, a path <code>shape-doctor.py</code> cannot print as itself is
+          written <code>$'&hellip;'</code>: bash, zsh and ksh read that; dash (<code>/bin/sh</code>
+          on Debian and Ubuntu) does not.</p>
         </div>
 
       </div>
@@ -1087,7 +1089,7 @@ <h4>What you have afterwards &mdash; the same on every platform</h4>
 
     <section id="partway">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <p class="eyebrow">Setup</p>
       <h2>If it fails part-way</h2>
@@ -1124,7 +1126,7 @@ <h2>If it fails part-way</h2>
 
     <section id="ci">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <!-- reads README.md § The three legs: blob 4ec313e8424665e41fc92a4147808e0bd4901d78 -->
 
@@ -1187,7 +1189,7 @@ <h2>Reading private legs in CI</h2>
 
     <section id="legs">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <!-- reads README.md § The three legs: blob 4ec313e8424665e41fc92a4147808e0bd4901d78 -->
 
@@ -1443,7 +1445,7 @@ <h3>The InkRouter example</h3>
 
     <section id="doublepin">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <!-- reads README.md § The double pin, and the lockstep invariant: blob 57fffa08ffad5476f8eae73dd3e8494a02e050c9 -->
 
@@ -1742,7 +1744,7 @@ <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
 
     <section id="park">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob 45a3f886c0203e91f17a7851cf2c1c71a2681b0c -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3d4a01ffadc322f88dfffd9cef50b1c48c58b9b3 -->
 
       <!-- reads README.md § Carrying in-flight work to another workstation: blob b84512ad39c09085dfe6bf7ea694017f5e28c1dd -->
 

scripts/shape_advisory.py

@@ -169,13 +169,15 @@
 def printable(text: str) -> str:
     """`text` as ASCII, so printing it can never be what fails a run.
 
-    THE SAME FLATTENING `shape-doctor.py`'s `ascii_text` applies to every row,
-    for the same reason, here for the two tools that print the advisory
-    themselves: a record's `kind:` is a person's text and may carry anything,
-    and a console in an ANSI code page -- or a `PYTHONIOENCODING=ascii`
-    pipe -- raises `UnicodeEncodeError` on the first character it cannot
-    write. The typography this repository writes is spelled out; anything
-    else becomes `?` rather than an exception.
+    THE FLATTENING `shape-doctor.py`'s `ascii_text` applied to every row
+    until #785, for the same reason, here for the two tools that print the
+    advisory themselves: a record's `kind:` is a person's text and may carry
+    anything, and a console in an ANSI code page -- or a
+    `PYTHONIOENCODING=ascii` pipe -- raises `UnicodeEncodeError` on the first
+    character it cannot write. The typography this repository writes is
+    spelled out; anything else becomes `?` rather than an exception. (The
+    doctor's now keeps a character its stdout can show, because a row names
+    paths a reader pastes; a `kind:` is never pasted.)
     """
     for source, target in (("—", "--"), ("–", "-"),
                            ("‘", "'"), ("’", "'"),

scripts/shape_materialize.py

@@ -162,11 +162,11 @@ def escape_what_stdout_cannot_encode(stream=None) -> None:
     file it is, and two names that differ only outside the code page do not
     both print as `??.md`. (A backslash is not escaped, so a name that holds
     the six characters `\\u65e5` prints as one holding `日` does.) ONCE, AT
-    THE START OF `main()`, and not at each `print`: `shape-doctor.py`'s
-    `ascii_text` and `shape_advisory.printable` flatten their own text to
-    ASCII on every console, which a name cannot afford -- it would change
-    what a UTF-8 terminal shows -- and a guard at each site is a guard the
-    next `print` goes without.
+    THE START OF `main()`, and not at each `print`: `shape_advisory.printable`
+    flattens its own text to ASCII on every console, as `shape-doctor.py`'s
+    `ascii_text` did until #785, which a name cannot afford -- it would
+    change what a UTF-8 terminal shows -- and a guard at each site is a
+    guard the next `print` goes without.
 
     GUARDED, because failing to set a handler is no reason to refuse the
     run: a stream a caller replaced may have no `reconfigure`, a closed or