[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [wsbpel] Issue - 149 - adding formal <documentation> supportto BPEL
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. > > >> > >> > > > > 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]