This manual is for liblouis (version 1.7.0, 21 August 2009), a Braille Translation and Back-Translation Library derived from the Linux screenreader BRLTTY.
Copyright © 1999-2006 by the BRLTTY Team.
Copyright © 2004-2007 ViewPlus Technologies, Inc. www.viewplus.com.
Copyright © 2007,2009 Abilitiessoft, Inc. www.abilitiessoft.com.
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 screenreader 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 maintainer, john.boyer@abilitiessoft.com
This documentation is derived from Chapter 7 of the BRLTTY manual, but it has been extensively rewritten to cover new features.
Please read the following copyright and warranty information. Note that this information also applies to all source code, tables and other files in this distribution of liblouis. It applies similarly to the sister library liblouisxml.
This file is maintained by John J. Boyer john.boyer@abilitiessoft.com.
Persons who wish to program with liblouis but will not be writing translation tables may want to skip ahead to Programming with liblouis.
Four test programs are provided as part of the liblouis package. They are intended for testing liblouis and for debugging tables. None of them is suitable for braille transcription. An application that can be used for transcription is xml2brl, which is part of the liblouisxml package (see Introduction). The source code of the test programs can be studied to learn how to use the liblouis library and they can be used to perform the following functions.
The lou_debug tool is intended for debugging liblouis translation tables. The command line for lou_debug is:
lou_debug table-name
The table (or comma-separated list of tables) is compiled. If no errors are found a brief command summary is printed, then the prompt ‘Command:’. You can then input one of the command letters and get output, as described below.
Most of the commands print information in the various arrays of
TranslationTableHeader. Since these arrays are pointers to
chains of hashed items, the commands first print the hash number, then
the first item, then the next item chained to it, and so on. After
each item there is a prompt indicated by ‘=>’. You can then press
enter (<RET>) to see the next item in the chain or the first
item in the next chain. Or you can press h (for next-(h)ash) to
skip to the next hash chain. You can also press e to exit the
command and go back to the ‘command:’ prompt.
correct opcode (see correct) and
the multipass opcodes are shown with the code that instructs the
virtual machine that interprets them. If you want to see only the
rules for a particular character string you can type p at the
‘command:’ prompt. This will take you to the ‘particular:’
prompt, where you can press f and then type in the string. The
whole hash chain containing the string will be displayed.
display opcode (see display).
capsign opcode (see capsign) and the numsign opcode (see numsign).
It also shows emphasis dot patterns, such as those for the
italword,
the firstletterbold opcode (see firstletterbold), etc. If a given
opcode has not been used nothing is printed for it.
To use this program type lou_checktable followed by a space and the name of a table. If the table contains errors, appropriate messages will be displayed. If there are no errors the message ‘no errors found.’ will be shown.
This program tests every capability of the liblouis library. It is completely interactive. To start it, type lou_allround and then <RET>. You will see a few lines telling you how to use the program. Pressing one of the letters in parentheses and then enter will take you to a message asking for more information or for the answer to a yes/no question. Typing the letter ‘r’ and then <RET> will take you to a screen where you can enter a line to be processed by the library and then view the results.
This program translates whatever is on the standard input unit and prints it on the standard output unit. It is intended for large-scale testing of the accuracy of translation and back-translation. The first argument must be -f for forward translation or -b for backward translation. To use it to translate or back-translate a file use a line like
./lou_translate -f en-us-g2.ctb <liblouis.txt >testtrans
Many translation (contraction) tables have already been made up. They are included in this distribution in the tables directory and should be studied as part of the documentation. The most helpful (and normative) are listed in the following table:
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, 16-bit big-endian Unicode files or 16-bit little-endian Unicode files. Blank lines are ignored. Any leading and trailing white-space (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. 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 (‘\’). See Opcode Index, for a list of opcodes, with a link to each one.
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:
If liblouis has been compiled for 32-bit Unicode the following are also recognized.
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 pathname for filename.
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 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).
Hyphenation tables must follow character definitions. 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. If more than
one cell is given and some of them have not previously been defined as
single cells, the undefined cells are entered into the dots table with
the space attribute. This is done for backward compatibility with
old tables, but it may cause problems with the above opcodes or
back-translation. For this reason, every single-cell dot pattern
should be defined before it is used in a multi-cell character
representation. The best way to do this is to use the 8-dot computer
braille representation for the particular braille code. If a character
or dot pattern used in any rule, except those with the display
opcode, the repeated opcode (see repeated) or the replace opcode (see replace), is not
defined by one of the character-definition opcodes, liblouis will give
an error message and refuse to continue until the problem is fixed. If
the translator or back-translator encounters an undefined character in
its input it produces a succinct error indication in its output, and
the character is treated as a space.
space character dotsspace \s 0 \s is the escape sequence for blank; 0 means no dots.
punctuation character dotspunctuation . 46 dot pattern for period in NAB computer braille
digit character dotsdigit 0 356 NAB computer braille
uplow characters dots [,dots]uplow Aa 17,1
grouping name characters dots ,dots grouping mrow \x0001\x0002 1e,2e
grouping mfrac \x0003\x0004 3e,4e
letter character dotslowercase character dotsuppercase character dotslowercase and uppercase
should be used when a letter has only one case. Otherwise use the
uplow opcode (see uplow).
litdigit digit dots litdigit 0 245
litdigit 1 1
sign character dotssign % 4-25-1234 literary percent sign
math character dotsmath + 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.
capsign dotscapsign 6
begcaps dotsbegcaps 6-6
endcaps dotsendcaps 6-3
letsign dotsletsign 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 charactersnoletsignbefore entry cancels the defaults. If more than one
noletsignbefore entry is used, the characters in all entries
are combined.
noletsignafter charactersnoletsignafter entry cancels the defaults. If more than one
noletsignafter entry is used the characters in all entries are
combined.
numsign dotslitdigit opcode (see litdigit) to show that they are a number
and not letters or some other symbols. For example:
numsign 3456
These also define braille indicators, but they require more explanation. There are four sets, for italic, bold, underline and computer braille. In each of the first three sets there are seven opcodes, for use before the first word of a phrase, for use before the last word, for use after the last word, for use before the first letter (or character) if emphasis starts in the middle of a word, for use after the last letter (or character) if emphasis ends in the middle of a word, before a single letter (or character), and to specify the length of a phrase to which the first-word and last-word-before indicators apply. This rather elaborate set of emphasis opcodes was devised to try to meet all contingencies. It is unlikely that a translation table will contain all of them. The translator checks for their presence. If they are present, it first looks to see if the single-letter indicator should be used. Then it looks at the word (or phrase) indicators and finally at the multi-letter indicators.
The translator will apply up to two emphasis indicators to each phrase
or string of characters, depending on what the typeform
parameter in its calling sequence indicates (see Programming with liblouis).
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) or the
literal opcode (see literal).
Here are the various emphasis opcodes.
firstwordital dotslenitalphrase opcode (see lenitalphrase). For example:
firstwordital 46-46 English indicator
lastworditalbefore dotsitalsign dotsfirstwordital is not used, this braille indicator is doubled
and placed before the first word. Do not use lastworditalbefore
and lastworditalafter in the same table. For example:
lastworditalbefore 4-6
lastworditalafter dotslastworditalbefore and
lastworditalafter in the same table. See also the
lenitalphrase opcode (see lenitalphrase) for more information.
firstletterital dotsbegital dotslastletterital dotsendital dotssingleletterital dotslenitalphrase numberlastworditalbefore is used, an italicized phrase is checked
to see how many words it contains. If this number is less than or
equal to the number given in the lenitalphrase opcode, the
lastworditalbefore sign is placed in front of each word. If it
is greater, the firstwordital indicator is placed before the
first word and the lastworditalbefore indicator is placed after
the last word. Note that if the firstwordital opcode is not
used its indicator is made up by doubling the dot pattern given in the
lastworditalbefore entry. For example:
lenitalphrase 4
firstwordbold dotsfirstwordbold 456-456
lastwordboldbefore dotsboldsign dotsfirstwordbold is not used, this braille indicator is doubled
and placed before the first word. Do not use lastwordboldbefore
and lastwordboldafter in the same table. For example:
lastwordboldbefore 456
lastwordboldafter dotslastwordboldbefore and
lastwordboldafter in the same table.
firstletterbold dotsbegbold dotslastletterbold dotsendbold dotssingleletterbold dotslenboldphrase numberlastwordboldbefore is used, a bold phrase is checked to see
how many words it contains. If this number is less than or equal to
the number given in the lenboldphrase opcode, the
lastwordboldbefore sign is placed in front of each word. If it
is greater, the firstwordbold indicator is placed before the
first word and the lastwordboldbefore indicator is placed after
the last word. Note that if the firstwordbold opcode is not
used its indicator is made up by doubling the dot pattern given in the
lastwordboldbefore entry.
firstwordunder dotslastwordunderbefore dotsundersign dotsfirstwordunder is not used, this braille indicator is doubled
and placed before the first word.
lastwordunderafter dotsfirstletterunder dotsbegunder dotslastletterunder dotsendunder dotssingleletterunder dotslenunderphrase numberlastwordunderbefore is used, an underlined phrase is checked
to see how many words it contains. If this number is less than or
equal to the number given in the lenunderphrase opcode, the
lastwordunderbefore sign is placed in front of each word. If it
is greater, the firstwordunder indicator is placed before the
first word and the lastwordunderbefore indicator is placed
after the last word. Note that if the firstwordunder opcode is
not used its indicator is made up by doubling the dot pattern given in
the lastwordunderbefore entry.
begcomp dotstypeform parameter (see Programming with liblouis) or
inferred because it contains a subsequence specified by the
compbrl opcode (see compbrl).
endcomp dotstypeform parameter (see Programming with liblouis) or
inferred because it contains a subsequence specified by the
compbrl opcode (see compbrl).
These opcodes define certain symbols, such as the decimal point, which require special treatment.
decpoint character dotsdecpoint . 46
hyphen character dotsThese opcodes cause special processing to be carried out.
capsnocontThese 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 being used. If there is more than one eligible entry for a given position in the text, then the one with the longest character string is used. If there is more than one eligible entry for the same character string, then the one defined first is is tested for legality first. (This is the only case in which the order of the entries makes a difference.)
The characters operand is a sequence or string of characters preceded and followed by whitespace. Each character can be entered in the normal way, or it can be defined as a four-digit hexadecimal number preceded by ‘\x’.
The dots operand defines the braille representation for the characters operand. It may also be specified as an equals sign (‘=’). This means that the the default representation for each character (see Character-Definition Opcodes) within the sequence is to be used.
In what follows the word ‘characters’ means a sequence of one or more consecutive letters between spaces and/or punctuation marks.
noback opcode ...noback always ;\s; 0
nofor opcode ...compbrl charactersliteral characterscomp6 opcode (see comp6), if 6-dot computer braille is enabled. For example:
compbrl www translate URLs in computer braille
comp6 character dotsnocont characterscompbrl, except that the string is uncontracted.
prepunc opcode (see prepunc) and postpunc opcode (see postpunc) rules are applied,
however. This is useful for specifying that foreign words should not
be contracted in an entire document.
replace characters {characters}correct opcode (see correct).
always characters dotsalways a 1. Use the
uplow, letter, etc. character definition opcodes
instead. For example:
always world 456-2456 unconditional translation
repeated characters dotsrepeated --- 36-36-36 shorten separator lines made with hyphens
repword characters dotsrepword - 123456
largesign characters dotslargesign is a bit of
braille jargon that pleases braille experts.
word characters dotssyllable characters dotssyllable horse = sawhorse, horseradish
nocross characters dotsnocross behaves like the always opcode (see always). For example, if
the English Grade 2 table is being used and the appropriate
hyphenation table has been included nocross sh 146 will cause
the ‘sh’ in ‘monkshood’ not to be contracted.
joinword characters dotsjoinword to
235. This means that if the word ‘to’ is followed by another
word the contraction is to be used and the space is to be omitted. If
these conditions are not met, the word is translated according to any
other opcodes that may apply to it.
lowword characters dotslowword derives from the
fact that in English these contractions are written in the lower part
of the cell. For example:
lowword were 2356
contraction charactersletsign opcode (see letsign)) is placed before such letter
combinations when they actually are abbreviations, not contractions.
The contraction opcode tells the translator to do this.
sufword characters dotsprfword characters dotsbegword characters dotsbegmidword characters dotsmidword characters dotsmidendword characters dotsendword characters dotspartword characters dotsexactdots @dotsexactdots @4-46-12356
will produce the characters with these dot patterns in the output.
prepunc characters dotspostpunc characters dotsbegnum characters dotsbegnum # 4.
midnum characters dotsmidnum . 46.
This is because the decimal point has a different dot pattern than the
period.
endnum characters dotsendnum th 1456.
This handles things like ‘4th’. A letter sign is NOT
inserted.
joinnum characters dotsThese opcodes define and use character classes. A character class associates a set of characters with a name. The name then refers to any character within the class. A character may belong to more than one class.
The basic character classes correspond to the character definition
opcodes, with the exception of the uplow opcode (see uplow), which defines
characters belonging to the two classes uppercase and
lowercase. These classes are:
spacedigitletterlowercaseuppercasepunctuationsignmathlitdigitundefinedThe opcodes which define and use character classes are shown below. For examples see fr-abrege.ctb.
class name charactersafter class opcode ...before class opcode ...The swap opcodes are needed to tell the context opcode (see context), the
correct opcode (see correct) and multipass opcodes which dot patterns to swap
for which characters. There are three, swapcd, swapdd
and swapcc. The first swaps dot patterns for characters. The
second swaps dot patterns for dot patterns and the third swaps
characters for characters. The first is used in the context
opcode and the second is used in the multipass opcodes. Dot patterns
are separated by commas and may contain more than one cell.
swapcd name characters dots, dots, dots, ...swapcd dropped 0123456789 356,2,23,...
swapdd name dots, dots, dots ... dotpattern1, dotpattern2, dotpattern3, ...swapdd opcode defines substitutions for the multipass
opcodes. In the second operand the dot patterns must be single cells,
but in the third operand multi-cell dot patterns are allowed. This is
because multi-cell patterns in the second operand would lead to
ambiguities.
swapcc name characters charactersswapcc opcode swaps characters in its second operand for
characters in the corresponding places in its third operand. It is
intended for use with correct opcodes and can solve problems
such as formatting phone numbers.
context test actionpass2 test actionpass3 test actionpass4 test actioncontext and multipass opcodes (pass2, pass3
and pass4) provide translation capabilities beyond those of the
basic translation opcodes (see Translation Opcodes) discussed
previously. The multipass opcodes cause additional passes to be made
over the string to be translated. The number after the word
pass indicates in which pass the entry is to be applied. If no
multipass opcodes are given, only the first translation pass is made.
The context opcode is basically a multipass opcode for the
first pass. It differs slightly from the multipass opcodes per se. The
format of all these opcodes is:
opcode test action
The test and action operands have suboperands. Each
suboperand begins with a non-alphanumeric character and ends when
another non-alphanumeric character is encountered. The suboperands and
their initial characters are as follows.
context opcode.
class opcode (see class) or the name of a
swap set defined by the swap opcodes (see Swap Opcodes). Names may
contain only letters. The letters may be upper or
lower-case. The case matters. Class names may be used in test parts
only. Swap names are valid everywhere.
#1, #2, #25. Variables may be set by
one context or multipass opcode and tested by another. Thus, an
operation that occurs at one place in a translation can tell an
operation that occurs later about itself. This feature will be used in
math translation, and it may also help to alleviate the need for new
opcodes. This suboperand is valid everywhere.
Variables are set in the action part. To set a variable use an
expression like #1=1, #2=5, etc. Variables are also
incremented and decremented in the action part with expressions like
#1+, #3-, etc. These operators increment or decrement
the variable by 1.
Variables are tested in the test part with expressions like
#1=2, #3<4, #5>6, etc.
The characters which can be used in attribute strings are as follows:
Note that if any multipass opcode or the correct opcode is used and the
pass1Only
mode bit (see lou_translateString) is not set input and output
positions may be incorrect.
correct test actioncorrect opcode. If there are no
correct opcodes in a table, the pre-translation pass is not
used. The format of the correct opcode is very similar to that
of the context opcode (see context). The only difference is that in the action
part strings may be used and dot patterns may not be used. Some
examples of correct opcode entries are:
correct "\\" ? Eliminate backslashes
correct "cornf" "comf" fix a common "scano"
correct "cornm" "comm"
correct "cornp" "comp"
correct "*" ? Get rid of stray asterisks
correct "|" ? ditto for vertical bars
correct "\s?" "?" drop space before question mark
Note that if the correct opcode is used and the
pass1Only mode bit (see lou_translateString) is not set
input and output positions may be incorrect.
include filenamefilename and incorporate or include
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 pathname for filename.
locale charactersdisplay character dots display a 1 When the character a is sent to the embosser or display,
it # will produce a dot 1.
display L 123 When the character L is sent to the display or embosser
# produces dots 1-2-3.
The display opcode is optional. It is used when the embosser or display has a different mapping of characters to dot patterns than that given in Character-Definition Opcodes. If used, display entries must proceed character-definition entries.
multind dots opcode opcode ...multind 56-6 letsign capsign.
The back-translator can generally handle single braille indicators,
but it cannot apply them when they immediately follow each other. It
recognizes the letter sign if it is followed by a letter and takes
appropriate action. It also recognizes the capital sign if it is
followed by a letter. But when there is a letter sign followed by a
capital sign it fails to recognize the letter sign unless the sequence
has been defined with multind. A multind entry may not
contain a comment because liblouis would attempt to interpret it as an
opcode.
Back-translation is carried out by the function
lou_backTranslateString. Its calling sequence is described in
Programming with liblouis. Tables containing no
context opcode (see context), correct opcode (see correct) or multipass opcodes can be
used for both forward and backward translation. If these opcodes are
needed different tables will be required.
lou_backTranslateString first performs pass4, if
present, then pass3, then pass2, then the
backtranslation, then corrections. Note that this is exactly the
inverse of forward translation.
Liblouis may contain code borrowed from the Linux screenreader BRLTTY, Copyright © 1999-2006 by the BRLTTY Team.
Copyright © 2004-2007 ViewPlus Technologies, Inc. www.viewplus.com.
Copyright © 2007,2009 Abilitiessoft, Inc. www.abilitiessoft.com.
Liblouis is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Liblouis 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 General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with Liblouis. If not, see http://www.gnu.org/licenses/.
You use the liblouis library by calling eleven functions,
lou_translateString, lou_backTranslateString,
lou_logFile, lou_logPrint, lou_getTable,
lou_translate, lou_backTranslate, lou_hyphenate,
lou_readCharFromFile, lou_version and lou_free.
These are described below. The header file, liblouis.h, also
contains brief descriptions. Liblouis is written in straight C. It has
just three code modules, compileTranslationTable.c,
lou_translateString.c and lou_backTranslateString.c. In
addition, there are two header files, liblouis.h, which defines
the API, and louis.h, used only internally. The latter includes
liblouis.h.
Persons who wish to use liblouis from Python may want to skip ahead to Python bindings.
compileTranslationTable.c keeps track of all translation tables
which an application has used. It is called by the translation,
hyphenation and checking functions when they start. If a table has not
yet been compiled compileTranslationTable.c checks it for
correctness and compiles it into an efficient internal representation.
The main entry point is lou_getTable. Since it is the module
that keeps track of memory usage, it also contains the lou_free
function. In addition, it contains the lou_logFile and
lou_logPrint functions, plus some utility functions which are
used by the other modules.
By default, liblouis handles all characters internally as 16-bit unsigned integers. It can be compiled for 32-bit characters as explained below. The meanings of these integers are not hard-coded. Rather they are defined by the character-definition opcodes. However, the standard printable characters, from decimal 32 to 126 are recognized for the purpose of processing the opcodes. Hence, the following definition is included in liblouis.h. It is correct for computers with at least 32-bit processors.
#define widechar unsigned short int
To make liblouis handle 32-bit Unicode simply remove the word
short in the above define. This will cause the translate and
back-translate functions to expect input in 32-bit form and to deliver
their output in this form. The input to the compiler (tables) is
unaffected except that two new escape sequences for 20-bit and 32-bit
characters are recognized.
Here are the definitions of the eleven liblouis functions and their parameters. They are given in terms of 16-bit Unicode. If liblouis has been compiled for 32-bit Unicode simply read 32 instead of 16.
The data structure TranslationTableHeader is defined by a
typedef statement in louis.h. To find the beginning,
search for the word ‘header’. As its name implies, this is
actually the table header. Data are placed in the ruleArea
array, which is the last item defined in this structure. This array is
declared with a length of 1 and is expanded as needed. The table
header consists mostly of arrays of pointers of size HASHNUM.
These pointers are actually offsets into ruleArea and point to
chains of items which have been placed in the same hash bucket by a
simple hashing algorithm. HASHNUM should be a prime and is
currently 1123. The structure of the table was chosen to optimize
speed rather than memory usage.
The first part of the table contains miscellaneous information, such as the number of passes and whether various opcodes have been used. It also contains the amount of memory allocated to the table and the amount actually used.
The next section contains pointers to various braille indicators and
begins with capitalSign. The rules pointed to contain the
dot pattern for the indicator and an opcode which is used by the
back-translator but does not appear in the list of opcodes. The
braille indicators also include various kinds of emphasis, such as
italic and bold and information about the length of emphasized
phrases. The latter is contained directly in the table item instead of
in a rule.
After the braille indicators comes information about when a letter sign should be used.
Next is an array of size HASHNUM which points to character
definitions. These are created by the character-definition opcodes.
Following this is a similar array pointing to definitions of
single-cell dot patterns. This is also created from the
character-definition opcodes. If a character definition contains a
multi-cell dot pattern this is compiled into ordinary forward and
backward rules. If such a multi-cell dot pattern contains a single
cell which has not previously been defined that cell is placed in this
array, but is given the attribute undefined.
Next come arrays that map characters to single-cell dot patterns and dots to characters. These are created from both character-definition opcodes and display opcodes.
Next is an array of size 256 which maps characters in this range to
dot patterns which may consist of multiple cells. It is used, for
example, to map ‘{’ to dots 456-246. These mappings are created
by the compdots
or the comp6 opcode (see comp6).
Next are two small arrays that held pointers to chains of rules
produced by the swapcd opcode (see swapcd) and the swapdd opcode (see swapdd) and by
some multipass, context and correct opcodes.
Now we get to an array of size HASHNUM which points to chains
of rules for forward translation.
Following this is a similar array for back-translation.
Finally is the ruleArea, an array of variable size to which
various structures are mapped and to which almost everything else
points.
char *lou_version ()
This function returns a pointer to a character string containing the version of liblouis, plus other information, such as the release date and perhaps notable changes.
int lou_translateString (
const char *const trantab,
const widechar *const inbuf,
int *inlen,
widechar *outbuf,
int *outlen,
char *typeform,
char *spacing,
int mode);
This function takes a string of 16-bit Unicode characters in
inbuf and translates it into a string of 16-bit characters in
outbuf. Each 16-bit character produces a particular dot pattern
in one braille cell when sent to an embosser or braille display or to
a screen typefont. Which 16-bit character represents which dot pattern
is indicated by the character-definition and display opcodes in the
translation table.
The trantab parameter points to a list of translation tables
separated by commas. If only one table is given, no comma should be
used after it. It is these tables which control just how the
translation is made, whether in Grade 2, Grade 1, or something else.
The first table in the list must be a full pathname, unless the tables
are in the current directory. The pathname is extracted up to the
filename. The first table is then compiled. The pathname is then added
to the name of the second table, which is compiled, and so on. The
tables in a list are all compiled into the same internal table. The
list is then regarded as the name of this table. As explained in
How to Write Translation Tables, each table is a file which may
be plain text, big-endian Unicode or little-endian Unicode. A table
(or list of tables) is compiled into an internal representation the
first time it is used. Liblouis keeps track of which tables have been
compiled. For this reason, it is essential to call the lou_free
function at the end of your application to avoid memory leaks. Do
NOT call lou_free after each translation. This will
force liblouis to compile the translation tables each time they are
used, leading to great inefficiency.
Note that both the *inlen and *outlen parameters are
pointers to integers. When the function is called, these integers
contain the maximum input and output lengths, respectively. When it
returns, they are set to the actual lengths used.
The typeform parameter is used to indicate italic type,
boldface type, computer braille, etc. It is a string of characters
with the same length as the input buffer pointed to by *inbuf.
However, it is used to pass back character-by-character results, so
enough space must be provided to match the *outlen parameter.
Each character indicates the typeform of the corresponding character
in the input buffer. The values are as follows: 0 plain-text; 1
italic; 2 bold; 4 underline; 8 computer braille. These values can be
added for multiple emphasis. If this parameter is NULL, no
checking for typeforms is done. In addition, if this parameter is not
NULL, it is set on return to have an 8 at every position
corresponding to a character in outbuf which was defined to
have a dot representation containing dot 7, dot 8 or both, and to 0
otherwise.
The spacing parameter is used to indicate differences in
spacing between the input string and the translated output string. It
is also of the same length as the string pointed to by *inbuf.
If this parameter is NULL, no spacing information is computed.
The mode parameter specifies how the translation should be
done. The valid values of mode are listed in liblouis.h. They
are all powers of 2, so that a combined mode can be specified by
adding up different values.
The function returns 1 if no errors were encountered and 0 if a complete translation could not be done.
int lou_translate (
const char *const trantab,
const widechar * const inbuf,
int *inlen,
widechar * outbuf,
int *outlen,
char *typeform,
char *spacing,
int *outputPos,
int *inputPos,
int *cursorPos,
int mode);
This function adds the parameters outputPos, inputPos
and cursorPos, to facilitate use in screenreader programs. The
outputPos parameter must point to an array of integers with at
least outlen elements. On return, this array will contain the
position in inbuf corresponding to each output position.
Similarly, inputPos must point to an array of integers of at
least inlen elements. On return, this array will contain the
position in outbuf corresponding to each position in
inbuf. cursorPos must point to an integer containing the
position of the cursor in the input. On return, it will contain the
cursor position in the output. Any parameter after outlen may
be NULL. In this case, the actions corresponding to it will not
be carried out. The mode parameter, however, must be present
and must be an integer, not a pointer to an integer. If the
compbrlAtCursor bit is set in the mode parameter the
space-bounded characters containing the cursor will be translated in
computer braille.
int lou_backTranslateString (
const char *const trantab,
const widechar *const inbuf,
int *inlen,
widechar *outbuf,
int *outlen,
char *typeform,
char *spacing,
int mode);
This is exactly the opposite of lou_translateString.
inbuf is a string of 16-bit Unicode characters representing
braille. outbuf will contain a string of 16–bit Unicode
characters. typeform will indicate any emphasis found in the
input string, while spacing will indicate any differences in
spacing between the input and output strings. The typeform and
spacing parameters may be NULL if this information is
not needed. mode again specifies how the back-translation
should be done.
int lou_backTranslate (
const char *const trantab,
const widechar *const inbufx,
int *inlen,
widechar * outbuf,
int *outlen,
char *typeform,
char *spacing,
int *outputPos,
int *inputPos,
int *cursorPos,
int mode);
This function is exactly the inverse of lou_translate.
int lou_hyphenate (
const char *const trantab,
const widechar * const inbuf,
int inlen,
char *hyphens,
int mode);
This function looks at the characters in inbuf and if it finds
a sequence of letters attempts to hyphenate it as a word. Note
that lou_hyphenate operates on single words only, and spaces or
punctuation marks between letters are not allowed. Leading and
trailing punctuation marks are ignored. The table named by the
trantab parameter must contain a hyphenation table. If it does
not, the function does nothing. inlen is the length of the
character string in inbuf. hyphens is an array of
characters and must be of size inlen. If hyphenation is
successful it will have a 1 at the beginning of each syllable and a 0
elsewhere. If the mode parameter is 0 inbuf is assumed
to contain untranslated characters. Any nonzero value means that
inbuf contains a translation. In this case, it is
back-translated, hyphenation is performed, and it is retranslated so
that the hyphens can be placed correctly. The lou_translate and
lou_backTranslate functions are used in this process.
lou_hyphenate returns 1 if hyphenation was successful and 0
otherwise. In the latter case, the contents of the hyphens
parameter are undefined. This function was provided for use in
liblouisxml.
void lou_logFile (char *fileName);
This function is used when it is not convenient either to let messages be printed on stderr or to use redirection, as when liblouis is used in a GUI application or in liblouisxml. Any error messages generated will be printed to the file given in this call. The entire pathname of the file must be given.
void lou_logPrint (char *format, ...);
This function is called like fprint. It can be used by other
libraries to print messages to the file specified by the call to
lou_logFile. In particular, it is used by the companion
library liblouisxml.
void *lou_getTable (char *tablelist);
tablelist is a list of names of table files separated by
commas, as explained previously
(see trantab parameter in lou_translateString). If no errors are found this function
returns a pointer to the compiled table. If errors are found messages
are printed to the log file, which is stderr unless a different
filename has been given using the lou_logFile function.
Errors result in a NULL pointer being returned.
int lou_readCharFromFile (const char *fileName, int *mode);
This function is provided for situations where it is necessary to read
a file which may contain little-endian or big-endian 16-bit Unicode
characters or ASCII8 characters. The return value is a little-endian
character, encoded as an integer. The fileName parameter is the
name of the file to be read. The mode parameter is a pointer to
an integer which must be set to 1 on the first call. After that, the
function takes care of it. On end-of-file the function returns
EOF.
void lou_free ();
This function should be called at the end of the application to free
all memory allocated by liblouis. Failure to do so will result in
memory leaks. Do NOT call lou_free after each
translation. This will force liblouis to compile the translation
tables every time they are used, resulting in great inefficiency.
There are Python bindings for lou_translateString,
lou_translate and lou_version. For installation
instructions see the the README file in the python
directory. Usage information is included in the Python module itself.
lou_backTranslate: lou_backTranslatelou_backTranslateString: lou_backTranslateStringlou_free: lou_freelou_getTable: lou_getTablelou_hyphenate: lou_hyphenatelou_logFile: lou_logFilelou_logPrint: lou_logPrintlou_readCharFromFile: lou_readCharFromFilelou_translate: lou_translatelou_translateString: lou_translateStringlou_version: lou_version