This manual is for liblouis (version 3.16.0, 30 November 2020), a Braille Translation and Back-Translation Library derived from the Linux screen reader BRLTTY.
Copyright © 1999-2006 by the BRLTTY Team.
Copyright © 2004-2007 ViewPlus Technologies, Inc. www.viewplus.com.
Copyright © 2007, 2009 Abilitiessoft, Inc. www.abilitiessoft.org.
Copyright © 2014, 2016 Swiss Library for the Blind, Visually Impaired and Print Disabled. www.sbs.ch.
This file is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser (or library) General Public License (LGPL) as published by the Free Software Foundation; either version 3, or (at your option) any later version.
This file is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser (or Library) General Public License LGPL for more details.
You should have received a copy of the GNU Lesser (or Library) General Public License (LGPL) along with this program; see the file COPYING. If not, write to the Free Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
Liblouis is an open-source braille translator and back-translator derived from the translation routines in the BRLTTY screen reader for Linux. It has, however, gone far beyond these routines. It is named in honor of Louis Braille. In Linux and Mac OSX it is a shared library, and in Windows it is a DLL. For installation instructions see the README file. Please report bugs and oddities to the mailing list, liblouis-liblouisxml@freelists.org
This documentation is derived from the BRLTTY manual, but it has been extensively rewritten to cover new features.
This manual has two main audiences: People who want to write or improve a braille translation table and people who want to use the braille translator library in their own programs. This manual is probably not for people who are looking for some turn-key braille translation software.
If you are mostly interested in writing braille translation tables then you want to focus on How to Write Translation Tables. You might want to look at Notes on Back-Translation if you are interested in back-translation. Read Table Metadata if you want to find out how you can augment your tables with metadata in order to make them discoverable by programs. Finally Testing Translation Tables interactively and Automated Testing of Translation Tables will show how your braille translation tables can be tested interactively and also in an automated fashion.
If you want to use the braille translation library in your own program or you are interested in enhancing the braille translation library itself then you will want to look at Programming with liblouis.
For many languages there is already a translation table, so before creating a new table start by looking at existing tables to modify them as needed.
Typically, a braille translation table consists of several parts. First are header and includes, in which you write what the table is for, license information and include tables you need for your table.
Following this, you’ll write various translation rules and lastly you write special rules to handle certain situations.
A translation rule is composed of at least three parts: the opcode (translation command), character(s) and braille dots. An opcode is a command you give to a machine or a program to perform something on your behalf. In liblouis, an opcode tells it which rule to use when translating characters into braille. An operand can be thought of as parameters for the translation rule and is composed of two parts: the character or word to be translated and the braille dots.
For example, suppose you want to read the word ‘world’ using braille dots ‘456’, followed by the letter ‘W’ all the time. Then you’d write:
always world 456-2456
The word always is an opcode which tells liblouis to always
honor this translation, that is to say when the word ‘world’ (an
operand) is encountered, always show braille dots ‘456’ followed
by the letter ‘w’ (‘2456’).
When you write any braille table for any language, we’d recommend working from some sort of official standard, and have a device or a program in which you can test your work.
Many translation (contraction) tables have already been made up. They are included in the distribution in the tables directory and can be studied as part of the documentation. Some of the more helpful (and normative) are listed in the following table:
Character definitions for U.S. tables
Remove excessive whitespace
Uncontracted American English
Contracted or Grade 2 American English
Make liblouis output conform to BRF standard
8-dot computer braille for use in coding examples
6-dot computer braille
Nemeth Code translation for use with liblouisutdml
Fixes errors at the boundaries of math and text
The names used for files containing translation tables are completely arbitrary. They are not interpreted in any way by the translator. Contraction tables may be 8-bit ASCII files, UTF-8, 16-bit big-endian Unicode files or 16-bit little-endian Unicode files. Blank lines are ignored. Any leading and trailing whitespace (any number of blanks and/or tabs) is ignored. Lines which begin with a number sign or hatch mark (‘#’) are ignored, i.e. they are comments. If the number sign is not the first non-blank character in the line, it is treated as an ordinary character. If the first non-blank character is less-than (‘<’) the line is also treated as a comment. This makes it possible to mark up tables as xhtml documents. Lines which are not blank or comments define table entries. The general format of a table entry is:
opcode operands comments
Table entries may not be split between lines. The opcode is a mnemonic that specifies what the entry does. The operands may be character sequences, braille dot patterns or occasionally something else. They are described for each opcode, please see Opcode Index. With some exceptions, opcodes expect a certain number of operands. Any text on the line after the last operand is ignored, and may be a comment. A few opcodes accept a variable number of operands. In this case a number sign (‘#’) begins a comment unless it is preceded by a backslash (‘\’).
Here are some examples of table entries.
# This is a comment. always world 456-2456 A word and the dot pattern of its contraction
Most opcodes have both a "characters" operand and a "dots" operand, though some have only one and a few have other types.
The characters operand consists of any combination of characters and escape sequences proceeded and followed by whitespace. Escape sequences are used to represent difficult characters. They begin with a backslash (‘\’). They are:
backslash
form feed
new line
carriage return
blank (space)
horizontal tab
vertical tab
"escape" character (hex 1b, dec 27)
4-digit hexadecimal value of a character
If liblouis has been compiled for 32-bit Unicode the following are also recognized.
5-digit (20 bit) character
Full 32-bit value.
Please take a look at the public directory of the Unicode Character Database as well as at the Unicode names list with their code points to figure out the corresponding Unicode code point for a given Unicode character.
The dots operand is a braille dot pattern. The real braille dots, 1 through 8, must be specified with their standard numbers.
liblouis recognizes virtual dots, which are used for special purposes, such as distinguishing accent marks. There are seven virtual dots. They are specified by the number 9 and the letters ‘a’ through ‘f’.
For a multi-cell dot pattern, the cell specifications must be separated from one another by a dash (‘-’). For example, the contraction for the English word ‘lord’ (the letter ‘l’ preceded by dot 5) would be specified as ‘5-123’. A space may be specified with the special dot number 0.
An opcode which is helpful in writing translation tables is
include. Its format is:
include filename
It reads the file indicated by filename and incorporates or
includes its entries into the table. Included files can include other
files, which can include other files, etc. For an example, see what
files are included by the entry include en-us-g1.ctb in the table
en-us-g2.ctb. If the included file is not in the same directory
as the main table, use a full path name for filename. Tables can also be
specified in a table list, in which the table names are separated by
commas and given as a single table name in calls to the translation
functions.
The order of the various types of opcodes or table entries is
important. Character-definition opcodes should come first. However, if
the optional display opcode (see display) is used it should precede
character-definition opcodes. Braille-indicator opcodes should come
next. Translation opcodes should follow. The context opcode (see context) is a
translation opcode, even though it is considered along with the
multipass opcodes. These latter should follow the translation opcodes.
The correct opcode (see correct) can be used anywhere after the
character-definition opcodes, but it is probably a good idea to group
all correct opcodes together. The include opcode (see include) can be
used anywhere, but the order of entries in the combined table must
conform to the order given above. Within each type of opcode, the
order of entries is generally unimportant. Thus the translation
entries can be grouped alphabetically or in any other order that is
convenient. Hyphenation tables may be specified either with an
include opcode or as part of a table list. They should come after
everything else.
Hyphenation tables are necessary to make opcodes such as the
nocross opcode (see nocross) function properly. There are no opcodes for
hyphenation table entries because these tables have a special format.
Therefore, they cannot be specified as part of an ordinary table.
Rather, they must be included using the include opcode (see include) or as part
of a table list. The liblouis hyphenation algorithm was adopted from the
one used by OpenOffice. Note that Hyphenation tables must follow
character definitions and should preferably be the last. For an example
of a hyphenation table, see hyph_en_US.dic.
These opcodes are needed to define attributes such as digit,
punctuation, letter, etc. for all characters and their dot patterns.
liblouis has no built-in character definitions, but such definitions
are essential to the operation of the context opcode (see context), the
correct opcode (see correct), the multipass opcodes and the back-translator. If
the dot pattern is a single cell, it is used to define the mapping
between dot patterns and characters, unless a display opcode (see display) for
that character-dot-pattern pair has been used previously. If only a
single-cell dot pattern has been given for a character, that dot
pattern is defined with the character’s own attributes.
You may have multiple definitions of a character using the same or different dot patterns. If you use different dot patterns for the same character, only the first dot pattern will be used during forward translation. However, during back-translation, all the relevant dot patterns will back-translate to the character you defined.
You can also define a character multiple times using the same dot
pattern for the character, but using different character classes. The
following example would define the character ‘*’ (star) as both
math opcode (see math) and sign opcode (see sign).
math * 16 sign * 16
Likewise, you can define multiple characters as the same dot pattern. The characters you define this way will be forward translated to the same dot pattern. However, when back-translating, the dot pattern will always back-translate to the first character that was defined with this pattern.
This technique may be useful when defining characters that have one
representation in the Windows character set (CP1252) and another
representation in the Unicode character set, e.g. the Euro sign,
‘€’. It may also be of use when you have to define several
variants of the same letter with different accents, which may be
represented in your Braille code by the same dot pattern. This is a
very common practice for accented letters that are foreign to the
Braille code. In the following example using the uplow opcode (see uplow)
opcode, both e acute (‘é’) and e grave (‘è’) are defined as
dot 4 followed by dots 1 and 5.
uplow \x00c9\x00e9 4-15 # E acute uplow \x00c8\x00e8 4-15 # E grave
In this example, the dot pattern would always back-translate to e
acute, since this is the first definition. You could use the
correct opcode (see correct) to correct at least the most common errors on that
account. However, there is no fail-safe way to know what accented
letter to use when you back-translate from a dot pattern representing
more than one variant.
space character dotsDefines a character as a space and also defines the dot pattern as such. for example:
space \s 0 \s is the escape sequence for blank; 0 means no dots.
punctuation character dotsAssociates a punctuation mark in the particular language with a braille representation and defines the character and dot pattern as punctuation. For example:
punctuation . 46 dot pattern for period in NAB computer braille
digit character dotsAssociates a digit with a dot pattern and defines the character as a digit. For example:
digit 0 356 NAB computer braille
uplow characters dots [,dots]The characters operand must be a pair of letters, of which the first is uppercase and the second lowercase. The first dots suboperand indicates the dot pattern for the upper-case letter. It may have more than one cell. The second dots suboperand must be separated from the first by a comma and is optional, as indicated by the square brackets. If present, it indicates the dot pattern for the lower-case letter. It may also have more than one cell. If the second dots suboperand is not present the first is used for the lower-case letter as well as the upper-case letter. This opcode is needed because not all languages follow a consistent pattern in assigning Unicode codes to upper and lower case letters. It should be used even for languages that do. The distinction is important in the forward translator. for example:
uplow Aa 17,1
grouping name characters dots ,dotsThis opcode is used to indicate pairs of grouping symbols used in
processing mathematical expressions. These symbols are usually
generated by the MathML interpreter in liblouisutdml. They are used in
multipass opcodes. The name operand must contain only letters (a-z and
A-Z). The letters may be upper or lower-case but the case matters. The
characters operand must contain exactly two Unicode characters. The
dots operand must contain exactly two braille cells, separated by a
comma. Note that grouping dot patterns also need to be declared with
the exactdots opcode (see exactdots). The characters may need to be declared with
the math opcode (see math).
grouping mrow \x0001\x0002 1e,2e grouping mfrac \x0003\x0004 3e,4e
letter character dotsAssociates a letter in the language with a braille representation and defines the character as a letter. This is intended for letters which are neither uppercase nor lowercase.
lowercase character dotsAssociates a character with a dot pattern and defines the character as a lowercase letter. Both the character and the dot pattern have the attributes lowercase and letter.
uppercase character dotsAssociates a character with a dot pattern and defines the character as
an uppercase letter. Both the character and the dot pattern have the
attributes uppercase and letter. lowercase and uppercase
should be used when a letter has only one case. Otherwise use the
uplow opcode (see uplow).
litdigit digit dotsAssociates a digit with the dot pattern which should be used to represent it in literary texts. For example:
litdigit 0 245 litdigit 1 1
sign character dotsAssociates a character with a dot pattern and defines both as a sign. This opcode should be used for things like at sign (‘@’), percent (‘%’), dollar sign (‘$’), etc. Do not use it to define ordinary punctuation such as period and comma. For example:
sign % 4-25-1234 literary percent sign
math character dotsAssociates a character and a dot pattern and defines them as a mathematical symbol. It should be used for less than (‘<’), greater than(‘>’), equals(‘=’), plus(‘+’), etc. For example:
math + 346 plus
Braille indicators are dot patterns which are inserted into the braille text to indicate such things as capitalization, italic type, computer braille, etc. The opcodes which define them are followed only by a dot pattern, which may be one or more cells.
capsletter dotsThe dot pattern which indicates capitalization of a single letter. In English, this is dot 6. For example:
capsletter 6
In addition, capsletter is used to mark every letter in a
sequence of uppercase letters when there is no begcaps
definition, or when the sequence happens in the middle of a word and
begcapsword is defined but no endcapsword
(see begcaps, begcapsword and endcapsword)
begcapsword dotsThe dot pattern which begins a block of capital letters at the beginning or within a word. The block is automatically terminated by any character that is not a capital letter, e.g. small letters, punctuation, numbers etc.
Apart from capital letters, you can define a list of characters that
can appear within a word in capitals without terminating the block.
Do this by using the capsmodechars opcode (see capsmodechars).
Example:
begcapsword 6-6
endcapsword dotsThe dot pattern which ends a block of capital letters within a word. It is used in cases where the block is not terminated automatically by a word boundary, a number or punctuation. A common case is when an uppercase block is followed directly by a lowercase letter.
For example:
endcapsword 6-3
capsmodechars charactersNormally, any character other than a capital letter will cancel the
begcapsword indicator. However, by using the
capsmodechars opcode, you can specify a list of characters that
are legal within a capitalized word. In some Braille codes, this might
be the case for the hyphen character, ‘-’.
Example:
capsmodechars -
begcaps dotsThe dot pattern which begins a block of capital letters defined by the
provided typeform without regard for any other rules.
This construct is sometimes also called a capsphrase. It is used
in some Braille codes to mark a whole phrase or sentence as capital
letters. The block can contain capital letters as well as
none-alphabetic characters, punctuation, numbers etc. The
block is terminated when a small letter is encountered or at the end of the input string.
Example:
begcaps 6-6-6
endcaps dotsThe dot pattern which ends a block of capital letters defined by the
provided typeform without regard for any other rules. For
example:
endcaps 6-3
letsign dotsThis indicator is needed in Grade 2 to show that a single letter is not a contraction. It is also used when an abbreviation happens to be a sequence of letters that is the same as a contraction. For example:
letsign 56
noletsign lettersThe letters in the operand will not be proceeded by a letter sign.
More than one noletsign opcode can be used. This is equivalent
to a single entry containing all the letters. In addition, if a single
letter, such as ‘a’ in English, is defined as a word
(see word) or largesign (see largesign), it will be
treated as though it had also been specified in a noletsign
entry.
noletsignbefore charactersIf any of the characters proceeds a single letter without a space a
letter sign is not used. By default the characters apostrophe
(‘'’) and period (‘.’) have this property. Use of a
noletsignbefore entry cancels the defaults. If more than one
noletsignbefore entry is used, the characters in all entries
are combined.
noletsignafter charactersIf any of the characters follows a single letter without a space a
letter sign is not used. By default the characters apostrophe
(‘'’) and period (‘.’) have this property. Use of a
noletsignafter entry cancels the defaults. If more than one
noletsignafter entry is used the characters in all entries are
combined.
nocontractsign dotsThe dots in this opcode are used to indicate a letter or a sequence of
letters that are not a contraction, e.g. ‘CD’
(see contraction). The opcode is similar to the
letsign opcode (see letsign).
Note: This opcode was implemented in Liblouis specifically in order to support Unified English Braille (UEB). It may be used in any table, but may have unpredicted side-effects if used outside the intended context. Use with great care, and test thoroughly.
numsign dotsThe translator inserts this indicator before numbers made up of digits
defined with the litdigit opcode (see litdigit) to show that they are a number
and not letters or some other symbols. A number is terminated when a
space, a letter or any other none-litdigit opcode (see litdigit) character is
encountered.
You can define characters or strings to be part of a number by using
the midnum opcode (see midnum), the numericmodechars opcode (see numericmodechars) or the
midendnumericmodechars opcode (see midendnumericmodechars).
Example:
numsign 3456
numericnocontchars charactersThis opcode specifies the characters that require a
nocontractsign opcode (see nocontractsign) if they appear after a number with no
intervening space, e.g. ‘1a’ or ‘2-B’.
These characters will typically be the letters a-j, which usually
constitute the literary digits (see litdigit opcode (see litdigit)). However,
in some Braille codes, all letters fall in this category.
Note: This opcode is case sensitive. So, if you need a
nocontractsign opcode (see nocontractsign) to also appear before the capital letters
a-j, you should include these letters in the definition. This is
especially relevant if you are also using the begcaps and
endcaps opcodes (see begcaps and endcaps). In
this case, you might otherwise end up having numbers immediately
followed by capital letters with no indicator between.
Note: This opcode was implemented in Liblouis specifically in order to support Unified English Braille (UEB). It may be used in any table, but may have unpredicted side-effects if used outside the intended context. Use with great care, and test thoroughly.
Example:
numericnocontchars abcdefghij
numericmodechars charactersmidendnumericmodechars charactersAny of these characters can appear within a number without terminating
the effect of the number sign (see numsign). In other words,
they don’t cancel numeric mode.
The difference between the two opcodes is that
numericmodechars opcode (see numericmodechars) characters can appear anywhere in a
number whereas midendnumericmodechars opcode (see midendnumericmodechars) characters can
appear only in the middle or at the end of a number. Like
midendnumericmodechars, numericmodechars characters keep
numeric mode active, but in addition they activate numeric mode
immediately when at least one digit follows, and the number sign will
precede the numericmodechars character in this case.
Example:
Note: This opcode was implemented in Liblouis specifically in order to support Unified English Braille (UEB). It may be used in any table, but may have unpredicted side-effects if used outside the intended context. Use with great care, and test thoroughly.
numericmodechars ., midendnumericmodechars -/
The term “standing alone” comes from the specification of Unified English Braille (UEB). In Liblouis, a letter or letters-sequence is considered to be standing alone if it is preceded and followed by a space, and/or other characters that you choose as delimiters, e.g. ‘-’. A standing alone sequence can be thought of as a word in a very broad sence. With the opcodes described in this section, you can decide what characters constitute a delimiter, and what characters can attach to the beginning or end of a word or standing alone sequence.
Note: The opcodes in this section were implemented in Liblouis specifically in order to support Unified English Braille (UEB). They may be used in any table, but may have unpredicted side-effects if used outside the intended context. Use with great care, and test thoroughly.
seqdelimiter <characters> All the characters listed withthis opcode designate a valid beginning and ending to a letter
sequence used to determine when a letter sequence is standing
alone. This again determines whether word contractions
(see word) or nocontractsign (see nocontractsign) should
be applied.
Spaces do not need to be listed as they are automatically delimiters.
For example, in UEB (section 2.6.1 page 15), any hyphen or dash count as delimiters.
This opcode can be used several times, but the characters must have already been defined.
Example:
seqdelimiter -—
seqbeforechars <characters>Characters specified with this opcode may appear between a beginning sequence delimiter and the letter sequence itself.
For example, in UEB (2.6.2, page 15), opening parenthesis and opening quotations and such are allowed.
This opcode can be used several times, but the characters must have already been defined.
Example:
seqbeforechars ([{"“'‘
seqafterchars <chars>Characters specified with this opcode may appear between a letter sequence itself and a end sequence delimiter.
For example, in UEB (2.6.3, page 16), closing parenthesis and closing quotations and such are allowed.
This opcode can be used several times, but the characters must have already been defined.
Example:
seqafterchars )]}"”'’.,;:.!?…
seqafterpattern <string>Specifies that a specific string of characters can be between the letter sequence itself and an ending sequence delimiter.
For example, in UEB (section 2.6.4, page 18), the ‘'d’, ‘'s’, ‘'ll’, ‘'ve’, etc. can be after a letter sequence provided the overall sequence is standing alone.
This opcode may be used multiple times, once per pattern.
Example:
seqafterpattern 'd
In many braille systems emphasis such as bold, italics or underline is indicated using special dot patterns that mark the beginning and if needed also the end. Some braille systems have several indicators for different situations, i.e. an indicator for an emphasized word and another one for an emphasized phrase. To accommodate for all these usage scenarios liblouis provides a number of opcodes.
At the same time some braille systems use different indicators for
different kinds of emphasis while others know only one kind of
emphasis. For that reason liblouis doesn’t hard code any emphasis
types but the table author defines which kind of emphasis exist for a
specific language using the emphclass opcode (see emphclass).
The emphclass opcode defines the classes of emphasis that are
relevant for a particular language. For all emphasis that need special
indicators an emphasis class has to be declared.
emphclass <emphasis class>Define an emphasis class to be used later in other emphasis related opcodes in the table.
emphclass italic emphclass underline emphclass bold emphclass transnote
In order to understand the capabilities of Liblouis for emphasis handling we have to look at the different kinds of indicators that exist and the different scopes. There are various indicators to mark the beginning of emphasis. Where the emphasis ends depends on the type of start indicator (the scope) and on the possible occurrence of an end indicator. Sometimes an indicator appears in the middle of an emphasized part in order to change the current scope.
Which indicators Liblouis uses in which situation depends on the specific combination of indicators that are defined in the table.
Many languages simply have an indicator for the beginning of emphasis and another one for the end of the emphasis. The emphasis is “permanent” in the sense that it needs an end indicator to cancel it. It is not implicitly cancelled by any character or space.
Characters that are defined as not emphasizable in braille
(see noemphchars) are not indicated as such by Liblouis. This
means that if an emphasized phrase begins or ends with such
characters, they will not be within the part enclosed by the two
indicators. Also, if multiple emphasized parts are separated by
unemphasizable characters only, it will be indicated as if it was a
single emphasized phrase, with one start indicator and one end
indicator.
A table can not specify both a permanent indicator and a word indicator (see Word indicator) for a certain emphasis class.
begemph <emphasis class> <dot pattern>Braille dot pattern to indicate the beginning of emphasis.
begemph italic 46
A begemph rule must always be combined with a endemph
rule.
endemph <emphasis class> <dot pattern>Braille dot pattern to indicate the end of emphasis.
endemph italic 46-36
noemphchars <emphasis class> charactersNormally, emphasis is indicated on all characters except spaces
(characters with a space attribute, see space). You can
change this with the noemphchars opcode. When this opcode is
specified, emphasis is indicated on all characters except the ones in
the list. That means that emphasis is also indicated on spaces unless
the list contains space characters (escaped, e.g. \s).
Example:
noemphchars italic \s'()
Some languages have special indicators for single letter emphasis. The letter indicator will be chosen over other indicators when the next character is emphasised, but not the characters thereafter.
In some situations the letter indicator is the only way to indicate emphasis. For instance when emphasis ends within the middle of a word, and a word indicator exists (see Word indicator), but no way to cancel it explicitly. In this case Liblouis will use the letter indicator for every emphasized character in the word.
A table is even allowed to define only a letter indicator and no word or permanent indicators (see Permanent indicator), in which case the letter indicator will be used for any emphasis. It is not very likely that there are braille systems that work this way, but this feature can be useful anyway.
emphletter <emphasis class> <dot pattern>Braille dot pattern to indicate that the next character is emphasized.
emphletter italic 46-25
Many languages have special indicators for emphasized words. The scope
of a word indicator is normally until the next unemphasizable
character, however this can be changed with the emphmodechars
opcode (see noemphchars and emphmodechars).
Word emphasis can also be cancelled with an explicit closing indicator. Usually a word indicator is put at the the beginning of the word, but it may also be used for cases where the emphasis starts in the middle of the word.
begemphword <emphasis class> <dot pattern>Braille dot pattern to indicate the beginning of an emphasized word or the beginning of emphasized characters within a word.
begemphword underline 456-36
endemphword <emphasis class> <dot pattern>Word emphasis ends implicitly when the word ends. When an indication is required to close word emphasis, i.e. when emphasis ends in the middle of a word, then this opcode defines the braille dot pattern that is used.
endemphword transnote 6-3
When emphasis ends in the middle of a word and there is no
endemphword definition, a letter indicator must be defined
(see Letter indicator).
emphmodechars <emphasis class> charactersNormally, only spaces and unemphasizable characters (see space
and noemphchars) will cancel the begemphword indicator
(see begemphword). However this can be overruled with the
emphmodechars opcode. If emphmodechars is specified, any
character that is not in the specified list and is not a letter
(see uppercase, lowercase or letter) will cancel
the begemphword indicator. Conversely, letters and characters
that are in the list will not cancel the word indicator.
Example:
emphmodechars underline -
Some languages have a concept of a phrase where the emphasis is valid for a number of words. The beginning of the phrase is indicated with a braille dot pattern and a closing indicator is put before or after the last word of the phrase. A phrase only contains whole words. The phrase indicator is a special kind of permanent indicator that must be used in combination with a word indicator (see Permanent indicator and Word indicator).
A word is defined as a character sequence that starts and ends with
emphasizable characters and does not contain characters that are both
unemphasizable and resetting (see emphmodechars and noemphchars).
To define how many words are considered a phrase in your language use
the lenemphphrase opcode (see lenemphphrase).
begemphphrase <emphasis class> <dot pattern>Braille dot pattern to indicate the beginning of a phrase.
begemphphrase bold 456-46-46
A begemphphrase rule must always be combined with a
endemphphrase rule.
endemphphrase <emphasis class> before <dot pattern>Braille dot pattern to indicate the end of a phrase. The closing indicator will be placed before the last word of the phrase.
endemphphrase bold before 456-46
If a table specifies endemphphrase before and the dot pattern
is the same as that of begemphword, the word scope applies
whenever this indicator is used (see Word indicator).
endemphphrase <emphasis class> after <dot pattern>Braille dot pattern to indicate the end of a phrase. The closing
indicator will be placed after the last word of the phrase. If both
endemphphrase <emphasis class> before and endemphphrase
<emphasis class> after are defined an error will be signaled.
endemphphrase underline after 6-3
lenemphphrase <emphasis class> <number>Define how many words are required before a sequence of words is considered a phrase.
lenemphphrase underline 3
With the above rule, a sequence of two emphasized words will not be indicated as a phrase, but the words will be indicated individually.
Contrary to older versions of liblouis there is limited fallback behavior. Generally opcodes have a very specific purpose. This is done for the sake of simplicity. While it would be possible to support more combinations of rules, Liblouis chooses to signal an error when certain combinations of opcodes are used (or not used).
For example, when a begemphphrase rule is defined it is
required that there is also an endemphphrase
definition. begemph must be combined with endemph. A
begemphphrase rule is only allowed if there is also a
begemphword. begemph and begemphword are mutually
exclusive. Etc.
When new requirements for indicating emphasis arise that are not supported yet, either more opcode combinations might be enabled, or more specific opcodes might be added.
For computer braille there are only two braille indicators, for the
beginning and end of a sequence of characters to be rendered in
computer braille. Such a sequence may also have other emphasis. The
computer braille indicators are applied not only when computer braille
is indicated in the typeform parameter, but also when a
sequence of characters is determined to be computer braille because it
contains a subsequence defined by the compbrl opcode (see compbrl).
These opcodes define certain symbols, such as the decimal point, which require special treatment.
decpoint character dotsThis opcode defines the decimal point. It is useful if your Braille
code requires the decimal separator to show as a dot pattern different
from the normal representation of this character, i.e. period or
comma. In addition, it allows the notation ‘.001’ to be
translated correctly. This notation is common in some languages
instead of ‘0.001’ (no leading 0). When you use the
decpoint opcode, the decimal point will be taken to be part of
the number and correctly preceded by number sign.
The character operand must have only one character. For example, in en-us-g1.ctb we have:
decpoint . 46
hyphen character dotsThis opcode defines the hyphen, that is, the character used in compound words such as ‘have-nots’. The back-translator uses it to determine the end of individual words.
These opcodes cause special processing to be carried out.
capsnocontThis opcode has no operands. If it is specified, words or parts of words in all caps are not contracted. This is needed for languages such as Norwegian.
These opcodes define the braille representations for character sequences. Each of them defines an entry within the contraction table. These entries may be defined in any order except, as noted below, when they define alternate representations for the same character sequence.
Each of these opcodes specifies a condition under which the translation is legal, and each also has a characters operand and a dots operand. The text being translated is processed strictly from left to right, character by character, with the most eligible entry for each position be