Re: MORE ACTION NEEDED (Uli): Better Examples for Insert and Delete

John,

I reworked the remaining examples according to your suggestions and
applied some minor fixes to the first four you already worked out. I
hope they are much clearer now. Thanks again for your valuable input.

Attached are the files. Note I renamed some of them again, so index.xml
also changed.

Regards,
Uli.

John Boyer wrote:
> 
> Hi Uli,
> 
> I've done a fair bit of work to incorporate the insert/delete examples
> into the spec.  I added them into a normative appendix rather than
> directly to the actions chapter because then insert and delete look more
> like the other action descriptions.  The appendix also allowed me the
> space to divide your examples into subsections for readability.
> 
> I removed your example about keeping a repeat non-empty because that
> exists already in the delete section.
> 
> I made quite a few changes to the first four examples, including some
> error corrections and quite a bit of format changes to enhance
> readability.  The main goal of these examples is, I think, to provide
> ease-to-understand usage patterns of insert and delete for common
> operations.  I have done all the work on the first four patterns to show
> how it should be done, and I would like to ask you to please get the
> source bundle [1] and do the same operations on the remaining 11 patterns.
> 
> [1] http://www.w3.org/MarkUp/Forms/specs/XForms1.1/xforms11.full.zip
> 
> Here are the things that need to be done (again, look to the first four
> to see how to do these things):
> 
> 1) Please rename the id attributes in each div2 to match the file name.
> 
> 2) Move the head element from the example to the first child of the
> div2, and give a title appropriate for the filename. I renamed some of
> your examples using the filename; please make the title match (e.g.
> change insert attribute list to copy attribute list).
> 
> 3) Start out by presenting a pattern that describes the general case.
> Consider whether your current 'operation' really is the general case and
> amend as needed (e.g. you will undoubtedly notice that my changes to the
> first four patterns were based on the need for better generalization).
>  Also, use the same markup I did to make the pattern more readable.
> 
> 4) Put the "Operation" first, and describe the operation.
> 
> 5) Remove unnecessary markup from the operation.  Remove trigger, label,
> and repeat.  Instead of using index() in at, use an exact number.  You
> can consider doing an 'alternate' version that uses index() if you
> really want, but all this extra markup is making it hard for people to
> quickly digest the material.
> 
> 6) Change the title of Starting data and Ending data to "Data Before
> Operation" and "Data After Operation"
> 
> 7) Show what changed between the before and after cases using the same
> markup as I used.  In the case of removing data, put the special markup
> in the "Data Before Operation" so we can see what got removed.  For the
> Move cases, highlight where it is in both the before and after cases.
> 
> 8) Put the main instance data *before* any prototype instances, and
> remove the id from the main data.  Fix the examples so that they do not
> call the instance function to get at the main data.  It is categorically
> too nerdy to invoke instance() on the main data.  
> 
> 9) Try not to use context if the nodeset indicates an exact node (i.e.
> if it is OK to no-op when nodeset returns empty).  We only use context
> on prepend and append because the parent node may have no children.
> 
> 10) Move xmlns="" from xforms:instance to the root of your data.  I know
> the old examples had xmlns="" on xforms:instance, but I have been seeing
> people in the field who copy/paste our data into a context that does not
> have xmlns="", and then everything stops working for them and they think
> XForms is hard when in fact they are being bitten by a property of XML.
>  Still, best to avoid trouble here.
> 
> 11) Consider removing your "Equivalent Operations" .  In the first few I
> did, I found they were not equivalent, just similar (e.g. insert using
> just nodeset really isn't the same as using context and nodeset).  Only
> add an alternate version if you need to show something important.
> 
> 12) Get rid of all the occurrences of ...  They don't add anything of
> value.
> 
> 13) I think the nodeset in B9 copy attribute list is wrong.  Remove @*,
> right?
> 
> 14) Remove unnecessary attributes, like position="after" in Replace
> Element.  Also, put [1] in the nodeset of insert and delete rather than
> bothering with at because the general case pattern will say that nodeset
> indicates the exact node to replace.
> 
> 15) I think your intent with the nodeset in replace attribute is to make
> the operation not work unless the attribute being replaced exists.  If
> so, make sure the description of the operation says this.  Similarly,
> some kind of note in replace element should say that if the element
> doesn't exist, then the insert will no-op, but so will the delete.
> 
> 16) In the last example, please add a bit more data so that we show both
> non-contiguous selection from a heterogeneous nodeset operation at the
> same time.  Break the document into two chapters, and have a header and
> then intermixed diagram and paragraph elements.  Let the first child
> after header in the second chapter be a diagram.  Make the nodeset bind
> to all diagram AND paragraph children, then use at to select the first
> diagram in the second chapter.  Set origin to add a new paragraph, and
> set position to before.  Show that the new paragraph is parented by the
> second chapter.
> 
> Add a note or some such to explain that the nodeset can have nodes with
> different local names and different parents, and that in such a case the
> parent of the new node is the same as the parent of the insert location
> node selected by the combination of nodeset and at.
> 
> Thanks for all of your help so far, and for all of these additional
> measures.
> 
> John M. Boyer, Ph.D.
> STSM: Lotus Forms Architect and Researcher
> Chair, W3C Forms Working Group
> Workplace, Portal and Collaboration Software
> IBM Victoria Software Lab
> E-Mail: boyerj@ca.ibm.com  
> 
> Blog: http://www.ibm.com/developerworks/blogs/page/JohnBoyer
<snip/>
-- 
Ulrich Nicolas Lissé