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