Use liblouis metadata for braille table descriptions

[LeonarddeR]

Originally posted by @bertfrees in https://github.com/nvaccess/nvda/pull/11268#issuecomment-648451536

I can't stress enough how much I would appreciate it if you would use our metadata instead of your own names.

Currently, most tables have been part of NVDA for ages and therefore had their description set a long time ago, before Liblouis provided metadata.

There are some possibilities:

1. We can just change all the names according to the metadata manually.
2. We can automate the process in a way that still allows the names to be translatable.

[zstanecic]

I am against it, cause not all metadata are complete.

[bertfrees]

@leonardder Thank you!

@zstanecic So why not work with us to make it complete? If you think that some metadata can be improved, why not make others benefit from your improvements?

[zstanecic]

Hi Bert,

I can create the complete metadata with all info needed,

But please allow me to work from my master fork.

One big note:

Some braille codes in liblouis define grade 1 as literary standard.

I think that we also need to change terms like this:

Contracted, unconstracted,

Instead of grade 1 grade 2.

One more thing:

If we plan to use metadata, why not detect new braille tables by discovering them by the metadata, instead of hardcoding this information?

@leonardder

[Adriani90]

@zstanecic I would not add automatic detection of tables since we never really know which issues new tables solve unless the autor of the tables document this. The improvements in newer tables in comparison to older tables should be still assessed manually when adding them to NVDA, including how experimental they are and which added value is there from an user perspective. Just because there is a newer version of a table out there it does not mean that it is finished or that it is better than old tables. In case of the german tables for example, we had a comprehensive discussion and it turns out that the newer tables are improving the user experience, so they can be considered. But this might not be valid for every language, see for example the norvegian braille tables.

[Adriani90]

Ideally, if an autor creates a new table, then he or she should also propose a pull request to NVDA to include it in the gui if he or she thinks that it is stable enough. Otherwise users should create an issue against Liblouis or NVDA requesting the table to be included and also marking the autor of the table into the respective issues.

[bertfrees]

@zstanecic

I can create the complete metadata with all info needed

Great that you want to help out! However before diving into it, may I ask you to create a Liblouis ticket first with a summary of what metadata you think is missing or wrong, and how you intend to fix it? I'd like to avoid getting into bikeshedding discussions about the exact phrasing of descriptions only after a lot of work has been done preparing a PR. I'd also like to have the opportunity to elaborate, if needed, on why we currently do certain things the way we do. Depending on what the exact requirements are, I might have suggestions for solutions. Thanks.

[DrSooom]

@Adriani90: As Liblouis is included in many end applications, I cannot agree with you that the main author of a new braille table also has to contact every possible end application teams, in which his braille table should be included. This is imho unrealistic. Furthermore the Liblouis team can offer this information already directly via their News page. If you think that the information in their Release Notes can be improved regarding this topic, then please open a new issue there. Thanks.

[feerrenrut]

I'm not really convinced about this idea:

• It is minimal work to manually set the name, using the metadata as a suggestion.
• Manually doing this ensures that a conscious decision is being made by NVDA developers about what will appear in NVDA
• I assume that translations are not provided by the metadata, English should be thought of as another target language for translation.
• Changing the existing names for no reason is not very friendly to existing users.

I can't stress enough how much I would appreciate it if you would use our metadata instead of your own names.

@bertfrees could you expand on this? Why would you like this? What problem does this solve?

[bertfrees]

@feerrenrut I don't want to involve myself in the question to which extend you want to automate things. That is only secondary to me. Also the exact phrasing of things is not the most important. Every application can have its own way of doing things, and I agree that sudden changes in names can cause confusion with some users so you need a good reason to do that.

What I'm really after is that we have a common understanding of what the various tables are, and that this is somehow reflected in the naming. Important is that if you are using a certain braille table in NVDA, it should be completely evident what the corresponding setting is in let's say a note taker that uses Liblouis, and you can be sure it is the exact same table. Key in this is that the list of tables available from the NVDA user interface is a subset of the list of Liblouis tables that have metadata.

I would like us to evolve to a situation where ideally any improvement that either of us do to table naming or metadata also benefits the other party. I don't have a ready-made answer for how to do this practically, but there are possibilities.

[feerrenrut]

Thanks for clarifying @bertfrees. I'm happy for someone to go through and try to make the two sets of names align better, though I think this should be a manual process. The first step should be identifying the differences, then deciding which need updating in NVDA vs liblouis. @leonardder would you mind editing the description of this issue for clarity?

[LeonarddeR]

Personally, I think we should reconsider this. @bertfrees I assume metadata is a pretty stable source nowadays?

We can make this opt-in with a feature flag, so people can either depend on the metadata provided by liblouis or our own metadata.

To make metadata translatable, we should add a tool to scons that does the following:

1. Load the metadata from liblouis
2. Translated that in a bunch of brailleTables.addTable statements that can be written to a python module. When we wrap the display names in gettext calls, this can be picked up by the translation system pretty easily.

[seanbudd]

I think we'd be better off creating a separate .po file for liblouis and integrating it to crowdin separately, that way they can easily take it upstream eventually

[seanbudd]

It might also be simpler to do this

[LeonarddeR]

@bertfrees Is making metadata translatable something you could consider?

[bertfrees]

@LeonarddeR Providing translations of the table descriptions has always been the idea, so it is definitely something that we would welcome.