Merge pull request #14195 from nvaccess/beta

Merge beta to rc for 2022.3rc1

.github/ISSUE_TEMPLATE/bug_report.md

@@ -16,8 +16,20 @@ Each of the questions and sections below start with multiple hash symbols (#). P
 ### Steps to reproduce:
 
 ### Actual behavior:
+<!--
+Use "Speak command keys" (NVDA+4) and speech viewer to copy and paste here. 
+Use braille viewer to copy and paste here.
+You may additionally include an explanation.
+-->
 
 ### Expected behavior:
+<!--
+Use "Speak command keys" (NVDA+4) and speech viewer to copy and paste here. 
+Use braille viewer to copy and paste here.
+You may additionally include an explanation.
+-->
+
+### NVDA logs, crash dumps and other attachments:
 
 ### System configuration
 #### NVDA installed/portable/running from source:

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,7 +9,9 @@ Please initially open PRs as a draft. See https://github.com/nvaccess/nvda/wiki/
 
 ### Summary of the issue:
 
-### Description of how this pull request fixes the issue:
+### Description of user facing changes
+
+### Description of development approach
 
 ### Testing strategy:
 

appveyor/scripts/buildSymbolStore.ps1

@@ -7,5 +7,6 @@ foreach ($syms in
 	"source\lib64\*.dll", "source\lib64\*.exe", "source\lib64\*.pdb",
 	"source\synthDrivers\*.dll", "source\synthDrivers\*.pdb"
 ) {
-	& $env:symstore add -:NOREFS /s symbols /compress /t NVDA /f $syms
+	# https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/symstore-command-line-options
+	& $env:symstore add /f $syms /s symbols /t NVDA /compress
 }

appveyor/scripts/setBuildVersionVars.ps1

@@ -1,5 +1,16 @@
 $ErrorActionPreference = "Stop";
-# iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/appveyor/ci/master/scripts/enable-rdp.ps1'))
+
+# Accessing Windows build worker via Remote Desktop (RDP)
+# To enable:
+# Set an RDP password (before triggering the build), ensure password requirements are met.
+# Remove the password after the RDP connection params are shown in the build output.
+# For passwords requirements and instructions for setting, see the appveyor docs:
+# https://www.appveyor.com/docs/how-to/rdp-to-build-worker/
+if ($env:APPVEYOR_RDP_PASSWORD) {
+	$rdpScriptURL = 'https://raw.githubusercontent.com/appveyor/ci/master/scripts/enable-rdp.ps1'
+	iex ((new-object net.webclient).DownloadString($rdpScriptURL))
+}
+
 $pythonVersion = (py --version)
 echo $pythonVersion
 if ($env:APPVEYOR_REPO_TAG_NAME -and $env:APPVEYOR_REPO_TAG_NAME.StartsWith("release-")) {

appveyor/scripts/tests/systemTests.ps1

@@ -1,6 +1,13 @@
 $testOutput = (Resolve-Path .\testOutput\)
 $systemTestOutput = (Resolve-Path "$testOutput\system")
-.\runsystemtests.bat --variable whichNVDA:installed --variable installDir:"${env:nvdaLauncherFile}" --include installer
+
+.\runsystemtests.bat `
+--variable whichNVDA:installed `
+--variable installDir:"${env:nvdaLauncherFile}" `
+--include installer `
+--include NVDA `
+# last line inentionally blank, allowing all lines to have line continuations.
+
 if($LastExitCode -ne 0) {
 	Set-AppveyorBuildVariable "testFailExitCode" $LastExitCode
 	Add-AppveyorMessage "FAIL: System tests. See test results for more information."

devDocs/featureFlags.md

@@ -0,0 +1,147 @@
+# Feature Flags
+
+NVDA makes judicious use of feature flags to enable and disable features that are in early development.
+The following are provided to streamline the creation of new feature flags:
+- A config spec type
+- A GUI control type
+
+## Background
+When providing a feature flag it is important to understand the importance of providing a "default" state.
+A boolean feature, must have 3 states selectable by the user:
+- `True`
+- `False`
+- `Default` (NVDA developer recommendation)
+
+This allows a choice between the following use-cases to be made at any point in time:
+- **Explicitly opt-in** to the feature, regardless of the default behavior. 
+An early adopter may choose to do this to test the feature and provide feedback.
+- **Explicitly opt-out** of the feature, regardless of the default behavior.
+A user may find the pre-existing behavior acceptable, and wants the maximum delay to adopt the new feature.
+They may be prioritising stability, or anticipating this feature flag receives a permanent home in NVDA settings.
+- **Explicitly choose the default** (NVDA developer recommended) behavior.
+Noting, that in this case it is important that the user must be able to select one of the other options first,
+and return to the default behavior at any point in time.
+
+This should be possible while still allowing developers to change the behaviour
+of the default option.
+The development process might require that initially NVDA is released with
+the feature disabled by default.
+In this case only testers, or the most curious users are expected to opt-in temporarily.
+As the feature improves, bugs are fixed, edge cases are handled, and the UX is improved,
+developers may wish to change the behavior of the default option to enable the feature.
+This change shouldn't affect those who have already explicitly opted out of the feature.
+Only those who maybe haven't tried the feature, because they were using the prior default behaviour, or
+those who have tried and found the feature to be unstable and decided they would wait for it to become
+stable.
+
+## Feature Flag Enum
+To aid static typing in NVDA, `enum` classes are used.
+`BoolFlag` is provided, the majority of feature flags are expected to use this.
+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.
+Adding the enum class to the `featureFlagEnums.py` file will automatically expose it for use in the config spec (see the next section).
+Example new `enum` class:
+
+```python
+
+class AllowUiaInMSWordFlag(DisplayStringEnum):
+	"""Feature flag for UIA in MS Word.
+	The explicit DEFAULT option allows developers to differentiate between a value set that happens to be
+	the current default, and a value that has been returned to the "default" explicitly.
+	"""
+
+	@property
+	def _displayStringLabels(self):
+		""" These labels will be used in the GUI when displaying the options.
+		"""
+		# To prevent duplication, self.DEFAULT is not included here.
+		return {
+			# Translators: Label for an option in NVDA settings.
+			self.WHEN_NECESSARY: _("Only when necessary"),
+			# Translators: Label for an option in NVDA settings.
+			self.WHERE_SUITABLE: _("Where suitable"),
+			# Translators: Label for an option in NVDA settings.
+			self.ALWAYS: _("ALWAYS"),
+		}
+
+	DEFAULT = enum.auto()
+	WHEN_NECESSARY = enum.auto()
+	WHERE_SUITABLE = enum.auto()
+	ALWAYS = enum.auto()
+```
+
+## Config Spec
+In `configSpec.py` specify the new config key, ideally in the category that is most relevant to the feature.
+Placing it in a category rather than a catch-all feature flags category, allows for the option to become
+permanent without having to write config upgrade code to move it from section to another.
+
+```ini
+[virtualBuffers]
+    newOptionForUsers = featureFlag(optionsEnum="BoolFlag", behaviourOfDefault="disabled")
+    anotherOptionForUsers = featureFlag(optionsEnum="AllowUiaInMSWordFlag", behaviourOfDefault="WHERE_SUITABLE")
+```
+
+The `featureFlag` type is a custom spec type.
+It will produce a `config.FeatureFlag` class instance when the key is accessed.
+```python
+newFlagValue: config.FeatureFlag = config.conf["virtualBuffers"]["newOptionForUsers"]
+
+# BoolFlag converts to bool automatically, taking into account 'behaviorOfDefault'
+if newFlagValue:
+    print("The new option is enabled")
+
+anotherFlagValue: config.FeatureFlag = config.conf["virtualBuffers"]["anotherOptionForUsers"]
+
+# Other "optionsEnum" types can compare with the value, the 'behaviorOfDefault' is taken into account.
+if flagValue == AllowUiaInMSWordFlag.ALWAYS:
+    print("Another option is enabled")
+```
+
+## GUI
+A control (`gui.nvdaControls.FeatureFlagCombo`) is provided to simplify exposing the feature flag to the user.
+
+### Usage:
+Note the comments in the example:
+- `creation`
+- `is default`
+- `reset to default value`
+- `save GUI value to config`
+
+
+```python
+import collections
+from gui import nvdaControls, guiHelper
+import config
+import wx
+
+sHelper = guiHelper.BoxSizerHelper(self, sizer=wx.BoxSizer(wx.HORIZONTAL))
+
+# Translators: Explanation for the group name
+label = _("Virtual Buffers")
+vbufSizer = wx.StaticBoxSizer(wx.VERTICAL, self, label=label)
+vbufGroup = guiHelper.BoxSizerHelper(vbufSizer, sizer=vbufSizer)
+sHelper.addItem(vbufGroup)
+
+# creation
+self.newOptionForUsersCombo: nvdaControls.FeatureFlagCombo = vbufGroup.addLabeledControl(
+    labelText=_(
+        # Translators: Explanation of what the control does and where it is used.
+        "New option for users"
+    ),
+    wxCtrlClass=nvdaControls.FeatureFlagCombo,
+    keyPath=["virtualBuffers", "newOptionForUsers"], # The path of keys, see config spec.
+    conf=config.conf, # The configObj instance, allows getting / setting the value
+)
+...
+# is default
+# Checking if the user has a saved (non-default) value
+self.loadChromeVbufWhenBusyCombo.isValueConfigSpecDefault()
+...
+# reset to default value:
+self.loadChromeVbufWhenBusyCombo.resetToConfigSpecDefault()
+...
+# save GUI value to config:
+self.loadChromeVbufWhenBusyCombo.saveCurrentValueToConf()
+```
+
+## User Guide Documentation
+Refer to [User Guide Standards](./userGuideStandards.md#feature-settings)

devDocs/githubIssueTemplateExplanationAndExamples.md

@@ -113,6 +113,10 @@ This section should tell us what you expect to happen when these steps are taken
 > NVDA Speech:
 > "checkbox enable sound"
 
+### NVDA logs, crash dumps and other attachments
+
+Refer to [Attachments / Images](#attachments--images).
+
 ### System configuration:
 
 This section has several sub-sections.

devDocs/githubPullRequestTemplateExplanationAndExamples.md

@@ -25,12 +25,20 @@ to be close manually after merging the pull request.
 ### Summary of the issue:
 A quick summary of the problem you are trying to solve.
 
-### Description of how this pull request fixes the issue:
-Please include a quick discussion of how this change addresses the issue.
+### Description of user facing changes:
+Please include a short explanation of how the user experience has changed to address the issue.
+
+### Description of development approach
+Provide a description of the technical changes.
 Please also include any links or external information you may have used in order to address the
 issue.
 This helps others to have the same background as you and learn from this work.
 
+Include reasoning as to why the approach followed is the best approach compared to other ways of fixing the issue.
+It may be worth including a summary of the history of the technical changes, and how the final approach was determined.
+
+Example: a new app module was created, which handles an event raised by UIA.
+
 ### Testing strategy:
 Outline the steps you took to test the change.
 This should allow someone else to reproduce your testing.

devDocs/synthesizers.md

@@ -0,0 +1,14 @@
+# Synthesizers
+
+## SAPI 4
+
+SAPI 4 synthesizers are not included with NVDA, and the runtimes are no longer included with Windows.
+Despite this, SAPI 4 support is still required, as many users prefer older synthesizers which rely on the SAPI 4 API.
+
+To test SAPI 4, you must install the SAPI 4 runtimes from Microsoft, as well as a synthesizer.
+Microsoft no longer hosts downloads for these, but archives and mirrors exist.
+
+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).
+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)
+
+After this, you should be able to select SAPI 4 as a NVDA synthesizer.

devDocs/userGuideStandards.md

@@ -0,0 +1,31 @@
+# User Guide Standards
+This document aims to create a standard style guide for writing documentation in the User Guide.
+
+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.
+
+## General standards
+- Key commands (e.g. ` ``NVDA+control+upArrow`` `):
+  - should be written in lowerCamelCase
+  - encapsulated in monospace code-block formatting
+  - NVDA should be capitalized
+- When referring to Windows terminology, follow the [Windows style guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
+  - For instance, instead of "system tray" refer to "notification area"
+
+## Feature settings
+
+Feature flags should be included using the following format.
+
+`FeatureDescriptionAnchor` should not include the settings category.
+Once the anchor is set it cannot be updated, while settings may move categories.
+
+```text2tags
+==== The name of a feature ====[FeatureDescriptionAnchor]
+: Default
+  Enabled
+: Options
+  Default (Enabled), Enabled, Disabled
+:
+
+This setting allows the feature of using functionality in a certain situation to be controlled in some way.
+If necessary, a description of a common use case that is supported by each option.
+```

include/espeak.md

@@ -1,17 +1,17 @@
-# Espeak-ng submodule
+# eSpeak-ng submodule
 
-The submodule contained in the espeak directory is a cross platform open source speech synthesizer.
+The submodule contained in the `espeak` directory is a cross platform open source speech synthesizer.
 
 ## Building
-NVDA has a custom build of ESpeak because not all components are required.
+NVDA has a custom build of eSpeak because not all components are required.
 
 ### Background
-The main authority on build requirements should be `<nvda repo root>/include/espeak/Makefile.am`.
-The `*.vcxproj` files in `<nvda repo root>/include/espeak/src/windows/` can also be considered,
+The main authority on build requirements should be [`include/espeak/Makefile.am`](./espeak/Makefile.am).
+The `*.vcxproj` files in [`include/espeak/src/windows/`](./espeak/src/windows/) can also be considered,
 however these are not always kept up to date.
 
-We don't use the auto make files or the visual studio files, we maintain our own method of building espeak.
-Modifications will need to be made in `<nvda repo root>/nvdaHelper/espeak`
+We don't use the auto make files or the visual studio files, we maintain our own method of building eSpeak.
+Modifications will need to be made in [`nvdaHelper/espeak`](../nvdaHelper/espeak)
 * `sconscript` for the build process.
 * `config.h` to set the eSpeak-ng version that NVDA outputs to the log file.
 
@@ -32,23 +32,36 @@ Modifications will need to be made in `<nvda repo root>/nvdaHelper/espeak`
    1. Changes to Dictionary compilation should be reflected in `espeakDictionaryCompileList`
    1. Some modules are intentionally excluded from the build.
       If unsure, err on the side of including it and raise it as a question when submitting a PR.
-   1. Modify the `<nvda repo root>/nvdaHelper/espeak/config.h` file as required.
+   1. Modify the [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h) file as required.
 1. Update our record of the version number and build.
    1. Change back to the NVDA repo root
-   1. Update the `/DPACKAGE_VERSION` in `espeak/sconscript`
-      - The preprocessor definition is used to supply these definitions instead of `<nvda repo root>/nvdaHelper/espeak/config.h`
-      - `<nvda repo root>/nvdaHelper/espeak/config.h` must exist (despite being empty) since a "config.h" is included within espeak.
-      - Compare to espeak source info: `<nvda repo root>/include/espeak/src/windows/config.h`.
-   1. Update NVDA `readme.md` with espeak version and commit.
-   1. Build NVDA
+   1. Update the `/DPACKAGE_VERSION` in [`nvdaHelper/espeak/sconscript`](../nvdaHelper/espeak/sconscript)
+      - The preprocessor definition is used to supply these definitions instead of [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h)
+      - [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h) must exist (despite being empty) since a "config.h" is included within eSpeak.
+      - Compare to eSpeak source config: [`include/espeak/src/windows/config.h`](./espeak/src/windows/config.h).
+      - Diff `src/windows/config.h` with the previous commit.
+   1. Update NVDA [`readme.md`](../readme.md) with eSpeak version and commit.
+   1. Build NVDA: `scons source`
+      - Expected warnings from eSpeak compilation:
+         - On the first build after changes, all languages may show this warning.
+         Our build intentionally compiles using the `phonemetable`.
+         ```log
+         espeak_compileDict_buildAction(["include\espeak\espeak-ng-data\uz_dict"], ["include\espeak\dictsource\uz_list", "include\espeak\dictsource\uz_rules"])
+         Can't read dictionary file: 'C:\Users\sean\projects\nvda\include\espeak/espeak-ng-data\uz_dict'
+         Using phonemetable: 'uz'
+         Compiling: 'C:\Users\sean\projects\nvda\include\espeak\dictsource/uz_list'
+               121 entries
+         Compiling: 'C:\Users\sean\projects\nvda\include\espeak\dictsource/uz_rules'
+               35 rules, 26 groups (0)
+         ```
 1. Run NVDA (set eSpeak-ng as the synthesizer) and test.
 1. Ensure that the log file contains the new version number for eSpeak-NG
 
 ### Troubleshooting Build failures
 
 If python crashes while building, check the log.
 If the last thing is compiling some dictionary try excluding it.
-This can be done in `<nvda repo root>/nvdaHelper/espeak/sconscript`.
+This can be done in [`nvdaHelper/espeak/sconscript`](../nvdaHelper/espeak/sconscript).
 Remember to report this to the eSpeak-ng project.
 
 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.
 ### Known issues
 Due to problems with emoji support (causing crashes), emoji dictionary files are being excluded
 from the build, they are deleted prior to compiling the dictionaries in the
-`<nvda repo root>/nvdaHelper/espeak/sconscript` file.
+[`nvdaHelper/espeak/sconscript`](../nvdaHelper/espeak/sconscript) file.
 
-## Manually testing Espeak-ng
+## Manually testing eSpeak-ng
 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.
 
-The [espeak docs](https://github.com/espeak-ng/espeak-ng/blob/master/docs/index.md) are worth reading.
-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.
+The [eSpeak docs](https://github.com/espeak-ng/espeak-ng/blob/master/docs/index.md) are worth reading.
+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.
 However, historically the Windows build for espeak-ng hasn't been well maintained, with periods of build failures.
 It is also different from the build approach within NVDA.