Add ability to report start of paragraphs in braille

source/braille.py

@@ -1142,6 +1142,9 @@ def getFormatFieldBraille(field, fieldCache, isAtStart, formatConfig):
 	"""
 	textList = []
 	if isAtStart:
+		paragraphStartMarker = getParagraphStartMarker()
+		if paragraphStartMarker:
+			textList.append(paragraphStartMarker)
 		if formatConfig["reportLineNumber"]:
 			lineNumber = field.get("line-number")
 			if lineNumber:
@@ -1195,6 +1198,25 @@ def getFormatFieldBraille(field, fieldCache, isAtStart, formatConfig):
 	return TEXT_SEPARATOR.join([x for x in textList if x])
 
 
+def getParagraphStartMarker() -> str | None:
+	brailleConfig = config.conf["braille"]
+	if brailleConfig["readByParagraph"]:
+		paragraphStartMarker = brailleConfig["paragraphStartMarker"]
+		if paragraphStartMarker == "¶":
+			# Translators: This is a paragraph start marker used in braille.
+			# The default symbol is the pilcrow,
+			# a symbol also known as "paragraph symbol" or "paragraph marker".
+			# This symbol should translate in braille via LibLouis automatically.
+			# If there is a more appropriate character for your locale,
+			# consider overwriting this (e.g. for Ge'ez ፨).
+			# You can also use Unicode Braille such as ⠘⠏.
+			# Ensure this is consistent with other strings with the context "paragraphMarker".
+			paragraphStartMarker = pgettext("paragraphMarker", "¶")
+	else:
+		paragraphStartMarker = None
+	return paragraphStartMarker
+
+
 def _getFormattingTags(
 	field: dict[str, str],
 	fieldCache: dict[str, str],
@@ -1899,6 +1921,16 @@ def _set_windowEndPos(self, endPos):
 					break
 		except ValueError:
 			pass
+		# When word wrap is enabled, the first block of spaces may be removed from the current window.
+		# This may prevent displaying the start of paragraphs.
+		paragraphStartMarker = getParagraphStartMarker()
+		if paragraphStartMarker and self.regions[-1].rawText.startswith(
+			paragraphStartMarker + TEXT_SEPARATOR,
+		):
+			region, regionStart, regionEnd = list(self.regionsWithPositions)[-1]
+			# Show paragraph start indicator if it is now at the left of the current braille window
+			if startPos <= len(paragraphStartMarker) + 1:
+				startPos = self.regionPosToBufferPos(region, regionStart)
 		self.windowStartPos = startPos
 
 	def _nextWindow(self):

source/config/configFlags.py

@@ -251,3 +251,22 @@ def _displayStringLabels(self):
 			# Translators: A label for an option to choose a method of reporting information, e.g. font attributes.
 			self.SPEECH_AND_BRAILLE: _("Speech and braille"),
 		}
+
+
+class ParagraphStartMarker(DisplayStringStrEnum):
+	NONE = ""
+	SPACE = " "
+	PILCROW = "¶"
+
+	@property
+	def _displayStringLabels(self):
+		return {
+			# Translators: This is a label for a paragraph start marker.
+			self.NONE: pgettext("paragraphMarker", "No paragraph start marker (default)"),
+			# Translators: This is a label for a paragraph start marker.
+			self.SPACE: pgettext("paragraphMarker", "Double space (  )"),
+			# Translators: This is a label for a paragraph start marker.
+			# Pilcrow is a symbol also known as "paragraph symbol" or "paragraph marker".
+			# Ensure this is consistent with other strings with the context "paragraphMarker".
+			self.PILCROW: pgettext("paragraphMarker", "Pilcrow (¶)"),
+		}

source/config/configSpec.py

@@ -85,6 +85,7 @@
 	reviewRoutingMovesSystemCaret = featureFlag(\
 		optionsEnum="ReviewRoutingMovesSystemCaretFlag", behaviorOfDefault="NEVER")
 	readByParagraph = boolean(default=false)
+	paragraphStartMarker = option("", " ", "¶", default="")
 	wordWrap = boolean(default=true)
 	unicodeNormalization = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")
 	focusContextPresentation = option("changedContext", "fill", "scroll", default="changedContext")

source/gui/settingsDialogs.py

@@ -31,6 +31,7 @@
 	NVDAKey,
 	ShowMessages,
 	TetherTo,
+	ParagraphStartMarker,
 	ReportLineIndentation,
 	ReportTableHeaders,
 	ReportCellBorders,
@@ -4386,8 +4387,24 @@ def makeSettings(self, settingsSizer):
 			wx.CheckBox(self.followCursorGroupBox, label=readByParagraphText),
 		)
 		self.bindHelpEvent("BrailleSettingsReadByParagraph", self.readByParagraphCheckBox)
+		self.readByParagraphCheckBox.Bind(wx.EVT_CHECKBOX, self.onReadByParagraphChange)
 		self.readByParagraphCheckBox.Value = config.conf["braille"]["readByParagraph"]
 
+		# Translators: This is a label for a combo-box in the Braille settings panel to select paragraph start markers.
+		labelText = _("Paragraph start marker:")
+		self.paragraphStartMarkersComboBox = followCursorGroupHelper.addLabeledControl(
+			labelText,
+			wx.Choice,
+			choices=[marker.displayString for marker in ParagraphStartMarker],
+		)
+		self.bindHelpEvent("BrailleParagraphStartMarkers", self.paragraphStartMarkersComboBox)
+		paragraphStartMarker = config.conf["braille"]["paragraphStartMarker"]
+		self.paragraphStartMarkersComboBox.SetSelection(
+			[marker.value for marker in ParagraphStartMarker].index(paragraphStartMarker),
+		)
+		if not self.readByParagraphCheckBox.GetValue():
+			self.paragraphStartMarkersComboBox.Disable()
+
 		# Translators: The label for a setting in braille settings to select how the context for the focus object should be presented on a braille display.
 		focusContextPresentationLabelText = _("Focus context presentation:")
 		self.focusContextPresentationValues = [x[0] for x in braille.focusContextPresentations]
@@ -4494,6 +4511,9 @@ def onSave(self):
 			braille.handler.setTether(tetherChoice, auto=False)
 		self.brailleReviewRoutingMovesSystemCaretCombo.saveCurrentValueToConf()
 		config.conf["braille"]["readByParagraph"] = self.readByParagraphCheckBox.Value
+		config.conf["braille"]["paragraphStartMarker"] = [marker.value for marker in ParagraphStartMarker][
+			self.paragraphStartMarkersComboBox.GetSelection()
+		]
 		config.conf["braille"]["wordWrap"] = self.wordWrapCheckBox.Value
 		self.unicodeNormalizationCombo.saveCurrentValueToConf()
 		config.conf["braille"]["focusContextPresentation"] = self.focusContextPresentationValues[
@@ -4520,6 +4540,9 @@ def onTetherToChange(self, evt: wx.CommandEvent) -> None:
 		tetherChoice = [x.value for x in TetherTo][evt.GetSelection()]
 		self.brailleReviewRoutingMovesSystemCaretCombo.Enable(tetherChoice != TetherTo.FOCUS.value)
 
+	def onReadByParagraphChange(self, evt: wx.CommandEvent):
+		self.paragraphStartMarkersComboBox.Enable(evt.IsChecked())
+
 	def _onModeChange(self, evt: wx.CommandEvent):
 		self.followCursorGroupBox.Enable(not evt.GetSelection())
 

user_docs/en/changes.md

@@ -13,6 +13,7 @@
 The available options are:
   * Liblouis (default): Uses formatting markers defined in the selected braille table.
   * Tags: Uses start and end tags to denote where certain font attributes begin and end. (#16864)
+* When the "Read by paragraph" option is enabled, NVDA can now be configured to indicate the start of paragraphs in braille. (#16895,  @nvdaes)
 * The timeout to perform a multiple keypress is now configurable; this may be especially useful for people with dexterity impairment. (#11929, @CyrilleB79)
 
 ### Changes

user_docs/en/userGuide.md

@@ -2163,6 +2163,19 @@ This means that you do not have to scroll the display at the end of each line ev
 This may allow for more fluent reading of large amounts of text.
 It is disabled by default.
 
+##### Paragraph start marker {#BrailleParagraphStartMarkers}
+
+If "Read by paragraph" is checked, the selected start marker will be displayed to indicate the start of a paragraph.
+This can be especially helpful in applications used to read large pieces of text, like structured documents or books.
+In such documents, knowing where paragraphs start may be useful to understand the structure of the content, or to set bookmarks or annotations based on paragraph position.
+
+The options include using double space for softer paragraph breaks, or alternatively the paragraph symbol, Pilcrow (¶), for more obvious paragraph breaks.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |No paragraph start marker, Double space (  ), Pilcrow (¶)|
+|Default |No paragraph start marker|
+
 ##### Focus context presentation {#BrailleSettingsFocusContextPresentation}
 
 This option allows you to choose what context information NVDA will show on the braille display when an object gets focus.