Improve Paragraph Navigation - add single and multi line break style

[rob-aph]

Link to issue number:

Closes #13797

Summary of the issue:

Not all applications support navigating by paragraph (control + up/down arrow) natively.
A specific example is web browsers.

Description of how this pull request fixes the issue:

Add "Document Navigation" settings panel allowing explicit choice of strategy for navigating by paragraph:

• Handled by application (default): No change in behavior. The application is responsible for responding to the key press.
• Single line break: Use a single end of line character to define a paragraph boundary.
• Multi line break: Use two or more end of line characters (I.E. at least one blank line) to define a paragraph boundary.

Fallback to "Handled by application" when single line break or double line break fails.

Testing strategy:

Tested with the following applications:

• Notepad
• Wordpad
• Visual Studio 2022
• Visual Studio Code
• Notepad++
• Bookworm
• TextPad

Known issues with pull request:

Microsoft Word and Outlook are only supported when using UIA. Only searches forward or backward a maximum of 250 lines to keep performance reasonable.

• TextPad (TextPad is not supported and is safely ignored when active.)
• Visual Studio 2022
  • Causes errors but works some of the time
  • These errors also occur when not using improved paragraph navigation, indicating that the problem lies with retrieving text from the TextInfo used with this app, and not with this feature.
• Visual Studio Code
  • Move to next paragraph when at the bottom of the document can wrap back to the top of the document. This appears to be an issue with the specific TextInfo used in this app.

Change log entries:

New features

* Adds support for both single line break (normal) and multi line break (block) paragraph navigation for use with editors that do not support such navigation natively.

Description of changes for the user:

Paragraph navigation is now supported in editors, such as Notepad and Notepad++, which do not support this feature natively. For editors which already support paragraph navigation, such as WordPad, block style paragraphs (those separated by one or more blank lines) may now be navigated in addition to single line break paragraphs.
When selecting the default option, Handled by application, paragraph navigation performs exactly as it did before this feature was added.

Code Review Checklist:

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

[cary-rowen]

I tested this and it looks good,
For 'Block Style': If in an editor with a lot of text NVDA takes some time to retrieve empty lines, NVDA will hang during the process.

[rob-aph]

Both normal and block styles give up after searching 250 lines. Can you tell me which editor you were using which made NVDA hang?

[cary-rowen]

@rob-aph
Hi, I opened an epub book using bookworm, The following is the repo of bookworm:
https://github.com/blindpandas/bookworm

Here is the book file used for testing（You need to unzip the file to get the epub file）:
test.zip

[rob-aph]

Can you please try again with my latest commit? I optimized a bit, and stopped trying to read more than the first 250 lines of paragraphs. I believe the paragraphs I detected in your book were much larger than I expected, and this caused the problem.

[cary-rowen]

Hi, @rob-aph

I tested the latest commit and there is a noticeable improvement in NVDA hang time, but there is still a lag in "block navigation".
I would also like to hear other people's opinions, Is this acceptable?

Thanks

[seanbudd]

Hi @rob-aph,

I think this is a helpful and acceptable feature.
I would also like to hear from users though, you may want to advertise #13797 and the AppVeyor PR build in the user groups to seek more feedback.

Which text editors did you test with?

Is there anything blocking the Word implementation?

[rob-aph]

Sean, I have tested with Notepad, Wordpad, Visual Studio Code, Notepad++, and TextPad. It doesn’t work with TextPad, but NVDA doesn’t work so well with TextPad anyway. There is an issue with VSCode where if using normal paragraph style, VSCode will wrap around to the top of the file if you attempt to move twice from the second to the last paragraph in the file to the next paragraph. I suspect this has something to do with the TextInfo used by VSCode, but I plan to see if I can improve the situation. As I recall, the issue with Word was a sluggishness issue – something would take too long, even in small files, and NVDA would eventually fail the call. Actually, it was more Outlook’s reading pane I was trying to get to work, but I believe Outlook and Word use the same TextInfo. There may be more I can do with Word when I become more knowledgeable on the peculiarities of it’s TextInfo – I haven’t entirely given up. I also recall this PR working in Visual Studio 2019 in the past, but I see now it doesn’t. I believe the issue may be that I require State.MULTILINE, and this value is not set in the focus object for VS 2019. Basically, I’m trying to avoid these commands getting run in single line edit fields, etc. I would be happy to advertise this PR and let users test it, but I have no idea how to get the URL for it’s AppVeyor build, or how long the build remains available. Can you point me in the right direction?

[rob-aph]

@seanbudd I have tried harder to get this to work in Word / Outlook. You asked if anything was blocking this, and I can now respond yes. It appears very inefficient to move by line in the TextInfo used by Word / Outlook. In fact, it can sometimes hang for reasons I currently do not understand. I worked around one issue, the fact that attempting to move to the next line when there is not another line returns 1 indicating that movement occurred, when in fact, nothing changed -- it should return 0.

I should add that I only have access to Windows 10, so I have no idea of the
performance on Windows 11. Perhaps it is better.

I have updated my branch to add a demo of Word / Outlook support. I find that even when it doesn't hang, navigating by block paragraphs is extremely slow, even in very short messages.

If you wish to try this in Word, you will have to switch to Browse mode, as I have not hooked up scripts for Focus mode yet, as this is really a test / demo. It works right out of the box in read-only Outlook messages.

[cary-rowen]

@rob-aph
You wrote: I feel it's more clear if a message is given, rather than repeating the current paragraph. In the case of the last paragraph with a blank line at the end of the document, "blank" would be repeated, which I feel is much more ambiguous than the message. In Notepad, for example, pressing down arrow in an empty document says "blank." You really have no idea if you are moving through blank lines, or you are at the end of the document.

---

