Update Braille Reading and Automatic Scroll Rate in User Guide#20477
Update Braille Reading and Automatic Scroll Rate in User Guide#20477Qchristensen wants to merge 16 commits into
Conversation
Moved from PR #20457 to make change against beta rather than master. Accommodated the suggestions from that PR and also expanded scope to add a new "Braille Reading" topic under the main Braille section which includes a sub-section on automatic Braille scrolling. Also added tables for Braille reading and input commands. These have many unassigned gestures. The intention is to eventually document all unassigned gestures in their respective sections of the user guide.
Co-authored-by: Sean Budd <sean@nvaccess.org>
Co-authored-by: Sean Budd <sean@nvaccess.org>
Co-authored-by: Sean Budd <sean@nvaccess.org>
Co-authored-by: Sean Budd <sean@nvaccess.org>
Qchristensen
left a comment
Qchristensen
left a comment
There was a problem hiding this comment.
Fixed up keystrokes not marked up
| To use automatic braille scrolling, a gesture needs to be set in NVDA's [input gestures](#InputGestures) before it can be used. | ||
| Gesture can also be set to speed up or slow down the rate of automatic scrolling. | ||
|
|
||
| While braille is scrolling, you can still use the scroll back command to read previous contents again, and scroll forward, for example, to skip a blank line, or if the line being read is too short. |
There was a problem hiding this comment.
could this line please be split up, it's quite long and would be hard for people with lower reading levels to parse.
There was a problem hiding this comment.
| While braille is scrolling, you can still use the scroll back command to read previous contents again, and scroll forward, for example, to skip a blank line, or if the line being read is too short. | |
| While braille is scrolling, you can still use the scroll back and scroll forward commands without stopping scrolling. | |
| Scroll back can be useful to read previous contents again. | |
| Scroll forward can be useful to skip a blank line, or if the line being read is short. |
| | Toggles braille mode | `NVDA+alt+t` | Allows cycling between available braille modes: "follow cursors" and "display speech output"| | ||
| | Tether braille |`VDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | | ||
| | Toggle automatic scroll | None | Scrolls the display to present information which is larger than will fit on the display at once. Press again to pause scrolling | | ||
| | Increase automatic scroll rate | none | Makes automatic scrolling faster (when enabled) | |
There was a problem hiding this comment.
Please capitalize None in the rest of these
Co-authored-by: Sean Budd <sean@nvaccess.org>
Co-authored-by: Sean Budd <sean@nvaccess.org>
Qchristensen
left a comment
Qchristensen
left a comment
There was a problem hiding this comment.
Fixed: "none" to "None" and added KC commands around the two tables.
|
|
||
| #### Braille Reading Gestures {BrailleReadingGestures} | ||
|
|
||
| | Name | Key | Description | |
There was a problem hiding this comment.
| | Name | Key | Description | | |
| <!-- KC:beginInclude --> | |
| | Name | Key | Description | |
| | Toggle braille mode | `NVDA+alt+t` | Toggles braille mode | | ||
| | Toggle speaking when navigating braille | none | Toggles on and off speaking when navigating by lines or paragraph with braille | | ||
| | Toggle speaking character when routing | none | Toggles speaking the character under the cursor when routing cursor in text | | ||
|
|
There was a problem hiding this comment.
| <!-- KC:endInclude --> | |
| This means that, to type alt+2 with a Braille code that uses a number sign, you must first toggle Alt and then type a number sign. | ||
|
|
||
| #### Braille Input Gestures {BrailleInputGestures} | ||
|
|
There was a problem hiding this comment.
| <!-- KC:beginInclude --> | |
| | Erase last entered | `dot7` | Erases the last entered braille cell or character | | ||
| | Translate braille input | `dot7+dot8` | Translates any braille input | | ||
| | Translate and press enter | `dot8` | Translates any braille input and presses the enter key | | ||
|
|
There was a problem hiding this comment.
| <!-- KC:endInclude --> | |
| | Toggles braille mode | `NVDA+alt+t` | Allows cycling between available braille modes: "follow cursors" and "display speech output"| | ||
| | Tether braille |`VDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | | ||
| | Toggle automatic scroll | None | Scrolls the display to present information which is larger than will fit on the display at once. Press again to pause scrolling | | ||
| | Increase automatic scroll rate | none | Makes automatic scrolling faster (when enabled) | |
There was a problem hiding this comment.
| | Increase automatic scroll rate | none | Makes automatic scrolling faster (when enabled) | | |
| | Increase automatic scroll rate | None | Makes automatic scrolling faster (when enabled) | |
| | Report braille formatting | none | Reports formatting info for the text under this braille cell | | ||
| | Route to or activate braille object | none | Routes the cursor to or activates the object under this braille cell | | ||
| | Scroll braille display back | none | Scrolls the braille display back | | ||
| | Scroll braille display forward | none | Scrolls the braille display forward | |
There was a problem hiding this comment.
| | Scroll braille display forward | none | Scrolls the braille display forward | | |
| | Scroll braille display forward | None | Scrolls the braille display forward | |
| | Scroll braille display back | none | Scrolls the braille display back | | ||
| | Scroll braille display forward | none | Scrolls the braille display forward | | ||
| | Toggle braille tethering | `NVDA+ctrl+t` | Toggle tethering of braille between the focus and the review position | | ||
| | Toggle braille cursor | none | Toggle the braille cursor on and off | |
There was a problem hiding this comment.
| | Toggle braille cursor | none | Toggle the braille cursor on and off | | |
| | Toggle braille cursor | None | Toggle the braille cursor on and off | |
| | Scroll braille display forward | none | Scrolls the braille display forward | | ||
| | Toggle braille tethering | `NVDA+ctrl+t` | Toggle tethering of braille between the focus and the review position | | ||
| | Toggle braille cursor | none | Toggle the braille cursor on and off | | ||
| | Toggle braille context information | none | Toggle the way context information is presented in braille | |
There was a problem hiding this comment.
| | Toggle braille context information | none | Toggle the way context information is presented in braille | | |
| | Toggle braille context information | None | Toggle the way context information is presented in braille | |
| | Toggle braille cursor | none | Toggle the braille cursor on and off | | ||
| | Toggle braille context information | none | Toggle the way context information is presented in braille | | ||
| | Toggle braille mode | `NVDA+alt+t` | Toggles braille mode | | ||
| | Toggle speaking when navigating braille | none | Toggles on and off speaking when navigating by lines or paragraph with braille | |
There was a problem hiding this comment.
| | Toggle speaking when navigating braille | none | Toggles on and off speaking when navigating by lines or paragraph with braille | | |
| | Toggle speaking when navigating braille | None | Toggles on and off speaking when navigating by lines or paragraph with braille | |
| | Toggle braille context information | none | Toggle the way context information is presented in braille | | ||
| | Toggle braille mode | `NVDA+alt+t` | Toggles braille mode | | ||
| | Toggle speaking when navigating braille | none | Toggles on and off speaking when navigating by lines or paragraph with braille | | ||
| | Toggle speaking character when routing | none | Toggles speaking the character under the cursor when routing cursor in text | |
There was a problem hiding this comment.
| | Toggle speaking character when routing | none | Toggles speaking the character under the cursor when routing cursor in text | | |
| | Toggle speaking character when routing | None | Toggles speaking the character under the cursor when routing cursor in text | |
| | Toggle braille tethering | `NVDA+ctrl+t` | Toggle tethering of braille between the focus and the review position | | ||
| | Toggle braille cursor | none | Toggle the braille cursor on and off | | ||
| | Toggle braille context information | none | Toggle the way context information is presented in braille | | ||
| | Toggle braille mode | `NVDA+alt+t` | Toggles braille mode | |
There was a problem hiding this comment.
This entry appears twice in the table.
|
|
||
| #### Braille Reading Gestures {BrailleReadingGestures} | ||
|
|
||
| | Name | Key | Description | |
There was a problem hiding this comment.
Even if there are, unfortunately, exceptions (e.g. Magnifier), the gesture corresponding to a setting are usually documented along with this same setting.
I'd recommend to stick to this approach with this PR and document here only the gestures which have no corresponding setting, e.g. toggle automatic scrolling (but not increase/decrease rate), scroll backward / forward, etc. Also, I've not looked at it but some of these gestures are probably already documented in the braille displays section (e.g. scroll backward/forward) Again, beware to duplicates.
We can then discuss in a subsequent issue / PR if settings gestures should be documented along with the corresponding setting description of the option in the dialog or in a single table in the section describing the feature.
There was a problem hiding this comment.
I'm a bit confused what you are arguing for here? The magnifier section in the user guide (not its settings) is where the table of settings for using magnification is.... which is consistent with object navigation, review cursor, mouse navigation, browse mode, etc. Having a table of Braille gestures in the main "Braille" section seems to be in line with that? (The section you are commenting on here IS in the main braille section, not the setting. This PR covers edits to both parts of the user guide).
The one thing I didn't put in was the little table where the setting is noting what the default keystroke etc is, is that what you were looking for?
There was a problem hiding this comment.
For example regarding object navigation:
In paragraph 5.4, you have a table with commands such as "Report current object", "Move to containing object", etc. All the commands of this table have no equivalent in the settings section ()
This is of course not 100% accurate. For mouse we have "Toggle mouse audio coordinates" in the table of the paragraph of the feature "5.7. Navigating with the Mouse" but none of the other mouse settings even when they are assigned such as mouse tracking (NVDA+M) which is documented in "13.1.12.3. Enable mouse tracking".
On the opposite, for Magnifier, we have duplicated commands to toggle settings which appear both in the table of paragraph "10.2. Magnifier Commands" and in the sub-paragraphs of paragraph "13.1.10. Magnifier", e.g. NVDA+shift+w, NVDA+shift+i.
| This slider controls the rate of automatic braille display scrolling, measured in cells per second. | ||
| This slider controls the rate at which NVDA scrolls the braille display when [automatic braille scrolling](#AutomaticBrailleScrolling) 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](#InputGestures). |
There was a problem hiding this comment.
This line should be removed.
It's related to the feature, not to the setting.
More, you've already written this in the section dedicated to the braille scrolling feature.
There was a problem hiding this comment.
Well, it's related to being able to use the setting. This is the first option we have in the whole settings dialog which affects a feature which does not have a default gesture. I'm concerned people may be confused by that so wanted to make it abundantly clear - but I'm open to what others think?
Meanwhile, Noelia has created an issue proposing a default gesture, so if that is adopted, then obviously this line can be removed in both places (though still applies to other braille gestures, but we can discuss that separately).
There was a problem hiding this comment.
Just above in the paragraph, you write:
This slider controls the rate at which NVDA scrolls the braille display when [automatic braille scrolling](#AutomaticBrailleScrolling) is enabled, measured in cells per second.
You already mention the feature, with a link to its description paragraph, and indicate that this parameter applies when the feature is enabled.
This seemed enough to me.
| This slider controls the rate at which NVDA scrolls the braille display when [automatic braille scrolling](#AutomaticBrailleScrolling) 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](#InputGestures). | ||
| You may also assign gestures to increase or decrease the scroll rate. |
There was a problem hiding this comment.
This wording would be more similar to what we already have in other paragraphs.
| You may also assign gestures to increase or decrease the scroll rate. | |
| To increase or decrease the scroll rate from anywhere, please assign custom gestures using the [Input Gestures dialog](#InputGestures). |
There was a problem hiding this comment.
I'm happy either way, my only thought is that it is then almost identical to the previous sentence? (and obviously this sentence would be kept - or removed per your other suggestion - along with that previous sentence.
There was a problem hiding this comment.
No, my suggestion was:
- to remove previous sentence, which is about the feature
- keep this one, which is about the setting, but reword it
Of course, if you discard my suggestion to drop the previous sentence, this suggestion does not fit anymore.
| | Name | Key | Description | | ||
| |---|---|---| | ||
| | Toggles braille mode | `NVDA+alt+t` | Allows cycling between available braille modes: "follow cursors" and "display speech output"| | ||
| | Tether braille |`VDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | |
There was a problem hiding this comment.
| | Tether braille |`VDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | | |
| | Tether braille |`NVDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | |
There was a problem hiding this comment.
| | Tether braille |`VDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | | |
| | Tether braille |`NVDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both | |
| | Toggle braille tethering | `NVDA+ctrl+t` | Toggle tethering of braille between the focus and the review position | | ||
| | Toggle braille cursor | none | Toggle the braille cursor on and off | | ||
| | Toggle braille context information | none | Toggle the way context information is presented in braille | | ||
| | Toggle braille mode | `NVDA+alt+t` | Toggles braille mode | |
There was a problem hiding this comment.
| | Toggle braille mode | `NVDA+alt+t` | Toggles braille mode | |
Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>
4 participants
Link to issue number:
No issue, but supersedes PR #20457 (Which I'll close now this is open)
Summary of the issue:
Moved from PR #20457 to make change against beta rather than master. Accommodated the suggestions from that PR and also expanded scope to add a new "Braille Reading" topic under the main Braille section which includes a sub-section on automatic Braille scrolling.
Also added tables for Braille reading and input commands. These have many unassigned gestures. The intention is to eventually document all unassigned gestures in their respective sections of the user guide.
Initially prompted because 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).
Description of user facing changes:
Updated user guide
Description of developer facing changes:
Description of development approach:
Testing strategy:
Known issues with pull request:
Issue #20473 proposes several gestures which will need to be added to the table / documentation once added. (They will also mean less emphasis on the gestures being undefined, though given the number of braille gestures which ARE undefined, it will still be worth highlighting in that section of the user guide).
Code Review Checklist: