xml-mkiv-commands.tex /size: 30 Kb    last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/xml
2
3\environment xml-mkiv-style
4
5\startcomponent xml-mkiv-commands
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{x-set-11.mkiv}) per January 2016:
44
45\startcolumns[n=2,balance=yes]
46\starttabulate[|l|r|]
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[|l|r|]
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 doesn't 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% \startxmlcmd {\cmdbasicsetup{xmltoparameters}}
211%     converts the match of \cmdinternal {cd:lpath} to key|/|values (for tracing)
212% \stopxmlcmd
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 {x-cals.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<?context-mathml-directive 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