Abraham

Abraham is a library for converting between LaTeX and the Braille math codes Nemeth and UEB. If you are interested in using this library, please contact us at partnerships@desmos.com.

Math Code Translation

The latexToNemeth, nemethToLatex, latexToUeb, and uebToLatex functions are used to translate between math codes.

Translating LaTeX to Nemeth:

Abraham.latexToNemeth('e_{f}^{x^{2}}');
{
  isError: false,
  value: '⠑⠰⠋⠘⠭⠘⠘⠆'
}

Translating Nemeth to LaTeX:

Abraham.nemethToLatex('⠑⠰⠋⠘⠭⠘⠘⠆');
{
  isError: false,
  value: 'e_{f}^{x^{2}}',
  warnings: []
}

Translating LaTeX to UEB:

Abraham.latexToUeb('1+1');
{
  isError: false,
  value: '⠼⠁⠐⠖⠼⠁'
}

Translating UEB to LaTeX:

Abraham.uebToLatex('⠼⠁⠐⠖⠼⠁');
{
  isError: false,
  value: '1+1',
  warnings: []
}

nemethToLatex and uebToLatex expect their input to be six-dot Unicode Braille Characters.

nemethToLatex, latexToNemeth, uebToLatex, and latexToUeb return Result objects that represent either a successfully translated value or an error.

Successfully translated results have an isError property set to false and a value property containing the translated result.

The value property of a latexToNemeth or latexToUeb Result is a Unicode Braille string, and the value property of a latexToNemeth or latexToUeb Result is a LaTeX string.

When a parse error occurs, the result has an isError property set to true, and an error property that gives the location of the place where the error occurred in the following format:

{
  // ...
  error: {
    location: {
      first_line: 1,
      last_line: 1,
      first_column: 0,
      last_column: 1
    }
  }
}

The error object also currently has a _diagnostic property with information that's useful for developers for understanding parse errors, but the contents of this property may change and are not part of the public API.

Strict and permissive translation

By default, nemethToLatex and uebToLatex will insert missing delimiters like open or close fraction symbols, and open or close radical symbols. This is useful because it allows translating to LaTeX as a user types, even before the expression is complete, and also because users may sometimes make mistakes in entering these delimiters.

The result of nemethToLatex and uebToLatex has a warnings property that lists each location a missing delimiter was inserted.

For example, the following input is missing a "close fraction" symbol:

Abraham.nemethToLatex('⠹⠂⠌⠆');
{
  isError: false,
  value: "\\frac{1}{2}",
  warnings: [{
    location: {
      first_line: 1,
      last_line: 1,
      first_column: 4,
      last_column: 4
    }
  }]
}

This behavior can be disabled (in which case missing delimiters will become a parse error) by passing {strict: true} as a second argument to the translators.

Abraham.nemethToLatex('⠹⠂⠌⠆', { strict: true });
{
  isError: true,
  error: {
    location: {
      first_line: 1,
      last_line: 1,
      first_column: 3,
      last_column: 4
    }
  }
}

LaTeX Operator Names

LaTeX includes the \operatorname command to allow displaying an arbitrary string in a similar way as built in math functions such as \sin. Neither Nemeth nor UEB provide a special convention for operator names, so operator names are translated to strings of letters. For example:

Abraham.latexToNemeth('\\operatorname{floor}(x)');
{
  isError: false,
  value: '⠋⠇⠕⠕⠗⠷⠭⠾'
}

In order to translate operator names in the reverse direction, from Braille to LaTeX, Abraham requires a list of expected operators to watch for. An extensive list encompassing values used in the Desmos calculators is included. To use a custom list of operator names, add an operatorNames property to the options parameter of the translation functions set to a list of operator name strings.

Abraham.nemethToLatex('⠃⠇⠁⠓⠷⠁⠃⠉⠾', { operatorNames: ['blah'] });
{
  isError: false,
  value: '\\operatorname{blah}(abc)'
}

Default Operator Names

Braille Cell Encodings

Abraham also includes functions for translating between Braille ASCII (a cell-by-cell encoding of six dot Braille cells into a subset of ASCII), and Unicode Braille cell characters:

var UnicodeBraille = Abraham.UnicodeBraille;
UnicodeBraille.toBrailleAscii('⠼⠁⠐⠖⠼⠁'); // '#A"6#A'
UnicodeBraille.toExpandedBrailleAscii('⠼⠁⠐⠖⠼⠁'); // '#a"6#a'
UnicodeBraille.coerceToSixDotCells('#A"6#A'); // '⠼⠁⠐⠖⠼⠁'

Expanded Braille ASCII is a similar encoding to Braille ASCII intended for eight dot Braille cells, which are very common on dynamic Braille displays. A primary difference is that expanded Braille ASCII encodes both upper case and lower case letters as single Braille cells, whereas Braille ASCII encodes upper case letters as digraphs: a comma followed by a letter.

UnicodeBraille.coerceToSixDotCells is useful for taking input in a variety of formats and coercing it to six dot Unicode Braille characters that the translator natively understands. It will convert either Braille ASCII or Expanded Braille ASCII (ignoring case) to six dot Unicode Braille characters, and will also convert any eight dot Unicode Braille characters to the six dot subset by stripping the bottom pair of dots.

Demonstration

This demonstration page uses Abraham to translate between either UEB or Nemeth Braille and visually typeset math as you type.

Braille Display Configuration

Refreshable Braille displays typically have a few different input modes for translating Braille keystrokes into output for a computer.

Grade 1 and Grade 2 literary modes are useful for typing prose because they allow the use of certain contractions (e.g. "tion" can be entered as a single Braille cell). In these modes, the input is usually buffered until the user signals that it is complete.

For entering Nemeth or UEB math, these contractions are counter-productive, so users should configure their devices to "Computer Braille" mode. In this mode, cells are passed through literally as they are entered.

For more details on configuring screen readers and refreshable Braille displays for math input, see Desmos's Screen Reader Configuration documentation.

Scope and limitations

Abraham is currently focused on supporting the subset of LaTeX math notations that are supported by the Desmos Calculators, and the subset of Braille notations that are easily read and edited on a single-line Refreshable Braille display. In particular, Abraham does not currently support multi-line notations such as matrices or multi-line addition.

Why Abraham

The library is named in honor of Abraham Nemeth, creator of the Nemeth Braille code (and also MathSpeak, a system for orally communicating mathematical text that inspired the screen reader system in MathQuill).

References

The Nemeth parser and tests are closely based on "The Nemeth Braille Code For Mathematics and Science Notation, 1972 Revision".

The UEB parser is derived from rules specified in "Guidelines for Technical Material 2014" written by the Maths Focus Group, a subgroup of the former UEB Rules Committee during the UEB development phase.