liblouis: lou_translateString

1 
1 6.5 lou_translateString
1 =======================
1 
1      int lou_translateString (
1          const char * tableList,
1          const widechar * inbuf,
1          int *inlen,
1          widechar *outbuf,
1          int *outlen,
1          char *typeform,
1          char *spacing,
1          int mode);
1 
1    This function takes a string of 16-bit Unicode characters in 'inbuf'
1 and translates it into a string of 16-bit characters in 'outbuf'.  Each
1 16-bit character produces a particular dot pattern in one braille cell
1 when sent to an embosser or braille display or to a screen type font.
1 Which 16-bit character represents which dot pattern is indicated by the
1 character-definition and display opcodes in the translation table.
1 
1    The 'tableList' parameter points to a list of translation tables
1 separated by commas.  If only one table is given, no comma should be
1 used after it.  It is these tables which control just how the
1 translation is made, whether in Grade 2, Grade 1, or something else.
1 
1    liblouis knows where to find all the tables that have been
1 distributed with it.  So you can just give a table name such as
1 'en-us-g2.ctb' and liblouis will load it.  You can also give a table
1 name which includes a path.  If this is the first table in a list, all
1 the tables in the list must be on the same path.  You can specify a path
1 on which liblouis will look for table names by setting the environment
1 variable 'LOUIS_TABLEPATH'.  This environment variable can contain one
1 or more paths separated by commas.  On receiving a table name liblouis
1 first checks to see if it can be found on any of these paths.  If not,
1 it then checks to see if it can be found in the current directory, or,
1 if the first (or only) name in a table list, if it contains a path name,
1 can be found on that path.  If not, it checks to see if it can be found
1 on the path where the distributed tables have been installed.  If a
1 table has already been loaded and compiled this path-checking is
1 skipped.
1 
1    The tables in a list are all compiled into the same internal table.
1 The list is then regarded as the name of this table.  As explained in
1 ⇒How to Write Translation Tables, each table is a file which may
1 be plain text, big-endian Unicode or little-endian Unicode.  A table (or
1 list of tables) is compiled into an internal representation the first
1 time it is used.  Liblouis keeps track of which tables have been
1 compiled.  For this reason, it is essential to call the 'lou_free'
1 function at the end of your application to avoid memory leaks.  Do _NOT_
1 call 'lou_free' after each translation.  This will force liblouis to
1 compile the translation tables each time they are used, leading to great
1 inefficiency.
1 
1    Note that both the '*inlen' and '*outlen' parameters are pointers to
1 integers.  When the function is called, these integers contain the
1 maximum input and output lengths, respectively.  When it returns, they
1 are set to the actual lengths used.
1 
1    The 'typeform' parameter is used to indicate italic type, boldface
1 type, computer braille, etc.  It is a string of characters with the same
1 length as the input buffer pointed to by '*inbuf'.  However, it is used
1 to pass back character-by-character results, so enough space must be
1 provided to match the '*outlen' parameter.  Each character indicates the
1 typeform of the corresponding character in the input buffer.  The values
1 are as follows: 0 plain-text; 1 italic; 2 bold; 4 underline; 8 computer
1 braille.  These values can be added for multiple emphasis.  If this
1 parameter is 'NULL', no checking for type forms is done.  In addition,
1 if this parameter is not 'NULL', it is set on return to have an 8 at
1 every position corresponding to a character in 'outbuf' which was
1 defined to have a dot representation containing dot 7, dot 8 or both,
1 and to 0 otherwise.
1 
1    The 'spacing' parameter is used to indicate differences in spacing
1 between the input string and the translated output string.  It is also
1 of the same length as the string pointed to by '*inbuf'.  If this
1 parameter is 'NULL', no spacing information is computed.
1 
1    The 'mode' parameter specifies how the translation should be done.
1 The valid values of mode are listed in 'liblouis.h'.  They are all
1 powers of 2, so that a combined mode can be specified by adding up
1 different values.
1 
1    The function returns 1 if no errors were encountered and 0 if a
1 complete translation could not be done.
1