Skip to content

Commit ef9f09b

Browse files
seanbuddseanbudd
authored
Merge a7507ba into c1d01a5 
2 parents c1d01a5 + a7507ba commit ef9f09b

106 files changed

Lines changed: 9293 additions & 6276 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,20 @@ Each of the questions and sections below start with multiple hash symbols (#). P
1616
### Steps to reproduce:
1717

1818
### Actual behavior:
19+
<!--
20+
Use "Speak command keys" (NVDA+4) and speech viewer to copy and paste here.
21+
Use braille viewer to copy and paste here.
22+
You may additionally include an explanation.
23+
-->
1924

2025
### Expected behavior:
26+
<!--
27+
Use "Speak command keys" (NVDA+4) and speech viewer to copy and paste here.
28+
Use braille viewer to copy and paste here.
29+
You may additionally include an explanation.
30+
-->
31+
32+
### NVDA logs, crash dumps and other attachments:
2133

2234
### System configuration
2335
#### NVDA installed/portable/running from source:

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ Please initially open PRs as a draft. See https://github.com/nvaccess/nvda/wiki/
99

1010
### Summary of the issue:
1111

12-
### Description of how this pull request fixes the issue:
12+
### Description of user facing changes
13+
14+
### Description of development approach
1315

1416
### Testing strategy:
1517

‎appveyor/scripts/buildSymbolStore.ps1‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@ foreach ($syms in
77
"source\lib64\*.dll", "source\lib64\*.exe", "source\lib64\*.pdb",
88
"source\synthDrivers\*.dll", "source\synthDrivers\*.pdb"
99
) {
10-
& $env:symstore add -:NOREFS /s symbols /compress /t NVDA /f $syms
10+
# https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/symstore-command-line-options
11+
& $env:symstore add /f $syms /s symbols /t NVDA /compress
1112
}

‎devDocs/featureFlags.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Feature Flags
2+
3+
NVDA makes judicious use of feature flags to enable and disable features that are in early development.
4+
The following are provided to streamline the creation of new feature flags:
5+
- A config spec type
6+
- A GUI control type
7+
8+
## Background
9+
When providing a feature flag it is important to understand the importance of providing a "default" state.
10+
A boolean feature, must have 3 states selectable by the user:
11+
- `True`
12+
- `False`
13+
- `Default` (NVDA developer recommendation)
14+
15+
This allows a choice between the following use-cases to be made at any point in time:
16+
- **Explicitly opt-in** to the feature, regardless of the default behavior.
17+
An early adopter may choose to do this to test the feature and provide feedback.
18+
- **Explicitly opt-out** of the feature, regardless of the default behavior.
19+
A user may find the pre-existing behavior acceptable, and wants the maximum delay to adopt the new feature.
20+
They may be prioritising stability, or anticipating this feature flag receives a permanent home in NVDA settings.
21+
- **Explicitly choose the default** (NVDA developer recommended) behavior.
22+
Noting, that in this case it is important that the user must be able to select one of the other options first,
23+
and return to the default behavior at any point in time.
24+
25+
This should be possible while still allowing developers to change the behaviour
26+
of the default option.
27+
The development process might require that initially NVDA is released with
28+
the feature disabled by default.
29+
In this case only testers, or the most curious users are expected to opt-in temporarily.
30+
As the feature improves, bugs are fixed, edge cases are handled, and the UX is improved,
31+
developers may wish to change the behavior of the default option to enable the feature.
32+
This change shouldn't affect those who have already explicitly opted out of the feature.
33+
Only those who maybe haven't tried the feature, because they were using the prior default behaviour, or
34+
those who have tried and found the feature to be unstable and decided they would wait for it to become
35+
stable.
36+
37+
## Feature Flag Enum
38+
To aid static typing in NVDA, `enum` classes are used.
39+
`BoolFlag` is provided, the majority of feature flags are expected to use this.
40+
However, if more values are required (E.G. `AllowUiaInMSWord` has options `WHEN_NECESSARY`, `WHERE_SUITABLE`, `ALWAYS`, in addition to `DEFAULT`), then a new `enum` class can be defined.
41+
Adding the enum class to the `featureFlagEnums.py` file will automatically expose it for use in the config spec (see the next section).
42+
Example new `enum` class:
43+
44+
```python
45+
46+
class AllowUiaInMSWordFlag(DisplayStringEnum):
47+
"""Feature flag for UIA in MS Word.
48+
The explicit DEFAULT option allows developers to differentiate between a value set that happens to be
49+
the current default, and a value that has been returned to the "default" explicitly.
50+
"""
51+
52+
@property
53+
def _displayStringLabels(self):
54+
""" These labels will be used in the GUI when displaying the options.
55+
"""
56+
# To prevent duplication, self.DEFAULT is not included here.
57+
return {
58+
# Translators: Label for an option in NVDA settings.
59+
self.WHEN_NECESSARY: _("Only when necessary"),
60+
# Translators: Label for an option in NVDA settings.
61+
self.WHERE_SUITABLE: _("Where suitable"),
62+
# Translators: Label for an option in NVDA settings.
63+
self.ALWAYS: _("ALWAYS"),
64+
}
65+
66+
DEFAULT = enum.auto()
67+
WHEN_NECESSARY = enum.auto()
68+
WHERE_SUITABLE = enum.auto()
69+
ALWAYS = enum.auto()
70+
```
71+
72+
## Config Spec
73+
In `configSpec.py` specify the new config key, ideally in the category that is most relevant to the feature.
74+
Placing it in a category rather than a catch-all feature flags category, allows for the option to become
75+
permanent without having to write config upgrade code to move it from section to another.
76+
77+
```ini
78+
[virtualBuffers]
79+
newOptionForUsers = featureFlag(optionsEnum="BoolFlag", behaviourOfDefault="disabled")
80+
anotherOptionForUsers = featureFlag(optionsEnum="AllowUiaInMSWordFlag", behaviourOfDefault="WHERE_SUITABLE")
81+
```
82+
83+
The `featureFlag` type is a custom spec type.
84+
It will produce a `config.FeatureFlag` class instance when the key is accessed.
85+
```python
86+
newFlagValue: config.FeatureFlag = config.conf["virtualBuffers"]["newOptionForUsers"]
87+
88+
# BoolFlag converts to bool automatically, taking into account 'behaviorOfDefault'
89+
if newFlagValue:
90+
print("The new option is enabled")
91+
92+
anotherFlagValue: config.FeatureFlag = config.conf["virtualBuffers"]["anotherOptionForUsers"]
93+
94+
# Other "optionsEnum" types can compare with the value, the 'behaviorOfDefault' is taken into account.
95+
if flagValue == AllowUiaInMSWordFlag.ALWAYS:
96+
print("Another option is enabled")
97+
```
98+
99+
## GUI
100+
A control (`gui.nvdaControls.FeatureFlagCombo`) is provided to simplify exposing the feature flag to the user.
101+
102+
### Usage:
103+
Note the comments in the example:
104+
- `creation`
105+
- `is default`
106+
- `reset to default value`
107+
- `save GUI value to config`
108+
109+
110+
```python
111+
import collections
112+
from gui import nvdaControls, guiHelper
113+
import config
114+
import wx
115+
116+
sHelper = guiHelper.BoxSizerHelper(self, sizer=wx.BoxSizer(wx.HORIZONTAL))
117+
118+
# Translators: Explanation for the group name
119+
label = _("Virtual Buffers")
120+
vbufSizer = wx.StaticBoxSizer(wx.VERTICAL, self, label=label)
121+
vbufGroup = guiHelper.BoxSizerHelper(vbufSizer, sizer=vbufSizer)
122+
sHelper.addItem(vbufGroup)
123+
124+
# creation
125+
self.newOptionForUsersCombo: nvdaControls.FeatureFlagCombo = vbufGroup.addLabeledControl(
126+
labelText=_(
127+
# Translators: Explanation of what the control does and where it is used.
128+
"New option for users"
129+
),
130+
wxCtrlClass=nvdaControls.FeatureFlagCombo,
131+
keyPath=["virtualBuffers", "newOptionForUsers"], # The path of keys, see config spec.
132+
conf=config.conf, # The configObj instance, allows getting / setting the value
133+
)
134+
...
135+
# is default
136+
# Checking if the user has a saved (non-default) value
137+
self.loadChromeVbufWhenBusyCombo.isValueConfigSpecDefault()
138+
...
139+
# reset to default value:
140+
self.loadChromeVbufWhenBusyCombo.resetToConfigSpecDefault()
141+
...
142+
# save GUI value to config:
143+
self.loadChromeVbufWhenBusyCombo.saveCurrentValueToConf()
144+
```
145+
146+
## User Guide Documentation
147+
Refer to [User Guide Standards](./userGuideStandards.md#feature-settings)

‎devDocs/githubIssueTemplateExplanationAndExamples.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,10 @@ This section should tell us what you expect to happen when these steps are taken
113113
> NVDA Speech:
114114
> "checkbox enable sound"
115115
116+
### NVDA logs, crash dumps and other attachments
117+
118+
Refer to [Attachments / Images](#attachments--images).
119+
116120
### System configuration:
117121

118122
This section has several sub-sections.

‎devDocs/githubPullRequestTemplateExplanationAndExamples.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,20 @@ to be close manually after merging the pull request.
2525
### Summary of the issue:
2626
A quick summary of the problem you are trying to solve.
2727

28-
### Description of how this pull request fixes the issue:
29-
Please include a quick discussion of how this change addresses the issue.
28+
### Description of user facing changes:
29+
Please include a short explanation of how the user experience has changed to address the issue.
30+
31+
### Description of development approach
32+
Provide a description of the technical changes.
3033
Please also include any links or external information you may have used in order to address the
3134
issue.
3235
This helps others to have the same background as you and learn from this work.
3336

37+
Include reasoning as to why the approach followed is the best approach compared to other ways of fixing the issue.
38+
It may be worth including a summary of the history of the technical changes, and how the final approach was determined.
39+
40+
Example: a new app module was created, which handles an event raised by UIA.
41+
3442
### Testing strategy:
3543
Outline the steps you took to test the change.
3644
This should allow someone else to reproduce your testing.

‎devDocs/synthesizers.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Synthesizers
2+
3+
## SAPI 4
4+
5+
SAPI 4 synthesizers are not included with NVDA, and the runtimes are no longer included with Windows.
6+
Despite this, SAPI 4 support is still required, as many users prefer older synthesizers which rely on the SAPI 4 API.
7+
8+
To test SAPI 4, you must install the SAPI 4 runtimes from Microsoft, as well as a synthesizer.
9+
Microsoft no longer hosts downloads for these, but archives and mirrors exist.
10+
11+
1. Download and install the SAPI 4 runtimes from [this Microsoft archive](http://web.archive.org/web/20150910165037/http://activex.microsoft.com/activex/controls/sapi/spchapi.exe).
12+
1. Download and install a SAPI 4 synthesizer from [this Microsoft archive](http://web.archive.org/web/20150910005021if_/http://activex.microsoft.com/activex/controls/agent2/tv_enua.exe)
13+
14+
After this, you should be able to select SAPI 4 as a NVDA synthesizer.

‎devDocs/userGuideStandards.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# User Guide Standards
2+
This document aims to create a standard style guide for writing documentation in the User Guide.
3+
4+
The principles outlined in ["The Documentation System" guide for reference materials](https://documentation.divio.com/reference/) are encouraged when working on the User Guide and this document.
5+
6+
## General standards
7+
- Key commands (e.g. ` ``NVDA+control+upArrow`` `):
8+
- should be written in lowerCamelCase
9+
- encapsulated in monospace code-block formatting
10+
- NVDA should be capitalized
11+
- When referring to Windows terminology, follow the [Windows style guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
12+
- For instance, instead of "system tray" refer to "notification area"
13+
14+
## Feature settings
15+
16+
Feature flags should be included using the following format.
17+
18+
`FeatureDescriptionAnchor` should not include the settings category.
19+
Once the anchor is set it cannot be updated, while settings may move categories.
20+
21+
```text2tags
22+
==== The name of a feature ====[FeatureDescriptionAnchor]
23+
: Default
24+
Enabled
25+
: Options
26+
Default (Enabled), Enabled, Disabled
27+
:
28+
29+
This setting allows the feature of using functionality in a certain situation to be controlled in some way.
30+
If necessary, a description of a common use case that is supported by each option.
31+
```

‎include/espeak‎

Submodule espeak updated 163 files

‎include/espeak.md‎

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
# Espeak-ng submodule
1+
# eSpeak-ng submodule
22

3-
The submodule contained in the espeak directory is a cross platform open source speech synthesizer.
3+
The submodule contained in the `espeak` directory is a cross platform open source speech synthesizer.
44

55
## Building
6-
NVDA has a custom build of ESpeak because not all components are required.
6+
NVDA has a custom build of eSpeak because not all components are required.
77

88
### Background
9-
The main authority on build requirements should be `<nvda repo root>/include/espeak/Makefile.am`.
10-
The `*.vcxproj` files in `<nvda repo root>/include/espeak/src/windows/` can also be considered,
9+
The main authority on build requirements should be [`include/espeak/Makefile.am`](./espeak/Makefile.am).
10+
The `*.vcxproj` files in [`include/espeak/src/windows/`](./espeak/src/windows/) can also be considered,
1111
however these are not always kept up to date.
1212

13-
We don't use the auto make files or the visual studio files, we maintain our own method of building espeak.
14-
Modifications will need to be made in `<nvda repo root>/nvdaHelper/espeak`
13+
We don't use the auto make files or the visual studio files, we maintain our own method of building eSpeak.
14+
Modifications will need to be made in [`nvdaHelper/espeak`](../nvdaHelper/espeak)
1515
* `sconscript` for the build process.
1616
* `config.h` to set the eSpeak-ng version that NVDA outputs to the log file.
1717

@@ -32,23 +32,36 @@ Modifications will need to be made in `<nvda repo root>/nvdaHelper/espeak`
3232
1. Changes to Dictionary compilation should be reflected in `espeakDictionaryCompileList`
3333
1. Some modules are intentionally excluded from the build.
3434
If unsure, err on the side of including it and raise it as a question when submitting a PR.
35-
1. Modify the `<nvda repo root>/nvdaHelper/espeak/config.h` file as required.
35+
1. Modify the [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h) file as required.
3636
1. Update our record of the version number and build.
3737
1. Change back to the NVDA repo root
38-
1. Update the `/DPACKAGE_VERSION` in `espeak/sconscript`
39-
- The preprocessor definition is used to supply these definitions instead of `<nvda repo root>/nvdaHelper/espeak/config.h`
40-
- `<nvda repo root>/nvdaHelper/espeak/config.h` must exist (despite being empty) since a "config.h" is included within espeak.
41-
- Compare to espeak source info: `<nvda repo root>/include/espeak/src/windows/config.h`.
42-
1. Update NVDA `readme.md` with espeak version and commit.
43-
1. Build NVDA
38+
1. Update the `/DPACKAGE_VERSION` in [`nvdaHelper/espeak/sconscript`](../nvdaHelper/espeak/sconscript)
39+
- The preprocessor definition is used to supply these definitions instead of [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h)
40+
- [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h) must exist (despite being empty) since a "config.h" is included within eSpeak.
41+
- Compare to eSpeak source config: [`include/espeak/src/windows/config.h`](./espeak/src/windows/config.h).
42+
- Diff `src/windows/config.h` with the previous commit.
43+
1. Update NVDA [`readme.md`](../readme.md) with eSpeak version and commit.
44+
1. Build NVDA: `scons source`
45+
- Expected warnings from eSpeak compilation:
46+
- On the first build after changes, all languages may show this warning.
47+
Our build intentionally compiles using the `phonemetable`.
48+
```log
49+
espeak_compileDict_buildAction(["include\espeak\espeak-ng-data\uz_dict"], ["include\espeak\dictsource\uz_list", "include\espeak\dictsource\uz_rules"])
50+
Can't read dictionary file: 'C:\Users\sean\projects\nvda\include\espeak/espeak-ng-data\uz_dict'
51+
Using phonemetable: 'uz'
52+
Compiling: 'C:\Users\sean\projects\nvda\include\espeak\dictsource/uz_list'
53+
121 entries
54+
Compiling: 'C:\Users\sean\projects\nvda\include\espeak\dictsource/uz_rules'
55+
35 rules, 26 groups (0)
56+
```
4457
1. Run NVDA (set eSpeak-ng as the synthesizer) and test.
4558
1. Ensure that the log file contains the new version number for eSpeak-NG
4659
4760
### Troubleshooting Build failures
4861
4962
If python crashes while building, check the log.
5063
If the last thing is compiling some dictionary try excluding it.
51-
This can be done in `<nvda repo root>/nvdaHelper/espeak/sconscript`.
64+
This can be done in [`nvdaHelper/espeak/sconscript`](../nvdaHelper/espeak/sconscript).
5265
Remember to report this to the eSpeak-ng project.
5366
5467
If the build fails, take note of the error, compare the diff of the `Makefile.am` file and mirror
@@ -57,13 +70,13 @@ any changes in our `sconscript` file.
5770
### Known issues
5871
Due to problems with emoji support (causing crashes), emoji dictionary files are being excluded
5972
from the build, they are deleted prior to compiling the dictionaries in the
60-
`<nvda repo root>/nvdaHelper/espeak/sconscript` file.
73+
[`nvdaHelper/espeak/sconscript`](../nvdaHelper/espeak/sconscript) file.
6174
62-
## Manually testing Espeak-ng
75+
## Manually testing eSpeak-ng
6376
If you wish to test eSpeak-ng directly, perhaps to create steps to reproduce when raising an issue for the eSpeak-ng project, consider feeding SSML directly to the executable provided by the project.
6477
65-
The [espeak docs](https://github.com/espeak-ng/espeak-ng/blob/master/docs/index.md) are worth reading.
66-
They describe the various [(espeak-ng) command line arguments](https://github.com/espeak-ng/espeak-ng/blob/master/src/espeak-ng.1.ronn) (note also [speak-ng command line](https://github.com/espeak-ng/espeak-ng/blob/master/src/speak-ng.1.ronn)), and [insturctions to build](https://github.com/espeak-ng/espeak-ng/blob/master/docs/building.md#windows) an `.exe` from a commit of eSpeak, locally on Windows.
78+
The [eSpeak docs](https://github.com/espeak-ng/espeak-ng/blob/master/docs/index.md) are worth reading.
79+
They describe the various [(eSpeak-ng) command line arguments](https://github.com/espeak-ng/espeak-ng/blob/master/src/espeak-ng.1.ronn) (note also [speak-ng command line](https://github.com/espeak-ng/espeak-ng/blob/master/src/speak-ng.1.ronn)), and [instructions to build](https://github.com/espeak-ng/espeak-ng/blob/master/docs/building.md#windows) an `.exe` from a commit of eSpeak, locally on Windows.
6780
However, historically the Windows build for espeak-ng hasn't been well maintained, with periods of build failures.
6881
It is also different from the build approach within NVDA.
6982

0 commit comments

Comments
 (0)