Support for custom braille tables

[LeonarddeR]

Many thanks to @JulienCochuyt for the initial implementation

Link to issue number:

Fixes #3304.
Fixes #9863.
Supersedes PR #9864, #10172.
Addresses #505 (comment)

Summary of the issue:

In NVDA, there is no easy and reliable way for an add-on to provide a new braille table. For an experienced users wishing to do so there are two options:

• Alter manually an existing table in louis/tables.
  The new table still has its original name in the settings GUI.
  This change is lost upon NVDA updates.

• Set the absolute path to the table file in the configuration in lieu of the usual file name.
  The settings GUI shows an empty entry for this one.
  Forces to manually alter nvda.ini.
  Forces to copy in the same directory the whole dependency chain of the new table plus braille-patterns.cti. This is because liblouis default table resolver only looks for tables in a single directory, See Make it easier for add-ons to supply custom braille tables #5489 (comment)

Description of how this pull request fixes the issue:

• Add a new brailleTables optional directory in both the user scratchpad directory and the add-on directory structure.

• Support reading tables metadata from an optional brailleTables section of the add-on manifest or from a manifest.ini file with the same format found in the root of the scratchpad directory, allowing a user to provide a display name and set output/input/contracted capabilities with no code.

• Implement a custom liblouis table resolver that resolves tables based on what is registered in the brailleTables module:

  • When liblouis calls the resolver without a base file specified, the table is looked up from the brailleTables module and either resolved from the add-ons brailleTables directory or the built-in tables directory
  • When liblouis calls the resolver with a base file specified (e.g. when processing includes in tables), the table is looked up from the folder of the base table and/or the built-in tables directory

• Enforce the existing fallback mechanism to ensure there still is braille output if the configured table cannot be found e.g. because an add-on or the scratchpad directory was disabled. This now applies both to the main configuration and individual profiles and also covers braille input.

Note that if an add-on author wants a table to be listed in the GUI, he/she should always define the table in the manifest. Contrary to earlier incarnations of this pr, replacing a table in an add-on (i.e. when it has the same filename as a built-in table) without defining it in the manifest is no longer possible. Therefore it is also not possible to replace unlisted tables that are included by listed tables. For example, if you want to replace spaces.uti as included in nl-comp8.utb, you weel need to both define and bundle a replacement of nl-comp8.utb and spaces.uti in your add-on.

Testing strategy:

From a source copy:

• added a new table via an add-on

• added a new table via the scratchpad directory

• replaced an existing table via an add-on

• replaced an existing table via the scratchpad directory

• altered existing table meta-data via an add-on

• altered existing table meta-data via the scratchpad directory

• ensured proper fallback when the user selected a new table which was provided by a later disabled add-on

• ensured proper fallback when the user selected a new table which was provided by a later removed add-on

• ensured proper fallback when the user selected a new table which was provided by the later disabled scratchpad directory

Known issues with pull request:

None known.

Code Review Checklist:

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

[LeonarddeR]

@seanbudd Any chance this can be reviewed any time soon? I might be unable to address review comments later this year.

[seanbudd]

changes here will have to be rebased when the 2024.3 change log is prepared

[seanbudd]

Thanks @LeonarddeR

[seanbudd]

The change log entry is now available for 2024.3 and PRs to master are unfrozen.
Can you please fix up merge conflicts?

[LeonarddeR]

Should now be done. Could you please have a quick look over the dev guide changes as well?
I'd expect code examples to be in a markdown code block, but it looks like they're only indented. Is that expected?

[seanbudd]

Merge fixes look fine other than the formatting of this code block

[seanbudd]

This should use code formatting blocks with grave marks, rather than indentation

[LeonarddeR]

I copied the style from other code blocks, like on line 267.

[seanbudd]

Thanks, while it appears to render fine we probably want to convert these and remove the start/end lines

[codeofdusk]

Should this change log entry be included? It looks like it was merged into 2019.3:

• The fallback braille input table is now equal to the fallback output table, which is Unified English Braille Code grade 1. (Braille: The fall-back input table does not match the default input table. #9863, @JulienCochuyt, @LeonarddeR)