docs(manual): keep backticks out of verbatim blocks and off line breaks

Two shapes reach a reader as literal punctuation rather than markup:

A backtick inside a four-space block. The block is verbatim in every
renderer -- pandoc sets it monospace, prettify() fences it for the site
-- so the backtick is a character on the page. Twelve such lines are
cleaned; each sat at the start of its column, so the alignment of the
C5 capture table and the component summaries is unchanged.

A span split over a line break. Markdown pairs it happily, but
config-help pairs backticks one line at a time, so `fish-deps\nupdate`
showed both halves. The sentence is reflowed.

Both are now enforced, the first by test_concat_section_five_stays_
verbatim and the second by test_concat_code_spans_never_straddle_a_line.
This commit is contained in:
2026-08-31 22:02:28 -04:00
parent b01124f99d
commit f0de5378fe
5 changed files with 33 additions and 14 deletions
+19
View File
@@ -1440,6 +1440,25 @@ def test_codespans_reach_the_man_page_pipeline():
assert "`tmux`" in text, "a vocabulary command was not wrapped in the concat"
def test_concat_code_spans_never_straddle_a_line():
"""`config-help` pairs backticks one line at a time.
Its `string replace` filters run per line, so a span split across a
line break -- ``run `fish-deps\\nupdate` `` -- leaves an unpaired
backtick the pager then shows literally. Markdown is happy to wrap
one, so nothing else catches this.
"""
import build_manual
text = build_manual.build_concat(Path(__file__).parent / "manual")
odd = [
(n, line)
for n, line in enumerate(text.split("\n"), 1)
if line.count("`") % 2
]
assert not odd, f"unpaired backtick, span wraps a line: {odd[:3]}"
def test_concat_section_five_stays_verbatim():
"""Section 5's entries are indented blocks, not prose.