14. convert

14. convert
	Chapter 6. Commands written in the Java™ programming language

Parameter syntax:

[ implicit_selection ]? [ S argument_node ]?

Converts text selection or selected nodes to argument node.

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, and also all compatible attributes, are transferred to the result of the conversion.
Example:
<simpara id="p1">the <emphasis>little</emphasis> girl.</simpara>
converted to para gives
<para id="p1">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 id="p1">the <emphasis>little</emphasis> girl.</simpara>
can be converted to blockquote and that gives us
<blockquote>
<simpara>Once upon a time.</simpara>
<simpara id="p1">the <emphasis>little</emphasis> girl.</simpara>
</blockquote>

Note that when argument node is an element template, command convert copies the attributes of the element template and ignores its child nodes.

Examples:

convert emphasis
convert [implicitElement] #text
convert #template({http://www.w3.org/1999/xhtml}span,highlight)

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


13. contextualMenu		15. convertCase