-
Notifications
You must be signed in to change notification settings - Fork 5
/
liblouis.html
4779 lines (4507 loc) · 255 KB
/
liblouis.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Liblouis User's and Programmer's Manual
---
<p>This manual is for liblouis (version 3.31.0, 27 May 2024),
a Braille Translation and Back-Translation Library derived from the
Linux screen reader <abbr class="acronym">BRLTTY</abbr>.
</p>
<p>Copyright © 1999-2006 by the BRLTTY Team.
</p>
<p>Copyright © 2004-2007 ViewPlus Technologies, Inc.
<a class="uref" href="www.viewplus.com">www.viewplus.com</a>.
</p>
<p>Copyright © 2007, 2009 Abilitiessoft, Inc.
<a class="uref" href="www.abilitiessoft.org">www.abilitiessoft.org</a>.
</p>
<p>Copyright © 2014, 2016 Swiss Library for the Blind, Visually
Impaired and Print Disabled. <a class="uref" href="www.sbs.ch">www.sbs.ch</a>.
</p>
<blockquote class="quotation">
<p>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.
</p>
<p>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.
</p>
<p>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.
</p></blockquote>
<div class="element-contents" id="SEC_Contents">
<h2 class="contents-heading">Table of Contents</h2>
<div class="contents">
<ul class="toc-numbered-mark">
<li><a id="toc-Introduction-1" href="#Introduction">1 Introduction</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Who-is-this-manual-for" href="#Who-is-this-manual-for">1.1 Who is this manual for</a></li>
<li><a id="toc-How-to-read-this-manual" href="#How-to-read-this-manual">1.2 How to read this manual</a></li>
</ul></li>
<li><a id="toc-How-to-Write-Translation-Tables-1" href="#How-to-Write-Translation-Tables">2 How to Write Translation Tables</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Overview-1" href="#Overview">2.1 Overview</a></li>
<li><a id="toc-Hyphenation-Tables-1" href="#Hyphenation-Tables">2.2 Hyphenation Tables</a></li>
<li><a id="toc-Character_002dDefinition-Opcodes-1" href="#Character_002dDefinition-Opcodes">2.3 Character-Definition Opcodes</a></li>
<li><a id="toc-Braille-Indicator-Opcodes-1" href="#Braille-Indicator-Opcodes">2.4 Braille Indicator Opcodes</a></li>
<li><a id="toc-Opcodes-for-Standing-Alone-Sequences-1" href="#Opcodes-for-Standing-Alone-Sequences">2.5 Opcodes for <em class="emph">Standing Alone</em> Sequences</a></li>
<li><a id="toc-Emphasis-Opcodes-1" href="#Emphasis-Opcodes">2.6 Emphasis Opcodes</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Emphasis-classes-1" href="#Emphasis-classes">2.6.1 Emphasis classes</a></li>
<li><a id="toc-Emphasis-indicators-1" href="#Emphasis-indicators">2.6.2 Emphasis indicators</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Permanent-indicator-1" href="#Permanent-indicator">2.6.2.1 Permanent indicator</a></li>
<li><a id="toc-Letter-indicator-1" href="#Letter-indicator">2.6.2.2 Letter indicator</a></li>
<li><a id="toc-Word-indicator-1" href="#Word-indicator">2.6.2.3 Word indicator</a></li>
<li><a id="toc-Phrase-indicator-1" href="#Phrase-indicator">2.6.2.4 Phrase indicator</a></li>
</ul></li>
<li><a id="toc-Note-about-fallback-behavior-1" href="#Note-about-fallback-behavior">2.6.3 Note about fallback behavior</a></li>
<li><a id="toc-Computer-braille-1" href="#Computer-braille">2.6.4 Computer braille</a></li>
</ul></li>
<li><a id="toc-Special-Symbol-Opcodes-1" href="#Special-Symbol-Opcodes">2.7 Special Symbol Opcodes</a></li>
<li><a id="toc-Special-Processing-Opcodes-1" href="#Special-Processing-Opcodes">2.8 Special Processing Opcodes</a></li>
<li><a id="toc-Translation-Opcodes-1" href="#Translation-Opcodes">2.9 Translation Opcodes</a></li>
<li><a id="toc-Character_002dClass-Opcodes-1" href="#Character_002dClass-Opcodes">2.10 Character-Class Opcodes</a></li>
<li><a id="toc-Swap-Opcodes-1" href="#Swap-Opcodes">2.11 Swap Opcodes</a></li>
<li><a id="toc-The-Context-and-Multipass-Opcodes-1" href="#The-Context-and-Multipass-Opcodes">2.12 The Context and Multipass Opcodes</a></li>
<li><a id="toc-The-correct-Opcode-1" href="#The-correct-Opcode">2.13 The correct Opcode</a></li>
<li><a id="toc-The-match-Opcode-1" href="#The-match-Opcode">2.14 The match Opcode</a></li>
<li><a id="toc-Miscellaneous-Opcodes-1" href="#Miscellaneous-Opcodes">2.15 Miscellaneous Opcodes</a></li>
</ul></li>
<li><a id="toc-Notes-on-Back_002dTranslation-1" href="#Notes-on-Back_002dTranslation">3 Notes on Back-Translation</a>
<ul class="toc-numbered-mark">
<li><a id="toc-General-Notes-1" href="#General-Notes-1">3.1 General Notes</a></li>
<li><a id="toc-Back_002dtranslation-with-Liblouis-1" href="#Back_002dtranslation-with-Liblouis-1">3.2 Back-translation with Liblouis</a></li>
</ul></li>
<li><a id="toc-Table-Metadata-1" href="#Table-Metadata">4 Table Metadata</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Syntax" href="#Syntax">4.1 Syntax</a></li>
<li><a id="toc-Query-Syntax-1" href="#Query-Syntax-1">4.2 Query Syntax</a></li>
</ul></li>
<li><a id="toc-Testing-Translation-Tables-interactively-1" href="#Testing-Translation-Tables-interactively">5 Testing Translation Tables interactively</a>
<ul class="toc-numbered-mark">
<li><a id="toc-lou_005fdebug-1" href="#lou_005fdebug">5.1 lou_debug</a></li>
<li><a id="toc-lou_005ftrace-1" href="#lou_005ftrace">5.2 lou_trace</a></li>
<li><a id="toc-lou_005fchecktable-1" href="#lou_005fchecktable">5.3 lou_checktable</a></li>
<li><a id="toc-lou_005fallround-1" href="#lou_005fallround">5.4 lou_allround</a></li>
<li><a id="toc-lou_005ftranslate-1" href="#lou_005ftranslate-_0028program_0029">5.5 lou_translate</a></li>
<li><a id="toc-lou_005fcheckhyphens-1" href="#lou_005fcheckhyphens">5.6 lou_checkhyphens</a></li>
<li><a id="toc-lou_005fcheckyaml-1" href="#lou_005fcheckyaml">5.7 lou_checkyaml</a></li>
</ul></li>
<li><a id="toc-Automated-Testing-of-Translation-Tables-1" href="#Automated-Testing-of-Translation-Tables">6 Automated Testing of Translation Tables</a>
<ul class="toc-numbered-mark">
<li><a id="toc-YAML-Tests-1" href="#YAML-Tests-1">6.1 YAML Tests</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Optional-test-description" href="#Optional-test-description">6.1.1 Optional test description</a></li>
<li><a id="toc-Testing-multiple-tables-within-the-same-YAML-test-file" href="#Testing-multiple-tables-within-the-same-YAML-test-file">6.1.2 Testing multiple tables within the same YAML test file</a></li>
<li><a id="toc-Multiple-test-sections-for-each-table" href="#Multiple-test-sections-for-each-table">6.1.3 Multiple test sections for each table</a></li>
<li><a id="toc-Inline-definition-of-tables-1" href="#Inline-definition-of-tables-1">6.1.4 Inline definition of tables</a></li>
<li><a id="toc-Running-the-same-test-data-on-multiple-tables" href="#Running-the-same-test-data-on-multiple-tables">6.1.5 Running the same test data on multiple tables</a></li>
</ul></li>
</ul></li>
<li><a id="toc-Programming-with-liblouis-1" href="#Programming-with-liblouis">7 Programming with liblouis</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Overview-2" href="#Overview-_0028library_0029">7.1 Overview</a></li>
<li><a id="toc-Data-structure-of-liblouis-tables-1" href="#Data-structure-of-liblouis-tables">7.2 Data structure of liblouis tables</a></li>
<li><a id="toc-How-tables-are-found-1" href="#How-tables-are-found">7.3 How tables are found</a></li>
<li><a id="toc-Deprecation-of-the-logging-system-1" href="#Deprecation-of-the-logging-system">7.4 Deprecation of the logging system</a></li>
<li><a id="toc-lou_005fversion-1" href="#lou_005fversion">7.5 lou_version</a></li>
<li><a id="toc-lou_005ftranslateString-1" href="#lou_005ftranslateString">7.6 lou_translateString</a></li>
<li><a id="toc-lou_005ftranslate-2" href="#lou_005ftranslate">7.7 lou_translate</a></li>
<li><a id="toc-lou_005fbackTranslateString-1" href="#lou_005fbackTranslateString">7.8 lou_backTranslateString</a></li>
<li><a id="toc-lou_005fbackTranslate-1" href="#lou_005fbackTranslate">7.9 lou_backTranslate</a></li>
<li><a id="toc-lou_005fhyphenate-1" href="#lou_005fhyphenate">7.10 lou_hyphenate</a></li>
<li><a id="toc-lou_005fcompileString-1" href="#lou_005fcompileString">7.11 lou_compileString</a></li>
<li><a id="toc-lou_005fgetTypeformForEmphClass-1" href="#lou_005fgetTypeformForEmphClass">7.12 lou_getTypeformForEmphClass</a></li>
<li><a id="toc-lou_005fdotsToChar-1" href="#lou_005fdotsToChar">7.13 lou_dotsToChar</a></li>
<li><a id="toc-lou_005fcharToDots-1" href="#lou_005fcharToDots">7.14 lou_charToDots</a></li>
<li><a id="toc-lou_005fregisterLogCallback-1" href="#lou_005fregisterLogCallback">7.15 lou_registerLogCallback</a></li>
<li><a id="toc-lou_005fsetLogLevel-1" href="#lou_005fsetLogLevel">7.16 lou_setLogLevel</a></li>
<li><a id="toc-lou_005flogFile-_0028deprecated_0029" href="#lou_005flogFile">7.17 lou_logFile (deprecated)</a></li>
<li><a id="toc-lou_005flogPrint-_0028deprecated_0029" href="#lou_005flogPrint">7.18 lou_logPrint (deprecated)</a></li>
<li><a id="toc-lou_005flogEnd-_0028deprecated_0029" href="#lou_005flogEnd">7.19 lou_logEnd (deprecated)</a></li>
<li><a id="toc-lou_005fsetDataPath-1" href="#lou_005fsetDataPath">7.20 lou_setDataPath</a></li>
<li><a id="toc-lou_005fgetDataPath-1" href="#lou_005fgetDataPath">7.21 lou_getDataPath</a></li>
<li><a id="toc-lou_005fgetTable-1" href="#lou_005fgetTable">7.22 lou_getTable</a></li>
<li><a id="toc-lou_005ffindTable-1" href="#lou_005ffindTable">7.23 lou_findTable</a></li>
<li><a id="toc-lou_005findexTables-1" href="#lou_005findexTables">7.24 lou_indexTables</a></li>
<li><a id="toc-lou_005fcheckTable-1" href="#lou_005fcheckTable">7.25 lou_checkTable</a></li>
<li><a id="toc-lou_005freadCharFromFile-1" href="#lou_005freadCharFromFile">7.26 lou_readCharFromFile</a></li>
<li><a id="toc-lou_005ffree-1" href="#lou_005ffree">7.27 lou_free</a></li>
<li><a id="toc-lou_005fcharSize-1" href="#lou_005fcharSize">7.28 lou_charSize</a></li>
<li><a id="toc-Python-bindings-1" href="#Python-bindings">7.29 Python bindings</a></li>
</ul></li>
<li><a id="toc-Concept-Index-1" href="#Concept-Index" rel="index">Concept Index</a></li>
<li><a id="toc-Opcode-Index-1" href="#Opcode-Index" rel="index">Opcode Index</a></li>
<li><a id="toc-Function-Index-1" href="#Function-Index" rel="index">Function Index</a></li>
<li><a id="toc-Program-Index-1" href="#Program-Index" rel="index">Program Index</a></li>
</ul>
</div>
</div>
<hr>
<div class="chapter-level-extent" id="Introduction">
<h2 class="chapter" id="Introduction-1"><span>1 Introduction<a class="copiable-link" href="#Introduction-1"> ¶</a></span></h2>
<p>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,
<a class="email" href="mailto:[email protected]">[email protected]</a>
</p>
<p>This documentation is derived from the BRLTTY manual, but
it has been extensively rewritten to cover new features.
</p>
<div class="section-level-extent" id="Who-is-this-manual-for">
<h3 class="section"><span>1.1 Who is this manual for<a class="copiable-link" href="#Who-is-this-manual-for"> ¶</a></span></h3>
<p>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.
</p>
</div>
<div class="section-level-extent" id="How-to-read-this-manual">
<h3 class="section"><span>1.2 How to read this manual<a class="copiable-link" href="#How-to-read-this-manual"> ¶</a></span></h3>
<p>If you are mostly interested in writing braille translation tables
then you want to focus on <a class="ref" href="#How-to-Write-Translation-Tables">How to Write Translation Tables</a>. You
might want to look at <a class="ref" href="#Notes-on-Back_002dTranslation">Notes on Back-Translation</a> if you are
interested in back-translation. Read <a class="ref" href="#Table-Metadata">Table Metadata</a> if you want
to find out how you can augment your tables with metadata in order to
make them discoverable by programs. Finally <a class="ref" href="#Testing-Translation-Tables-interactively">Testing Translation Tables interactively</a> and <a class="ref" href="#Automated-Testing-of-Translation-Tables">Automated Testing of Translation Tables</a> will show how your braille translation tables can be tested
interactively and also in an automated fashion.
</p>
<p>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 <a class="ref" href="#Programming-with-liblouis">Programming with liblouis</a>.
</p>
<hr>
</div>
</div>
<div class="chapter-level-extent" id="How-to-Write-Translation-Tables">
<h2 class="chapter" id="How-to-Write-Translation-Tables-1"><span>2 How to Write Translation Tables<a class="copiable-link" href="#How-to-Write-Translation-Tables-1"> ¶</a></span></h2>
<p>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.
</p>
<p>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.
</p>
<p>Following this, you’ll write various translation rules and lastly you
write special rules to handle certain situations.
</p>
<a class="index-entry-id" id="index-Opcode"></a>
<p>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.
</p>
<p>For example, suppose you want to read the word ‘<samp class="samp">world</samp>’ using
braille dots ‘<samp class="samp">456</samp>’, followed by the letter ‘<samp class="samp">W</samp>’ all the time.
Then you’d write:
</p>
<div class="example">
<pre class="example-preformatted">always world 456-2456
</pre></div>
<p>The word <code class="code">always</code> is an opcode which tells liblouis to always
honor this translation, that is to say when the word ‘<samp class="samp">world</samp>’ (an
operand) is encountered, always show braille dots ‘<samp class="samp">456</samp>’ followed
by the letter ‘<samp class="samp">w</samp>’ (‘<samp class="samp">2456</samp>’).
</p>
<p>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.
</p>
<hr>
<div class="section-level-extent" id="Overview">
<h3 class="section" id="Overview-1"><span>2.1 Overview<a class="copiable-link" href="#Overview-1"> ¶</a></span></h3>
<p>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:
</p>
<dl class="table">
<dt><samp class="file">chardefs.cti</samp></dt>
<dd><p>Character definitions for U.S. tables
</p></dd>
<dt><samp class="file">compress.ctb</samp></dt>
<dd><p>Remove excessive whitespace
</p></dd>
<dt><samp class="file">en-us-g1.ctb</samp></dt>
<dd><p>Uncontracted American English
</p></dd>
<dt><samp class="file">en-us-g2.ctb</samp></dt>
<dd><p>Contracted or Grade 2 American English
</p></dd>
<dt><samp class="file">en-us-brf.dis</samp></dt>
<dd><p>Make liblouis output conform to BRF standard
</p></dd>
<dt><samp class="file">en-us-comp8.ctb</samp></dt>
<dd><p>8-dot computer braille for use in coding examples
</p></dd>
<dt><samp class="file">en-us-comp6.ctb</samp></dt>
<dd><p>6-dot computer braille
</p>
</dd>
</dl>
<p>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 (‘<samp class="samp">#</samp>’) 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 (‘<samp class="samp"><</samp>’) 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:
</p>
<div class="example">
<pre class="example-preformatted">opcode operands comments
</pre></div>
<p>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 <a class="pxref" href="#Opcode-Index">Opcode Index</a>. 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 (‘<samp class="samp">#</samp>’) begins a comment unless it is preceded by a
backslash (‘<samp class="samp">\</samp>’).
</p>
<p>Here are some examples of table entries.
</p>
<div class="example">
<pre class="example-preformatted"># This is a comment.
always world 456-2456 A word and the dot pattern of its contraction
</pre></div>
<p>Most opcodes have both a "characters" operand and a "dots" operand,
though some have only one and a few have other types.
</p>
<a class="index-entry-id" id="index-Characters-operand"></a>
<p>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 (‘<samp class="samp">\</samp>’). They are:
</p>
<dl class="table">
<dt><kbd class="kbd">\</kbd></dt>
<dd><p>backslash
</p></dd>
<dt><kbd class="kbd">\f</kbd></dt>
<dd><p>form feed
</p></dd>
<dt><kbd class="kbd">\n</kbd></dt>
<dd><p>new line
</p></dd>
<dt><kbd class="kbd">\r</kbd></dt>
<dd><p>carriage return
</p></dd>
<dt><kbd class="kbd">\s</kbd></dt>
<dd><p>blank (space)
</p></dd>
<dt><kbd class="kbd">\t</kbd></dt>
<dd><p>horizontal tab
</p></dd>
<dt><kbd class="kbd">\v</kbd></dt>
<dd><p>vertical tab
</p></dd>
<dt><kbd class="kbd">\e</kbd></dt>
<dd><p>"escape" character (hex 1b, dec 27)
</p></dd>
<dt><kbd class="kbd">\xhhhh</kbd></dt>
<dd><p>4-digit hexadecimal value of a character
</p>
</dd>
</dl>
<p>If liblouis has been compiled for 32-bit Unicode the following are
also recognized.
</p>
<dl class="table">
<dt><kbd class="kbd">\yhhhhh</kbd></dt>
<dd><p>5-digit (20 bit) character
</p></dd>
<dt><kbd class="kbd">\zhhhhhhhh</kbd></dt>
<dd><p>Full 32-bit value.
</p>
<p>Please take a look at the
<a class="url" href="https://unicode.org/Public/UNIDATA/">public directory of the
Unicode Character Database</a> as well as at the
<a class="url" href="https://unicode.org/Public/UNIDATA/NamesList.txt">Unicode names
list with their code points</a> to figure out the corresponding Unicode
code point for a given Unicode character.
</p>
</dd>
</dl>
<a class="index-entry-id" id="index-Dots-operand"></a>
<p>The dots operand is a braille dot pattern. The real braille dots, 1
through 8, must be specified with their standard numbers.
</p>
<a class="index-entry-id" id="index-Virtual-dots"></a>
<a class="anchor" id="virtual-dots"></a><p>liblouis recognizes <em class="emph">virtual dots</em>, 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 ‘<samp class="samp">a</samp>’
through ‘<samp class="samp">f</samp>’.
</p>
<a class="index-entry-id" id="index-Multi_002dcell-dot-pattern"></a>
<p>For a multi-cell dot pattern, the cell specifications must be
separated from one another by a dash (‘<samp class="samp">-</samp>’). For example, the
contraction for the English word ‘<samp class="samp">lord</samp>’ (the letter ‘<samp class="samp">l</samp>’
preceded by dot 5) would be specified as ‘<samp class="samp">5-123</samp>’. A space may be
specified with the special dot number 0.
</p>
<p>An opcode which is helpful in writing translation tables is
<code class="code">include</code>. Its format is:
</p>
<div class="example">
<pre class="example-preformatted">include filename
</pre></div>
<p>It reads the file indicated by <code class="code">filename</code> 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 <code class="code">include en-us-g1.ctb</code> in the table
<samp class="file">en-us-g2.ctb</samp>. 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.
</p>
<p>The order of the various types of opcodes or table entries is
important. Character-definition opcodes should come first. However, if
the optional <code class="code">display</code> opcode (see <a class="pxref" href="#display-opcode"><code class="code">display</code></a>) is used it should precede
character-definition opcodes. Braille-indicator opcodes should come
next. Translation opcodes should follow. The <code class="code">context</code> opcode (see <a class="pxref" href="#context-opcode"><code class="code">context</code></a>) is a
translation opcode, even though it is considered along with the
multipass opcodes. These latter should follow the translation opcodes.
The <code class="code">correct</code> opcode (see <a class="pxref" href="#correct-opcode"><code class="code">correct</code></a>) can be used anywhere after the
character-definition opcodes, but it is probably a good idea to group
all <code class="code">correct</code> opcodes together. The <code class="code">include</code> opcode (see <a class="pxref" href="#include-opcode"><code class="code">include</code></a>) 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
<code class="code">include</code> opcode or as part of a table list. They should come after
everything else.
</p>
<hr>
</div>
<div class="section-level-extent" id="Hyphenation-Tables">
<h3 class="section" id="Hyphenation-Tables-1"><span>2.2 Hyphenation Tables<a class="copiable-link" href="#Hyphenation-Tables-1"> ¶</a></span></h3>
<p>Hyphenation tables are necessary to make opcodes such as the
<code class="code">nocross</code> opcode (see <a class="pxref" href="#nocross-opcode"><code class="code">nocross</code></a>) 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 <code class="code">include</code> opcode (see <a class="pxref" href="#include-opcode"><code class="code">include</code></a>) 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 <samp class="file">hyph_en_US.dic</samp>.
</p>
<hr>
</div>
<div class="section-level-extent" id="Character_002dDefinition-Opcodes">
<h3 class="section" id="Character_002dDefinition-Opcodes-1"><span>2.3 Character-Definition Opcodes<a class="copiable-link" href="#Character_002dDefinition-Opcodes-1"> ¶</a></span></h3>
<p>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 <code class="code">context</code> opcode (see <a class="pxref" href="#context-opcode"><code class="code">context</code></a>), the
<code class="code">correct</code> opcode (see <a class="pxref" href="#correct-opcode"><code class="code">correct</code></a>), 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 <code class="code">display</code> opcode (see <a class="pxref" href="#display-opcode"><code class="code">display</code></a>) 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.
</p>
<p>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.
</p>
<p>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 ‘<samp class="samp">*</samp>’ (star) as both
<code class="code">math</code> opcode (see <a class="pxref" href="#math-opcode"><code class="code">math</code></a>) and <code class="code">sign</code> opcode (see <a class="pxref" href="#sign-opcode"><code class="code">sign</code></a>).
</p>
<div class="example">
<pre class="example-preformatted">math * 16
sign * 16
</pre></div>
<p>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.
</p>
<p>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,
‘<samp class="samp">€</samp>’. 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, both e acute (‘<samp class="samp">é</samp>’) and e
grave (‘<samp class="samp">è</samp>’) are defined as dot 4 followed by dots 1 and 5.
</p>
<div class="example">
<pre class="example-preformatted">lowercase \x00e9 4-15 # E acute
lowercase \x00e8 4-15 # E grave
</pre></div>
<p>In this example, the dot pattern would always back-translate to e
acute, since this is the first definition. You could use the
<code class="code">correct</code> opcode (see <a class="pxref" href="#correct-opcode"><code class="code">correct</code></a>) 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.
</p>
<dl class="table">
<dd><a class="index-entry-id" id="index-space"></a>
<a class="anchor" id="space-opcode"></a></dd>
<dt><code class="code">space character dots</code></dt>
<dd><p>Defines a character as a space and also defines the dot pattern as
such. for example:
</p>
<div class="example">
<pre class="example-preformatted">space \s 0 \s is the escape sequence for blank; 0 means no dots.
</pre></div>
<a class="index-entry-id" id="index-punctuation"></a>
<a class="anchor" id="punctuation-opcode"></a></dd>
<dt><code class="code">punctuation character dots</code></dt>
<dd><p>Associates a punctuation mark in the particular language with a
braille representation and defines the character and dot pattern as
punctuation. For example:
</p>
<div class="example">
<pre class="example-preformatted">punctuation . 46 dot pattern for period in NAB computer braille
</pre></div>
<a class="index-entry-id" id="index-digit"></a>
<a class="anchor" id="digit-opcode"></a></dd>
<dt><code class="code">digit character dots</code></dt>
<dd><p>Associates a digit with a dot pattern and defines the character as a
digit. For example:
</p>
<div class="example">
<pre class="example-preformatted">digit 0 356 NAB computer braille
</pre></div>
<a class="index-entry-id" id="index-letter"></a>
<a class="anchor" id="letter-opcode"></a></dd>
<dt><code class="code">letter character dots</code></dt>
<dd><p>Associates 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.
</p>
<a class="index-entry-id" id="index-lowercase"></a>
<a class="anchor" id="lowercase-opcode"></a></dd>
<dt><code class="code">lowercase character dots</code></dt>
<dd><p>Associates 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.
</p>
<a class="index-entry-id" id="index-uppercase"></a>
<a class="anchor" id="uppercase-opcode"></a></dd>
<dt><code class="code">uppercase character dots</code></dt>
<dd><p>Associates 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.
</p>
<a class="index-entry-id" id="index-litdigit"></a>
<a class="anchor" id="litdigit-opcode"></a></dd>
<dt><code class="code">litdigit digit dots</code></dt>
<dd><p>Associates a digit with the dot pattern which should be used to
represent it in literary texts. For example:
</p>
<div class="example">
<pre class="example-preformatted">litdigit 0 245
litdigit 1 1
</pre></div>
<a class="index-entry-id" id="index-sign"></a>
<a class="anchor" id="sign-opcode"></a></dd>
<dt><code class="code">sign character dots</code></dt>
<dd><p>Associates a character with a dot pattern and defines both as a sign.
This opcode should be used for things like at sign (‘<samp class="samp">@</samp>’),
percent (‘<samp class="samp">%</samp>’), dollar sign (‘<samp class="samp">$</samp>’), etc. Do not use it to
define ordinary punctuation such as period and comma. For example:
</p>
<div class="example">
<pre class="example-preformatted">sign % 4-25-1234 literary percent sign
</pre></div>
<a class="index-entry-id" id="index-math"></a>
<a class="anchor" id="math-opcode"></a></dd>
<dt><code class="code">math character dots</code></dt>
<dd><p>Associates a character and a dot pattern and defines them as a
mathematical symbol. It should be used for less than (‘<samp class="samp"><</samp>’),
greater than(‘<samp class="samp">></samp>’), equals(‘<samp class="samp">=</samp>’), plus(‘<samp class="samp">+</samp>’), etc. For
example:
</p>
<div class="example">
<pre class="example-preformatted">math + 346 plus
</pre></div>
<a class="index-entry-id" id="index-grouping"></a>
<a class="anchor" id="grouping-opcode"></a></dd>
<dt><code class="code">grouping name characters dots ,dots</code></dt>
<dd><p>This opcode is different from the previous ones in that it defines two
characters in one rule, and associates them with each other. The
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.
</p>
<div class="example">
<pre class="example-preformatted">grouping mrow \x0001\x0002 1e,2e
grouping mfrac \x0003\x0004 3e,4e
</pre></div>
<a class="index-entry-id" id="index-base"></a>
<a class="anchor" id="base-opcode"></a></dd>
<dt><code class="code">base attribute <derived character> <base character></code></dt>
<dd>
<p>This opcode is different in that it does not associate a character
with a dot pattern, but it associates a character with another already
defined character. The derived character inherits the dot pattern of
the base character, and braille indicators (see <a class="pxref" href="#Braille-Indicator-Opcodes">Braille Indicator Opcodes</a>) are used to distinguish them. The attribute operand refers
to the character class (see <a class="pxref" href="#Character_002dClass-Opcodes">Character-Class Opcodes</a>) to which the
character should be added. By defining braille indicator rules associated
with this character class, you can determine the braille indicators to
be inserted. The character operands are the derived character and the
base character, respectively. A typical use of this opcode is for
defining a pair of letters, a lowercase and the corresponding
uppercase. For example:
</p>
<div class="example">
<pre class="example-preformatted">lowercase a 1
base uppercase A a
</pre></div>
</dd>
</dl>
<hr>
</div>
<div class="section-level-extent" id="Braille-Indicator-Opcodes">
<h3 class="section" id="Braille-Indicator-Opcodes-1"><span>2.4 Braille Indicator Opcodes<a class="copiable-link" href="#Braille-Indicator-Opcodes-1"> ¶</a></span></h3>
<p>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.
</p>
<dl class="table">
<dd><a class="index-entry-id" id="index-modeletter"></a>
<a class="anchor" id="modeletter-opcode"></a></dd>
<dt><a id="index-capsletter"></a><span><code class="code">modeletter attribute dots</code><a class="copiable-link" href="#index-capsletter"> ¶</a></span></dt>
<dd><a class="anchor" id="capsletter-opcode"></a></dd>
<dt><code class="code">capsletter dots</code></dt>
<dd><p>The dot pattern which indicates that a certain mode is entered and
ends after a single character. A “mode” is a state in which dot
patterns must be interpreted a certain way. For example, in uppercase
mode dots ‘<samp class="samp">1</samp>’ is to be interpreted as a capital “A” and not a
small “a”. In numeric mode dots ‘<samp class="samp">1</samp>’ is to be interpreted as a
“1”. The attribute operand identifies the mode and corresponds with
the name of the character class that determines when the mode must be
entered and exited.
</p>
<p><code class="code">modeletter</code> is also used to mark every character when a mode
must last for several characters but when there is no <code class="code">begmode</code>
definition, or when the sequence happens in the middle of a word and
<code class="code">begmodeword</code> is defined but no <code class="code">endmodeword</code>
(see <a class="pxref" href="#begmode-opcode"><code class="code">begmode</code></a>, <a class="ref" href="#begmodeword-opcode"><code class="code">begmodeword</code></a> and <a class="ref" href="#endmodeword-opcode"><code class="code">endmodeword</code></a>)
</p>
<p><code class="code">capsletter</code> is an alias for <code class="code">modeletter uppercase</code>. The
following two examples are equivalent:
</p>
<div class="example">
<pre class="example-preformatted">capsletter 6
</pre></div>
<div class="example">
<pre class="example-preformatted">modeletter uppercase 6
</pre></div>
<p><code class="code">emphletter</code> (see <a class="pxref" href="#emphletter-opcode"><code class="code">emphletter</code></a>) is the counterpart of
<code class="code">modeletter</code> for indication of emphasis.
</p>
<a class="index-entry-id" id="index-begmodeword"></a>
<a class="anchor" id="begmodeword-opcode"></a></dd>
<dt><a id="index-begcapsword"></a><span><code class="code">begmodeword attribute dots</code><a class="copiable-link" href="#index-begcapsword"> ¶</a></span></dt>
<dd><a class="anchor" id="begcapsword-opcode"></a></dd>
<dt><code class="code">begcapsword dots</code></dt>
<dd><p>The dot pattern which indicates that a certain mode is entered for the
following word or remainder of the current word. The mode is
automatically terminated by the first character that is not a letter.
</p>
<p>For uppercase mode, you can define a list of characters that can
appear within a word in capitals without terminating the block. Do
this by using the <code class="code">capsmodechars</code> opcode (see <a class="pxref" href="#capsmodechars-opcode"><code class="code">capsmodechars</code></a>).
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">begcapsword 6-6
</pre></div>
<p><code class="code">begemphword</code> (see <a class="pxref" href="#begemphword-opcode"><code class="code">begemphword</code></a>) is the counterpart of
<code class="code">begmodeword</code> for indication of emphasis.
</p>
<a class="index-entry-id" id="index-endmodeword"></a>
<a class="anchor" id="endmodeword-opcode"></a></dd>
<dt><a id="index-endcapsword"></a><span><code class="code">endmodeword attribute dots</code><a class="copiable-link" href="#index-endcapsword"> ¶</a></span></dt>
<dd><a class="anchor" id="endcapsword-opcode"></a></dd>
<dt><code class="code">endcapsword dots</code></dt>
<dd><p>The dot pattern which terminates a mode 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.
</p>
<p>For example:
</p>
<div class="example">
<pre class="example-preformatted">endcapsword 6-3
</pre></div>
<p><code class="code">endemphword</code> (see <a class="pxref" href="#endemphword-opcode"><code class="code">endemphword</code></a>) is the counterpart of
<code class="code">endmodeword</code> for indication of emphasis.
</p>
<a class="index-entry-id" id="index-capsmodechars"></a>
<a class="anchor" id="capsmodechars-opcode"></a></dd>
<dt><code class="code">capsmodechars characters</code></dt>
<dd><p>Normally, any character other than a letter will automatically cancel the
<code class="code">begcapsword</code> indicator. However, by using the
<code class="code">capsmodechars</code> 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, ‘<samp class="samp">-</samp>’.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">capsmodechars -
</pre></div>
<a class="index-entry-id" id="index-begmode"></a>
<a class="anchor" id="begmode-opcode"></a></dd>
<dt><a id="index-begcaps"></a><span><code class="code">begmode attribute dots</code><a class="copiable-link" href="#index-begcaps"> ¶</a></span></dt>
<dd><a class="anchor" id="begcaps-opcode"></a></dd>
<dt><code class="code">begcaps dots</code></dt>
<dd><p>The dot pattern which indicates that a mode is entered until it is
terminated by a <code class="code">endmode</code> indicator. It is used in some Braille
codes to mark a whole sentence or several words as capital
letters. The block can contain capital letters as well as
non-alphabetic characters, punctuation, numbers etc.
</p>
<p>This is the most general opening mark, i.e. it can be used for opening
at any position.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">begcaps 6-6-6
</pre></div>
<p><code class="code">begemph</code> (see <a class="pxref" href="#begemph-opcode"><code class="code">begemph</code></a>) is the counterpart of
<code class="code">begmode</code> for indication of emphasis.
</p>
<a class="index-entry-id" id="index-endmode"></a>
<a class="anchor" id="endmode-opcode"></a></dd>
<dt><a id="index-endcaps"></a><span><code class="code">endmode attribute dots</code><a class="copiable-link" href="#index-endcaps"> ¶</a></span></dt>
<dd><a class="anchor" id="endcaps-opcode"></a></dd>
<dt><code class="code">endcaps dots</code></dt>
<dd><p>The dot pattern which terminates a mode.
</p>
<div class="example">
<pre class="example-preformatted">endcaps 6-3
</pre></div>
<p><code class="code">endemph</code> (see <a class="pxref" href="#endemph-opcode"><code class="code">endemph</code></a>) is the counterpart of
<code class="code">endmode</code> for indication of emphasis.
</p>
<a class="index-entry-id" id="index-letsign"></a>
<a class="anchor" id="letsign-opcode"></a></dd>
<dt><code class="code">letsign dots</code></dt>
<dd><p>This 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:
</p>
<div class="example">
<pre class="example-preformatted">letsign 56
</pre></div>
<a class="index-entry-id" id="index-noletsign"></a>
<a class="anchor" id="noletsign-opcode"></a></dd>
<dt><code class="code">noletsign letters</code></dt>
<dd>
<p>The letters in the operand will not be proceeded by a letter sign.
More than one <code class="code">noletsign</code> opcode can be used. This is equivalent
to a single entry containing all the letters. In addition, if a single
letter, such as ‘<samp class="samp">a</samp>’ in English, is defined as a <code class="code">word</code>
(see <a class="pxref" href="#word-opcode"><code class="code">word</code></a>) or <code class="code">largesign</code> (see <a class="pxref" href="#largesign-opcode"><code class="code">largesign</code></a>), it will be
treated as though it had also been specified in a <code class="code">noletsign</code>
entry.
</p>
<a class="index-entry-id" id="index-noletsignbefore"></a>
<a class="anchor" id="noletsignbefore-opcode"></a></dd>
<dt><code class="code">noletsignbefore characters</code></dt>
<dd><p>If any of the characters proceeds a single letter without a space a
letter sign is not used. By default the characters apostrophe
(‘<samp class="samp">'</samp>’) and period (‘<samp class="samp">.</samp>’) have this property. Use of a
<code class="code">noletsignbefore</code> entry cancels the defaults. If more than one
<code class="code">noletsignbefore</code> entry is used, the characters in all entries
are combined.
</p>
<a class="index-entry-id" id="index-noletsignafter"></a>
<a class="anchor" id="noletsignafter-opcode"></a></dd>
<dt><code class="code">noletsignafter characters</code></dt>
<dd><p>If any of the characters follows a single letter without a space a
letter sign is not used. By default the characters apostrophe
(‘<samp class="samp">'</samp>’) and period (‘<samp class="samp">.</samp>’) have this property. Use of a
<code class="code">noletsignafter</code> entry cancels the defaults. If more than one
<code class="code">noletsignafter</code> entry is used the characters in all entries are
combined.
</p>
<a class="index-entry-id" id="index-nocontractsign"></a>
<a class="anchor" id="nocontractsign-opcode"></a></dd>
<dt><code class="code">nocontractsign dots</code></dt>
<dd>
<p>The dots in this opcode are used to indicate a letter or a sequence of
letters that are not a contraction, e.g. ‘<samp class="samp">CD</samp>’
(see <a class="pxref" href="#contraction-opcode"><code class="code">contraction</code></a>). The opcode is similar to the
<code class="code">letsign</code> opcode (see <a class="pxref" href="#letsign-opcode"><code class="code">letsign</code></a>).
</p>
<p><strong class="strong">Note:</strong> 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.
</p>
<a class="index-entry-id" id="index-numsign"></a>
<a class="anchor" id="numsign-opcode"></a></dd>
<dt><code class="code">numsign dots</code></dt>
<dd><p>The translator inserts this indicator before numbers made up of digits
defined with the <code class="code">litdigit</code> opcode (see <a class="pxref" href="#litdigit-opcode"><code class="code">litdigit</code></a>) 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-<code class="code">litdigit</code> opcode (see <a class="pxref" href="#litdigit-opcode"><code class="code">litdigit</code></a>) character is
encountered.
</p>
<p>You can define characters or strings to be part of a number by using
the <code class="code">midnum</code> opcode (see <a class="pxref" href="#midnum-opcode"><code class="code">midnum</code></a>), the <code class="code">numericmodechars</code> opcode (see <a class="pxref" href="#numericmodechars-opcode"><code class="code">numericmodechars</code></a>) or the
<code class="code">midendnumericmodechars</code> opcode (see <a class="pxref" href="#midendnumericmodechars-opcode"><code class="code">midendnumericmodechars</code></a>).
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">numsign 3456
</pre></div>
<a class="index-entry-id" id="index-nonumsign"></a>
<a class="anchor" id="nonumsign-opcode"></a></dd>
<dt><code class="code">nonumsign dots</code></dt>
<dd><p>Usually the end of a number doesn’t need to be indicated as the reader
expects the the number to end at a space character. However for mixed
number word combinations you might want to have an indicator that lets
the reader notice the end of the number.
</p>
<p>For a word like “123abc” for example the reader expects an indicator
between the number “123” and the characters “abc”. This can be
achieved using the <code class="code">nonumsign</code>.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">numsign 56
</pre></div>
<a class="index-entry-id" id="index-numericnocontchars"></a>
<a class="anchor" id="numericnocontchars-opcode"></a></dd>
<dt><code class="code">numericnocontchars characters</code></dt>
<dd>
<p>This opcode specifies the characters that require a
<code class="code">nonumsign</code> opcode (see <a class="pxref" href="#nonumsign-opcode"><code class="code">nonumsign</code></a>) if they appear after a number with no
intervening space, e.g. ‘<samp class="samp">1a</samp>’ or ‘<samp class="samp">2-B</samp>’.
</p>
<p>These characters will typically be the letters a-j, which usually
constitute the literary digits (see <code class="code">litdigit</code> opcode (see <a class="pxref" href="#litdigit-opcode"><code class="code">litdigit</code></a>)). However,
in some Braille codes, all letters fall in this category.
</p>
<p><strong class="strong">Note:</strong> This opcode is case sensitive. So, if you need a
<code class="code">nonumsign</code> opcode (see <a class="pxref" href="#nonumsign-opcode"><code class="code">nonumsign</code></a>) 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 <code class="code">begcaps</code> and
<code class="code">endcaps</code> opcodes (see <a class="pxref" href="#begcaps-opcode"><code class="code">begcaps</code></a> and <a class="ref" href="#endcaps-opcode"><code class="code">endcaps</code></a>). In
this case, you might otherwise end up having numbers immediately
followed by capital letters with no indicator between.
</p>
<p><strong class="strong">Note:</strong> 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.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">numericnocontchars abcdefghij
</pre></div>
<a class="index-entry-id" id="index-numericmodechars"></a>
<a class="anchor" id="numericmodechars-opcode"></a></dd>
<dt><code class="code">numericmodechars characters</code></dt>
<dd>
<a class="index-entry-id" id="index-midendnumericmodechars"></a>
<a class="anchor" id="midendnumericmodechars-opcode"></a></dd>
<dt><code class="code">midendnumericmodechars characters</code></dt>
<dd>
<p>Any of these characters can appear within a number without terminating
the effect of the number sign (see <a class="pxref" href="#numsign-opcode"><code class="code">numsign</code></a>). In other words,
they don’t cancel numeric mode.
</p>
<p>The difference between the two opcodes is that
<code class="code">numericmodechars</code> opcode (see <a class="pxref" href="#numericmodechars-opcode"><code class="code">numericmodechars</code></a>) characters can appear anywhere in a
number whereas <code class="code">midendnumericmodechars</code> opcode (see <a class="pxref" href="#midendnumericmodechars-opcode"><code class="code">midendnumericmodechars</code></a>) characters can
appear only in the middle or at the end of a number. Like
<code class="code">midendnumericmodechars</code>, <code class="code">numericmodechars</code> 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 <code class="code">numericmodechars</code> character in this case.
</p>
<p><strong class="strong">Note:</strong> 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.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">numericmodechars .,
midendnumericmodechars -/
</pre></div>
</dd>
</dl>
<hr>
</div>
<div class="section-level-extent" id="Opcodes-for-Standing-Alone-Sequences">
<h3 class="section" id="Opcodes-for-Standing-Alone-Sequences-1"><span>2.5 Opcodes for <em class="emph">Standing Alone</em> Sequences<a class="copiable-link" href="#Opcodes-for-Standing-Alone-Sequences-1"> ¶</a></span></h3>
<a class="index-entry-id" id="index-Standing-alone"></a>
<p>The term “standing alone” comes from the specification of Unified
English Braille (UEB). In Liblouis, a letter or letters-sequence is
considered to be <em class="emph">standing alone</em> if it is preceded and followed
by a space, and/or other characters that you choose as delimiters,
e.g. ‘<samp class="samp">-</samp>’. A <em class="emph">standing alone</em> sequence can be thought of as a
word in a very broad sense. 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
<em class="emph">standing alone</em> sequence.
</p>
<p><strong class="strong">Note:</strong> 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.
</p>
<dl class="table">
<dd><a class="index-entry-id" id="index-seqdelimiter"></a>
<a class="anchor" id="seqdelimiter-opcode"></a></dd>
<dt><code class="code">seqdelimiter <characters></code></dt>
<dd><p>All the characters listed with this opcode designate a valid beginning
and ending to a letter sequence used to determine when a letter
sequence is <em class="emph">standing alone</em>. This again determines whether word
contractions (see <a class="pxref" href="#word-opcode"><code class="code">word</code></a>) or nocontractsign
(see <a class="pxref" href="#nocontractsign-opcode"><code class="code">nocontractsign</code></a>) should be applied.
</p>
<p>Spaces do not need to be listed as
they are automatically delimiters.
</p>
<p>For example, in UEB (section 2.6.1 page 15), any hyphen or dash count
as delimiters.
</p>
<p>This opcode can be used several times, but the characters must have
already been defined.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example-preformatted">seqdelimiter -—
</pre></div>
<a class="index-entry-id" id="index-seqbeforechars"></a>
<a class="anchor" id="seqbeforechars-opcode"></a></dd>
<dt><code class="code">seqbeforechars <characters></code></dt>
<dd><p>Characters specified with this opcode may appear between a beginning
sequence delimiter and the letter sequence itself.
</p>
<p>For example, in UEB (2.6.2, page 15), opening parenthesis and opening
quotations and such are allowed.
</p>
<p>This opcode can be used several times, but the characters must have
already been defined.
</p>
<p>Example:
</p><div class="example">
<pre class="example-preformatted">seqbeforechars ([{"“'‘
</pre></div>
<a class="index-entry-id" id="index-seqafterchars"></a>
<a class="anchor" id="seqafterchars-opcode"></a></dd>
<dt><code class="code">seqafterchars <chars></code></dt>
<dd><p>Characters specified with this opcode may appear between a letter
sequence itself and a end sequence delimiter.
</p>
<p>For example, in UEB (2.6.3, page 16), closing parenthesis and closing
quotations and such are allowed.
</p>
<p>This opcode can be used several times, but the characters must have
already been defined.
</p>
<p>Example:
</p><div class="example">
<pre class="example-preformatted">seqafterchars )]}"”'’.,;:.!?…