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
|
<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>The m17n Library: Data format of the m17n database</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.3 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" id="m17nDBFormat">Data format of the m17n database </a></h1><p>This section describes formats of these data supplied by the m17n database.</p>
<ul>
<li>
<a class="el" href="m17nDBFormat.html#mdbGeneral">General</a> -- General Format </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbCharsetList">CharsetList</a> -- List of character set definitions </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbCodingList">CodingList</a> -- List of coding system definitions </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbDir">Dir</a> -- List of data in a database directory. </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbFLT">FLT</a> -- Font Layout Table </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbFontEncoding">FontEncoding</a> -- Font Encoding </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbFontSize">FontSize</a> -- Font Size </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbFontset">Fontset</a> -- Fontset </li>
<li>
<a class="el" href="m17nDBFormat.html#mdbIM">IM</a> -- Input Method </li>
</ul>
<h2><a class="anchor" id="mdbGeneral">
General Format</a></h2>
<h3><a class="anchor" id="general-description">
DESCRIPTION</a></h3>
<p>The <a class="el" href="group__m17nDatabase.html#ga62e5cf92d1b2836a9f6a988bcc20c26e" title="Load a data from the database.">mdatabase_load()</a> function returns the data specified by tags in the form of plist if the first tag is not <code>Mchartable</code> nor <code>Mcharset</code>. The keys of the returned plist are limited to <code>Minteger</code>, <code>Msymbol</code>, <code>Mtext</code>, and <code>Mplist</code>. The type of the value is unambiguously determined by the corresponding key. If the key is <code>Minteger</code>, the value is an integer. If the key is <code>Msymbol</code>, the value is a symbol. And so on.</p>
<p>A number of expressions are possible to represent a plist. For instance, we can use the form <code>(K1:V1, K2:V2, ..., Kn:Vn)</code> to represent a plist whose first property key and value are K1 and V1, second key and value are K2 and V2, and so on. However, we can use a simpler expression here because the types of plists used in the m17n database are fairly restricted.</p>
<p>Hereafter, we use an expression, which is similar to S-expression, to represent a plist. (Actually, the default database loader of the m17n library is designed to read data files written in this expression.)</p>
<p>The expression consists of one or more <em>elements</em>. Each element represents a property, i.e. a single element of a plist.</p>
<p>Elements are separated by one or more <em>whitespaces</em>, i.e. a space (code 32), a tab (code 9), or a newline (code 10). Comments begin with a semicolon (<code>;</code>) and extend to the end of the line.</p>
<p>The key and the value of each property are determined based on the type of the element as explained below.</p>
<ul>
<li>
<p class="startli">INTEGER</p>
<p>An element that matches the regular expression <code>-?[0-9]+</code> or <code>0[xX][0-9A-Fa-f]+</code> represents a property whose key is <code>Minteger</code>. An element matching the former expression is interpreted as an integer in decimal notation, and one matching the latter is interpreted as an integer in hexadecimal notation. The value of the property is the result of interpretation.</p>
<p>For instance, the element <code>0xA0</code> represents a property whose value is 160 in decimal.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">SYMBOL</p>
<p>An element that matches the regular expression <code>[^-0-9(]([^\()]|\.)+</code> represents a property whose key is <code> Msymbol</code>. In the element, <code>\t</code>, <code>\n</code>, <code>\r</code>, and <code>\e</code> are replaced with tab (code 9), newline (code 10), carriage return (code 13), and escape (code 27) respectively. Other characters following a backslash is interpreted as it is. The value of the property is the symbol having the resulting string as its name.</p>
<p>For instance, the element <code>abc\ def</code> represents a property whose value is the symbol having the name "abc def".</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">MTEXT</p>
<p>An element that matches the regular expression <code>"([^"]|\")*"</code> represents a property whose key is <code>Mtext</code>. The backslash escape explained above also applies here. Moreover, each part in the element matching the regular expression <code> \[xX][0-9A-Fa-f][0-9A-Fa-f]</code> is replaced with its hexadecimal interpretation.</p>
<p>After having resolved the backslash escapes, the byte sequence between the double quotes is interpreted as a UTF-8 sequence and decoded into an M-text. This M-text is the value of the property.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">PLIST</p>
<p>Zero or more elements surrounded by a pair of parentheses represent a property whose key is <code>Mplist</code>. Whitespaces before and after a parenthesis can be omitted. The value of the property is a plist, which is the result of recursive interpretation of the elements between the parentheses.</p>
<p class="endli"></p>
</li>
</ul>
<h3><a class="anchor" id="general-syntax">
SYNTAX NOTATION</a></h3>
<p>In an explanation of a plist format of data, a BNF-like notation is used. In the notation, non-terminals are represented by a string of uppercase letters (including '-' in the middle), terminals are represented by a string surrounded by '"'. Special non-terminals INTEGER, SYMBOL, MTEXT and PLIST represents property integer, symbol, M-text, or plist respectively.</p>
<h3><a class="anchor" id="general-example">
EXAMPLE</a></h3>
<p>Here is an example of database data that is read into a plist of this simple format:</p>
<div class="fragment"><pre class="fragment">
DATA-FORMAT ::=
[ INTEGER | SYMBOL | MTEXT | FUNC ] *
FUNC ::=
'(' FUNC-NAME FUNC-ARG * ')'
FUNC-NAME ::=
SYMBOL
FUNC-ARG ::=
INTEGER | SYMBOL | MTEXT | '(' FUNC-ARG ')'
</pre></div><p>For instance, a data file that contains this text matches the above syntax:</p>
<div class="fragment"><pre class="fragment">
abc 123 (pqr 0xff) "m\"text" (_\\_ ("string" xyz) -456)
</pre></div><p>and is read into this plist:</p>
<div class="fragment"><pre class="fragment">
1st element: key: Msymbol, value: abc
2nd element: key: Minteger, value: 123
3rd element: key: Mplist, value: a plist of these elements:
1st element: key Msymbol, value: pgr
2nd element: key Minteger, value: 255
4th element: key: Mtext, value: m"text
5th element: key: Mplist, value: a plist of these elements:
1st element: key: Msymbol, value: _\_
2nd element: key: Mplist, value: a plist of these elements:
1st element: key: Mtext, value: string
2nd element: key: Msymbol, value: xyz
3rd element: key: Minteger, value: -456
</pre></div><h2><a class="anchor" id="mdbCharsetList">
List of character set definitions</a></h2>
<h3><a class="anchor" id="cslist-description">
DESCRIPTION</a></h3>
<p>The m17n library loads a list of charset definitions from the data of tag <charset-list>. The data is loaded as a plist of this format.</p>
<div class="fragment"><pre class="fragment">
CHARSET-LIST ::= DEFINITION *
DEFINITION ::= '(' NAME ( KEY VALUE ) * ')'
NAME ::= SYMBOL
KEY ::= SYMBOL
VALUE ::= SYMBOL | INTEGER | MTEXT | PLIST
</pre></div><p><code>NAME</code> is a name of a charset to define.</p>
<p><code>KEY</code> and <code>VALUE</code> pair is a property given to the function <a class="el" href="group__m17nCharset.html#gaadbf43a8bb53d9056dd10a64e8424e30" title="Define a charset.">mchar_define_charset()</a> as an element of the second argument <b>plist</b>.</p>
<h3><a class="anchor" id="cslist-seealso">
SEE ALSO</a></h3>
<p><a class="el" href="m17nDBFormat.html#mdbGeneral">mdbGeneral(5)</a>, <a class="el" href="group__m17nCharset.html#gaadbf43a8bb53d9056dd10a64e8424e30" title="Define a charset.">mchar_define_charset()</a></p>
<h2><a class="anchor" id="mdbCodingList">
List of coding system definitions</a></h2>
<h3><a class="anchor" id="coding-list-description">
DESCRIPTION</a></h3>
<p>The m17n library loads a list of coding system definitions from the m17n database by the tags <coding-list> at initialization time. The data is loaded as a plist of this format.</p>
<div class="fragment"><pre class="fragment">
CODING-LIST ::= DEFINITION *
DEFINITION ::= '(' NAME ( KEY VALUE ) * ')'
NAME ::= SYMBOL
KEY ::= SYMBOL
VALUE ::= SYMBOL | INTEGER | MTEXT | PLIST
</pre></div><p><code>NAME</code> is a name of a coding system to define.</p>
<p><code>KEY</code> and <code>VALUE</code> pair is a property given to the function <a class="el" href="group__m17nConv.html#gabbd4a423903d2c1e55030f59ea86c34c" title="Define a coding system.">mconv_define_coding()</a> as the second argument.</p>
<h3><a class="anchor" id="coding-list-seealso">
SEE ALSO</a></h3>
<p><a class="el" href="m17nDBFormat.html#mdbGeneral">mdbGeneral(5)</a>, <a class="el" href="group__m17nConv.html#gabbd4a423903d2c1e55030f59ea86c34c" title="Define a coding system.">mconv_define_coding()</a></p>
<h2><a class="anchor" id="mdbDir">
List of data in a database directory.</a></h2>
<h3><a class="anchor" id="dir-description">
DESCRIPTION</a></h3>
<p>The m17n library loads a list of definitions of data of the m17n database from files of name "mdb.dir" in each database directory at initialization time. The plist format of this file is as follows:</p>
<div class="fragment"><pre class="fragment">
MDB-DIR ::= DEFINITION *
DEFINITION ::= '(' TAG0 [ TAG1 [ TAG2 [ TAG3 ] ] ] FILE [ VERSION ]')'
TAGn ::= SYMBOL
FILE ::= MTEXT
VERSION ::= MTEXT
</pre></div><p>If TAG0 is neither `charset' nor `char-table', and TAGn (n > 0) is a symbol `*', FILE can contain a wildcard charater, and all files matching FILE accoding to the rules used by the shell are the target of database files. In that case, each file must contain SELF-DEFINITION which is a plist element providing the actual TAGn values by the form:</p>
<div class="fragment"><pre class="fragment">
SELF-DEFINITION ::= '(' TAG0 TAG1 TAG2 TAG3 [ VERSION ] ')'
</pre></div><p>For instance, if a database directory contains these files:</p>
<div class="fragment"><pre class="fragment">
zh-py.mim:
(input-method zh py)
ko-han2.mim:
(input-method ko han2)
</pre></div><p>these lines in "mdb.dir":</p>
<div class="fragment"><pre class="fragment">
(input-method zh py "zh-py.mim")
(input-method ko han2 "ko-han2.mim")
</pre></div><p>can be shortened to this single line:</p>
<div class="fragment"><pre class="fragment">
(input-method * "*.mim")
</pre></div><p>VERSION is a required version number of the m17n library. The format is "XX.YY.ZZ" where XX is a major version number, YY is a minor version number, and ZZ is a patch level.</p>
<h2><a class="anchor" id="mdbFLT">
Font Layout Table</a></h2>
<h3><a class="anchor" id="flt-description">
DESCRIPTION</a></h3>
<p>For simple scripts, the rendering engine converts character codes into glyph codes one by one by consulting the encoding of each selected font. But, to render text that requires complicated layout (e.g. Thai and Indic scripts), one to one conversion is not sufficient. A sequence of characters may have to be drawn as a single ligature. Some glyphs may have to be drawn at 2-dimensionally shifted positions.</p>
<p>To handle those complicated scripts, the m17n library uses Font Layout Tables (FLTs for short). The FLT driver interprets an FLT and converts a character sequence into a glyph sequence that is ready to be passed to the rendering engine.</p>
<p>An FLT can contain information to extract a grapheme cluster from a character sequence and to reorder the characters in the cluster, in addition to information found in OpenType Layout Tables (CMAP, GSUB, and GPOS).</p>
<p>An FLT is a cascade of one or more conversion stages. In each stage, a sequence is converted into another sequence to be read in the next stage. The length of sequences may differ from stage to stage. Each element in a sequence has the following integer attributes.</p>
<ul>
<li>
<p class="startli">code</p>
<p>In the first conversion stage, this is the character code in the original character sequence. In the last stage, it is the glyph code passed to the rendering engine. In other cases, it is an intermediate glyph code.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">category</p>
<p>The category code defined in the <code>CATEGORY-TABLE</code> of the current stage, or defined in the one of the former stages and not overwritten by later stages.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">combining-spec</p>
<p>If nonzero, it specifies how to combine this (intermediate) glyph with the previous one.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">left-padding-flag</p>
<p>If nonzero, it instructs the rendering function to insert a padding space before this (intermediate) glyph so that the glyph does not overlap with the previous one.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">right-padding-flag</p>
<p>If nonzero, it instructs the rendering function to insert a padding space after this (intermediate) glyph so that the glyph does not overlap with the next one.</p>
<p class="endli"></p>
</li>
</ul>
<p>When the layout engine draws text, it at first determines a font and an FLT for each character in the text. For each subsequence of characters that use the same font and FLT, the layout engine generates a corresponding intermediate glyph sequence. The code attribute of each element in the intermediate glyph sequence is its character code, and all other attributes are zeros. This sequence is processed in the first stage of FLT as the current <em>run</em> (substring).</p>
<p>Each stage works as follows.</p>
<p>At first, if the stage has a <code>CATEGORY-TABLE</code>, the category of each glyph in the current run is updated. If there is a glyph that has no category, the current run ends before that glyph.</p>
<p>Then, the default values of code-offset, combining-spec, and left-padding-flag of this stage are initialized to zero.</p>
<p>Next, the initial conversion rule of the stage is applied to the current run.</p>
<p>Lastly, the current run is replaced with the newly produced (intermediate) glyph sequence.</p>
<h3><a class="anchor" id="flt-syntax">
SYNTAX and SEMANTICS</a></h3>
<p>The m17n library loads an FLT from the m17n database using the tag <font, layouter, FLT-NAME>. The date format of an FLT is as follows:</p>
<div class="fragment"><pre class="fragment">
FONT-LAYOUT-TABLE ::= FLT-DECLARATION ? STAGE0 STAGE *
FLT-DECLARATION ::= '(' 'font' 'layouter' FLT-NAME nil PROP * ')'
FLT-NAME ::= SYMBOL
PROP :: = VERSION | FONT
VERSION ::= '(' 'version' MTEXT ')'
FONT ::= '(' 'font' FONT-SPEC ')'
FONT-SPEC ::=
'(' [[ FOUNDRY FAMILY
[ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ]]]]]
REGISTRY ]
[ OTF-SPEC ] [ LANG-SPEC ] ')'
STAGE0 ::= CATEGORY-TABLE GENERATOR
STAGE ::= CATEGORY-TABLE ? GENERATOR
CATEGORY-TABLE ::= '(' 'category' CATEGORY-SPEC + ')'
CATEGORY-SPEC ::= '(' CODE CATEGORY ')'
| '(' CODE CODE CATEGORY ')'
CODE ::= INTEGER
CATEGORY ::= INTEGER
</pre></div><p>In the definition of <code>CATEGORY-SPEC</code>, <code>CODE</code> is a glyph code, and <code>CATEGORY</code> is ASCII code of an upper or lower letter, i.e. one of 'A', ... 'Z', 'a', .. 'z'.</p>
<p>The first form of <code>CATEGORY-SPEC</code> assigns <code>CATEGORY</code> to a glyph whose code is <code>CODE</code>. The second form assigns <code>CATEGORY</code> to glyphs whose code falls between the two <code>CODEs</code>.</p>
<div class="fragment"><pre class="fragment">
GENERATOR ::= '(' 'generator' RULE MACRO-DEF * ')'
RULE ::= REGEXP-BLOCK | MATCH-BLOCK | SUBST-BLOCK | COND-BLOCK
FONT-FACILITY-BLOCK | DIRECT-CODE | COMBINING-SPEC | OTF-SPEC
| PREDEFINED-RULE | MACRO-NAME
MACOR-DEF ::= '(' MACRO-NAME RULE + ')'
</pre></div><p>Each <code>RULE</code> specifies glyphs to be consumed and glyphs to be produced. When some glyphs are consumed, they are taken away from the current run. A rule may fail in some condition. If not described explicitly to fail, it should be regarded that the rule succeeds.</p>
<div class="fragment"><pre class="fragment">
DIRECT-CODE ::= INTEGER
</pre></div><p>This rule consumes no glyph and produces a glyph which has the following attributes:</p>
<ul>
<li>
code : <code>INTEGER</code> plus the default code-offset </li>
<li>
combining-spec : default value </li>
<li>
left-padding-flag : default value </li>
<li>
right-padding-flag : zero </li>
</ul>
<p>After having produced the glyph, the default code-offset, combining-spec, and left-padding-flag are all reset to zero.</p>
<div class="fragment"><pre class="fragment">
PREDEFINED-RULE ::= '=' | '*' | '<' | '>' | '|' | '[' | ']'
</pre></div><p>They perform actions as follows.</p>
<ul>
<li>
<p class="startli"><code>=</code> </p>
<p>This rule consumes the first glyph in the current run and produces the same glyph. It fails if the current run is empty.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>*</code> </p>
<p>This rule repeatedly executes the previous rule. If the previous rule fails, this rule does nothing and fails.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code><</code> </p>
<p>This rule specifies the start of a grapheme cluster.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>></code> </p>
<p>This rule specifies the end of a grapheme cluster.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@</code>[</p>
<p>This rule sets the default left-padding-flag to 1. No glyph is consumed. No glyph is produced.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@</code>]</p>
<p>This rule changes the right-padding-flag of the lastly generated glyph to 1. No glyph is consumed. No glyph is produced.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code></code>|</p>
<p>This rule consumes no glyph and produces a special glyph whose category is ' ' and other attributes are zero. This is the only rule that produces that special glyph.</p>
<p class="endli"></p>
</li>
</ul>
<div class="fragment"><pre class="fragment">
REGEXP-BLOCK ::= '(' REGEXP RULE * ')'
REGEXP ::= MTEXT
</pre></div><p><code>MTEXT</code> is a regular expression that should match the sequence of categories of the current run. If a match is found, this rule executes <code>RULEs</code> temporarily limiting the current run to the matched part. The matched part is consumed by this rule.</p>
<p>Parenthesized subexpressions, if any, are recorded to be used in <code>MATCH-BLOCK</code> that may appear in one of <code>RULEs</code>.</p>
<p>If no match is found, this rule fails.</p>
<div class="fragment"><pre class="fragment">
MATCH-BLOCK ::= '(' MATCH-INDEX RULE * ')'
MATCH-INDEX ::= INTEGER
</pre></div><p><code>MATCH-INDEX</code> is an integer specifying a parenthesized subexpression recorded by the previous <code>REGEXP-BLOCK</code>. If such a subexpression was found by the previous regular expression matching, this rule executes <code>RULEs</code> temporarily limiting the current run to the matched part of the subexpression. The matched part is consumed by this rule.</p>
<p>If no match was found, this rule fails.</p>
<p>If this is the first rule of the stage, <code>MATCH-INDEX</code> must be 0, and it matches the whole current run.</p>
<div class="fragment"><pre class="fragment">
SUBST-BLOCK ::= '(' SOURCE-PATTERN RULE * ')'
SOURCE-PATTERN ::= '(' CODE + ')'
| (' 'range' CODE CODE ')'
</pre></div><p>If the sequence of codes of the current run matches <code>SOURCE-PATTERN</code>, this rule executes <code>RULEs</code> temporarily limiting the current run to the matched part. The matched part is consumed.</p>
<p>The first form of <code>SOURCE-PATTERN</code> specifies a sequence of glyph codes to be matched. In this case, this rule resets the default code-offset to zero.</p>
<p>The second form specifies a range of codes that should match the first glyph code of the code sequence. In this case, this rule sets the default code-offset to the first glyph code minus the first <code>CODE</code> specifying the range.</p>
<p>If no match is found, this rule fails.</p>
<div class="fragment"><pre class="fragment">
FONT-FACILITY-BLOCK ::= '(' FONT-FACILITY RULE * ')'
FONT-FACILITY = '(' 'font-facility' CODE * ')'
| '(' 'font-facility' FONT-SPEC ')'
</pre></div><p>If the current font has glyphs for <code>CODEs</code> or matches with <code>FONT-SPEC</code>, this rule succeeds and <code>RULEs</code> are executed. Otherwise, this rule fails.</p>
<div class="fragment"><pre class="fragment">
COND-BLOCK ::= '(' 'cond' RULE + ')'
</pre></div><p>This rule sequentially executes <code>RULEs</code> until one succeeds. If no rule succeeds, this rule fails. Otherwise, it succeeds.</p>
<p><a class="anchor" id="OTF-SPEC"></a> </p>
<div class="fragment"><pre class="fragment">
OTF-SPEC ::= SYMBOL
</pre></div><p><code>OTF-SPEC</code> is a symbol whose name specifies an instruction to the OTF driver. The name has the following syntax.</p>
<div class="fragment"><pre class="fragment">
OTF-SPEC-NAME ::= ':otf=' SCRIPT LANGSYS ? GSUB-FEATURES ? GPOS-FEATURES ?
SCRIPT ::= SYMBOL
LANGSYS ::= '/' SYMBOL
GSUB-FEATURES ::= '=' FEATURE-LIST ?
GPOS-FEATURES ::= '+' FEATURE-LIST ?
FEATURE-LIST ::= ( SYMBOL ',' ) * [ SYMBOL | '*' ]
</pre></div><p>Each <code>SYMBOL</code> specifies a tag name defined in the OpenType specification.</p>
<p>For <code>SCRIPT</code>, <code>SYMBOL</code> specifies a Script tag name (e.g. deva for Devanagari).</p>
<p>For <code>LANGSYS</code>, <code>SYMBOL</code> specifies a Language System tag name. If <code>LANGSYS</code> is omitted, the Default Language System table is used.</p>
<p>For <code>GSUB-FEATURES</code>, each <code>SYMBOL</code> in <code>FEATURE-LIST</code> specifies a GSUB Feature tag name to apply. '*' is allowed as the last item to specify all remaining features. If <code>SYMBOL</code> is preceded by '~' and the last item is '*', <code>SYMBOL</code> is excluded from the features to apply. If no <code>SYMBOL</code> is specified, no GSUB feature is applied. If <code>GSUB-FEATURES</code> itself is omitted, all GSUB features are applied.</p>
<p>When <code>OTF-SPEC</code> appears in a <code>FONT-SPEC</code>, <code>FEATURE-LIST</code> specifies features that the font must have (or must not have if preceded by '~'), and the last'*', even if exists, has no meaning.</p>
<p>The specification of <code>GPOS-FEATURES</code> is analogous to that of <code>GSUB-FEATURES</code>.</p>
<p>Please note that all the tags above must be 4 ASCII printable characters.</p>
<p>See the following page for the OpenType specification.<br/>
<<a href="http://www.microsoft.com/typography/otspec/default.htm">http://www.microsoft.com/typography/otspec/default.htm</a>></p>
<div class="fragment"><pre class="fragment">
COMBINING ::= SYMBOL
</pre></div><p><code>COMBINING</code> is a symbol whose name specifies how to combine the next glyph with the previous one. This rule sets the default combining-spec to an integer code that is unique to the symbol name. The name has the following syntax.</p>
<div class="fragment"><pre class="fragment">
COMBINING-NAME ::= VPOS HPOS OFFSET VPOS HPOS
VPOS ::= 't' | 'c' | 'b' | 'B'
HPOS ::= 'l' | 'c' | 'r'
OFFSET :: = '.' | XOFF | YOFF XOFF ?
XOFF ::= ('<' | '>') INTEGER ?
YOFF ::= ('+' | '-') INTEGER ?
</pre></div><p><code>VPOS</code> and <code>HPOS</code> specify the vertical and horizontal positions as described below.</p>
<div class="fragment"><pre class="fragment">
POINT VPOS HPOS
----- ---- ----
0----1----2 <---- top 0 t l
| | 1 t c
| | 2 t r
| | 3 B l
9 10 11 <---- center 4 B c
| | 5 B r
--3----4----5-- <-- baseline 6 b l
| | 7 b c
6----7----8 <---- bottom 8 b r
9 c l
| | | 10 c c
left center right 11 c r
</pre></div><p>The left figure shows 12 reference points of a glyph by numbers 0 to 11. The rectangle 0-6-8-2 is the bounding box of the glyph, the positions 3, 4, and 5 are on the baseline, 9-11 are on the vertical center of the box, 0-2 and 6-8 are on the top and on the bottom respectively. 1, 10, 4, and 7 are on the horizontal center of the box.</p>
<p>The right table shows how those reference points are specified by a pair of <code>VPOS</code> and <code>HPOS</code>.</p>
<p>The first <code>VPOS</code> and <code>HPOS</code> in the definition of <code>COMBINING-NAME</code> specify the reference point of the previous glyph, and the second <code>VPOS</code> and <code>HPOS</code> specify that of the next glyph. The next glyph is drawn so that these two reference points align.</p>
<p><code>OFFSET</code> specifies the way of alignment in detail. If it is '.', the reference points are on the same position.</p>
<p><code>XOFF</code> specifies how much the X position of the reference point of the next glyph should be shifted to the left ('<') or right ('>') from the previous reference point.</p>
<p><code>YOFF</code> specifies how much the Y position of the reference point the next glyph should be shifted upward ('+') or downward ('-') from the previous reference point.</p>
<p>In both cases, <code>INTEGER</code> is the amount of shift expressed as a percentage of the font size, i.e., if <code>INTEGER</code> is 10, it means 10% (1/10) of the font size. If <code>INTEGER</code> is omitted, it is assumed that 5 is specified.</p>
<p>Once the next glyph is combined with the previous one, they are treated as a single combined glyph.</p>
<div class="fragment"><pre class="fragment">
MACRO-NAME ::= SYMBOL
</pre></div><p><code>MACRO-NAME</code> is a symbol that appears in one of <code>MACRO-DEF</code>. It is exapanded to the sequence of the corresponding <code>RULEs</code>.</p>
<h3><a class="anchor" id="flt-context-dependent">
CONTEXT DEPENDENT BEHAVIOR</a></h3>
<p>So far, it has been assumed that each sequence, which is drawn with a specific font, is context free, i.e. not affected by the glyphs preceding or following that sequence. This is true when sequence S1 is drawn with font F1 while the preceding sequence S0 unconditionally requires font F0.</p>
<div class="fragment"><pre class="fragment">
sequence S0 S1
currently used font F0 F1
usable font(s) F0 F1
</pre></div><p>Sometimes, however, a clear separation of sequences is not possible. Suppose that the preceding sequence S0 can be drawn not only with F0 but also with F1.</p>
<div class="fragment"><pre class="fragment">
sequence S0 S1
currently used font F0 F1
usable font(s) F0,F1 F1
</pre></div><p>In this case, glyphs used to draw the preceding S0 may affect glyph generation of S1. Therefore it is necessary to access information about S0, which has already been processed, when processing S1. Generation rules in the first stage (only in the first stage) accept a special regular expression to access already processed parts.</p>
<div class="fragment"><pre class="fragment">
"RE0 RE1"
</pre></div><p><code>RE0</code> and <code>RE1</code> are regular expressions that match the preceding sequence S0 and the following sequence S1, respectively.</p>
<p>Pay attention to the space between the two regular expressions. It represents the special category ' ' (see above). Note that the regular expression above belongs to glyph generation rules using font F1, therefore not only RE1 but also RE0 must be expressed with the categories for F1. This means when the preceding sequence S0 cannot be expressed with the categories for F1 (as in the first example above) generation rules having these patterns never match.</p>
<h3><a class="anchor" id="flt-seealso">
SEE ALSO</a></h3>
<p><a class="el" href="m17nDBFormat.html#mdbGeneral">mdbGeneral(5)</a>, <a class="el" href="m17nDBData.html#flt-list">FLTs provided by the m17n database</a></p>
<h2><a class="anchor" id="mdbFontEncoding">
Font Encoding</a></h2>
<h3><a class="anchor" id="font-encoding-description">
DESCRIPTION</a></h3>
<p>The m17n library loads information about the encoding of each font form the m17n database by the tags <font, encoding>. The data is loaded as a plist of this format.</p>
<div class="fragment"><pre class="fragment">
FONT-ENCODING ::= PER-FONT *
PER-FONT ::= '(' FONT-SPEC ENCODING [ REPERTORY ] ')'
FONT-SPEC ::=
'(' [ FOUNDRY FAMILY
[ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ]]]]]
REGISTRY ')'
ENCODING ::= SYMBOL
</pre></div><p><code>FONT-SPEC</code> is to specify properties of a font. <code>FOUNDRY</code> to <code>REGISTRY</code> are symbols corresponding to <a class="el" href="group__m17nFont.html#gaaf47ff596e3d9768b214a039014b6ea5" title="Key of font property specifying foundry.">Mfoundry</a> to <a class="el" href="group__m17nFont.html#gab8c5e8d3685a530e2ae45f3b8a21ae76" title="Key of font property specifying registry.">Mregistry</a> property of a font. See <a class="el" href="group__m17nFont.html">Font</a> for the meaning of each property.</p>
<p>For instance, this <code>FONT-SPEC</code>:</p>
<div class="fragment"><pre class="fragment">
(nil alice0\ lao iso8859-1)
</pre></div><p>should be applied to all fonts whose family name is "alice0 lao", and registry is "iso8859-1".</p>
<p><code>ENCODING</code> is a symbol representing a charset. A font matching <code>FONT-SPEC</code> supports all characters of the charset, and a character code is mapped to the corresponding glyph code of the font by this charset.</p>
<p><code>REPERTORY</code> is a symbol representing a charset or "nil". Omitting it is the same as specifying <code>ENCODING</code> as <code>REPERTORY</code>. If it is not "nil", the charset specifies the repertory of the font, i.e, which character it supports. Otherwise, whether a specific character is supported by the font or not is asked to each font driver.</p>
<p>For so called Unicode fonts (registry is "iso10646-1"), it is recommended to specify "nil" as <code>REPERTORY</code> because such fonts usually supports only a subset of Unicode characters.</p>
<h2><a class="anchor" id="mdbFontSize">
Font Size</a></h2>
<h3><a class="anchor" id="font-size-description">
DESCRIPTION</a></h3>
<p>In some case, a font contains incorrect information about its size (typically in the case of a hacked TrueType font), which results in a bad text layout when such a font is used in combination with the other fonts. To overcome this problem, the m17n library loads information about font-size adjustment from the m17n database by the tags <font, resize>. The data is loaded as a plist of this format.</p>
<div class="fragment"><pre class="fragment">
FONT-SIZE-ADJUSTMENT ::= PER-FONT *
PER-FONT ::= '(' FONT-SPEC ADJUST-RATIO ')'
FONT-SPEC ::=
'(' [ FOUNDRY FAMILY
[ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ]]]]]
REGISTRY ')'
ADJUST-RATIO ::= INTEGER
</pre></div><p><code>FONT-SPEC</code> is to specify properties of a font. <code>FOUNDRY</code> to <code>REGISTRY</code> are symbols corresponding to <a class="el" href="group__m17nFont.html#gaaf47ff596e3d9768b214a039014b6ea5" title="Key of font property specifying foundry.">Mfoundry</a> to <a class="el" href="group__m17nFont.html#gab8c5e8d3685a530e2ae45f3b8a21ae76" title="Key of font property specifying registry.">Mregistry</a> property of a font. See <a class="el" href="group__m17nFont.html">Font</a> for the meaning of each property.</p>
<p><code>ADJUST-RATIO</code> is an integer number specifying by percentage how much the font-size must be adjusted. For instance, this <code>PER-FONT</code>:</p>
<div class="fragment"><pre class="fragment">
((devanagari-cdac) 150)
</pre></div><p>instructs the font handler of the m17n library to open a font of 1.5 times bigger than a requested size on opening a font whose registry is "devanagari-cdac".</p>
<h2><a class="anchor" id="mdbFontset">
Fontset</a></h2>
<h3><a class="anchor" id="fontset-description">
DESCRIPTION</a></h3>
<p>The m17n library loads a fontset definition from the m17n database by the tags <fontset, FONTSET-NAME>. The plist format of the data is as follows:</p>
<div class="fragment"><pre class="fragment">
FONTSET ::= PER-SCRIPT * PER-CHARSET * FALLBACK *
PER-SCRIPT ::= '(' SCRIPT PER-LANGUAGE + ')'
PER-LANGUAGE ::= '(' LANGUAGE FONT-SPEC-ELEMENT + ')'
PER-CHARSET ::= '(' CHARSET FONT-SPEC-ELEMENT + ')'
FALLBACK ::= FONT-SPEC-ELEMENT
FONT-SPEC-ELEMENT ::= '(' FONT-SPEC [ FLT-NAME ] ')'
FONT-SPEC ::=
'(' [ FOUNDRY FAMILY
[ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ]]]]]
REGISTRY
[ OTF-SPEC ] [ LANG-SPEC ] ')'
</pre></div><p><code>SCRIPT</code> is a symbol of script name (e.g. latin, han) or <code>nil</code>. <code>LANGUAGE</code> is a two-letter symbol of language name code defined by ISO 639 (e.g. ja, zh) or <code>nil</code>.</p>
<p><code>FONT-SPEC</code> is to specify properties of a font. <code>FOUNDRY</code> to <code>REGISTRY</code> are symbols corresponding to <a class="el" href="group__m17nFont.html#gaaf47ff596e3d9768b214a039014b6ea5" title="Key of font property specifying foundry.">Mfoundry</a> to <a class="el" href="group__m17nFont.html#gab8c5e8d3685a530e2ae45f3b8a21ae76" title="Key of font property specifying registry.">Mregistry</a> property of a font. See <a class="el" href="group__m17nFont.html">Font</a> for the meaning of each property.</p>
<p><code>OTF-SPEC</code> is a symbol specifyng the required OTF features. The symbol name has the following syntax.</p>
<div class="fragment"><pre class="fragment">
OTF-SPEC-NAME ::= ':otf=' SCRIPT LANGSYS ? GSUB-FEATURES ? GPOS-FEATURES ?
SCRIPT ::= SYMBOL
LANGSYS ::= '/' SYMBOL
GSUB-FEATURES ::= '=' FEATURE-LIST ?
GPOS-FEATURES ::= '+' FEATURE-LIST ?
FEATURE-LIST ::= '~' ? FEATURE ( ',' '~' ? FEATURE ',' )
</pre></div><p>Here, <code>FEATURE</code> is a four-letter Open Type feature.</p>
<p><code>LANG-SPEC</code> is a symbol specifying the required language support. The symbol name has the following syntax.</p>
<div class="fragment"><pre class="fragment">
LANG-SPEC-NAME ::= ':lang=' LANG
</pre></div><p>Here, <code>LANG</code> is a two or three-letter ISO-639 language code.</p>
<p><code>FLT-NAME</code> is a name of Font Layout Table (<a class="el" href="m17nDBFormat.html#mdbFLT">Font Layout Table</a>).</p>
<h3><a class="anchor" id="fontset-example">
EXAMPLE</a></h3>
<p>This is an example of <code>PER_SCRIPT</code>.</p>
<div class="fragment"><pre class="fragment">
(han
(ja
((jisx0208.1983-0)))
(zh
((gb2312.1980-0)))
(nil
((big5-0))))
</pre></div><p>It instructs the font selector to use a font of registry "jisx0208.1983-0" for a "han" character (i.e. a character whose <a class="el" href="group__m17nCharacter.html#ga1efea11830fa151fad724fbdc4212750" title="Key for script.">Mscript</a> property is 'han') if the character has <a class="el" href="group__m17nMtext.html#ga32374f3750874ea0142af8dac831ab25">Mlanguage</a> text property "ja" in an M-text and the character is in the repertories of such fonts. Otherwise, try a font of registry "gb2312.1980-0" or "big5-0". If that "han" character does not have <a class="el" href="group__m17nMtext.html#ga32374f3750874ea0142af8dac831ab25">Mlanguage</a> text property, try all three fonts.</p>
<p>See the function <a class="el" href="group__m17nDraw.html#ga02f9efd2c5d1bdd9d7a6ab18475bbd08" title="Draw an M-text on a window.">mdraw_text()</a> for the detail of how a font is selected.</p>
<h2><a class="anchor" id="mdbIM">
Input Method</a></h2>
<h3><a class="anchor" id="im-description">
DESCRIPTION</a></h3>
<p>The m17n library provides a driver for input methods that are dynamically loadable from the m17n database (see <a class="el" href="group__m17nInputMethod.html">Input Method (basic)</a> ).</p>
<p>This section describes the data format that defines those input methods.</p>
<h3><a class="anchor" id="im-format">
SYNTAX and SEMANTICS</a></h3>
<p>The following data format defines an input method. The driver loads a definition from a file, a stream, etc. The definition is converted into the form of plist in the driver.</p>
<div class="fragment"><pre class="fragment">
INPUT-METHOD ::=
IM-DECLARATION ? IM-DESCRIPTION ? TITLE ?
VARIABLE-LIST ? COMMAND-LIST ? MODULE-LIST ?
MACRO-LIST ? MAP-LIST ? STATE-LIST ?
IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME EXTRA-ID ? VERSION ? ')'
LANGUAGE ::= SYMBOL
NAME ::= SYMBOL
EXTRA-ID ::= SYMBOL
VERSION ::= '(' 'version' VERSION-NUMBER ')'
IM-DESCRIPTION ::= '(' 'description' DESCRIPTION ')'
DESCRIPTION ::= MTEXT-OR-GETTEXT | 'nil'
MTEXT-OR-GETTEXT ::= [ MTEXT | '(' '_' MTEXT ')']
TITLE ::= '(' 'title' TITLE-TEXT ')'
TITLE-TEXT ::= MTEXT
VARIABLE-LIST ::= '(' 'variable' VARIABLE-DECLARATION * ')'
VARIABLE-DECLARATION ::= '(' VAR-NAME [ DESCRIPTION VALUE VALUE-CANDIDATE * ]')'
VAR-NAME ::= SYMBOL
VALUE ::= MTEXT | SYMBOL | INTEGER
VALUE-CANDIDATE ::= VALUE | '(' RANGE-FROM RANGE-TO ')'
RANGE-FROM ::= INTEGER
RANGE-TO ::= INTEGER
COMMAND-LIST ::= '(' 'command' COMMAND-DECLARATION * ')'
COMMAND-DECLARATION ::= '(' CMD-NAME [ DESCRIPTION KEYSEQ * ] ')'
CMD-NAME ::= SYMBOL
</pre></div><p><code>IM-DECLARATION</code> specifies the language and name of this input method.</p>
<p>When <code>LANGUAGE</code> is <code>t</code>, the use of the input method is not limited to one language.</p>
<p>When <code>NAME</code> is <code>nil</code>, the input method is not standalone, but is expected to be used in other input methods. In such cases, <code>EXTRA-ID</code> is required to identify the input method.</p>
<p><code>VERSION</code> specifies the required minimum version number of the m17n library. The format is "XX.YY.ZZ" where XX is a major version number, YY is a minor version number, and ZZ is a patch level.</p>
<p><code>DESCRIPTION</code>, if not nil, specifies the description text of an input method, a variable or a command. If <code>MTEXT-OR-GETTEXT</code> takes the second form, the text is translated according to the current locale by "gettext" (if the translation is provided).</p>
<p><code>TITLE-TEXT</code> is a text displayed on the screen when this input method is active.</p>
<p>There is one special input method file "global.mim" that declares common variables and commands. The input method driver always loads this file and other input methods can inherit the variables and the commands.</p>
<p><code>VARIABLE-DECLARATION</code> declares a variable used in this input method. If a variable must be initialized to the default value, or is to be customized by a user, it must be declared here. The declaration can be used in two ways. One is to introduce a new variable. In that case, <code>VALUE</code> must not be omitted. Another is to inherit the variable from what declared in "global.mim", and to give the different default value and/or to make the variable customizable specially for the current input method. In the latter case, <code>VALUE</code> can be omitted.</p>
<p><code>COMMAND-DECLARATION</code> declares a command used in this input method. If a command must be bound to the default key sequence, or is to be customized by a user, it must be declared here. Like <code>VARIABLE-DECLARATION</code>, the declaration can be used in two ways. One is to introduce a new command. In that case, <code>KEYSEQ</code> must not be omitted. Another is to inherit the command from what declared in "global.mim", and to give the different key binding and/or to make the command customizable specially for the current input method. In the latter case, <code>KEYSEQ</code> can be omitted.</p>
<div class="fragment"><pre class="fragment">
MODULE-LIST ::= '(' 'module' MODULE * ')'
MODULE ::= '(' MODULE-NAME FUNCTION * ')'
MODULE-NAME ::= SYMBOL
FUNCTION ::= SYMBOL
</pre></div><p>Each <code>MODULE</code> declares the name of an external module (i.e. dynamic library) and function names exported by the module. If a <code>FUNCTION</code> has name "init", it is called with only the default arguments (see the section about <code>CALL</code>) when an input context is created for the input method. If a <code>FUNCTION</code> has name "fini", it is called with only the default arguments when an input context is destroyed.</p>
<div class="fragment"><pre class="fragment">
MACRO-LIST ::= MACRO-INCLUSION ? '(' 'macro' MACRO * ')' MACRO-INCLUSION ?
MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'
MACRO-NAME ::= SYMBOL
MACRO-ACTION ::= ACTION
TAGS ::= `(` LANGUAGE NAME EXTRA-ID ? `)`
MACRO-INCLUSION ::= '(' 'include' TAGS 'macro' MACRO-NAME ? ')'
</pre></div><p><code>MACRO-INCLUSION</code> includes macros from another input method specified by <code>TAGS</code>. When <code>MACRO-NAME</code> is not given, all macros from the input method are included.</p>
<div class="fragment"><pre class="fragment">MAP-LIST ::= MAP-INCLUSION ? '(' 'map' MAP * ')'
MAP-INCLUSION ?
MAP ::= '(' MAP-NAME RULE * ')'
MAP-NAME ::= SYMBOL
RULE ::= '(' KEYSEQ MAP-ACTION * ')'
KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'
MAP-INCLUSION ::= '(' 'include' TAGS 'map' MAP-NAME ? ')'
</pre></div><p>When an input method is never standalone and always included in another method, <code>MAP-LIST</code> can be omitted.</p>
<p><code>SYMBOL</code> in the definitions of <code>MAP-NAME</code> must not be <code>t</code> nor <code>nil</code>.</p>
<p><code>MTEXT</code> in the definition of <code>KEYSEQ</code> consists of characters that can be generated by a keyboard. Therefore <code>MTEXT</code> usually contains only ASCII characters. However, if the input method is intended to be used, for instance, with a West European keyboard, <code>MTEXT</code> may contain Latin-1 characters.</p>
<p><code>SYMBOL</code> in the definition of <code>KEYSEQ</code> must be the return value of the <a class="el" href="group__m17nInputMethodWin.html#ga58715c630a04fd33f12394e9c93f1bad" title="Convert an event to an input key.">minput_event_to_key()</a> function. Under the X window system, you can quickly check the value using the <code>xev</code> command. For example, the return key, the backspace key, and the 0 key on the keypad are represented as <code></code>(Return) , <code></code>(BackSpace) , and <code></code>(KP_0) respectively. If the shift, control, meta, alt, super, and hyper modifiers are used, they are represented by the S- , C- , M- , A- , s- , and H- prefixes respectively in this order. Thus, "return with
shift with meta with hyper" is <code></code>(S-M-H-Return) . Note that "a with
shift" .. "z with shift" are represented simply as A .. Z . Thus "a
with shift with meta with hyper" is <code></code>(M-H-A) .</p>
<p><code>INTEGER</code> in the definition of <code>KEYSEQ</code> must be a valid character code.</p>
<p><code>MAP-INCLUSION</code> includes maps from another input method specified by <code>TAGS</code>. When <code>MAP-NAME</code> is not given, all maps from the input method are included.</p>
<div class="fragment"><pre class="fragment">
MAP-ACTION ::= ACTION
ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK
| SHOW | HIDE | PUSHBACK | POP | UNDO
| COMMIT | UNHANDLE | SHIFT | CALL
| SET | IF | COND | '(' MACRO-NAME ')'
PREDEFINED-SYMBOL ::=
'@0' | '@1' | '@2' | '@3' | '@4'
| '@5' | '@6' | '@7' | '@8' | '@9'
| '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
| '@@'
| '@-0' | '@-N' | '@+N'
</pre></div><div class="fragment"><pre class="fragment">
STATE-LIST ::= STATE-INCUSION ? '(' 'state' STATE * ')' STATE-INCUSION ?
STATE ::= '(' STATE-NAME [ STATE-TITLE-TEXT ] BRANCH * ')'
STATE-NAME ::= SYMBOL
STATE-TITLE-TEXT ::= MTEXT
BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
| '(' 'nil' BRANCH-ACTION * ')'
| '(' 't' BRANCH-ACTION * ')'
STATE-INCLUSION ::= '(' 'include' TAGS 'state' STATE-NAME ? ')'
</pre></div><p>When an input system is never standalone and always included in another system, <code>STATE-LIST</code> can be omitted.</p>
<p><code>STATE-INCLUSION</code> includes states from another input method specified by <code>TAGS</code>. When <code>STATE-NAME</code> is not given, all states from the input method are included.</p>
<p>The optional <code>STATE-TITLE-TEXT</code> specifies a title text displayed on the screen when the input method is in this state. If <code>STATE-TITLE-TEXT</code> is omitted, <code>TITLE-TEXT</code> is used.</p>
<p>In the first form of <code>BRANCH</code>, <code>MAP-NAME</code> must be an item that appears in <code>MAP</code>. In this case, if a key sequence matching one of <code>KEYSEQs</code> of <code>MAP-NAME</code> is typed, <code>BRANCH-ACTIONs</code> are executed.</p>
<p>In the second form of <code>BRANCH</code>, <code>BRANCH-ACTIONs</code> are executed if a key sequence that doesn't match any of <code>Branch's</code> of the current state is typed.</p>
<p>If there is no <code>BRANCH</code> beginning with <code>nil</code> and the typed key sequence does not match any of the current <code>BRANCHs</code>, the input method transits to the initial state.</p>
<p>In the third form of <code>BRANCH</code>, <code>BRANCH-ACTIONs</code> are executed when shifted to the current state. If the current state is the initial state, <code>BRANCH-ACTIONs</code> are executed also when an input context of the input method is created.</p>
<div class="fragment"><pre class="fragment">
BRANCH-ACTION ::= ACTION
</pre></div><p>An input method has the following two lists of symbols.</p>
<ul>
<li>
<p class="startli">marker list</p>
<p>A marker is a symbol indicating a character position in the preediting text. The <code>MARK</code> action assigns a position to a marker. The position of a marker is referred by the <code>MOVE</code> and the <code>DELETE</code> actions.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">variable list</p>
<p>A variable is a symbol associated with an integer, a symbol, or an M-text value. The integer value of a variable can be set and referred by the <code>SET</code> action. It can be referred by the <code>SET</code>, the <code>INSERT</code>, the <code>SELECT</code>, the <code>UNDO</code>, the <code>IF</code>, the <code>COND</code> actions. The M-text value of a variable can be referred by the <code>INSERT</code> action. The symbol value of a variable can not be referred directly, is used the library implicitly (e.g. candidates-charset). All variables are implicitly initialized to the integer value zero.</p>
<p class="endli"></p>
</li>
</ul>
<p>Each <code>PREDEFINED-SYMBOL</code> has a special meaning when used as a marker.</p>
<ul>
<li>
<p class="startli"><code>@0</code>, <code>@1</code>, <code>@2</code>, <code>@3</code>, <code>@4</code>, <code>@5</code>, <code>@6</code>, <code>@7</code>, <code>@8</code>, <code>@9</code> </p>
<p>The 0th, 1st, 2nd, ... 9th position respectively.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@<</code>, <code>@=</code>, <code>@></code> </p>
<p>The first, the current, and the last position.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@-</code>, <code>@+</code> </p>
<p>The previous and the next position.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@</code>[, <code>@</code>]</p>
<p class="endli">The previous and the next position where a candidate list changes. </p>
</li>
</ul>
<p>Some of the <code>PREDEFINED-SYMBOL</code> has a special meaning when used as a candidate index in the <code>SELECT</code> action.</p>
<ul>
<li>
<p class="startli"><code>@<</code>, <code>@=</code>, <code>@></code> </p>
<p>The first, the current, and the last candidate of the current candidate group.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@-</code> </p>
<p>The previous candidate. If the current candidate is the first one in the current candidate group, then it means the last candidate in the previous candidate group.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@+</code> </p>
<p>The next candidate. If the current candidate is the last one in the current candidate group, then it means the first candidate in the next candidate group.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@</code>[, <code>@</code>]</p>
<p class="endli">The candidate in the previous and the next candidate group having the same candidate index as the current one. </p>
</li>
</ul>
<p>And, this also has a special meaning.</p>
<ul>
<li>
<p class="startli"><code>@@</code> </p>
<p>Number of handled keys at that moment.</p>
<p class="endli"></p>
</li>
</ul>
<p>These are for supporting surround text handling.</p>
<ul>
<li>
<p class="startli"><code>@-0</code> </p>
<p>-1 if surrounding text is supported, -2 if not.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@-N</code> </p>
<p>Here, <code>N</code> is a positive integer. The value is the Nth previous character in the preedit buffer. If there are only M (M<N) previous characters in it, the value is the (N-M)th previous character from the inputting spot. When this is used as the argument of <code>delete</code> action, it specifies the number of characters to be deleted.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>@+N</code> </p>
<p class="endli">Here, <code>N</code> is a positive integer. The value is the Nth following character in the preedit buffer. If there are only M (M<N) following characters in it, the value is the (N-M)th following character from the inputting spot. When this is used as the argument of <code>delete</code> action, it specifies the number of characters to be deleted. </p>
</li>
</ul>
<p>The arguments and the behavior of each action are listed below.</p>
<div class="fragment"><pre class="fragment">
INSERT ::= '(' 'insert' MTEXT ')'
| MTEXT
| INTEGER
| SYMBOL
| '(' 'insert' SYMBOL ')'
| '(' 'insert' '(' CANDIDATES * ')' ')'
| '(' CANDIDATES * ')'
CANDIDATES ::= MTEXT | '(' MTEXT * ')'
</pre></div><p>The first and second forms insert <code>MTEXT</code> before the current position.</p>
<p>The third form inserts the character <code>INTEGER</code> before the current position.</p>
<p>The fourth and fith form treats <code>SYMBOL</code> as a variable, and inserts its value (if it is a valid character code) before the current position.</p>
<p>In the sixth and seventh forms, each <code>CANDIDATES</code> represents a candidate group, and each element of <code>CANDIDATES</code> represents a candidate, i.e. if <code>CANDIDATES</code> is an M-text, the candidates are the characters in the M-text; if <code>CANDIDATES</code> is a list of M-texts, the candidates are the M-texts in the list.</p>
<p>These forms insert the first candidate before the current position. The inserted string is associated with the list of candidates and the information indicating the currently selected candidate.</p>
<p>The marker positions affected by the insertion are automatically relocated.</p>
<div class="fragment"><pre class="fragment">
DELETE ::= '(' 'delete' SYMBOL ')'
| '(' 'delete' INTEGER ')'
</pre></div><p>The first form treats <code>SYMBOL</code> as a marker, and deletes characters between the current position and the marker position.</p>
<p>The second form treats <code>INTEGER</code> as a character position, and deletes characters between the current position and the character position.</p>
<p>The marker positions affected by the deletion are automatically relocated.</p>
<div class="fragment"><pre class="fragment">
SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
| '(' 'select' INTEGER ')'
| '(' 'select' SYMBOL ')'
</pre></div><p>This action first checks if the character just before the current position belongs to a string that is associated with a candidate list. If it is, the action replaces that string with a candidate specified by the argument.</p>
<p>The first form treats <code>PREDEFINED-SYMBOL</code> as a candidate index (as described above) that specifies a new candidate in the candidate list.</p>
<p>The second form treats <code>INTEGER</code> as a candidate index that specifies a new candidate in the candidate list.</p>
<p>In the third form, <code>SYMBOL</code> must have a integer value, and it is treated as a candidate index.</p>
<div class="fragment"><pre class="fragment">SHOW ::= '(show)' </pre></div><p>This actions instructs the input method driver to display a candidate list associated with the string before the current position.</p>
<div class="fragment"><pre class="fragment">
HIDE ::= '(hide)'
</pre></div><p>This action instructs the input method driver to hide the currently displayed candidate list.</p>
<div class="fragment"><pre class="fragment">
MOVE ::= '(' 'move' SYMBOL ')'
| '(' 'move' INTEGER ')'
</pre></div><p>The first form treats <code>SYMBOL</code> as a marker, and makes the marker position be the new current position.</p>
<p>The second form treats <code>INTEGER</code> as a character position, and makes that position be the new current position.</p>
<div class="fragment"><pre class="fragment">
MARK ::= '(' 'mark' SYMBOL ')'
</pre></div><p>This action treats <code>SYMBOL</code> as a marker, and sets its position to the current position. <code>SYMBOL</code> must not be a <code>PREDEFINED-SYMBOL</code>.</p>
<div class="fragment"><pre class="fragment">
PUSHBACK :: = '(' 'pushback' INTEGER ')'
| '(' 'pushback' KEYSEQ ')'
</pre></div><p>The first form pushes back the latest <code>INTEGER</code> number of key events to the event queue if <code>INTEGER</code> is positive, and pushes back all key events if <code>INTEGER</code> is zero.</p>
<p>The second form pushes back keys in <code>KEYSEQ</code> to the event queue.</p>
<div class="fragment"><pre class="fragment">
POP ::= '(' 'pop' ')'
</pre></div><p>This action pops the first key event that is not yet handled from the event queue.</p>
<div class="fragment"><pre class="fragment">
UNDO :: = '(' 'undo' [ INTEGER | SYMBOL ] ')'
</pre></div><p>If there's no argument, this action cancels the last two key events (i.e. the one that invoked this command, and the previous one).</p>
<p>If there's an integer argument NUM, it must be positive or negative (not zero). If positive, from the NUMth to the last events are canceled. If negative, the last (- NUM) events are canceled.</p>
<p>If there's a symbol argument, it must be resolved to an integer number and the number is treated as the actual argument as above.</p>
<div class="fragment"><pre class="fragment">
COMMIT :: = '(commit)'
</pre></div><p>This action commits the current preedit.</p>
<div class="fragment"><pre class="fragment">
UNHANDLE :: = '(unhandle)'
</pre></div><p>This action commits the current preedit and returns the last key as unhandled.</p>
<div class="fragment"><pre class="fragment">
SHIFT :: = '(' 'shift' STATE-NAME ')'
</pre></div><p>If <code>STATE-NAME</code> is <code>t</code>, this action shifts the current state to the previous one, otherwise it shifts to <code>STATE-NAME</code>. In the latter case, <code>STATE-NAME</code> must appear in <code>STATE-LIST</code>.</p>
<div class="fragment"><pre class="fragment">
CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'
ARG ::= INTEGER | SYMBOL | MTEXT | PLIST
</pre></div><p>This action calls the function <code>FUNCTION</code> of external module <code>MODULE-NAME</code>. <code>MODULE-NAME</code> and <code>FUNCTION</code> must appear in <code>MODULE-LIST</code>.</p>
<p>The function is called with an argument of the type (<a class="el" href="group__m17nPlist.html#gac8b2ac3c9a8f0a6afb7f189b694035e2" title="Type of property list objects.">MPlist</a> *). The key of the first element is <a class="el" href="group__m17nSymbol.html#ga8769a573efbb023b4d77f9d03babc09f" title="Symbol whose name is "t".">Mt</a> and its value is a pointer to an object of the type <a class="el" href="structMInputContext.html" title="Structure of input context.">MInputContext</a>. The key of the second element is <a class="el" href="group__m17nSymbol.html#ga6592d4eb3c46fe7fb8993c252b8fedeb" title="Symbol whose name is "symbol".">Msymbol</a> and its value is the current state name. <code>ARGs</code> are used as the value of the third and later elements. Their keys are determined automatically; if an <code>ARG</code> is an integer, the corresponding key is <a class="el" href="group__m17nPlist.html#ga0ce08eb57aa339db4d4745e75e80fdd8" title="Symbol whose name is "integer".">Minteger</a>; if an <code>ARG</code> is a symbol, the corresponding key is <a class="el" href="group__m17nSymbol.html#ga6592d4eb3c46fe7fb8993c252b8fedeb" title="Symbol whose name is "symbol".">Msymbol</a>, etc.</p>
<p>The function must return NULL or a value of the type (<a class="el" href="group__m17nPlist.html#gac8b2ac3c9a8f0a6afb7f189b694035e2" title="Type of property list objects.">MPlist</a> *) that represents a list of actions to take.</p>
<div class="fragment"><pre class="fragment">
SET ::= '(' CMD SYMBOL1 EXPRESSION ')'
CMD ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERATOR EXPRESSION * ')'
OPERATOR ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
| '=' | '<' | '>' | '<=' | '>='
</pre></div><p>This action treats <code>SYMBOL1</code> and <code>SYMBOL2</code> as variables and sets the value of <code>SYMBOL1</code> as below.</p>
<p>If <code>CMD</code> is 'set', it sets the value of <code>SYMBOL1</code> to the value of <code>EXPRESSION</code>.</p>
<p>If <code>CMD</code> is 'add', it increments the value of <code>SYMBOL1</code> by the value of <code>EXPRESSION</code>.</p>
<p>If <code>CMD</code> is 'sub', it decrements the value of <code>SYMBOL1</code> by the value of <code>EXPRESSION</code>.</p>
<p>If <code>CMD</code> is 'mul', it multiplies the value of <code>SYMBOL1</code> by the value of <code>EXPRESSION</code>.</p>
<p>If <code>CMD</code> is 'div', it divides the value of <code>SYMBOL1</code> by the value of <code>EXPRESSION</code>.</p>
<div class="fragment"><pre class="fragment">
IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ? ')'
CONDITION ::= [ '=' | '<' | '>' | '<=' | '>=' ] EXPRESSION1 EXPRESSION2
ACTION-LIST1 ::= '(' ACTION * ')'
ACTION-LIST2 ::= '(' ACTION * ')'
</pre></div><p>This action performs actions in <code>ACTION-LIST1</code> if <code>CONDITION</code> is true, and performs <code>ACTION-LIST2</code> (if any) otherwise.</p>
<div class="fragment"><pre class="fragment">
COND ::= '(' 'cond' [ '(' EXPRESSION ACTION * ') ] * ')'
</pre></div><p>This action performs the first action <code>ACTION</code> whose corresponding <code>EXPRESSION</code> has nonzero value.</p>
<h3><a class="anchor" id="im-example1">
EXAMPLE 1</a></h3>
<p>This is a very simple example for inputting Latin characters with diacritical marks (acute and cedilla). For instance, when you type: </p>
<div class="fragment"><pre class="fragment">
Comme'die-Franc,aise, chic,,
</pre></div><p> you will get this:</p>
<p>The definition of the input method is very simple as below, and it is quite straight forward to extend it to cover all Latin characters.</p>
<h3><a class="anchor" id="im-example2">
EXAMPLE 2</a></h3>
<p>This example is for inputting Unicode characters by typing C-u (Control-u) followed by four hexadecimal digits. For instance, when you type ("^u" means Control-u): </p>
<div class="fragment"><pre class="fragment">
^u2190^u2191^u2192^u2193
</pre></div><p> you will get this (Unicode arrow symbols):</p>
<p>The definition utilizes <code>SET</code> and <code>IF</code> commands as below: </p>
<div class="fragment"><pre class="fragment">
(title "UNICODE")
(map
(starter
((C-U) "U+"))
(hex
("0" ?0) ("1" ?1) ... ("9" ?9) ("a" ?A) ("b" ?B) ... ("f" ?F)))
(state
(init
(starter (set code 0) (set count 0) (shift unicode)))
(unicode
(hex (set this @-)
(< this ?A
((sub this 48))
((sub this 55)))
(mul code 16) (add code this)
(add count 1)
(= count 4
((delete @<) (insert code) (shift init))))))
</pre></div><h3><a class="anchor" id="im-example3">
EXAMPLE 3</a></h3>
<p>This example is for inputting Chinese characters by typing PinYin key sequence.</p>
<h3><a class="anchor" id="im-seealso">
SEE ALSO</a></h3>
<p><a class="el" href="m17nDBData.html#mim-list">Input Methods provided by the m17n database</a>, <a class="el" href="m17nDBFormat.html#mdbGeneral">mdbGeneral(5)</a> </p>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr>
<ADDRESS>
<a href="http://www.m17n.org/m17n-lib-en/index.html" target="mulewindow"><img src="parrot.png" align=bottom alt="m17n-lib Home" border=0></a>
</ADDRESS>
</body>
</HTML>
<!-- Copyright information
Copyright (C) 2001 Information-technology Promotion Agency (IPA)
Copyright (C) 2001-2011
National Institute of Advanced Industrial Science and Technology (AIST)
This file is part of the m17n library documentation.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Section, no Front-Cover Texts,
and no Back-Cover Texts. A copy of the license is included in the
appendix entitled "GNU Free Documentation License".
-->
|
