OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

wsbpel message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [wsbpel] Issue - 149 - adding formal <documentation> supportto BPEL



Thanks for agreeing with me in general.

Yes, I agree that the spec should say the documentation is the 
information for human consumption only.

Any tool proprietary information (e.g. screen layout) may be potentially 
added through the general BPEL extension mechanism.

And, the content of documentation is recommended to be plain-text, html, 
or XHTML. (I am still thinking whether XHTML only requirement is too 
strict? I don't have a strong opinion on this yet)

Regards,
Alex


Yaron Y. Goland wrote:

> This seems fairly reasonable to me but it does beg what I think is a 
> very important question - what presumptions about the human 
> readability of the contents of documentation is a tool allowed to make?
>
> In other words, would it be reasonable for someone hovering their 
> mouse over an activity in a BPEL editor to be displayed the contents 
> of the documentation element associated with that activity?
>
> If a tool wants to record some proprietary information (for example, 
> screen lay out data), should it record it in a documentation element 
> or in its own element outside of documentation?
>
> I suspect that documentation should be exclusively reserved for 
> information that is intended to be human readable. I would even go so 
> far as saying that we should recommend that all comments be expressed 
> as XHTML.
>
>     Yaron
>
> ws-bpel issues list editor wrote:
>
>>
>>
>> This issue has been added to the wsbpel issue list. The issues list 
>> is posted as a Technical Committee document to the OASIS WSBPEL TC 
>> pages <http://www.oasis-open.org/apps/org/workgroup/wsbpel> on a 
>> regular basis. The current edition, as a TC document, is the most 
>> recent version of the document entitled ** in the "Issues" folder of 
>> the WSBPEL TC document list 
>> <http://www.oasis-open.org/apps/org/workgroup/wsbpel/documents.php> - 
>> the next posting as a TC document will include this issue. The list 
>> editor's working copy, which will normally include an issue when it 
>> is announced, is available at this constant URL 
>> <http://www.choreology.com/external/WS_BPEL_issues_list.html>.
>>
>>
>>     Issue - 149 - adding formal <documentation> support to BPEL
>>
>> *Status:* open
>> *Categories:* Syntax and validation <#category_syntax_and_validation>
>> *Date added:* 20 Jul 2004
>> *Submitter:* Alex Yiu <mailto:alex.yiu@oracle.com>
>> *Date submitted:* 20 July 2004
>> *Description:* It would be a good idea to add a formal 
>> <documentation> element to all BPEL extensible elements. The element 
>> pattern will be based on XSD/annotation/documentation (which is 
>> slightly different from WSDL/documentation pattern). Hopefully, this 
>> suggestion is not controversial.
>> *Submitter's proposal:* Here is the suggested schema changes:
>>
>>     <import namespace="http://www.w3.org/XML/1998/namespace";         
>> schemaLocation="http://www.w3.org/2001/xml.xsd"; />
>>      <element name="documentation" id="documentation">
>>         <complexType mixed="true">
>>             <sequence minOccurs="0" maxOccurs="unbounded">
>>                    <any processContents="lax"/>
>>             </sequence>
>>             <attribute name="source" type="anyURI"/>
>>             <attribute ref="xml:lang"/>
>>         </complexType>
>>     </element>
>>     <complexType name="tExtensibleElements">
>>         <annotation>
>>             <documentation>
>>         This type is extended by other component types
>>         to allow elements and attributes from
>>         other namespaces to be added.
>>        </documentation>
>>         </annotation>
>>         <sequence>
>>             *<element ref="bpws:documentation" minOccurs="0" 
>> maxOccus="unbounded" />*
>>             <any namespace="##other" processContents="lax" 
>> minOccurs="0" maxOccurs="unbounded"/>
>>         </sequence>
>>         <anyAttribute namespace="##other" processContents="lax"/>
>>     </complexType>
>>
>>
>> *Changes:* 20 Jul 2004 - new issue
>>
>> To comment on this issue, please follow-up to this announcement on 
>> the wsbpel@lists.oasis-open.org list (replying to this message should 
>> automatically send your message to that list), or ensure the subject 
>> line as you send it *starts* "Issue - 149 - [anything]" or is a reply 
>> to such a message. If you want to formally propose a resolution, 
>> please start the subject line "Issue - 149 - Proposed resolution", 
>> without any Re: or similar.
>>
>> To add a new issue, see the issues procedures document (but the 
>> address for new issue submission is the sender of this announcement).
>>
>> To unsubscribe from this mailing list (and be removed from the roster 
>> of the OASIS TC), go to 
>> http://www.oasis-open.org/apps/org/workgroup/wsbpel/members/leave_workgroup.php. 
>>
>>
>
> To unsubscribe from this mailing list (and be removed from the roster 
> of the OASIS TC), go to 
> http://www.oasis-open.org/apps/org/workgroup/wsbpel/members/leave_workgroup.php. 
>
>



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]