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

John,

thanks for the input. I'm working on it.

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
> 
> 
> 
> 
> *Ulrich Nicolas Lissé <unl@dreamlab.net>*
> 
> 09/26/2007 07:36 AM
> 
> 	
> To
> 	John Boyer/CanWest/IBM@IBMCA
> cc
> 	ebruchez@orbeon.com, "Forms WG (new)" <public-forms@w3.org>
> Subject
> 	Re: ACTION NEEDED ((Erik, Uli): Better Examples for Insert and Delete
> 
> 
> 	
> 
> 
> 
> 
> 
> John, Erik, all,
> 
> I compiled some insert/delete examples. I hope they make a bit sense and
> are clear enough for our readers. Please review for errors.
> 
> I had a struggle with xmlspec rendering. I couldn't get a table layout
> working with example elements. Most of the examples wouldn't fit into a
> four-column table anyway.
> 
> The examples are broken down to seperate files. These can be included
> into actions.xml via entity expansion.
> 
> Regards,
> Uli.
> 
> John Boyer wrote:
>>
>> We had hoped to get some time on this during the face to face meeting,
>> but the last call issues proved too time consuming (though I would
>> characterize our progress as outstanding).
>>
>> This still leaves us in a precarious position of needing to have the
>> spec ready for CR transition before the publication moratorium that will
>> precede the tech plenary.  I need you, Erik and Uli, to help out by
>> creating that table of better examples for insert and delete.
>>
>> The idea is that we need
>>
>> 1) a list of the expected common operations
>> 2) develop the insert/delete calls for those operations
>> 3) a four column table that has the following columns
>>
>> i) operation description
>> ii) starting data
>> iii) insert or delete call
>> iv) ending data
>>
>> These operations will be potential targets for ease-of-authoring actions
>> in XForms 1.2.
>>
>> Starting tomorrow, I need you guys to please please please begin
>> exchanging some email on the list to work out the above, divide up the
>> subtasks and get this done.  We need to have an idea of how long it will
>> take given the "one day a week" commitment you and your organization made.
>>
>> P.S. Uli, it turns out that it is not Lotus Notes that is messing up the
>> accented e at the end of your name, but rather Shane's bug tracker.
>>
>> Cheers,
>> 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
>>
> 
> 
> -- 
> Ulrich Nicolas Lissé

-- 
Ulrich Nicolas Lissé

Received on Wednesday, 3 October 2007 13:26:15 UTC