Skip to content

Latest commit

 

History

History
79 lines (61 loc) · 3.38 KB

CONTRIBUTING.md

File metadata and controls

79 lines (61 loc) · 3.38 KB

Contributions guide

You only need Inkscape>=1.0, a posix shell and the xvfb package to develop and test.

Make changes to the code

  1. Move text_braille_l18n.inx and text_braille_l18n.py files to your user's extensions directory. If you don't know its location, open it from Edit -> Preferences -> System -> Users extensions.
  2. Edit the code there.
  3. Once edited and manually tested, move the files to this repository, it's time to run tests.

Test your changes

  • sh tests/run.sh: Run tests.

Environment variables

Some environment variables can be defined to control the execution of tests:

  • LOCALES=en,es sh tests/run.sh: Run tests for specified alphabets.
  • DEBUG=1 sh tests/run.sh: Run tests showing all executed commands (mainly for tests script debugging).
  • GUI=1 sh tests/run.sh: Run tests in GUI mode (showing Inkscape UI).
  • NO_COLOR=1 sh tests/run.sh: Run tests showing differences between produced and expected output in black/white (by default colored output). See NO_COLOR standard.

You'll see that a folder is created under tests/tmp/ where the output for each locale is stored.

How to add a new language?

  1. Check the official established encoding specification for your language in the document World Braille Usage. Search the document for the language, but note that will be written in that language, so translate it to your language using an online translator if you can't follow it.
  2. Create the option for the language in text_braille_l18n.inx inside locale parameter.
  3. Create a function for characters mapping for the language in text_braille_l18n.py. Use other languages as reference if you don't know how to structure it.
  4. Include that function in LOCALE_CHARMAPS, being the key the ISO-639-1 correspondent to the language.
  5. Create the expected file for the locale in tests/{locale}.expect.txt.
  6. Add the language to README Supported alphabets table.
  7. Add a section with details about the implementation for that language in NOTES.md. This is specially useful if the implementation contains singularities and will help future developers to maintain the code.

Some tricks developing

  • Convert Braille unicode character to hexadecimal integer representation: hex(ord("⠿")).
  • Convert hexadecimal integer representation to Braille unicode character: chr(0x283f).
  • Copy Braille unicode character from Braille ASCII Wikipedia page. You can search by their binary representation, for example: ⠽ would be 101111.