Research
Six bugs we found in the reference braille tables
liblouis is the implementation this entire site measures itself against. Writing Arabic and Portuguese engines against it turned up six rows where it departs from its own stated rule, or from the standard it implements.
First, the part that matters more than the list: liblouis is very good, and this site depends on it. It is the free software behind most braille output in the world — screen readers, embossers, transcription tools — it covers scores of languages, and it is the yardstick every measurement on this site is taken against. Nothing below changes that. A project that ships tables for that many languages will have rows that are wrong, and the useful thing to do with one is to write down exactly which row and why.
These six were not found by reading the tables looking for trouble. They fell out of building two new engines — Arabic grade 1 and Portuguese grade 1 — and comparing every word of a frequency corpus against the reference. Where the two disagreed, each disagreement had to be resolved one way or the other before the engine could ship, and these are the six that resolved against the reference.
The method
- Question
- Where this engine and the reference disagree, which one departs from the published rule?
- Compared against
- liblouis 3.29.0 (en-ueb-g2), using its Arabic (ar-ar-g1) and Portuguese (pt-pt-g1) tables, and the table sources themselves rather than only their output.
- Over
- 5,000 Arabic words and 5,045 Portuguese texts by frequency, with every remaining disagreement resolved by hand against the table source or the national standard.
- Committed as
forge/topics/braille/data/ar-reference.tsv, pt-reference.tsv
Each defect below is asserted from both ends on every build: that the reference still behaves the way this page describes, and that this engine does something different. The first half is the one that matters. The day liblouis fixes one of these, that assertion fails, the build breaks, and this page is corrected instead of quietly becoming a lie about someone else's software.
Arabic — four rows in ar-ar-g1
Arabic grade 1 is letter-for-letter, so there is little room for interpretation: a divergence is either a rule or a slip. All four of these are slips, and three of them are visible in the table source without running anything.
Measured over 5,000 words, this engine and the reference agree on 4,999 — the disagreements below are rare in running text, which is exactly why they survive.
The shadda after alif maqsura
- liblouis
- leaves the shadda where it stands, after the letter
- This site
- moves it before the letter, as it does for every other letter
- Evidence
- The table lists thirty-six rules that move the shadda before its letter, and its own comment says they cover every Arabic letter. Alif maqsura is the one letter missing from the list. That is an omission in an enumeration, not an orthographic rule — no published source treats alif maqsura differently.
- Source
ar-ar-g1-core.uti lines 96–131- Check it
$ echo "علىّ" | lou_translate --forward unicode.dis,ar-ar-g1.utbliblouis 3.29.0 answers ⠷⠇⠕⠠ · this site answers ⠷⠇⠠⠕.
The shadda does not survive a round trip
- liblouis
- leaves the shadda before the letter, producing Arabic that cannot be read
- This site
- puts the shadda back after the letter it doubles
- Evidence
- Every shadda rule in the table is marked noback, so it applies in one direction only. Back-translating ⠌⠠⠝ yields أّن instead of أنّ — a shadda before its letter, which is not a valid sequence in Arabic. Forward translation is correct; only the reverse is affected, which is why it survives a forward-only test suite.
- Source
ar-ar-g1-core.uti lines 97–131- Check it
$ echo "⠌⠠⠝" | lou_translate --backward unicode.dis,ar-ar-g1.utbliblouis 3.29.0 answers أّن · this site answers أنّ.
Tatweel is written as two sukun cells
- liblouis
- writes it as two cells of dots 2-5
- This site
- drops it
- Evidence
- Tatweel is a typographic stretch with no sound — it exists to justify a line, not to be pronounced. Dots 2-5 is the sukun, so a reader cannot tell a tatweel from two sukun, and back-translation resolves it as two sukun: مـم returns as مْْم. Dropping a mark that carries no sound loses nothing; writing it as a different mark loses the word.
- Source
ar-ar-g1-core.uti line 89- Check it
$ echo "مـم" | lou_translate --forward unicode.dis,ar-ar-g1.utbliblouis 3.29.0 answers ⠍⠒⠒⠍ · this site answers ⠍⠍.
No letter sign before fa after a digit
- liblouis
- omits it, so the letter is read as a digit
- This site
- writes it, as it does before the other six ambiguous letters
- Evidence
- Fa is dots 1-2-4, which is also the digit 6. So 1ف and 16 produce identical cells, and back-translation reads both as 16 — the letter is gone. The table writes the letter sign before alif, ba, jeem, dal, ha and ya for exactly this reason, and omits fa alone.
- Source
ar-ar-g1-core.uti line 172 and 278- Check it
$ echo "1ف" | lou_translate --forward unicode.dis,ar-ar-g1.utbliblouis 3.29.0 answers ⠼⠁⠋ · this site answers ⠼⠁⠰⠋ — liblouis writes the same three cells for 16, so the two are indistinguishable.
Portuguese — two marks in pt-pt-g1
Portuguese has a published national standard, the Grafia Braille para a Língua Portuguesa, agreed jointly by Portugal and Brazil. Both of these are cases where the table and the standard say different things, and where the table's answer is not a defensible alternative reading but a cell that means something else entirely.
The apostrophe
- liblouis
- writes dot 6
- This site
- writes dot 3, the cell the published standard assigns
- Evidence
- The Grafia Braille gives the apostrophe the same cell as the full stop, dot 3. Dot 6 is not a mark at all in this code — it is the prefix that opens angle quotes and closing brackets — so the reference does not merely choose differently, it emits a prefix where a mark belongs.
- Source
Grafia Braille para a Língua Portuguesa (Comissão de Braille, MEC)- Check it
$ echo "'" | lou_translate --forward unicode.dis,pt-pt-g1.utbliblouis 3.29.0 answers ⠠ · this site answers ⠄.
The ellipsis
- liblouis
- writes dots 3-5, 2-6, 3-5
- This site
- writes dot 3 three times, as three full stops
- Evidence
- An ellipsis is three full stops, and the standard spells it 3 3 3. liblouis gets this right when the three stops are typed separately and only fails on the single character “…”, which points at a transcription slip in one rule rather than a different reading of the standard.
- Source
Alterações à Grafia Braille para a Língua Portuguesa (Comissão de Braille)- Check it
$ echo "…" | lou_translate --forward unicode.dis,pt-pt-g1.utbliblouis 3.29.0 answers ⠔⠢⠔ · this site answers ⠄⠄⠄.
What this page is not claiming
It is not claiming this site is more accurate than liblouis. On English it plainly is not: measured over the same kind of corpus, this site's Grade 2 output matches the reference on 99.7% of the 5,000 commonest words and gets 14 of them wrong — and every one of those failures is listed, with the reference's answer beside this engine's. There, the reference is right and this engine is not.
It is also not claiming these are the only defects. They are the six that a specific exercise — two new engines, two frequency corpora — happened to surface. A third engine would probably find more.
Checking any of this yourself
Every defect above carries the command that shows it and the answer each side gives, so nothing here has to be taken on trust. All you need is liblouis 3.29.0 or later — unicode.dis in front of the table name is what makes it print braille characters rather than the ASCII form.
The table sources are in the liblouis repository under tables/, and the line numbers above are from the files as shipped in 3.29.0. This site's own answers come from the API, which publishes all five codes as JSON, and the divergences are carried in the coverage.divergesFromReference field of the Arabic and Portuguese documents so a consumer diffing against the reference learns why rather than concluding this site is broken.
Then this page is the thing that should change. These are claims about someone else's software, made from reading its tables and its output; if a rule below has a justification not visible from the source, say so and it comes off the list. The other measurements cover the reference tables, contraction positions and page counts.
The finding as an image
For a slide, an issue thread or a message.
