Braille-ready output
From Zacess main at 2bc7be2. Edit this page on GitHub
How a document becomes a file a braille display or embosser can read. The code is in
crates/zacess-core/src/export/braille.rs.
Done when
The core of the issue is done when all of these hold. A real display or embosser is the one item that cannot be checked here.
- A document becomes Grade 1 or Grade 2 Unified English Braille through a translator trait, with liblouis as the adapter. The adapter is found at run time and detection returns nothing when liblouis is absent, so the caller can say so instead of writing an empty file.
- The
.brffile is North American Braille Computer Code, the characters a BRF reader expects, with lines of the chosen length, pages of the chosen size, CRLF line endings and a form feed between pages. It holds nothing but printable ASCII. - No line is longer than the cell width, at any width a device uses, whatever the text holds. That includes deeply nested lists on the narrowest display.
- A page never opens with a blank line. A title or heading, every line of it, stays on a page with the line after it.
- Pages can carry braille page numbers.
- Settings no device uses are refused with a reason instead of being changed quietly. A character that cannot be shown is counted and reported, not dropped without a word.
- Known translations from the liblouis tables are checked against written-out cells. A translation reads back as the text it came from.
- Reading the output on a physical braille display and embossing it are checked by a person with the hardware (issue 9).
Translation
Translation is liblouis's job. It runs as the lou_translate command behind the BrailleTranslator
trait, detected at run time the same way as the OCR tools, so the mobile shells can put a bundled
liblouis build behind the same trait later. Without it an export says that no braille translator is
available rather than producing nothing quietly.
| Code | liblouis tables | Used for |
|---|---|---|
| UEB grade 2 (the default) | en-ueb-g2.ctb |
Ordinary text, contracted as fluent readers expect |
| UEB grade 1 | en-ueb-g1.ctb |
Ordinary text spelt out letter by letter |
| UEB technical | en-ueb-g1.ctb,en-ueb-math.ctb |
Equations, always uncontracted |
Formats
BRF is the file embossers and displays read: ASCII braille (North American Braille Computer Code) in lines of 40 cells and pages of 25 lines, with a form feed between pages and CRLF line endings. Both sizes can be changed. Line length can be 10 to 255 cells. Lines per page can be 0 for no page breaks, otherwise at least 3 (4 with page numbers). Anything else is an error.
liblouis is run with its en-us-brf.dis display table, so cells come out as uppercase letters and
the symbols NABCC uses. Without it dot 4 is printed as a backtick, which no embosser reads as a
cell.
Pages follow transcriber practice. A page never opens with a blank line. The title and each heading stay on a page with the line after them. With page numbers on, every page after the first starts with its braille number (the numeric indicator and the digits as the letters A to J) at the right margin. The number takes one of the page's lines.
Whatever the text holds is made safe before it reaches the file. All whitespace inside a run, such
as a newline from OCR, becomes one space before translation, so runs of spaces are not kept. The
cells that come back must be printable ASCII, because a tab or a stray character would shift every
cell after it. A translator that returns dot patterns (U+2800 to U+283F) is read back to ASCII
braille. Anything else is replaced with a question mark and counted: to_brf_with_report returns
the count with the file. A caller should tell the person when it is not zero.
Unicode braille is the same lines as dot patterns (U+2800 to U+28FF), for software that
shows braille on screen or feeds a display directly.
Layout
The layout follows the conventions braille readers know, so a document reads the same way it would from a transcriber.
| Block | Braille |
|---|---|
| Title | Centred on the first line |
| Heading | Cell 5 for a major heading, cell 7 for a minor one, with a blank line before |
| Paragraph | Starts at cell 3 and runs over at cell 1 |
| List | Items at cell 1 running over at cell 3; each nested level steps in two cells; ordered items keep their numbers |
| Table | Listed row by row after a transcriber's note giving the number of data rows, with the cells of a row separated by a translated semicolon. Each cell is preceded by its column heading, so a row makes sense on its own on a one-line display |
| Image | Its description in a transcriber's note. When it has none yet, the note says so |
| Equation | The equation, then its natural reading in a transcriber's note for readers who have not met the technical code. The equation is a plain-text rendering of the source put through the UEB technical tables: a fraction becomes (a)/(b), subscripts and powers lose their braces and any other LaTeX is left as it is. Full UEB technical structure (radicals, matrices) needs a maths braille translator and is not done here |
| Page break | A blank line. A page break in the source does not start a new braille page; braille pages follow the length setting |
Text that needs checking is preceded by a transcriber's note reading "unclear", framed by the UEB transcriber's note indicators, so a braille reader gets the same warning a sighted reader gets from the highlight.
Checking it
The tests that need liblouis run when lou_translate is installed. CI installs it (see the
workflow), so they run there; on a machine without it they report that they were skipped.
- Known translations. Written-out cells, uppercase as a BRF has them, for the strong contractions (the, and, for, with, of), the alphabetic wordsigns (knowledge, children, braille), groupsigns, capitals, numbers and a decimal, in both grades. A change in a table or in how it is called shows up here.
- Read back. Sentences are translated and back-translated by liblouis in both grades and must match the original. Grade 2 must come out shorter than grade 1.
- Every width. The example document is exported at 20, 32, 40 and 80 cells with and without page breaks and page numbers. No line is too long, no page too tall and nothing but printable ASCII appears.
The unit tests with a stand-in translator cover layout, pagination, page numbers, settings and text that would corrupt a line. The output has not yet been read on a physical braille display or embossed; that test is outstanding and needs the hardware.