Update automatic scrolling in the userGuide

[Qchristensen]

Link to issue number:

NA - as a relatively small change to the user guide, I went straight to this PR.

Summary of the issue:

Automatic braille scrolling requires an unassigned gesture to be used in order to work. This wasn't 100% obvious in the documentation originally (at least not to me), so I've updated the description of the slider in the user guide to more clearly convey that.

Description of user facing changes:

Updated the "Automatic Scroll Rate {#BrailleAutoScrollRate}" topic in the user guide to more clearly convey that you need to assign a gesture. The topic now starts:

"This slider controls the rate at which NVDA scrolls the braille display when automatic scrolling is enabled, measured in cells per second.

In order to use this feature, you first need to assign a gesture to toggle automatic braille scrolling in the "Braille" section of the Input Gestures dialog. You may also assign gestures to increase or decrease the scroll rate."

Description of developer facing changes:

Description of development approach:

Testing strategy:

Known issues with pull request:

Code Review Checklist:

• [ X ] 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
• [ X ] UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• [ X ] API is compatible with existing add-ons.
• Security precautions taken.

[CyrilleB79]

Actually the way Automatic braille scrolling feature works was not, and still isn't so much, because the feature itself is not described in the User Guide; only one of its parameter is described.

Automatic braille scrolling is a feature which does not correspond to a setting, i.e. there is no checkbox in the settings dialog to tell if auto braille scrolling is enabled/disabled. It may be compared with speech mode, which has a gesture, but which is not stored in the config itself. Only specific setting of speech mode (the modes in the cycle command) can be stored in settings.

To me, a paragraph in the braille section (just before the "Braille Input" paragraph) is missing: it should describe the feature:

• what it does
• Indicate if / when the feature is disabled; according to my tests, it can disable automatically, not only upon dedicated command, but did not yet really understand when (when calling other scripts?)
• a table with the (unassigned) gesture to enable/disable it (with the tags to include it in Commands quick reference too)

Cc @nvdaes in case Quentin writes such a paragraph so that you can review it.

Also, my opinion is that such a feature, which has no equivalent enable/disable setting in the GUI, deserves a gesture assigned by default; this may be considered out-of-scope in this PR though.

[nvdaes]

@CyrilleB79 wrote:

• Indicate if / when the feature is disabled; according to my tests, it can disable automatically, not only upon dedicated command, but did not yet really understand when (when calling other scripts?)
Hi Cyrille: Have you seen this paragraph, included in the user guide? I think that I can read it in this PR:

Automatic scrolling will be disabled if a routing key is pressed, if a message is presented in braille, if a new object is displayed, when entering a secure screen, when the session is locked, or when the end of the window is reached.

Personal note on this comment: Auto-scrolling is disabled when a message is displayed in braille, except for the message which indicates "Auto scroll enabled".
Also, technically, the feature is disabled when it tries to run nextLine but this is not possible (an exception is raised), what should happen, for example, when the cursor reaches the end of the current document.
About adding a new gesture, I guess that this would require further discussion, since we don't know if this feature is used too much. For me it's useful, and I use NVDA+alt+j to toggle it, NVDA+j to increase the scroll rate, and NVDA+shift+j to decrease.
Hope this helps, or let us know how to proceed here.

[seanbudd]

@Qchristensen could you please make these changes against beta rather than master?

You can do that in the GitHub interface via: https://github.com/nvaccess/nvda/edit/beta/user_docs/en/userGuide.md

[CyrilleB79]

Sorry @nvdaes you're right, the stop condition are detailed in the paragraph.

My comment still stands regarding the need to split the paragraph content in 2:

• A sub-paragraph describing the "Automatic braille scroll" feature in the "Braille" section.
• Restrict the content of "Automatic Scroll Rate" paragraph to the description of this specific option and link to the new paragraph describing more generally the feature

It has no sense (and is less clear) to describe a whole feature in the paragraph dedicated to one of its parameters.

@Qchristensen, @seanbudd your opinion?

[SaschaCowley]

@CyrilleB79, @nvdaes personally, I think that braille display gestures make the most sense for braille auto scroll. For example, on the Hims displays (BrailleEdge, Braille eMotion, BrailleSense6 at the very least), I think that leftSideScrollDown+rightSideScrollDown to toggle braille auto scroll, leftSideScrollUp+leftSideScrollDown to decrease the rate, and rightSideScrollUp+rightSideScrollDown to increase it feel intuitive. Those gestures aren't actually available (they're already used by default), but they feel intuitive to me. Note that we can't use the same gestures as the eMotion uses internally as they use space+Dot3 and dot6 to increase and decrease the rate.
@nvdaes NVDA+alt+j/k/l for decrease, toggle and increase respectively make a lot of sense to me for keyboard gestures.
All of that being said, this conversation should take place in its own issue :)

[nvdaes]

@SaschaCowley , thanks for your previous comment about gestures for this feature.
I'm happy to open a new issue unless @CyrilleB79 wants to do it, and also I may open a PR if the issue is accepted as a new feature.

[CyrilleB79]

I am not a user of this feature; I'm only an occasional braille user.
So yes @nvdaes you can open an issue and I'll comment there if needed.
My point was just that having a feature with no GUI control nor assigned shortcut to enable it was quite uncommon and would make it quite hard to discover.

[Qchristensen]

I've taken all the comments into account and created new PR #20477 to target beta instead of master. It also adds the requested information about braille reading to the user guide and moves some of the description of this feature from the setting to the (new) automatic braille scrolling sub-section.

Note that in the meantime, issue #20473 has proposed some default keystrokes for the feature, which will lesson the emphasis on the gestures being undefined, but as noted in my other PR, given the number of unassigned braille gestures, it's still definitely worth having AN emphasis of how to do that in there somewhere.

Closed in favour of #20477