12. convert
Prev | Chapter 6. Commands written in the Java™ programming language | Next

## 12. convert

Parameter syntax:

    [ implicit_selection ]? [ S '#text' | element_name ]?

Converts text selection or selected nodes to argument node[3].

Unlike replace which creates an empty new element, convert transfers the content of the selection to the new element which is the result of the conversion.

More precisely, in the case of node selection:

- When a single element is selected, all its children (but not its attributes) are transferred to the result of the conversion.

  Example:

  "`<simpara>the <emphasis>little</emphasis> girl.</simpara>`"

  converted to `<para>` gives

  "`<para>the <emphasis>little</emphasis> girl.</para>`".

- When several nodes or a single non-element node are selected, all these nodes are given a new parent element which is the result of the conversion.

  Example:

  "`<simpara>Once upon a time.</simpara>`"

  plus

  "`<simpara>the <emphasis>little</emphasis> girl.</simpara>`"

  can be converted to `<blockquote>` and that gives us

  "`<blockquote><simpara>Once upon a time.</simpara><simpara>the <emphasis>little</emphasis> girl.</simpara></blockquote>`".

Examples:

    convert emphasis
    convert [implicitElement] #text

See also command wrap, a variant of command convert which has a different behavior in the case of single element selection.

[3] Note that, unlike commands insert, replace, add, a `#template()` argument is not supported by command convert.

Prev | Up | Next
11. confirm | Home | 13. convertCase