Skip to content

docs: rewrite the em-dash sentences across docs, comments and generated text - #1712

Merged
Jaro-c merged 1 commit into
developfrom
docs/no-em-dashes
Sep 6, 2026
Merged

Jaro-c merged 1 commit into
developfrom
docs/no-em-dashes

Conversation

@Jaro-c

@Jaro-c Jaro-c commented Sep 6, 2026

Copy link
Copy Markdown
Member

Summary

  • Removes every em dash from this repository's public text: 1626 of them across 357 files, in the Markdown docs, the code comments, the workflows, the Debian packaging and two generated surfaces.
  • Each is rewritten sentence by sentence, not substituted. A spaced hyphen left behind would be the same tell the standard warns about.
  • No behaviour change, and no line added or removed anywhere.

Changes

  • Markdown, 161 across 9 files. docs/commands.md carried 48, docs/docker-migration.md 26, docs/self-update.md 23. Three README.md headings changed shape (### Optional: macOS), which moves their anchors; I grepped the tree and nothing links to them.
  • Code comments, roughly 1440. internal/compose/types/service.rs alone had 98, all of one shape: a doc comment naming a backticked compose key, then a dash, then the description. A colon there would read as a doubled colon, since the compose key already ends in one, so those 98 took a verb instead (`image:` is the container image reference). The booleans do not take a verb, so there the dash became a comma.
  • Generated text kept in step with its generator. bench/chart.py writes the SVG title, so docs/assets/bench.svg changed with it. about.hbs renders the NOTICES attribution line.
  • debian/changelog, 27, all in entries for 2.0.0 through 4.0.0. dpkg-parsechangelog still reads the file.
  • Deliberately left alone: bench/aggregate.py returns an em-dash string for a table cell with no measurement. That is a data glyph rather than punctuation, and changing it would alter published benchmark output without removing any tell.

git diff --numstat shows every file at equal insertions and deletions, so line-limit cannot move and the diff reads one line for one line.

Test plan

  • cargo fmt --all --check is clean
  • cargo clippy --locked --all-targets --all-features -- -D warnings is clean
  • cargo test --locked --all-features --workspace passes locally (2385 tests, 0 failures)
  • ./tests/shell/*.test.sh pass locally (every tracked test, including ci-runs-every-test.test.sh)
  • shellcheck is clean on every tracked *.sh and every extensionless script with a shell shebang
  • Podman lane ran (live Podman 5 and Podman 6, in the PR's own check run) for changes to internal/, the engine integration, or the libpod REST adapter
  • Asset-contract fixtures ran for changes to install.sh, install.ps1, internal/update/install.rs, the signing scripts or the release fixtures

The last two run in this PR's own checks rather than locally; internal/ and install.sh are both touched, comments only in each. This PR adds and changes no check, so there is no control to delete and watch go red. What it does touch is the wording of existing log and error strings, and I grepped the suites for every reworded string first to confirm none is asserted on.

  • New or changed checks were verified by deleting the control and watching them fail

Checklist

  • Targets develop (the release pull request that targets main is the one exception, gated by reusable-main-guard.yml)
  • Commits are signed off (DCO, git commit -s)
  • Commits are signed (required_signatures is enforced on develop and main)
  • Labels applied (type:, prio:, effort:, area: where applicable)
  • Every new file in tests/shell/ is named in some workflow's test-command (no new file here)
  • No secrets, keys or credentials in code, logs or fixtures
  • Docs updated if behaviour changed (behaviour is unchanged; the docs change is the point of the PR)
  • Cargo.toml and debian/changelog are at the same version (neither version line is touched)
  • cargo build --release --locked --bin podup fits bench/binary-budget-mib for changes that can move the binary size (comments and docs cannot move it)

Related issues

Refs #1711.

…ed text

The style standard names the em dash as the mark that makes prose read as
machine-written, and I would rather not carry it in public text at all than
argue each one against the rate threshold.

1626 of them, across the nine Markdown files, the code comments, the
workflows, the Debian packaging and the two generated surfaces. Every one is
a sentence-level rewrite: a comma, a colon, a semicolon, parentheses or a
split sentence, whichever the sentence actually wanted. A spaced hyphen left
in place would be the same tell.

Two deliberate exceptions, both recorded in the issue. bench/aggregate.py
keeps its em-dash string for a table cell with no measurement, because there
it is a data glyph rather than punctuation. And no line is added or removed
anywhere: every rewrite substitutes inside the existing wrapping, so the
diff reads one line for one line and the line-limit gate cannot move.

Behaviour is unchanged. No test asserts on any of the reworded log or error
strings, and the version-controlled SVG was regenerated in step with the
generator that writes it.

Signed-off-by: Jaro-c <75870284+Jaro-c@users.noreply.github.com>
@Jaro-c Jaro-c added type:docs Documentation prio:P3 Low priority effort:L Large area:meta Subsystem: meta labels Sep 6, 2026
@Jaro-c
Jaro-c enabled auto-merge (squash) September 6, 2026 04:56
@Jaro-c
Jaro-c merged commit eb29897 into develop Sep 6, 2026
50 checks passed
@Jaro-c
Jaro-c deleted the docs/no-em-dashes branch September 6, 2026 04:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:meta Subsystem: meta effort:L Large prio:P3 Low priority type:docs Documentation

Development

Successfully merging this pull request may close these issues.

1 participant