Debian Codegraph @

manual/compatibility.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="compatibility">
5 <title>Compatibility and Incompatibilities</title>
6
7 <para>
8 Things to be aware of.
9 </para>
10
11 <section id="gotchas">
12 <title>Gotcha's</title>
13
14 <section id="gotcha-magic-readings">
15 <title>Magic Readings</title>
16 <para>
17 In CG-3 all cohorts have at least one reading. If none are given in the input, one is generated
18 from the wordform. These magic readings can be the target of rules, which may not always be intended.
19 </para>
20 <para>
21 For example, given the input
22 <screen>
23 "&lt;word&gt;"
24 &nbsp; "word" N NOM SG
25 "&lt;$.&gt;"
26 </screen>
27 a magic reading is made so the cohorts internally looks like
28 <screen>
29 "&lt;word&gt;"
30 &nbsp; "word" N NOM SG
31 "&lt;$.&gt;"
32 &nbsp; "&lt;$.&gt;" &lt;&lt;&lt;
33 </screen>
34 </para>
35 <para>
36 The above input combined with a rule a'la
37 <screen>
38 MAP (@X) (*) ;
39 </screen>
40 will give the output
41 <screen>
42 "&lt;word&gt;"
43 &nbsp; "word" N NOM SG @X
44 "&lt;$.&gt;"
45 &nbsp; "&lt;$.&gt;" &lt;&lt;&lt; @X
46 </screen>
47 because MAP promoted the last magic reading to a real reading.
48 </para>
49 <para>
50 If you do not want these magic readings to be the possible target of rules, you can use the
51 cmdline option --no-magic-readings. Internally they will still be generated and contextual tests
52 can still reference them, but rules cannot touch or modify them directly.
53 <emphasis>
54 <link linkend="keyword-setchild">SETCHILD</link> is an exception.
55 </emphasis>
56 </para>
57 </section>
58
59 <section id="gotcha-not-negate">
60 <title>NOT and NEGATE</title>
61 <para>
62 In CG-2 and VISLCG the keyword NOT behaved differently depending on whether it was
63 in front of the first test or in front of a linked test. In the case of
64 <screen>
65 (NOT 1 LSet LINK 1 KSet LINK 1 JSet)
66 </screen>
67 the NOT would apply last, meaning it would invert the result of the entire chain,
68 but in the case of
69 <screen>
70 (1 LSet LINK NOT 1 KSet LINK 1 JSet)
71 </screen>
72 it only inverts the result of the immediately following test.
73 </para>
74
75 <para>
76 CG-3 implements the <link linkend="test-negate">NEGATE</link> keyword to make the distinction clearer.
77 This means that if you are converting grammars to CG-3 you must replace starting NOTs with NEGATEs
78 to get the same functionality. So the first test should instead be
79 <screen>
80 (NEGATE 1 LSet LINK 1 KSet LINK 1 JSet)
81 </screen>
82 </para>
83
84 <para>
85 Alternatively you can use the --vislcg-compat (short form -2) to work with older grammars that you
86 do not wish to permanently update to use NEGATE.
87 </para>
88 </section>
89
90 <section id="gotcha-preferred-targets">
91 <title>PREFERRED-TARGETS</title>
92 <indexterm>
93 <primary>PREFERRED-TARGETS</primary>
94 </indexterm>
95 <para>
96 <link linkend="keyword-preferred-targets">PREFERRED-TARGETS</link> is currently ignored in CG-3.
97 See <link linkend="keyword-preferred-targets">PREFERRED-TARGETS</link> for details.
98 </para>
99 </section>
100
101 <section id="gotcha-codepage">
102 <title>Default Codepage / Encoding</title>
103 <para>
104 CG-3 will auto-detect the codepage from the environment, which in some cases is not what you want.
105 It is not uncommon to work with UTF-8 data but have your environment set to US-ASCII which would
106 produce some unfortunate errors.
107 You can use the runtime option -C to override the default codepage, and you should always enforce
108 it if you plan on distributing packages that depend on a certain codepage.
109 </para>
110 </section>
111
112 <section id="gotcha-setop-minus">
113 <title>Set Operator -</title>
114 <para>
115 In CG-2 the - operator meant set difference; in VISLCG it meant set fail-fast; in CG-3
116 <link linkend="set-operator-except">operator -</link> means something in between.
117 The new <link linkend="set-operator-failfast">operator ^</link> takes place of VISLCG's behavior,
118 and <link linkend="set-operator-difference">operator \</link> takes the place of CG-2's behavior.
119 </para>
120 </section>
121
122 <section id="gotcha-origin-passing">
123 <title>Scanning Past Point of Origin</title>
124 <para>
125 In CG-1 and some versions of CG-2, scanning tests could not pass the point of origin, but in CG-3
126 they can by default do so. The cmdline flag --no-pass-origin can set the default behavior to that of
127 CG-1. See <link linkend="test-origin">Scanning Past Point of Origin</link> for more details.
128 </para>
129 </section>
130
131 <section id="gotcha-first-last-tags">
132 <title>&gt;&gt;&gt; and &lt;&lt;&lt;</title>
133 <para>
134 In VISLCG the magic tags &gt;&gt;&gt; and &lt;&lt;&lt;,
135 denoting sentence start and end respectively, could sometimes wind up in the output.
136 In CG-3 they are never part of the output.
137 </para>
138 </section>
139
140 <section id="gotcha-application-order">
141 <title>Rule Application Order</title>
142 <para>
143 In CG-2 the order in which rules are applied on cohorts cannot be reliably predicted.
144 </para>
145 <para>
146 In VISLCG rules can be forced to be applied in the order they occur in the grammar, but
147 VISLCG will try to run all rules on the current cohort before trying next cohort:
148 <screen>
149 ForEach (Window)
150 &nbsp; ForEach (Cohort)
151 &nbsp;&nbsp; ForEach (Rule)
152 &nbsp;&nbsp;&nbsp; ApplyRule
153 </screen>
154 </para>
155 <para>
156 CG-3 always applies rules in the order they occur in the grammar, and will try the current
157 rule on all cohorts in the window before moving on to the next rule.
158 This yields a far more predictable result and cuts down on the need for many sections in the grammar.
159 <screen>
160 ForEach (Window)
161 &nbsp; ForEach (Rule)
162 &nbsp;&nbsp; ForEach (Cohort)
163 &nbsp;&nbsp;&nbsp; ApplyRule
164 </screen>
165 </para>
166 </section>
167
168 <section id="gotcha-endless-loops">
169 <title>Endless Loops</title>
170 <para>
171 Since any rule can be in any section, it is possible to write endless loops.
172 </para>
173 <para>
174 For example, this grammar will potentially loop forever:
175 <screen>
176 SECTION
177 ADD (@not-noun) (N) (0 (V)) ;
178 ADD (@noun) (N) ;
179
180 SECTION
181 REMOVE (@noun) IF (0 (V)) ;
182 </screen>
183 Since ADD is in a SECTION it will be run again after REMOVE, and since ADD does not block from further
184 appending of mapping tags it can re-add @noun each time, leading to REMOVE finding it and removing,
185 ad nauseum.
186 </para>
187 <para>
188 In order to prevent this, the REMOVE rule can in most cases be rewritten to:
189 <screen>
190 REMOVE (N) IF (0 (@noun) + (N)) (0 (V)) ;
191 </screen>
192 That is, the target of the REMOVE rule should be a non-mapping tag with the mapping tag as 0 context.
193 This will either remove the entire reading or nothing, as opposed to a single mapping tag, and will not
194 cause the grammar to rewind.
195 </para>
196 <para>
197 Similarly, it is possible to make loops with APPEND and SELECT/REMOVE/IFF combinations, and probably
198 many other to-be-discovered mixtures of rules. Something to be aware of.
199 </para>
200 </section>
201
202 <section id="gotcha-mapping-visibility">
203 <title>Visibility of Mapped Tags</title>
204 <para>
205 In CG-1, CG-2, and VISLCG it was not always clear when you could refer to a previously mapped in the same
206 grammar. In VISL CG-3 all changes to readings become visible to the rest of the grammar immediately.
207 </para>
208 </section>
209
210 <section id="gotcha-cc-vs-cstar">
211 <title>Contextual position 'cc' vs. 'c*'</title>
212 <para>
213 The contextual positions '<link linkend="dep-ct-descendents">cc</link>' and
214 '<link linkend="dep-ct-deep">c*</link>' may at first glance seem to behave exactly the same,
215 but there is a subtle difference when combined with the
216 <link linkend="dep-ct-leftof">left-of/right-of filters</link> that can lead to wildly different cohorts
217 being chosen in rules asking for TO/FROM contextual targets:
218 </para>
219 <para>
220 <emphasis>cc</emphasis> will first create a complete list of all children and grand-children, then apply
221 any left-of/right-of filters.
222 </para>
223 <para>
224 <emphasis>c*</emphasis> will apply left-of/right-of filters at each step down the child tree, not
225 following any branch which doesn't uphold the filter.
226 </para>
227 </section>
228 </section>
229
230 <section id="incompatibilites">
231 <title>Incompatibilites</title>
232
233 <section id="incompat-mapping">
234 <title>Mappings</title>
235 <para>
236 The CG-2 spec says that readings in the format
237 <screen>
238 "word" tag @MAP @MUP ntag @MIP
239 </screen>
240 should be equivalent to
241 <screen>
242 "word" tag @MAP
243 "word" tag @MUP
244 "word" tag ntag @MIP
245 </screen>
246 </para>
247
248 <para>
249 Since the tag order does not matter in CG-3, this is instead equivalent to
250 <screen>
251 "word" tag ntag @MAP
252 "word" tag ntag @MUP
253 "word" tag ntag @MIP
254 </screen>
255 </para>
256 </section>
257
258 <section id="incompat-baseforms">
259 <title>Baseforms &amp; Mixed Input</title>
260 <para>
261 The CG-2 spec says that the first tag of a reading is the baseform, whether it looks like
262 [baseform] or "baseform".
263 This is not true for CG-3; only "baseform" is valid.
264 </para>
265
266 <para>
267 The reason for this is that CG-3 has to ignore all meta text such as XML, and the only way I can be sure
268 what is a reading and what is meta text is to declare that a reading is only valid in the forms of
269 <screen>
270 "baseform" tag tags moretags
271 "base form" tag tags moretags
272 </screen>
273 and not in the forms of
274 <screen>
275 [baseform] tag tags moretags
276 baseform tag tags moretags
277 </screen>
278 </para>
279
280 </section>
281 </section>
282
283 </chapter>