Restore sentence as the default say all reading unit, with a setting to read by paragraph or line

[LeonarddeR]

Link to issue number:

Related to #13420, #9179 and #13971
Fixes #13829 by making paragraph available as an additional unit, so say all can send whole paragraphs to the synthesizer.

Summary of the issue:

For rich text controls where UNIT_READINGCHUNK was previously mapped to line (ITextDocumentTextInfo, e.g. WordPad, NVDA's log viewer, and third-party apps such as Paperback), say all's caret/review position hardly updates when word wrap is off and a paragraph spans many visual lines — the position only advances once the whole (very long) paragraph line is read. This was introduced by #13971, which changed the reading unit from sentence to line for these controls to fix caret tracking in other apps (#13420, #9179).

This PR effectively reverts the default introduced by #13971: say all now reads by sentence again by default wherever sentence boundaries are supported, restoring smoother caret tracking in rich edit controls with long paragraphs. To avoid regressing the caret-tracking fix #13971 provided for apps/languages without usable sentence boundaries, the choice is no longer hardcoded: a new speech setting lets users switch back to line-based reading, re-enabling the behavior @lukaszgo1 introduced in #13971 where they need it. A paragraph unit is also available, which sends larger chunks of text to the synthesizer so it can determine sentence boundaries (and e.g. abbreviations like "Mr.") itself (#13829).

Description of user facing changes:

• New "Say all reads by" combo box in the Speech settings panel, with three options:
  • Sentence where possible (default) — say all reads sentence by sentence where the control supports sentence boundaries, falling back to line where it doesn't.
  • Paragraph — say all reads paragraph by paragraph.
  • Line — say all always reads line by line, matching the behavior introduced by Use line as a unit for which say all is moved in rich edit controls #13971.
• Say all now reads by sentence by default in Rich Edit controls such as WordPad and NVDA's log viewer.

Description of developer facing changes:

• Added SayAllReadingUnitFlag feature flag (config.featureFlagEnums) with a [speech] sayAllReadingUnit configSpec entry, behaviorOfDefault="sentence".
• Added TextInfo.unit_readingChunk, resolving textInfos.UNIT_READINGCHUNK to UNIT_SENTENCE/UNIT_PARAGRAPH/UNIT_LINE based on the flag's calculated value; cached per core pump (_cache_unit_readingChunk) to avoid repeated config lookups in the say all loop.
• Added TextInfo._resolveReadingChunkUnit, used by winword.py/edit.py expand/move to substitute the resolved unit for UNIT_READINGCHUNK before their static unit-map lookup; the now-unreachable UNIT_READINGCHUNK entries were removed from those maps.
• OffsetsTextInfo._getReadingChunkOffsets dispatches self.unit_readingChunk through the existing _getUnitOffsets, falling back to line offsets if the resolved unit raises NotImplementedError.
• UIA-based TextInfos are unaffected: UIAHandler.NVDAUnitsToUIAUnits hardcodes UNIT_READINGCHUNK to TextUnit_Line, since UIA's TextPattern has no sentence text unit. This means modern UIA Word (NVDAObjects/UIA/wordDocument.py) already reads by line for say all regardless of this flag (the paragraph option is likewise ignored there for now); only legacy Word Object Model Word (winword.py, wdSentence) is driven by the flag.

Description of development approach:

Introduced the reading unit as a feature flag rather than hardcoding a default, so the sentence/line choice from #13971 remains available per user preference instead of being an all-or-nothing global default. SayAllReadingUnitFlag avoids a module-level import textInfos in featureFlagEnums.py, since that module is imported during config package init, before languageHandler installs the _ gettext builtin, and textInfos transitively calls _() at import time.

Testing strategy:

• Added unit tests for _getReadingChunkOffsets covering the sentence, paragraph, line, and unsupported-unit-falls-back-to-line cases.
• Manually verified say all in WordPad and NVDA's log viewer with both settings.

Known issues with pull request:

This PR defaults the flag to sentence, effectively reverting #13971's default. If reviewers decide line should remain the default (per #13971's rationale for #13420/#9179), the fix is a one-line change: flip behaviorOfDefault in the sayAllReadingUnit configSpec entry (source/config/configSpec.py) from "sentence" to "line". Note this would also move Word Object Model Word (winword.py, legacy Word) to line-based reading — it currently reads by sentence unconditionally on master (wdSentence, unaffected by #13971) and is now driven by the same flag as WordPad/log viewer. I consider this acceptable: a single uniform default across all UNIT_READINGCHUNK-capable TextInfos is preferable to Word Object Model Word and rich-edit controls disagreeing on reading unit by default. Modern UIA Word is unaffected by the default either way — it already reads by line unconditionally (see developer facing changes).

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

[LeonarddeR]

Also mentioning @cary-rowen here, since he was particularly involved with #13420 debugging.
Personally I'm using Paperback a lot lately and it is a real thorn in my eye that for long paragraphs, caret doesn't follow per sentence. I tend to disable word wrap when studying because it makes skimming a load more difficult.
Would the solution filed here be acceptable for you?
I have considered filing an issue first, but given how efficient AI is these days, I figured that it would be more helpful to provide a prototype so we can test the implementation while discussing😉

[Copilot]

Pull request overview

This PR reintroduces sentence-based “Say All” as the default reading unit (where supported) and makes the reading-chunk unit user-configurable via a new Speech setting, including a paragraph option to allow larger chunks to be sent to synthesizers.

Changes:

• Added a new “Say all reads by” Speech setting (feature flag-backed) with options for sentence (where possible), paragraph, and line.
• Updated TextInfo implementations to resolve UNIT_READINGCHUNK dynamically based on the configured reading unit, including support in legacy Word (winword) and Rich Edit (ITextDocument).
• Added unit tests for reading-chunk offsets resolution and fallback-to-line behavior when a unit isn’t implemented.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
user_docs/en/userGuide.md	Documents the new Speech setting in the User Guide.
user_docs/en/changes.md	Adds a changelog entry for the new setting / default behavior change.
tests/unit/test_textInfos.py	Adds unit tests for reading-chunk offset behavior across configured units.
source/textInfos/offsets.py	Resolves reading-chunk offsets via the configured unit with fallback to line when unsupported.
source/textInfos/init.py	Introduces unit_readingChunk and unit resolution helper for UNIT_READINGCHUNK.
source/NVDAObjects/window/winword.py	Resolves UNIT_READINGCHUNK before mapping units to Word units.
source/NVDAObjects/window/edit.py	Resolves UNIT_READINGCHUNK before mapping units to TOM units.
source/config/configSpec.py	Adds the new [speech] sayAllReadingUnit feature-flag config entry.

[SaschaCowley]

Two very minor things

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

source/textInfos/offsets.py:574

• _getReadingChunkOffsets currently catches NotImplementedError around both resolving the configured reading-chunk unit and computing offsets. If unit_readingChunk raises NotImplementedError (e.g. due to an unexpected flag value), this will be silently masked and fall back to line offsets, making configuration/logic errors hard to detect.

		try:
			return self._getUnitOffsets(self.unit_readingChunk, offset)
		except NotImplementedError:
			return self._getLineOffsets(offset)

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

user_docs/en/userGuide.md:2307

• The descriptions for the "Paragraph" and "Line" options imply they apply universally ("reads paragraph by paragraph" / "always reads line by line"). In practice, some TextInfo implementations override these units (e.g. MSHTML maps line/readingChunk to sentence), and others hardcode readingChunk to line regardless of user choice. To avoid user-facing documentation being incorrect, it would be better to qualify these options as "where supported" / "otherwise falls back to line" (similar to the sentence option).

When set to "Sentence where possible", NVDA reads sentence by sentence in controls and documents that support sentence boundaries, and automatically falls back to reading by line where sentence boundaries are not supported.
When set to "Paragraph", NVDA reads paragraph by paragraph.
When set to "Line", NVDA always reads line by line.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

user_docs/en/userGuide.md:2307

• The description of the "Paragraph" option is absolute, but (as with sentences) not all controls/TextInfo implementations support paragraph boundaries for say all reading chunks. The docs should qualify this (e.g. "where supported" / fallback to line) to avoid promising behavior that NVDA may not be able to deliver in some contexts.

This combo box lets you choose the unit of text that say all (continuous reading) advances by.
When set to "Sentence where possible", NVDA reads sentence by sentence in controls and documents that support sentence boundaries, and automatically falls back to reading by line where sentence boundaries are not supported.
When set to "Paragraph", NVDA reads paragraph by paragraph.
When set to "Line", NVDA always reads line by line.

user_docs/en/changes.md:27

• The PR description explicitly mentions fixing #13829 (paragraph-sized chunks to improve synthesizer sentence handling), but this change log entry doesn’t reference it. Please include #13829 in the issue list for traceability.

* A new "Say all reads by" speech setting lets you choose whether say all reads by sentence, paragraph or line; say all now reads by sentence by default where supported. (#13420, #9179, #13971, @LeonarddeR)

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Qchristensen]

User Guide changes are all fine, though I was wondering if it was worth a line of clarification on what this feature does? Just something simple like:

"This setting affects how frequently the text caret and view move during say all, and can also affect intonation in long blocks of text."

(I think an article in the In-Process blog could go into more detail, but I can see some users being confused by "Doesn't say all read from the current point to the end of the document? So what do you mean by moving by line or paragraph etc?)

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (2)

user_docs/en/userGuide.md:2316

• The documentation for the "Paragraph" option implies say all will always advance by paragraph, but the implementation falls back to line offsets when paragraph boundaries aren't implemented (e.g. OffsetsTextInfo._getReadingChunkOffsets catches NotImplementedError and returns line offsets). Consider documenting this fallback so users know what to expect in controls without paragraph support.

When set to "Paragraph", NVDA reads paragraph by paragraph.

user_docs/en/changes.md:29

• Minor grammar: add a serial comma in the list "sentence, paragraph or line".

* A new "Say all reads by" speech setting lets you choose whether say all reads by sentence, paragraph or line; say all now reads by sentence by default where supported. (#13420, #9179, #13971, @LeonarddeR)

[Qchristensen]

Reads well, thanks!

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (3)

source/textInfos/offsets.py:581

• _getReadingChunkOffsets is annotated/documented to return a tuple, but it currently returns whatever _getUnitOffsets/_getLineOffsets return (which can be a list in this class). Converting to tuple here keeps the runtime behavior consistent with the type hint and avoids callers having to handle mixed list/tuple return types.

		unit = self.unit_readingChunk
		try:
			return self._getUnitOffsets(unit, offset)
		except NotImplementedError:
			return self._getLineOffsets(offset)

user_docs/en/userGuide.md:2310

• The User Guide anchor includes the settings category ("SpeechSettings"). NVDA’s User Guide anchors are intended to remain stable even if a setting moves categories; introducing a category-specific anchor now risks locking in a misleading anchor name.

##### Say all reads by {#SpeechSettingsSayAllReadingUnit}

source/gui/settingsDialogs.py:1765

• If the User Guide anchor is changed to be category-independent (e.g. "SayAllReadingUnit"), this help topic ID should be updated to match so that F1 help continues to jump to the correct section.

		self.bindHelpEvent("SpeechSettingsSayAllReadingUnit", self.sayAllReadingUnitCombo)