[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [wsbpel] Issue - 149 - adding formal <documentation> supportto BPEL
|
Hi, all, I agree that we don't need to say about the preference of XHTML over HTML in our spec. I guess we would still like to say that the following: ---------------------------- The content of <documentation> are for human-consumption. Example types for those content are: plain text, HTML and XHTML. Tools-implementation specific information (e.g. the graphical layout details) should be added through the general extension mechanism. (i.e. bpws:tExtensibleElements). ---------------------------- I guess the description of the documentation field is non-invasive enough for the BPEL spec now. Does it make sense to you guys now? If so, I will make a formal proposal to vote. Thanks! Regards, Alex Yiu P.S.: There are two examples of <documentation> of XML Schema (Part 1) spec. One is plain text. Another one is XHTML. E.g.: <annotation> <documentation> <html:p>[Some documentation for my schema]</html:p> </documentation> </annotation> Therefore mentioning XHTML as one of the example is not too much. Thanks again! Satish Thatte wrote: +1 to Paco. We should limit ourselves to problems that only BPEL can solve in its own domain. ________________________________ From: Francisco Curbera [mailto:curbera@us.ibm.com] Sent: Wed 7/28/2004 2:12 PM To: wsbpel@lists.oasis-open.org Subject: RE: [wsbpel] Issue - 149 - adding formal <documentation> support to BPEL I agree that constraining documentation contents is not a very good idea. WSDL 2.0 and XML Schema allow arbitrary mixed content to be specified. I think this should be enough for us as well. In fact I don't see much point in even recommending a particular documentation format; I am not saying it may not be useful (like so many other things), just that is essentially not a BPEL problem. Paco "Tony Fletcher" <tony_fletcher@btope To: <wsbpel@lists.oasis-open.org> nworld.com> cc: Subject: RE: [wsbpel] Issue - 149 - adding formal <documentation> support to BPEL 07/27/2004 08:17 PM Dear Alex, Yaron and other Colleagues, If we add a documentation element, which I would support (I think at present - though not strongly so I could be persuaded it is not a good idea) I wonder if it is either wise, or possible to really restrict the content. I would agree with the specification making a recommendation or 'best practice' statements, but it seems to me that ultimately all the specification can positively state is the negative (!). That is, that the documentation element shall not contain any other BPEL specification defined elements as children. Best Regards Tony A M Fletcher Cohesions (TM) Business transaction management software for application coordination www.choreology.com Choreology Ltd., 68 Lombard Street, London EC3V 9LJ UK Tel: +44 (0) 1473 729537 Fax: +44 (0) 870 7390077 Mobile: +44 (0) 7801 948219 tony.fletcher@choreology.com (Home: amfletcher@iee.org) -----Original Message----- From: Alex Yiu [mailto:alex.yiu@oracle.com] Sent: 23 July 2004 00:18 To: ygoland@bea.com Cc: wsbpel@lists.oasis-open.org; Alex Yiu Subject: Re: [wsbpel] Issue - 149 - adding formal <documentation> support to BPEL Got it and agree. Explicitly express preference to XHTML over HTML, while people can still just use plain text, if they want. Regards, Alex Yiu Yaron Y. Goland wrote:I am not suggesting that it only be XHTML. Rather, I am suggestion that we explicitly suggest to people that XHTML would be a good choice. What is especially nice about XHTML is that it is self identifying. E.g. a well formed XHTML document should look something like: <html xmlns="http://www.w3.org/1999/xhtml"" xml:lang="en" lang="en"> <head>... </head> <body>... </body> </html> The root element, html from the http://www.w3.org/1999/xhtml namespace clearly tells the BPEL engine what it should expect. On the other hand how should a BPEL engine interpret: <documentation>This is an <b>important</b> note!</documentation> Is that a text string? Is it a HTML fragment? Who knows. It really comes down to - how do we want tools to decide on the 'type' of the content in a documentation node? Alex Yiu wrote: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. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]