fix up merge conflicts.

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    # Workflow files stored in the default location of `.github/workflows`. (You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.)
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions-minor:
+        update-types:
+          - minor
+          - patch

.github/workflows/build_addon.yml

@@ -17,14 +17,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - run: echo -e "pre-commit\nscons\nmarkdown">requirements.txt
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: 3.11
         cache: 'pip'
 
     - name: Install dependencies
@@ -38,27 +38,36 @@ jobs:
       run: export SKIP=no-commit-to-branch; pre-commit run --all
 
     - name: building addon
-      run: scons
+      run: scons && scons pot
 
-    - uses: actions/upload-artifact@v3
+    - uses: actions/upload-artifact@v4
       with:
         name: packaged_addon
-        path: ./*.nvda-addon
+        path: |
+          ./*.nvda-addon
+          ./*.pot
 
   upload_release:
     runs-on: ubuntu-latest
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     needs: ["build"]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: download releases files
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
     - name: Display structure of downloaded files
       run: ls -R
+    - name: Calculate sha256
+      run: |
+        echo -e "\nSHA256: " >> changelog.md
+        sha256sum packaged_addon/*.nvda-addon >> changelog.md
 
     - name: Release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       with:
-        files: packaged_addon/*.nvda-addon
+        files: |
+          packaged_addon/*.nvda-addon
+          packaged_addon/*.pot
+        body_path: changelog.md
         fail_on_unmatched_files: true
         prerelease: ${{ contains(github.ref, '-') }}

.vscode/extensions.json

@@ -5,7 +5,8 @@
 	"recommendations": [
 		"ms-python.python",
 		"ms-python.vscode-pylance",
-		"redhat.vscode-yaml"
+		"redhat.vscode-yaml",
+		"charliermarsh.ruff"
 	],
 	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
 	"unwantedRecommendations": []

.vscode/settings.json

@@ -1,25 +1,16 @@
 {
     "editor.accessibilitySupport": "on",
-    "python.linting.enabled": true,
-    "python.linting.maxNumberOfProblems": 10000,
-    "python.linting.flake8Args": [
-        "--config=flake8.ini"
-    ],
-    "python.linting.flake8Enabled": true,
-    "python.linting.pylintEnabled": false,
     "python.autoComplete.extraPaths": [
         "../nvda/source",
         "../nvda/miscDeps/python"
-        ],	
+    ],
     "files.insertFinalNewline": true,
     "files.trimFinalNewlines": true,
     "editor.insertSpaces": false,
-    "python.analysis.diagnosticSeverityOverrides": {
-        "reportUndefinedVariable": "none"
-    },
+    "python.analysis.stubPath": "${workspaceFolder}/.vscode/typings",
     "python.analysis.extraPaths": [
         "../nvda/source",
         "../nvda/miscDeps/python"
     ],
-    "python.defaultInterpreterPath": "../nvda/.venv/scripts/python.exe"
+    "python.defaultInterpreterPath": "${workspaceFolder}/../nvda/.venv/scripts/python.exe"
 }

.vscode/typings/__builtins__.pyi

@@ -0,0 +1,6 @@
+def _(msg: str) -> str:
+	...
+
+
+def pgettext(context: str, message: str) -> str:
+	...

buildVars.py

@@ -69,6 +69,7 @@ def _(arg):
 # Base language for the NVDA add-on
 # If your add-on is written in a language other than english, modify this variable.
 # For example, set baseLanguage to "es" if your add-on is primarily written in spanish.
+# You must also edit .gitignore file to specify base language files to be ignored.
 baseLanguage = "en"
 
 # Markdown extensions for add-on documentation
@@ -77,3 +78,22 @@ def _(arg):
 # Extensions string must be of the form "markdown.extensions.extensionName"
 # e.g. "markdown.extensions.tables" to add tables.
 markdownExtensions = []
+
+# Custom braille translation tables
+# If your add-on includes custom braille tables (most will not), fill out this dictionary.
+# Each key is a dictionary named according to braille table file name,
+# with keys inside recording the following attributes:
+# displayName (name of the table shown to users and translatable),
+# contracted (contracted (True) or uncontracted (False) braille code),
+# output (shown in output table list),
+# input (shown in input table list).
+brailleTables = {}
+
+# Custom speech symbol dictionaries
+# Symbol dictionary files reside in the locale folder, e.g. `locale\en`, and are named `symbols-<name>.dic`.
+# If your add-on includes custom speech symbol dictionaries (most will not), fill out this dictionary.
+# Each key is the name of the dictionary,
+# with keys inside recording the following attributes:
+# displayName (name of the speech dictionary  shown to users and translatable),
+# mandatory (True when always enabled, False when not.
+symbolDictionaries = {}

changelog.md

@@ -0,0 +1 @@
+Use this file to explain what has changed in your add-on since the previous release. This will be included automatically in the release description when used with GitHub actions.

pyproject.toml

@@ -0,0 +1,40 @@
+[tool.ruff]
+line-length = 110
+
+builtins = [
+	# translation lookup
+	"_",
+	# translation lookup
+	"ngettext",
+	# translation lookup
+	"pgettext",
+	# translation lookup
+	"npgettext",
+]
+
+include = [
+	"*.py",
+	"sconstruct",
+]
+
+exclude = [
+	".git",
+	"__pycache__",
+]
+
+[tool.ruff.format]
+indent-style = "tab"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint]
+ignore = [
+	# indentation contains tabs
+	"W191",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# sconstruct contains many inbuilt functions not recognised by the lint,
+# so ignore F821.
+"sconstruct" = ["F821"]

readme.md

@@ -1,23 +1,20 @@
-# NVDA Add-on Scons Template #
+# NVDA Add-on Scons Template
 
 This package contains a basic template structure for NVDA add-on development, building, distribution and localization.
 For details about NVDA add-on development, please see the [NVDA Add-on Development Guide](https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide).
 The NVDA add-on development/discussion list [is here](https://nvda-addons.groups.io/g/nvda-addons)
 Information specific to NV Access add-on store [can be found here](https://github.com/nvaccess/addon-datastore).
 
-Copyright (C) 2012-2023 NVDA Add-on team contributors.
+Copyright (C) 2012-2024 NVDA Add-on team contributors.
 
 This package is distributed under the terms of the GNU General Public License, version 2 or later. Please see the file COPYING.txt for further details.
 
-
-
 [alekssamos](https://github.com/alekssamos/) added automatic package of add-ons through Github Actions.
 
 For details about Github Actions  please see the [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions).
 
 Copyright (C) 2022 alekssamos
 
-
 ## Features
 
 This template provides the following features you can use during NVDA add-on development and packaging:
@@ -33,11 +30,10 @@ This template provides the following features you can use during NVDA add-on dev
 	* To generate a gettext pot file, please run `scons pot`. An `addon-name.pot` file will be created with all gettext messages for your add-on. You need to check the `buildVars.i18nSources` variable to comply with your requirements.
 * Automatic generation of manifest localization files directly from gettext po files. Please make sure buildVars.py is included in i18nFiles.
 * Automatic generation of HTML documents from markdown (.md) files, to manage documentation in different languages.
-* Automatic generation of entries for NV Access add-on store (json format).
 
 In addition, this template includes configuration files for the following tools for use in add-on development and testing (see "additional tools" section for details):
 
-* Flake8 (flake8.ini): a base configuration file for Flake8 linting tool based on NVDA's own Flake8 configuration file.
+* Ruff (pyproject.toml/tool.ruff sections): a Python linter written in Rust. Sections starting with tool.ruff house configuration options for Ruff.
 * Configuration for VS Code. It requires NVDA's repo at the same level as the add-on folder containing your actual source files, with prepared source code (`scons source`). preparing the source code is a step in the instructions for building NVDA itself, see [The NVDA Repository](https://github.com/nvaccess/nvda) for details.
         * Place the .vscode in this repo within the addon folder, where your add-on source files (will) reside. The settings file within this folder assumes the NVDA repository is within the parent folder of this folder. If your addon folder is within the addonTemplate folder, then your NVDA repository folder needs to also be within the addonTemplate folder, or the source will not be found.
         * Open the addon folder in VS Code. This should initialize VS Code with the correct settings and provide you with code completion and other VS Code features. 
@@ -49,8 +45,8 @@ In addition, this template includes configuration files for the following tools
 
 You need the following software to use this code for your NVDA add-on development and packaging:
 
-* a Python distribution (3.7 or later is recommended). Check the [Python Website](https://www.python.org) for Windows Installers. Please note that at present, preparing the NVDA source code requires the 32-bit version of Python 3.7.
-* Scons - [Website](https://www.scons.org/) - version 4.3.0 or later. You can install it via PIP.
+* a Python distribution (3.11 or later is recommended). Check the [Python Website](https://www.python.org) for Windows Installers. Please note that at present, preparing the NVDA source code requires the 32-bit version of Python 3.11.
+* Scons - [Website](https://www.scons.org/) - version 4.5.2 or later. You can install it via PIP.
 * GNU Gettext tools, if you want to have localization support for your add-on - Recommended. Any Linux distro or cygwin have those installed. You can find windows builds [here](https://gnuwin32.sourceforge.net/downlinks/gettext.php).
 * Markdown 3.3.0 or later, if you want to convert documentation files to HTML documents. You can install it via PIP.
 
@@ -83,30 +79,54 @@ and file:
 .pre-commit-config.yaml
 ```
 4. Create an `addon` folder inside your new folder. You will put your code in the usual folders for NVDA extensions, under the `addon` folder. For instance: `globalPlugins`, `synthDrivers`, etc.
-5. In the `buildVars.py` file, change variable `addon_info` with your add-on's information (name, summary, description, version, author, url, source url, license, and license URL). Also, be sure to carefully set the paths contained in the other variables in that file.
+5. In the `buildVars.py` file, change variable `addon_info` with your add-on's information (name, summary, description, version, author, url, source url, license, and license URL). Also, be sure to carefully set the paths contained in the other variables in that file. If you need to use custom Markdown extensions, original add-on interface language is not English, or include custom braille translations tables, be sure to fil out markdown list, base language variable, and braille tables dictioanry, respectively.
 6. Gettext translations must be placed into `addon\locale\<lang>/LC_MESSAGES\nvda.po`.
 
 #### Add-on manifest specification
 
 An add-on manifest generated manually or via `buildVars.py` must include the following information:
 
 * Name (string): a unique identifier for the add-on. It must use camel case (e.g. someModule). This is also used as part of add-on store to identify the add-on uniquely.
-* Summary (string): name as shown on NVDA's Add-ons Manager.
+* Summary (string): name as shown on NVDA's Add-on store.
 * Description (string): a short detailed description about the add-on.
 * Version (string), ideally number.number with an optional third number, denoting major.minor.patch.
 * Author (string and an email address): one or more add-on author contact information in the form "name <email@address>".
-* URL (string): a web address where the add-on information can be found (typically community add-ons website address (https://addons.nvda-project.org) is used).
+* URL (string): a web address where the add-on information can be found such as add-on repository.
 * docFileName (string): name of the documentation file.
 * minimumNVDAVersion (year.major or year.major.minor): the earliest version of NVDA the add-on is compatible with (e.g. 2019.3). Add-ons are expected to use features introduced in this version of NVDA or declare compatibility with it.
 * lastTestedNVDAVersion (year.major or year.major.minor): the latest or last tested version of NVDA the add-on is said to be compatible with (e.g. 2020.3). Add-on authors are expected to declare this value after testing add-ons with the version of NVDA specified.
 * addon_updateChannel (string or None): the update channel for the add-on release.
 
-In addition, the following information must be filled out (not used in the manifest but used elsewhere such as add-on store):
+In addition, the following information must be filled out (not used in the manifest but used elsewhere such as add-on store) in buildVars:
 
 * sourceURL (string): repository URL for the add-on source code.
 * license (string): the license of the add-on and its source code.
 * licenseURL: the URL for the license file.
 
+##### Custom add-on information
+
+In addition to the core manifest data, custom add-on information can be specified. 
+
+###### Braille translation tables
+Information on custom braille tables must be specified in buildVars under `brailleTables` dictionary as follows:
+
+* Table name (string key for a nested dictionary): each `brailleTables` entry is a filename for the included custom braille table placed in `brailleTables` folder inside `addon` folder. This nested dictionary should specify:
+	* displayName (string): the name of the table shown to users and is translatable.
+	* contracted (True/False): is this a contracted braille table (True) or uncontracted (False).
+	* output (True/False): the table can be listed in output table list in NVDA's braille settings.
+	* input (True/False): braille can be entered using this table and listed in input table list in NVDA's braille settings.
+
+Note: you must fill out this dictionary if at least one custom braille table is included in the add-on. If not, leave the dictionary empty.
+
+###### Speech symbol dictionaries
+Information on custom symbol dictionaries must be specified in buildVars under `symbolDictionaries` dictionary as follows:
+
+* Dictionary name (string key for a nested dictionary): each `symbolDictionaries` entry is a name for the included custom symbol dictionary placed in `locale\<language>` folder inside `addon` folder. The file is named `symbols-<dictionary_name>.dic`. This nested dictionary should specify:
+	* displayName (string): the name of the dictionary shown to users and is translatable.
+	* mandatory (True/False): Always enabled (True) or optional and visible in the GUI (False)
+
+Note: you must fill out this dictionary if at least one custom symbol dictionary is included in the add-on. If not, leave the dictionary empty.
+
 ### To manage documentation files for your addon:
 
 1. Copy the `readme.md` file for your add-on to the first created folder, where you copied `buildVars.py`. You can also copy `style.css` to improve the presentation of HTML documents.
@@ -126,7 +146,7 @@ In addition, the following information must be filled out (not used in the manif
 
 The template includes configuration files for use with additional tools such as linters. These include:
 
-* Flake8 (flake8.ini): a Python code linter (3.7.9 or later, can be installed with PIP).
+* Ruff (pyproject.toml): a Python linter written in Rust (0.4.10 or later, can be installed with PIP).
 
 Read the documentation for the tools you wish to use when building and developing add-ons.