I think the situation you mentioned belongs to another issue, and the relationship with this PR is not strongly related.
In the current situation, if I navigate to the last paragraph/first paragraph, I want to listen to the complete content of the last paragraph/first paragraph again, which cannot be completed. I can only go back to the adjacent paragraph and repeat the above action.
But for Windows' default behavior, I can press ctrl+Up/Down again to accomplish this.

[CyrilleB79]

@seanbudd, I do not know on which point you were expecting an input from me. So I have had a look on last comments of this PR. I have found new point to discuss or clarifys, sorry...

Here is my feedback:

Replace _findEndOfSentence by _findNextEndOfSentence

@rob-aph, this should be implemented as confirmed by @seanbudd in #13798 (comment).

What happens when we press ctrl+up/downArrow and document boundary is reached?

There are 3 options:

1. Report "No next/previous paragraph"
2. Report again the current paragraph
3. Report "No next/previous paragraph" and then report again the current paragraph

For now you have choosen solution 1. Personally, I would prefer solution 3.

However NVDA does not seem fully consistent between all related usages (e.g. upArrow, ctrl+upArrow, PavNum8). It would be interesting to standardize what NVDA reports in all these cases. However, I would recommend not to hold off this PR for this since it could lead to long discussions; rather open a new specific issue.

Behaviour in browse mode (browsers or Word)

What is/should be the behaviour in browse mode? @rob-aph, could you update the initial description to indicate if a specific paragraph navigation is supported or not? And if it is, what is the expected result?

When the cursor is not at the beginning of the paragraph

(edited: This point is not to take into account anymore, see further discussion.)
Where should the cursor jump when pressing ctrl+upArrow?

1. Go before the first character of the current paragraph
2. Go before the first character of the previous paragraph

It seems that you have choosen option 2. However, in the following case, option 1. happens:

• Set paragraph style on "Multi line break"
• Open Notepad
• Type the 4 following lines where <emptyLine> is just an empty line:

  abc
  <emptyLine>
  def
  <emptyLine>
  

* Put the cursor on the 4th line
* Press ctrl+upArrow

Result: the cursor jump to the first character of the current paragraph (solution 1.) which is in contradiction with other usages.

[CyrilleB79]

@rob-aph, please also consider the slight changes suggested in this review. Thanks.

[seanbudd]

This is ready to merge now. Is the pull request description up to date?

Can you add a new section "Description of changes for the user".
Include any behaviour which has changed, e.g.

• new applications which support paragraph navigation
• any changed paragraph navigation behaviour when using the default navigation style

[rob-aph]

@seanbudd I think it's ready to go.

[seanbudd]

Thanks @rob-aph for all your work on this PR!

[cary-rowen]

Hi, @rob-aph
This feature caused NVDA to lag when navigating output text within VS Code's terminal.
Navigating the output of VS Code requires you to be in browse mode, but perhaps NVDA is in edit mode by default, if you try to press Ctrl+up/downArrow before manually pressing NVDA+Spacebar you will find that NVDA is silent briefly, and after a few seconds you hear "No previous paragraph/No next paragraph".
Do you have any thoughts on the situation? In VS Code, especially in non-editable areas, should paragraph navigation be handled by the application?

[seanbudd]

@cary-rowen how do you know it is this pull request? could you create an issue to track this problem?

[cary-rowen]

Hi, @seanbudd @rob-aph
See #14522

[Adriani90]

@rob-aph first of all thanks for this huge work, really appreciated that you help us in making the world more accessible through your contribution.

I came accross an issue while using this great feature, the speech and UI messages seem not to be translatable:
Se paragraph_helper.py; line 132, 135 and 229; and globalcommands.py line 3980. The messages need to be translatable, this is a standard for all speech and UI messages in NVDA, so you need to put them in a wraper function in order to send them through Gettext to the translators. We use _("") like in this tutorial:
https://phrase.com/blog/posts/translate-python-gnu-gettext/

@seanbudd, @michaelDCurran, @nvdaes maybe this needs a broader documentation in the developer guide?

[nvdaes]

Adriani90 commented

maybe this needs a broader documentation in the developer guide?

IMO, this is well documented in the contributing.
Note that the developer guide doesn't contain info about files in standard format, just about specific files used for NVDA, like character description and symbol pronounciation.
Please see developer guide.
Cheers

[Adriani90]

It might make sense to integrate a gettext linter to make this process more secure.
Here is a good one for example:
https://www.technomancy.org/python/pylint-i18n-lint-checker/

Pylint is already included in flake8 so it should be relatively easy to include this plugin as well.
Ofcourse it needs a check beforehand to change any rules that should or should not be ignored.

[cary-rowen]

@Adriani90
Doesn't #14751 already solve the untranslatable string issue you mentioned?
If you want to suggest that NV Access improve the documentation, can you open a separate Issue?

[Adriani90]

Ah thanks, I missed that one.Then only the string in globalcommands.py still needs to be made translatable.Reg your request to me, I created a new issue.Von meinem iPhone gesendetAm 10.04.2023 um 11:44 schrieb Rowen ***@***.***>: @Adriani90 Doesn't #14751 already solve the untranslatable string issue you mentioned? If you want to suggest that NV Access improve the documentation, can you open a separate Issue? —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[seanbudd]

Then only the string in globalcommands.py still needs to be made translatable.

Could you also open an issue for this, if it is still outstanding?

[CyrilleB79]

Then only the string in globalcommands.py still needs to be made translatable.

Could you also open an issue for this, if it is still outstanding?

@Adriani90 I cannot see any untranslatable string in last alpha.
Could you confirm here that all required strings are now translatable in last alpha or give information on what should still be made translatable? Preferably in a new issue for better traceability.

[Adriani90]

It seems now everything is translatable from here, not sure which commit made line 3980 in globalCommands translatable but it seems this is fixed now.