Skip to content

Four passages stop describing themselves and describe their subject - #349

Merged
iderex merged 1 commit into
mainfrom
docs/952-the-texts-stop-explaining-themselves
Aug 14, 2026
Merged

Four passages stop describing themselves and describe their subject#349
iderex merged 1 commit into
mainfrom
docs/952-the-texts-stop-explaining-themselves

Conversation

@iderex

@iderex iderex commented Aug 14, 2026

Copy link
Copy Markdown
Owner

What & why

Four passages in three documents described themselves rather than their
subject. NOTICE.md said its provenance section exists because recording
provenance is worth doing on its own terms; docs/MASTERPLAN.md section 11
opened by saying what the section states; and two bullets in
docs/BENCHMARK-METHODOLOGY.md used a dash pair where a subordinate clause
belongs, in the sentences that carry the security-posture claim about a
decompression bomb.

No claim moves. The degradation factor stays 2.2-2.3x, the mutual exclusivity
of the throughput worst case and a bomb stays, the GDeflate provenance stays,
and section 11 still takes no design decision.

Closes #348

Type of change

  • Docs

Engineering checklist

Not applicable. No decode path, no device code, no API surface and no build
input is touched; the diff is three Markdown files.

  • An adversarial review was not run, and this line says so rather than
    being ticked. This change reaches no kernel, no format parsing, no C-ABI
    boundary, no build tooling and no workflow, which is the set that
    requires one.

GPU sanitizer gate

  • Not applicable: this change touches no device code.

Performance checklist

Not applicable: nothing on the hot path is touched, and docs/BENCHMARKS.md
is not among the changed files.

Quality checklist

  • Minimal: three files, 15 lines added and 17 removed.
  • Self-documenting: the rewrites are shorter than what they replace and
    keep every number.
  • No new structural property is established, so there is nothing to lock
    in as a conformance test.

Verification

The build and test boxes are NOT ticked and the reason is stated rather than
implied: no C++ toolchain run was made for this change, because the diff
reaches no source, no header, no CMake input and no test. CI is the authority
here and its build and format contexts are what the ruleset requires.

  • cmake --build build - not run, see above.
  • ctest --test-dir build - not run, see above.
  • Prettier clean on the three changed files, run locally at the head
    commit:
$ npx --yes prettier@3 --check "NOTICE.md" "docs/MASTERPLAN.md" "docs/BENCHMARK-METHODOLOGY.md"
Checking formatting...
All matched files use Prettier code style!
  • Docs synced: no behaviour, API or performance change to reflect.

Notes

The 21 en dashes in this tree are number ranges and are deliberately left
alone. Before and after the change:

$ git grep -oP '\x{2013}' -- '*.md' | wc -l
21

The docs/BENCHMARK-METHODOLOGY.md bullet list keeps two of its bold openers,
on the "No size amplification" and "The GPU advantage holds" items. Only the
first bullet lost its bold label, because that bullet's label ran into a dash
and then into the sentence, which is the construction the issue names. Making
the whole list consistent one way or the other is a larger judgement about that
document's voice and is not taken here.

There is no second reader on this change. The reasoning above and the commands
it quotes stand in place of one.

Correction, after the merge, to the number in the Notes above

The Notes section quoted

$ git grep -oP '\x{2013}' -- '*.md' | wc -l
21

and that command does not return 21. It returns 24, at the base commit and at
the merge commit alike:

$ git grep -oP '\x{2013}' 1294267 -- '*.md' | wc -l
24
$ git grep -oP '\x{2013}' f38b542 -- '*.md' | wc -l
24

21 is the number of LINES carrying an en dash, which is what a per-file count
returns and what #348 counted:

$ git grep -cP '\x{2013}' f38b542 -- '*.md'
docs/BENCHMARK-METHODOLOGY.md:2
docs/BENCHMARKS.md:11
docs/MASTERPLAN.md:8

2 plus 11 plus 8 is 21. So the figure was right about the tree and wrong about
the command that was pasted beside it, which is the pairing a reader checks.
The claim it supports is unchanged and is now measured with the command that
produces it: the en-dash count does not move across this change, 24 before and
24 after. #348's body carries the same wrong pairing and this is the correction
for both.

`NOTICE.md` said that its provenance section exists because recording
provenance is worth doing on its own terms. `docs/MASTERPLAN.md` section 11
opened by saying what the section states. Both are the document talking about
itself, and a reader who wants the provenance or the dossier has to step over a
sentence about the document first.

The two `docs/BENCHMARK-METHODOLOGY.md` bullets carried a dash pair doing the
work of a subordinate clause, in a place where the sentence is a
security-posture claim about a decompression bomb. That is the passage where
the punctuation should be doing the least work.

No claim moves. The degradation factor stays 2.2-2.3x, the mutual exclusivity
of the throughput worst case and a bomb stays, the GDeflate provenance stays,
and section 11 still takes no design decision.

The 21 en dashes in this tree are number ranges and are deliberately untouched:
`git grep -oP '\x{2013}' -- '*.md' | wc -l` returns 21 before and after.

Closes #348
@iderex
iderex merged commit f38b542 into main Aug 14, 2026
7 checks passed
@iderex
iderex deleted the docs/952-the-texts-stop-explaining-themselves branch August 14, 2026 04:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Four passages describe themselves instead of their subject

1 participant