6. Macro-variables

6. Macro-variables
	Chapter 2. Writing macro-commands

Variables which are referenced as "%variable_name" are macro-variables. They are referenced in the parameter of commands. They are substituted with their values before the command (or construct) is tested for execution and before the command (or construct) is actually executed.

We have already studied the "%_" variable. There are other macro-variables: "%0", "%1", "%*", "%d", etc.

Note that all macro-variables are predefined, which means that there is no way for a user to define its own macro-variables in its custom macros.

The following macro pastes after explicitly or implicitly element, the content of the clipboard after parsing this content as paragraphs. For example, if the clipboard contains several lines of text, each line can be converted to a paragraph. Such macro is useful to convert legacy documents to XML documents.

This macro is built using a sequence of commands formatTextAs and paste.

<command name="insertAfterAs">
  <macro>
    <sequence>
      <command name="formatTextAs" parameter="%0" />
      <command name="paste"
               parameter="after[implicitElement] %_" />
    </sequence>
  </macro>
</command>

<!-- template(para,PAA.para) is defined in the stock 
     DocBook 4 configuration. -->

<binding>
  <keyPressed code="F5" />
  <command name="insertAfterAs" 
           parameter="#template(para,PAA.para)" />
</binding>

Command formatTextAs has a mandatory parameter string which must be used to specify which paragraph element to create: is it XHTML p? Is it DocBook para? Is it DocBook simpara? Etc.

Macro insertAfterAsParagraphs has been made as generic as command formatTextAs because it must be passed a parameter string specifying which paragraph elements to create. This question is simply: how to reference the parameter string passed to a macro inside this macro? The answer is: use following macro-variables:

%*

is the value of the whole parameter string.

%0, %1, %2, ..., %9

are parts of the parameter string, split like what is done for command line arguments. For example, if parameter string is:

foo 'bar is a gee' "gee is a wiz"

%0 is "foo", %1 is "bar is a gee", %2 is "gee is a wiz" and %3, ..., %9 are substituted with the empty string.


5. The "%_" variable		7. Simple use of named variables