1
2
3\environment xmlmkivstyle
4
5\startcomponent xmlmkivcommands
6
7\startchapter[title={Commands}]
8
9\startsection[title={nodes and lpaths}]
10
11The amount of commands available for manipulating the \XML\ file is rather large.
12Many of the commands cooperate with the already discussed setups, a fancy name
13for a collection of macro calls either or not mixed with text.
14
15Most of the commands are just shortcuts to \LUA\ calls, which means that the real
16work is done by \LUA. In fact, what happens is that we have a continuous transfer
17of control from \TEX\ to \LUA, where \LUA\ prints back either data (like element
18content or attribute values) or just invokes a setup whereby it passes a
19reference to the node resolved conform the path expression. The invoked setup
20itself might return control to \LUA\ again, etc.
21
22This sounds complicated but examples will show what we mean here. First we
23present the whole repertoire of commands. Because users can read the source code,
24they might uncover more commands, but only the ones discussed here are official.
25The commands are grouped in categories.
26
27In the following sections \cmdinternal {cd:node} means a reference to a node:
28this can be the identifier of the root (the loaded xml tree) or a reference to a
29node in that tree (often the result of some lookup. A \cmdinternal {cd:lpath} is
30a fancy name for a path expression (as with \XSLT) but resolved by \LUA.
31
32\stopsection
33
34\startsection[title={commands}]
35
36There are a lot of commands available but you probably can ignore most of them.
37We try to be complete which means that there is for instance \type {\xmlfirst} as
38well as \type {\xmllast} but you probably never need the last one. There are also
39commands that were used when testing this interface and we see no reason to
40remove them. Some obscure ones are used in modules and after a while even I often
41forget that they exist. To give you an idea of what commands are important we
42show their use in generating the \CONTEXT\ command definitions (\type
43{xset11.mkiv}) per January 2016:
44
45\startcolumns[n=2,balance=yes]
46\starttabulate[lr]
47\NC \type {\xmlall} \NC 1 \NC \NR
48\NC \type {\xmlatt} \NC 23 \NC \NR
49\NC \type {\xmlattribute} \NC 1 \NC \NR
50\NC \type {\xmlcount} \NC 1 \NC \NR
51\NC \type {\xmldoif} \NC 2 \NC \NR
52\NC \type {\xmldoifelse} \NC 1 \NC \NR
53\NC \type {\xmlfilterlist} \NC 4 \NC \NR
54\NC \type {\xmlflush} \NC 5 \NC \NR
55\NC \type {\xmlinclude} \NC 1 \NC \NR
56\NC \type {\xmlloadonly} \NC 1 \NC \NR
57\NC \type {\xmlregisterdocumentsetup} \NC 1 \NC \NR
58\NC \type {\xmlsetsetup} \NC 1 \NC \NR
59\NC \type {\xmlsetup} \NC 4 \NC \NR
60\stoptabulate
61\stopcolumns
62
63As you can see filtering, flushing and accessing attributes score high. Below we show
64the statistics of a quite complex rendering (5 variants of schoolbooks: basic book,
65answers, teachers guide, worksheets, full blown version with extensive tracing).
66
67\startcolumns[n=2,balance=yes]
68\starttabulate[lr]
69\NC \type {\xmladdindex} \NC 3 \NC \NR
70\NC \type {\xmlall} \NC 5 \NC \NR
71\NC \type {\xmlappendsetup} \NC 1 \NC \NR
72\NC \type {\xmlapplyselectors} \NC 1 \NC \NR
73\NC \type {\xmlatt} \NC 40 \NC \NR
74\NC \type {\xmlattdef} \NC 9 \NC \NR
75\NC \type {\xmlattribute} \NC 10 \NC \NR
76\NC \type {\xmlbadinclusions} \NC 3 \NC \NR
77\NC \type {\xmlconcat} \NC 3 \NC \NR
78\NC \type {\xmlcount} \NC 1 \NC \NR
79\NC \type {\xmldelete} \NC 11 \NC \NR
80\NC \type {\xmldoif} \NC 39 \NC \NR
81\NC \type {\xmldoifelse} \NC 28 \NC \NR
82\NC \type {\xmldoifelsetext} \NC 13 \NC \NR
83\NC \type {\xmldoifnot} \NC 2 \NC \NR
84\NC \type {\xmldoifnotselfempty} \NC 1 \NC \NR
85\NC \type {\xmlfilter} \NC 100 \NC \NR
86\NC \type {\xmlfirst} \NC 51 \NC \NR
87\NC \type {\xmlflush} \NC 69 \NC \NR
88\NC \type {\xmlflushcontext} \NC 2 \NC \NR
89\NC \type {\xmlinclude} \NC 1 \NC \NR
90\NC \type {\xmlincludeoptions} \NC 5 \NC \NR
91\NC \type {\xmlinclusion} \NC 16 \NC \NR
92\NC \type {\xmlinjector} \NC 1 \NC \NR
93\NC \type {\xmlloaddirectives} \NC 1 \NC \NR
94\NC \type {\xmlmapvalue} \NC 4 \NC \NR
95\NC \type {\xmlmatch} \NC 1 \NC \NR
96\NC \type {\xmlprependsetup} \NC 5 \NC \NR
97\NC \type {\xmlregisterdocumentsetup} \NC 2 \NC \NR
98\NC \type {\xmlregistersetup} \NC 1 \NC \NR
99\NC \type {\xmlremapnamespace} \NC 1 \NC \NR
100\NC \type {\xmlsetfunction} \NC 2 \NC \NR
101\NC \type {\xmlsetinjectors} \NC 2 \NC \NR
102\NC \type {\xmlsetsetup} \NC 11 \NC \NR
103\NC \type {\xmlsetup} \NC 76 \NC \NR
104\NC \type {\xmlstrip} \NC 1 \NC \NR
105\NC \type {\xmlstripanywhere} \NC 1 \NC \NR
106\NC \type {\xmltag} \NC 1 \NC \NR
107\NC \type {\xmltext} \NC 53 \NC \NR
108\NC \type {\xmlvalue} \NC 2 \NC \NR
109\stoptabulate
110\stopcolumns
111
112Here many more are used but this is an exceptional case. The top is again
113dominated by filtering, flushing and attribute consulting. The list can actually
114be smaller. For instance, the \type {\xmlcount} can just as well be \type
115{\xmlfilter} with a \type {count} finalizer. There are also some special ones,
116like the injectors, that are needed for finetuning the final result.
117
118\stopsection
119
120\startsection[title={loading}]
121
122\startxmlcmd {\cmdbasicsetup{xmlloadfile}}
123 loads the file \cmdinternal {cd:file} and registers it under \cmdinternal
124 {cd:name} and applies either given or standard \cmdinternal
125 {cd:xmlsetup} (alias: \type {\xmlload})
126\stopxmlcmd
127
128\startxmlcmd {\cmdbasicsetup{xmlloadbuffer}}
129 loads the buffer \cmdinternal {cd:buffer} and registers it under
130 \cmdinternal {cd:name} and applies either given or standard
131 \cmdinternal {cd:xmlsetup}
132\stopxmlcmd
133
134\startxmlcmd {\cmdbasicsetup{xmlloaddata}}
135 loads \cmdinternal {cd:text} and registers it under \cmdinternal
136 {cd:name} and applies either given or standard \cmdinternal
137 {cd:xmlsetup}
138\stopxmlcmd
139
140\startxmlcmd {\cmdbasicsetup{xmlloadonly}}
141 loads \cmdinternal {cd:text} and registers it under \cmdinternal
142 {cd:name} and applies either given or standard \cmdinternal
143 {cd:xmlsetup} but doesnt flush the content
144\stopxmlcmd
145
146\startxmlcmd {\cmdbasicsetup{xmlinclude}}
147 includes the file specified by attribute \cmdinternal {cd:name} of the
148 element located by \cmdinternal {cd:lpath} at node \cmdinternal {cd:node}
149\stopxmlcmd
150
151\startxmlcmd {\cmdbasicsetup{xmlprocessfile}}
152 registers file \cmdinternal {cd:file} as \cmdinternal {cd:name} and
153 process the tree starting with \cmdinternal {cd:xmlsetup} (alias:
154 \type {\xmlprocess})
155\stopxmlcmd
156
157\startxmlcmd {\cmdbasicsetup{xmlprocessbuffer}}
158 registers buffer \cmdinternal {cd:name} as \cmdinternal {cd:name} and process
159 the tree starting with \cmdinternal {cd:xmlsetup}
160\stopxmlcmd
161
162\startxmlcmd {\cmdbasicsetup{xmlprocessdata}}
163 registers \cmdinternal {cd:text} as \cmdinternal {cd:name} and process
164 the tree starting with \cmdinternal {cd:xmlsetup}
165\stopxmlcmd
166
167The initial setup defaults to \type {xml:process} that is defined
168as follows:
169
170\starttyping
171\startsetups xml:process
172 \xmlregistereddocumentsetups\xmldocument
173 \xmlmain\xmldocument
174\stopsetups
175\stoptyping
176
177First we apply the setups associated with the document (including common setups)
178and then we flush the whole document. The macro \type {\xmldocument} expands to
179the current document id. There is also \type {\xmlself} which expands to the
180current node number (\type {#1} in setups).
181
182\startxmlcmd {\cmdbasicsetup{xmlmain}}
183 returns the whole document
184\stopxmlcmd
185
186Normally such a flush will trigger a chain reaction of setups associated with the
187child elements.
188
189\stopsection
190
191\startsection[title={saving}]
192
193\startxmlcmd {\cmdbasicsetup{xmlsave}}
194 saves the given node \cmdinternal {cd:node} in the file \cmdinternal {cd:file}
195\stopxmlcmd
196
197\startxmlcmd {\cmdbasicsetup{xmltofile}}
198 saves the match of \cmdinternal {cd:lpath} in the file \cmdinternal {cd:file}
199\stopxmlcmd
200
201\startxmlcmd {\cmdbasicsetup{xmltobuffer}}
202 saves the match of \cmdinternal {cd:lpath} in the buffer \cmdinternal {cd:buffer}
203\stopxmlcmd
204
205\startxmlcmd {\cmdbasicsetup{xmltobufferverbose}}
206 saves the match of \cmdinternal {cd:lpath} verbatim in the buffer \cmdinternal
207 {cd:buffer}
208\stopxmlcmd
209
210
211
212
213
214The next command is only needed when you have messed with the tree using
215\LUA\ code.
216
217\startxmlcmd {\cmdbasicsetup{xmladdindex}}
218 (re)indexes a tree
219\stopxmlcmd
220
221The following macros are only used in special situations and are not really meant
222for users.
223
224\startxmlcmd {\cmdbasicsetup{xmlraw}}
225 flush the content if \cmdinternal {cd:node} with original entities
226\stopxmlcmd
227
228\startxmlcmd {\cmdbasicsetup{startxmlraw}}
229 flush the wrapped content with original entities
230\stopxmlcmd
231
232\stopsection
233
234\startsection[title={flushing data}]
235
236When we flush an element, the associated \XML\ setups are expanded. The most
237straightforward way to flush an element is the following. Keep in mind that the
238returned values itself can trigger setups and therefore flushes.
239
240\startxmlcmd {\cmdbasicsetup{xmlflush}}
241 returns all nodes under \cmdinternal {cd:node}
242\stopxmlcmd
243
244You can restrict flushing by using commands that accept a specification.
245
246\startxmlcmd {\cmdbasicsetup{xmltext}}
247 returns the text of the matching \cmdinternal {cd:lpath} under \cmdinternal
248 {cd:node}
249\stopxmlcmd
250
251\startxmlcmd {\cmdbasicsetup{xmlpure}}
252 returns the text of the matching \cmdinternal {cd:lpath} under \cmdinternal
253 {cd:node} without \type {\Ux} escaped special \TEX\ characters
254\stopxmlcmd
255
256\startxmlcmd {\cmdbasicsetup{xmlflushtext}}
257 returns the text of the \cmdinternal {cd:node}
258\stopxmlcmd
259
260\startxmlcmd {\cmdbasicsetup{xmlflushpure}}
261 returns the text of the \cmdinternal {cd:node} without \type {\Ux} escaped
262 special \TEX\ characters
263\stopxmlcmd
264
265\startxmlcmd {\cmdbasicsetup{xmlnonspace}}
266 returns the text of the matching \cmdinternal {cd:lpath} under \cmdinternal
267 {cd:node} without embedded spaces
268\stopxmlcmd
269
270\startxmlcmd {\cmdbasicsetup{xmlall}}
271 returns all nodes under \cmdinternal {cd:node} that matches \cmdinternal
272 {cd:lpath}
273\stopxmlcmd
274
275\startxmlcmd {\cmdbasicsetup{xmllastmatch}}
276 returns all nodes found in the last match
277\stopxmlcmd
278
279\startxmlcmd {\cmdbasicsetup{xmlfirst}}
280 returns the first node under \cmdinternal {cd:node} that matches \cmdinternal
281 {cd:lpath}
282\stopxmlcmd
283
284\startxmlcmd {\cmdbasicsetup{xmllast}}
285 returns the last node under \cmdinternal {cd:node} that matches \cmdinternal
286 {cd:lpath}
287\stopxmlcmd
288
289\startxmlcmd {\cmdbasicsetup{xmlfilter}}
290 at a match of \cmdinternal {cd:lpath} a given filter \type {filter} is applied
291 and the result is returned
292\stopxmlcmd
293
294\startxmlcmd {\cmdbasicsetup{xmlsnippet}}
295 returns the \cmdinternal {cd:number}\high{th} element under \cmdinternal
296 {cd:node}
297\stopxmlcmd
298
299\startxmlcmd {\cmdbasicsetup{xmlposition}}
300 returns the \cmdinternal {cd:number}\high{th} match of \cmdinternal
301 {cd:lpath} at node \cmdinternal {cd:node}; a negative number starts at the
302 end (alias: \type {\xmlindex})
303\stopxmlcmd
304
305\startxmlcmd {\cmdbasicsetup{xmlelement}}
306 returns the \cmdinternal {cd:number}\high{th} child of node \cmdinternal {cd:node};
307 a negative number starts at the end
308\stopxmlcmd
309
310\startxmlcmd {\cmdbasicsetup{xmlpos}}
311 returns the index (position) in the parent node of \cmdinternal {cd:node}
312\stopxmlcmd
313
314\startxmlcmd {\cmdbasicsetup{xmldepth}}
315 returns the depth in the tree of \cmdinternal {cd:node}
316\stopxmlcmd
317
318\startxmlcmd {\cmdbasicsetup{xmlconcat}}
319 returns the sequence of nodes that match \cmdinternal {cd:lpath} at
320 \cmdinternal {cd:node} whereby \cmdinternal {cd:text} is put between each
321 match
322\stopxmlcmd
323
324\startxmlcmd {\cmdbasicsetup{xmlconcatrange}}
325 returns the \cmdinternal {cd:first}\high {th} upto \cmdinternal
326 {cd:last}\high {th} of nodes that match \cmdinternal {cd:lpath} at
327 \cmdinternal {cd:node} whereby \cmdinternal {cd:text} is put between each
328 match
329\stopxmlcmd
330
331\startxmlcmd {\cmdbasicsetup{xmlcommand}}
332 apply the given \cmdinternal {cd:xmlsetup} to each match of \cmdinternal
333 {cd:lpath} at node \cmdinternal {cd:node}
334\stopxmlcmd
335
336\startxmlcmd {\cmdbasicsetup{xmlstrip}}
337 remove leading and trailing spaces from nodes under \cmdinternal {cd:node}
338 that match \cmdinternal {cd:lpath}
339\stopxmlcmd
340
341\startxmlcmd {\cmdbasicsetup{xmlstripped}}
342 remove leading and trailing spaces from nodes under \cmdinternal {cd:node}
343 that match \cmdinternal {cd:lpath} and return the content afterwards
344\stopxmlcmd
345
346\startxmlcmd {\cmdbasicsetup{xmlstripnolines}}
347 remove leading and trailing spaces as well as collapse embedded spaces
348 from nodes under \cmdinternal {cd:node} that match \cmdinternal {cd:lpath}
349\stopxmlcmd
350
351\startxmlcmd {\cmdbasicsetup{xmlstrippednolines}}
352 remove leading and trailing spaces as well as collapse embedded spaces from
353 nodes under \cmdinternal {cd:node} that match \cmdinternal {cd:lpath} and
354 return the content afterwards
355\stopxmlcmd
356
357\startxmlcmd {\cmdbasicsetup{xmlverbatim}}
358 flushes the content verbatim code (without any wrapping, i.e. no fonts
359 are selected and such)
360\stopxmlcmd
361
362\startxmlcmd {\cmdbasicsetup{xmlinlineverbatim}}
363 return the content of the node as inline verbatim code; no further
364 interpretation (expansion) takes place and spaces are honoured; it uses the
365 following wrapper
366\stopxmlcmd
367
368\startxmlcmd {\cmdbasicsetup{startxmlinlineverbatim}}
369 wraps inline verbatim mode using the environment specified (a prefix \type
370 {xml:} is added to the environment name)
371\stopxmlcmd
372
373\startxmlcmd {\cmdbasicsetup{xmldisplayverbatim}}
374 return the content of the node as display verbatim code; no further
375 interpretation (expansion) takes place and leading and trailing spaces and
376 newlines are treated special; it uses the following wrapper
377\stopxmlcmd
378
379\startxmlcmd {\cmdbasicsetup{startxmldisplayverbatim}}
380 wraps the content in display verbatim using the environment specified (a prefix
381 \type {xml:} is added to the environment name)
382\stopxmlcmd
383
384\startxmlcmd {\cmdbasicsetup{xmlprettyprint}}
385 pretty print (with colors) the node \cmdinternal {cd:node}; use the \CONTEXT\
386 \SCITE\ lexers when available (\type {\usemodule [scite]})
387\stopxmlcmd
388
389\startxmlcmd {\cmdbasicsetup{xmlflushspacewise}}
390 flush node \cmdinternal {cd:node} obeying spaces and newlines
391\stopxmlcmd
392
393\startxmlcmd {\cmdbasicsetup{xmlflushlinewise}}
394 flush node \cmdinternal {cd:node} obeying newlines
395\stopxmlcmd
396
397\stopsection
398
399\startsection[title={information}]
400
401The following commands return strings. Normally these are used in tests.
402
403\startxmlcmd {\cmdbasicsetup{xmlname}}
404 returns the complete name (including namespace prefix) of the
405 given \cmdinternal {cd:node}
406\stopxmlcmd
407
408\startxmlcmd {\cmdbasicsetup{xmlnamespace}}
409 returns the namespace of the given \cmdinternal {cd:node}
410\stopxmlcmd
411
412\startxmlcmd {\cmdbasicsetup{xmltag}}
413 returns the tag of the element, without namespace prefix
414\stopxmlcmd
415
416\startxmlcmd {\cmdbasicsetup{xmlcount}}
417 returns the number of matches of \cmdinternal {cd:lpath} at node \cmdinternal
418 {cd:node}
419\stopxmlcmd
420
421\startxmlcmd {\cmdbasicsetup{xmlatt}}
422 returns the value of attribute \cmdinternal {cd:name} or empty if no such
423 attribute exists
424\stopxmlcmd
425
426\startxmlcmd {\cmdbasicsetup{xmlattdef}}
427 returns the value of attribute \cmdinternal {cd:name} or \cmdinternal
428 {cd:string} if no such attribute exists
429\stopxmlcmd
430
431\startxmlcmd {\cmdbasicsetup{xmlrefatt}}
432 returns the value of attribute \cmdinternal {cd:name} or empty if no such
433 attribute exists; a leading \type {#} is removed (nicer for tex)
434\stopxmlcmd
435
436\startxmlcmd {\cmdbasicsetup{xmlchainatt}}
437 returns the value of attribute \cmdinternal {cd:name} or empty if no such
438 attribute exists; backtracks till a match is found
439\stopxmlcmd
440
441\startxmlcmd {\cmdbasicsetup{xmlchainattdef}}
442 returns the value of attribute \cmdinternal {cd:name} or \cmdinternal
443 {cd:string} if no such attribute exists; backtracks till a match is found
444\stopxmlcmd
445
446\startxmlcmd {\cmdbasicsetup{xmlattribute}}
447 finds a first match for \cmdinternal {cd:lpath} at \cmdinternal {cd:node} and
448 returns the value of attribute \cmdinternal {cd:name} or empty if no such
449 attribute exists
450\stopxmlcmd
451
452\startxmlcmd {\cmdbasicsetup{xmlattributedef}}
453 finds a first match for \cmdinternal {cd:lpath} at \cmdinternal {cd:node} and
454 returns the value of attribute \cmdinternal {cd:name} or \cmdinternal
455 {cd:text} if no such attribute exists
456\stopxmlcmd
457
458\startxmlcmd {\cmdbasicsetup{xmllastatt}}
459 returns the last attribute found (this avoids a lookup)
460\stopxmlcmd
461
462\startxmlcmd {\cmdbasicsetup{xmlsetatt}}
463 set the value of attribute \cmdinternal {cd:name}
464\stopxmlcmd
465
466\startxmlcmd {\cmdbasicsetup{xmlsetattribute}}
467 set the value of attribute \cmdinternal {cd:name} for each match of \cmdinternal
468 {cd:lpath}
469\stopxmlcmd
470
471\stopsection
472
473\startsection[title={manipulation}]
474
475You can use \LUA\ code to manipulate the tree and it makes no sense to duplicate
476this in \TEX. In the future we might provide an interface to some of this
477functionality. Keep in mind that manipuating the tree might have side effects as
478we maintain several indices into the tree that also needs to be updated then.
479
480\stopsection
481
482\startsection[title={integration}]
483
484If you write a module that deals with \XML, for instance processing cals tables,
485then you need ways to control specific behaviour. For instance, you might want to
486add a background to the table. Such directives are collected in \XML\ files and
487can be loaded on demand.
488
489\startxmlcmd {\cmdbasicsetup{xmlloaddirectives}}
490 loads \CONTEXT\ directives from \cmdinternal {cd:file} that will get
491 interpreted when processing documents
492\stopxmlcmd
493
494A directives definition file looks as follows:
495
496\starttyping
497<?xml version="1.0" standalone="yes"?>
498
499<directives>
500 <directive attribute=id value="100"
501 setup="cdx:100">
502 <directive attribute=id value="101"
503 setup="cdx:101">
504 <directive attribute=cdx value="colors" element="cals:table"
505 setup="cdx:cals:table:colors">
506 <directive attribute=cdx value="vertical" element="cals:table"
507 setup="cdx:cals:table:vertical">
508 <directive attribute=cdx value="noframe" element="cals:table"
509 setup="cdx:cals:table:noframe">
510 <directive attribute=cdx value="*" element="cals:table"
511 setup="cdx:cals:table:*">
512<directives>
513\stoptyping
514
515Examples of usage can be found in \type {xcals.mkiv}. The directive is triggered
516by an attribute. Instead of a setup you can specify a setup to be applied before
517and after the node gets flushed.
518
519\startxmlcmd {\cmdbasicsetup{xmldirectives}}
520 apply the setups directive associated with the node
521\stopxmlcmd
522
523\startxmlcmd {\cmdbasicsetup{xmldirectivesbefore}}
524 apply the before directives associated with the node
525\stopxmlcmd
526
527\startxmlcmd {\cmdbasicsetup{xmldirectivesafter}}
528 apply the after directives associated with the node
529\stopxmlcmd
530
531\startxmlcmd {\cmdbasicsetup{xmlinstalldirective}}
532 defines a directive that hooks into a handler
533\stopxmlcmd
534
535Normally a directive will be put in the \XML\ file, for instance as:
536
537\starttyping
538<?contextmathmldirective minus reduction yes ?>
539\stoptyping
540
541Here the \type {mathml} is the general class of directives and \type {minus} a
542subclass, in our case a specific element.
543
544\stopsection
545
546\startsection[title={setups}]
547
548The basic building blocks of \XML\ processing are setups. These are just
549collections of macros that are expanded. These setups get one argument passed
550(\type {#1}):
551
552\starttyping
553\startxmlsetups somedoc:somesetup
554 \xmlflush{#1}
555\stopxmlsetups
556\stoptyping
557
558This argument is normally a number that internally refers to a specific node in
559the \XML\ tree. The user should see it as an abstract reference and not depend on
560its numeric property. Just think of it as \quote {the current node}. You can (and
561probably will) call such setups using:
562
563\startxmlcmd {\cmdbasicsetup{xmlsetup}}
564 expands setup \cmdinternal {cd:setup} and pass \cmdinternal {cd:node} as
565 argument
566\stopxmlcmd
567
568However, in most cases the setups are associated to specific elements,
569something that users of \XSLT\ might recognize as templates.
570
571\startxmlcmd {\cmdbasicsetup{xmlsetfunction}}
572 associates function \cmdinternal {cd:luafunction} to the elements in
573 namespace \cmdinternal {cd:name} that match \cmdinternal {cd:lpath}
574\stopxmlcmd
575
576\startxmlcmd {\cmdbasicsetup{xmlsetsetup}}
577 associates setups \cmdinternal {cd:setup} (\TEX\ code) with the matching
578 nodes of \cmdinternal {cd:lpath} or root \cmdinternal {cd:node}
579\stopxmlcmd
580
581\startxmlcmd {\cmdbasicsetup{xmlprependsetup}}
582 pushes \cmdinternal {cd:setup} to the front of global list of setups
583\stopxmlcmd
584
585\startxmlcmd {\cmdbasicsetup{xmlappendsetup}}
586 adds \cmdinternal {cd:setup} to the global list of setups to be applied
587 (alias: \type{\xmlregistersetup})
588\stopxmlcmd
589
590\startxmlcmd {\cmdbasicsetup{xmlbeforesetup}}
591 pushes \cmdinternal {cd:setup} into the global list of setups; the
592 last setup is the position
593\stopxmlcmd
594
595\startxmlcmd {\cmdbasicsetup{xmlaftersetup}}
596 adds \cmdinternal {cd:setup} to the global list of setups; the last setup
597 is the position
598\stopxmlcmd
599
600\startxmlcmd {\cmdbasicsetup{xmlremovesetup}}
601 removes \cmdinternal {cd:setup} from the global list of setups
602\stopxmlcmd
603
604\startxmlcmd {\cmdbasicsetup{xmlprependdocumentsetup}}
605 pushes \cmdinternal {cd:setup} to the front of list of setups to be applied
606 to \cmdinternal {cd:name}
607\stopxmlcmd
608
609\startxmlcmd {\cmdbasicsetup{xmlappenddocumentsetup}}
610 adds \cmdinternal {cd:setup} to the list of setups to be applied to
611 \cmdinternal {cd:name} (you can also use the alias: \type
612 {\xmlregisterdocumentsetup})
613\stopxmlcmd
614
615\startxmlcmd {\cmdbasicsetup{xmlbeforedocumentsetup}}
616 pushes \cmdinternal {cd:setup} into the setups to be applied to \cmdinternal
617 {cd:name}; the last setup is the position
618\stopxmlcmd
619
620\startxmlcmd {\cmdbasicsetup{xmlafterdocumentsetup}}
621 adds \cmdinternal {cd:setup} to the setups to be applied to \cmdinternal
622 {cd:name}; the last setup is the position
623\stopxmlcmd
624
625\startxmlcmd {\cmdbasicsetup{xmlremovedocumentsetup}}
626 removes \cmdinternal {cd:setup} from the global list of setups to be applied
627 to \cmdinternal {cd:name}
628\stopxmlcmd
629
630\startxmlcmd {\cmdbasicsetup{xmlresetsetups}}
631 removes all global setups
632\stopxmlcmd
633
634\startxmlcmd {\cmdbasicsetup{xmlresetdocumentsetups}}
635 removes all setups from the \cmdinternal {cd:name} specific list of setups to
636 be applied
637\stopxmlcmd
638
639\startxmlcmd {\cmdbasicsetup{xmlflushdocumentsetups}{setup}}
640 applies \cmdinternal {cd:setup} (can be a list) to \cmdinternal {cd:name}
641\stopxmlcmd
642
643\startxmlcmd {\cmdbasicsetup{xmlregisteredsetups}}
644 applies all global setups to the current document
645\stopxmlcmd
646
647\startxmlcmd {\cmdbasicsetup{xmlregistereddocumentsetups}}
648 applies all document specific \cmdinternal {cd:setup} to document
649 \cmdinternal {cd:name}
650\stopxmlcmd
651
652\stopsection
653
654\startsection[title={testing}]
655
656The following test macros all take a \cmdinternal {cd:node} as first argument
657and an \cmdinternal {cd:lpath} as second:
658
659\startxmlcmd {\cmdbasicsetup{xmldoif}}
660 expands to \cmdinternal {cd:true} when \cmdinternal {cd:lpath} matches at
661 node \cmdinternal {cd:node}
662\stopxmlcmd
663
664\startxmlcmd {\cmdbasicsetup{xmldoifnot}}
665 expands to \cmdinternal {cd:true} when \cmdinternal {cd:lpath} does not match
666 at node \cmdinternal {cd:node}
667\stopxmlcmd
668
669\startxmlcmd {\cmdbasicsetup{xmldoifelse}}
670 expands to \cmdinternal {cd:true} when \cmdinternal {cd:lpath} matches at
671 node \cmdinternal {cd:node} and to \cmdinternal {cd:false} otherwise
672\stopxmlcmd
673
674\startxmlcmd {\cmdbasicsetup{xmldoiftext}}
675 expands to \cmdinternal {cd:true} when the node matching \cmdinternal
676 {cd:lpath} at node \cmdinternal {cd:node} has some content
677\stopxmlcmd
678
679\startxmlcmd {\cmdbasicsetup{xmldoifnottext}}
680 expands to \cmdinternal {cd:true} when the node matching \cmdinternal
681 {cd:lpath} at node \cmdinternal {cd:node} has no content
682\stopxmlcmd
683
684\startxmlcmd {\cmdbasicsetup{xmldoifelsetext}}
685 expands to \cmdinternal {cd:true} when the node matching \cmdinternal
686 {cd:lpath} at node \cmdinternal {cd:node} has content and to \cmdinternal
687 {cd:false} otherwise
688\stopxmlcmd
689
690\startxmlcmd {\cmdbasicsetup{xmldoifatt}}
691 expands to \cmdinternal {cd:true} when the attribute matching \cmdinternal
692 {cd:node} and the name given as second argument matches the third argument
693\stopxmlcmd
694
695\startxmlcmd {\cmdbasicsetup{xmldoifnotatt}}
696 expands to \cmdinternal {cd:true} when the attribute matching \cmdinternal
697 {cd:node} and the name given as second argument differs from the third
698 argument
699\stopxmlcmd
700
701\startxmlcmd {\cmdbasicsetup{xmldoifelseatt}}
702 expands to \cmdinternal {cd:true} when the attribute matching \cmdinternal
703 {cd:node} and the name given as second argument matches the third argument
704 and to \cmdinternal {cd:false} otherwise
705\stopxmlcmd
706
707\startxmlcmd {\cmdbasicsetup{xmldoifelseempty}}
708 expands to \cmdinternal {cd:true} when the node matching \cmdinternal
709 {cd:lpath} at node \cmdinternal {cd:node} is empty and to \cmdinternal
710 {cd:false} otherwise
711\stopxmlcmd
712
713\startxmlcmd {\cmdbasicsetup{xmldoifelseselfempty}}
714 expands to \cmdinternal {cd:true} when the node is empty and to \cmdinternal
715 {cd:false} otherwise
716\stopxmlcmd
717
718\startxmlcmd {\cmdbasicsetup{xmldoifselfempty}}
719 expands to \cmdinternal {cd:true} when \cmdinternal {cd:node} is empty
720\stopxmlcmd
721
722\startxmlcmd {\cmdbasicsetup{xmldoifnotselfempty}}
723 expands to \cmdinternal {cd:true} when \cmdinternal {cd:node} is not empty
724\stopxmlcmd
725
726\stopsection
727
728\startsection[title={initialization}]
729
730The general setup command (not to be confused with setups) that deals with the
731\MKIV\ tree handler is \type {\setupxml}. There are currently only a few options.
732
733\cmdfullsetup{setupxml}
734
735When you set \type {default} to \cmdinternal {cd:text} elements with no setup
736assigned will end up as text. When set to \type {hidden} such elements will be
737hidden. You can apply the default yourself using:
738
739\startxmlcmd {\cmdbasicsetup{xmldefaulttotext}}
740 presets the tree with root \cmdinternal {cd:node} to the handlers set up with
741 \type {\setupxml} option \cmdinternal{default}
742\stopxmlcmd
743
744You can set \type {compress} to \type {yes} in which case comment is stripped
745from the tree when the file is read.
746
747\startxmlcmd {\cmdbasicsetup{xmlregisterns}}
748 associates an internal namespace (like \type {mml}) with one given in the
749 document as \URL\ (like mathml)
750\stopxmlcmd
751
752\startxmlcmd {\cmdbasicsetup{xmlremapname}}
753 changes the namespace and tag of the matching elements
754\stopxmlcmd
755
756\startxmlcmd {\cmdbasicsetup{xmlremapnamespace}}
757 replaces all references to the given namespace to a new one (applied
758 recursively)
759\stopxmlcmd
760
761\startxmlcmd {\cmdbasicsetup{xmlchecknamespace}}
762 sets the namespace of the matching elements unless a namespace is already set
763\stopxmlcmd
764
765\stopsection
766
767\startsection[title={helpers}]
768
769Often an attribute will determine the rendering and this may result in many
770tests. Especially when we have multiple attributes that control the output such
771tests can become rather extensive and redundant because one gets $n\times m$ or
772more such tests.
773
774Therefore we have a convenient way to map attributes onto for instance strings or
775commands.
776
777\startxmlcmd {\cmdbasicsetup{xmlmapvalue}}
778 associate a \cmdinternal {cd:text} with a \cmdinternal {cd:category} and
779 \cmdinternal {cd:name} (alias: \type{\xmlmapval})
780\stopxmlcmd
781
782\startxmlcmd {\cmdbasicsetup{xmlvalue}}
783 expand the value associated with a \cmdinternal {cd:category} and
784 \cmdinternal {cd:name} and if not resolved, expand to the \cmdinternal
785 {cd:text} (alias: \type{\xmlval})
786\stopxmlcmd
787
788\startxmlcmd {\cmdbasicsetup{xmldoifelsevalue}}
789 associate a \cmdinternal {cd:text} with a \cmdinternal {cd:category} and
790 \cmdinternal {cd:name}
791\stopxmlcmd
792
793This is used as follows. We define a couple of mappings in the same category:
794
795\starttyping
796\xmlmapvalue{emph}{bold} {\bf}
797\xmlmapvalue{emph}{italic}{\it}
798\stoptyping
799
800Assuming that we have associated the following setup with the \type {emph}
801element, we can say (with \type {#1} being the current element):
802
803\starttyping
804\startxmlsetups demo:emph
805 \begingroup
806 \xmlvalue{emph}{\xmlatt{#1}{type}}{}
807 \endgroup
808\stopxmlsetups
809\stoptyping
810
811In this case we have no default. The \type {type} attribute triggers the actions,
812as in:
813
814\starttyping
815normal <emph type=bold>bold<emph> normal
816\stoptyping
817
818This mechanism is not really bound to elements and attributes so you can use this
819mechanism for other purposes as well.
820
821\stopsection
822
823\startsection[title={Parameters}]
824
825\startbuffer[test]
826<something whatever="alpha">
827 <what>
828 beta
829 <what>
830<something>
831\stopbuffer
832
833\startbuffer
834\startxmlsetups xml:mysetups
835 \xmlsetsetup{\xmldocument}{*}{xml:*}
836\stopxmlsetups
837
838\xmlregistersetup{xml:mysetups}
839
840\startxmlsetups xml:something
841 parameter : \xmlpar {#1}{whatever}\par
842 attribute : \xmlatt {#1}{whatever}\par
843 text : \xmlfirst {#1}{what} \par
844 \xmlsetpar{#1}{whatever}{gamma}
845 parameter : \xmlpar {#1}{whatever}\par
846 \xmlflush{#1}
847\stopxmlsetups
848
849\startxmlsetups xml:what
850 what: \xmlflush{#1}\par
851 parameter : \xmlparam{#1}{..}{whatever}\par
852\stopxmlsetups
853
854\xmlprocessbuffer{main}{test}{}
855\stopbuffer
856
857Say that we have this \XML\ blob:
858
859\typebuffer[test]
860
861With:
862
863\typebuffer
864
865we get:
866
867\getbuffer
868
869Parameters are stored with a node.
870
871\startxmlcmd {\cmdbasicsetup{xmlpar}}
872 returns the value of parameter \cmdinternal {cd:name} or empty if no such
873 parameter exists
874\stopxmlcmd
875
876\startxmlcmd {\cmdbasicsetup{xmlparam}}
877 finds a first match for \cmdinternal {cd:lpath} at \cmdinternal {cd:node} and
878 returns the value of parameter \cmdinternal {cd:name} or empty if no such
879 parameter exists
880\stopxmlcmd
881
882\startxmlcmd {\cmdbasicsetup{xmllastpar}}
883 returns the last parameter found (this avoids a lookup)
884\stopxmlcmd
885
886\startxmlcmd {\cmdbasicsetup{xmlsetpar}}
887 set the value of parameter \cmdinternal {cd:name}
888\stopxmlcmd
889
890\startxmlcmd {\cmdbasicsetup{xmlsetparam}}
891 set the value of parameter \cmdinternal {cd:name} for each match of \cmdinternal
892 {cd:lpath}
893\stopxmlcmd
894
895\stopsection
896
897\stopchapter
898
899\stopcomponent
900 |