Skip to content

Stop calling a role with prose in it a no-op - #59

Merged
tamnd merged 1 commit into
mainfrom
noop-reads-role-display-text
Aug 18, 2026
Merged

Stop calling a role with prose in it a no-op#59
tamnd merged 1 commit into
mainfrom
noop-reads-role-display-text

Conversation

@tamnd

@tamnd tamnd commented Aug 18, 2026

Copy link
Copy Markdown
Owner

Closes #54.

is_noop strips the markup and asks whether anything is left. A role written :ref:`text <target>` has words a reader sees inside the backticks, and stripping the span takes them away with the target it was protecting.

:ref:`Documentation on attributes and methods on classes <class-attrs-and-methods>`.

Seven English words, classified noop. batch never queued it so no model was asked, and Corpus.prose() never showed it so no check looked at it. Invisible from every angle that would have reported it, which is the failure the is_version_marker docstring describes, occurring in a different rule.

It surfaced only because one person had translated one of these by hand, correctly, and that made it the one non-prose entry in the mirror whose translation was not a copy of its source.

Size, measured

130 entries. The roles carrying the display text:

role entries
:ref: 117
:rfc: 6
:term: 4
:doc: 3
:option: 2

All 130 display strings were read rather than sampled. A logging cookbook, Basic Tutorial, Configurable memory allocators, Explanation of the object-oriented interface, Filesystem encoding, Command Line Interface Libraries. Prose, all of it.

Where the line is

Words are counted between the spaces, not by running [A-Za-z]{2,} over the text. That difference is 136 entries and every one of them would be wrong:

:c:member:`base_exec_prefix <PyConfig.base_exec_prefix>`

One identifier, which a pattern looking for runs of letters reads as base, exec and prefix and calls a sentence.

A display text of one word stays a no-op, which is 81 :c:member: entries naming a struct field. That is the same call is_version_marker makes about a bare token, and it is deliberately the cautious direction here: a missed entry stays exactly as it is today, while a false positive sends an identifier to a model to be translated into something that links nowhere.

A role with no display text is untouched and still a no-op.

Measured

before after
prose 75,593 75,723
noop 5,721 5,591
batches on a full run 2,801 2,803

This is the expensive direction, and it is the right one. These 130 entries have never cost a model call and have never been checked, and both of those were silent.

Checks

make check green, 1,412 tests, 97.46 per cent coverage. H03 clean.

is_noop strips the markup and asks whether anything is left. A role written
`:ref:`text <target>`` has words a reader sees inside the backticks, and
stripping the span takes them away with the target.

`:ref:`Documentation on attributes and methods on classes
<class-attrs-and-methods>`` came out a no-op. Seven English words that batch
never queued and Corpus.prose never showed to a check, so no model was asked
and nothing reported it. That is the failure the is_version_marker docstring
describes, in a different rule.

It surfaced only because one person had translated one of these by hand,
correctly, which made it the one non-prose entry in the mirror whose
translation was not a copy of its source.

130 entries in the corpus are this shape, and they carry :ref: 117 times,
:rfc: 6, :term: 4, :doc: 3 and :option: 2. All 130 display strings were read:
`A logging cookbook`, `Basic Tutorial`, `Configurable memory allocators`,
`Explaining the object-oriented interface`. Prose, all of it.

The words are counted between the spaces rather than by running the word
pattern over the text. That is worth 136 entries and every one of them is
wrong: `:c:member:`base_exec_prefix <PyConfig.base_exec_prefix>`` is one
identifier, and a pattern looking for runs of letters finds three words in it.
A display text of one word stays a no-op, which is 81 `:c:member:` entries
naming a struct field, and it is the cautious direction: a missed entry stays
as it is today, and a false positive sends an identifier to a model to be
translated into something that links nowhere.

prose 75 593 to 75 723, noop 5 721 to 5 591, batches 2 801 to 2 803.
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.

is_noop calls a :ref: with display text markup, so its prose is never translated

1 participant