Debian Codegraph @

manual/subreadings.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="subreadings">
5 <title>Sub-Readings</title>
6
7 <para>
8 Sub-readings introduce a bit of hierarchy into readings, letting a reading have a hidden reading attached to it,
9 which in turn may have another hidden reading, and so on. See the <code>test/T_SubReading_Apertium</code> and
10 <code>test/T_SubReading_CG</code> tests for usage examples.
11 </para>
12
13 <section id="sub-stream-apertium">
14 <title>Apertium Format</title>
15
16 <para>
17 The Apertium stream format supports sub-readings via the + delimiter for readings. E.g.
18 </para>
19 <screen>
20 ^word/aux3&lt;tag&gt;+aux2&lt;tag&gt;+aux1&lt;tag&gt;+main&lt;tag&gt;$
21 </screen>
22 <para>
23 is a cohort with 1 reading which has a three level deep sub-reading. The order of which is the primary reading
24 vs. sub-readings depends on the grammar SUBREADINGS setting:
25 </para>
26 <screen>
27 SUBREADINGS = RTL ; # Default, right-to-left
28 SUBREADINGS = LTR ; # Alternate, left-to-right
29 </screen>
30 <para>
31 In default RTL mode, the above reading has the primary reading <code>"main"</code> with sub-reading
32 <code>"aux1"</code> with sub-reading <code>"aux2"</code> and finally sub-reading <code>"aux3"</code>.
33 </para>
34 <para>
35 In LTR mode, the above reading has the primary reading <code>"aux3"</code> with sub-reading
36 <code>"aux2"</code> with sub-reading <code>"aux1"</code> and finally sub-reading <code>"main"</code>.
37 </para>
38 </section>
39
40 <section id="sub-stream-cg">
41 <title>CG Format</title>
42
43 <para>
44 The CG stream format supports sub-readings via indentation level. E.g.
45 </para>
46 <screen>
47 "&lt;word&gt;"
48 "main" tag
49 "aux1" tag
50 "aux2" tag
51 "aux3" tag
52 </screen>
53 <para>
54 is a cohort with 1 reading which has a three level deep sub-reading. Unlike the Apertium format, the order is
55 strictly defined by indentation and cannot be changed. The above reading has the primary reading
56 <code>"main"</code> with sub-reading <code>"aux1"</code> with sub-reading <code>"aux2"</code>
57 and finally sub-reading <code>"aux3"</code>.
58 </para>
59 <para>
60 The indentation level is detected on a per-cohort basis. All whitespace counts the same for purpose of determining
61 indentation, so 1 tab is same as 1 space is same as 1 no-break space and so on. Since it is per-cohort, it won't
62 matter if previous cohorts has a different indentation style, so it is safe to mix cohorts from multiple sources.
63 </para>
64 </section>
65
66 <section id="sub-grammar">
67 <title>Grammar Syntax</title>
68
69 <para>
70 Working with sub-readings involves 2 new grammar features: Rule Option SUB:N and Contextual Option /N.
71 </para>
72
73 <section id="sub-grammar-subn">
74 <title>Rule Option SUB:N</title>
75 <indexterm>
76 <primary>SUB:N</primary>
77 </indexterm>
78
79 <para>
80 Rule option SUB:N tells a rule which sub-reading it should operate on and which it should test as target.
81 The N is an integer in the range -2^31 to 2^31. SUB:0 is the primary reading and same as not specifying SUB.
82 Positive numbers refer to sub-readings starting from the primary and going deeper, while negative numbers start
83 from the last sub-reading and go towards the primary. Thus, SUB:-1 always refers to the deepest sub-reading.
84 </para>
85 <para>
86 Given the above CG input and the rules
87 <screen>
88 ADD SUB:-1 (mark) (*) ;
89 ADD SUB:1 (twain) (*) ;
90 </screen>
91 the output will be
92 <screen>
93 "&lt;word&gt;"
94 "main" tag
95 "aux1" tag twain
96 "aux2" tag
97 "aux3" tag mark
98 </screen>
99 Note that SUB:N also determines which reading is looked at as target, so it will work for all rule types.
100 </para>
101 </section>
102
103 <section id="sub-grammar-slashn">
104 <title>Contextual Option /N</title>
105 <indexterm>
106 <primary>/N</primary>
107 <secondary>/*</secondary>
108 </indexterm>
109
110 <para>
111 Context option /N tests the N'th sub-reading of the currently active reading, where N follows the same rules
112 as for SUB:N above. The /N must be last in the context position.
113 </para>
114 <para>
115 If N is * then the test will search the main reading and all sub-readings.
116 </para>
117 <para>
118 Given the above CG input and the rules
119 <screen>
120 ADD (mark) (*) (0/-1 ("aux3")) ; # matches 3rd sub-reading "aux3"
121 ADD (twain) (*) (0/1 ("aux1")) ; # matches 1st sub-reading "aux1"
122 ADD (writes) (*) (0/1 ("main")) ; # won't match as 1st sub-reading doesn't have tag "main"
123 </screen>
124 the output will be
125 <screen>
126 "&lt;word&gt;"
127 "main" tag mark twain
128 "aux1" tag
129 "aux2" tag
130 "aux3" tag
131 </screen>
132 </para>
133 </section>
134 </section>
135
136 </chapter>