1. Reference

<command
  name = NMTOKEN
>
  Content: class | menu | macro | process
</command>

<macro
  trace = boolean : false
  repeatable = boolean : false
  undoable = boolean : false
  label = non empty token
>
  Content: choice | sequence
</macro>

<choice>
  Content: [ command|sequence|choice|pass|fail| 
             match|test|get|set ]+
</choice>

<sequence>
  Content: [ command|sequence|choice|pass|fail| 
             match|test|get|set ]+
</sequence>

<command
  name = NMTOKEN
  parameter = string
/>

<pass>
  Content: [ command|sequence|choice|pass|fail| 
             match|test|get|set ]+
</pass>

<fail>
  Content: [ command|sequence|choice|pass|fail| 
             match|test|get|set ]+
</fail>

<match
  context = XPath expr. returning a node set : "/"
  pattern = XSLT pattern
  antiPattern = boolean : false
/>

<test
  context = XPath expr. returning a node set : "/"
  expression = XPath expr. returning a boolean
/>

<get
  context = XPath expr. returning a node set : "/"
  expression = XPath expr. returning a string
/>

<set
  variable = QName
  context = XPath expr. returning a node set : "/"
  expression = XPath expression
  plainString = boolean : false
/>

Define, to make it simple, a sequence of native commands, menu commands, process commands or other macro-commands.

Attributes of macro:

trace

When specified with value true, this attribute causes the macro to print debug information on the console, which is extremely useful when developing a sophisticated macro.

repeatable

When specified with value true, this attribute marks the macro as being repeatable as a whole.

By default, macros are not marked as being repeatable as a whole because few macros really need this. For example, macros which are bound to a keystroke don't need to be marked repeatable.

undoable

When specified with value true, this attribute marks the macro as being undoable as a whole.

By default, macros are not marked as being undoable as a whole because few macros really need this. For example, macros which just select text or nodes, macros which are used to invoke process commands, macros which just perform a single editing action chosen by examining the editing context, don't need to be marked as undoable.

label

Label used by the GUI (example: the Edit popup menu) to refer to an undoable and/or repeatable macro-command.

If attribute label is not specified, a label is automatically generated by ``beautifying'' the name under which the macro-command has been registered.

Example 1: label "Transpose chars" is used for macro "transposeChars".

Example 2: label "Move list item down" is used for macro "docb.moveListItemDown". In this case, simple rules are used to recognize "docb." as a prefix and therefore to discard it from the generated label.

Simple child elements of macro:

sequence

Can be executed if its first child can be executed (See Execution of a command). Executes all its children one after the other.

Returns the result of its last child.

choice

Can be executed if any of its children can be executed. Execute the first child that can be executed.

Returns the result of its executed child.

pass

Can be executed if all its children can be executed. Execution does nothing at all: this element is just a test.

See pass and fail cheat sheet.

Returns the result of the last executed get, sequence, choice or command (that is, does not change %_).

fail

Can be executed if any of its children cannot be executed. Execution does nothing at all: this element is just a test.

Fail is the negation of pass. See pass and fail cheat sheet.

Returns the result of the last executed get, sequence, choice or command (that is, does not change %_).

XPath-based child elements of macro:

match

Can be executed if the context node matches specified XSLT pattern. Execution does nothing at all: this element is just a test.

If attribute antiPattern is specified with value true, this pseudo-command can be executed if the context node does not match specified pattern.

Returns the result of the last executed get, sequence, choice or command (that is, does not change %_).

The context and pattern attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

test

Can be executed if the specified expression evaluates to true given the context node. Execution does nothing at all: this element is just a test.

Returns the result of the last executed get, sequence, choice or command (that is, does not change %_).

The context and expression attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

get

Can be executed if there is a context node (that is, attribute context evaluates to a node). Execution returns the string value of specified expression.

The context and expression attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

set

Can be executed if there is a context node. Execution assigns to specified variable the value of specified expression.

Attribute variable specifies the qualified name of the variable to be assigned.

Caution

Do not specify: <set variable="$x" expression="2+2"/>. Specify: <set variable="x" expression="2+2"/>.

If attribute plainString is specified with value true, attribute expression is considered to contain a plain string rather than an XPath expression. In this case, expression is not evaluated before being assigned to the variable.

Returns nothing at all (that is, clears %_).

The context and expression attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

For the above XPath-based elements, the context node is the result of the context expression (evaluated using the document as its own context node).

If the context expression is not specified, the context node is the document itself.

If this context expression evaluates to multiple nodes, the context node is the first node of the node set in document order.

If this context expression evaluates to anything other than a node set, the match, test, get, set pseudo-commands cannot be executed.

If this context expression evaluates to a node which is not attached to a document or which is attached to a document other than the one for which the macro-command is executed, the match, test, get, set pseudo-commands cannot be executed.