Proposed declarative text for <insert/>

What follows is 330 words of declarative description, to replace the 700 
words of procedural text at 
https://www.w3.org/community/xformsusers/wiki/XForms_2.0#The_insert_Element
Maybe you can check to see if you can spot any cases I missed.



What I also propose is to merge the examples from 
https://www.w3.org/community/xformsusers/wiki/XForms_2.0#Patterns_for_Data_Mutations_(Non-Normative) 
into this section, so that it is all together in one place. 


I have also included the text as an attachment, in case the W3C mail 
interface messes with the layout.


Steven



The insert action inserts items into an instance, and has 5 attributes, all 
optional:

ref or bind that gives a destination sequence (default an empty sequence);
context, that gives the context for the ref (default the element context);
origin, evaluated in the in-scope evaluation context, that specifies a 
source sequence, (default, the last item in the destination sequence);
at, that specifies a numeric location in the destination sequence for the 
insertion (default, the size of the destination sequence);
position, whether to insert before or after the destination location 
(default after).

After successful conclusion, an xforms-insert event is dispatched to the 
destination instance with appropriate context information, including a list 
of the items inserted.

An insert action has no effect if:

the source sequence is empty (which includes the destination sequence being 
empty, with no non-default source sequence);
the destination location, or its parent is read-only;
the at attribute, evaluated as a number in the Element Evaluation Context 
and rounded to the nearest integer, is not a number or is out of bounds of 
a non-empty destination sequence.

Each item of the source sequence is inserted:

next to the destination location, if the destination sequence is non-empty,
into the context node otherwise, ignoring at and position.

If an item to be inserted is a node, it and its entire subtree are copied 
and inserted; if it is an atomic value, a text node is created and 
inserted.

An item is not inserted:

if it or the destination location is a root node (the parent of a root 
element);
if it doesn't match the location where it is being inserted (for instance, 
an attribute may not be a sibling of an element).

If the destination location is a root element, the item must be an element, 
and it replaces the destination element and its children, otherwise the 
item is not inserted.

If the destination sequence has sort properties, the inserted nodes will 
end up sorted accordingly, regardless of the at and position attributes.