RE: comment: documentation scenario and requirement

Ronald, thanks for pointing out this subtle, but important point. I will
add this as a draft requirement for WG consideration.

--Jeff

-----Original Message-----
From: Ronald Daniel [mailto:rdaniel@interwoven.com] 
Sent: Friday, May 03, 2002 9:12 AM
To: 'www-ws-desc@w3.org'
Subject: comment: documentation scenario and requirement

Quick comment on the requirements working draft... I did
not see anything in the scenarios and requirements
around the use of the <documentation> element. Don't think
its very controversial, we just want to make sure the
Schema for <wsdl:documentation> remains open.
At least one of the current WSDL compilers
silently fails when <documentation> elements contain markup,
so a test case covering this would be nice.

Suggested requirement:

The content model of <documentation> must be open to allow
people to insert markup of their choice.

Reason:  Current practice
We have written XSLT scripts that harvest those elements,
as well as contextual information, to generate documentation
which follows the xmlspec DTD. Others may want to go direct
to XHTML, or to other DTDs such as DocBook. Explanations of
messages, parts, ... may need multiple paragraphs or want to
use things like bulleted or numbered lists. The spec should
let people use whatever markup in their documentation that they
want.


Thanks,
Ron Daniel Jr.
Standards Architect
Interwoven, Inc.
803 11'th Ave.
Sunnyvale, CA, USA  94089
Tel: 408 530 5922
Cell: 925 368 8371 
Email: rdaniel@interwoven.com

Visit www.interwoven.com
The Leader in Enterprise Content Management

Received on Friday, 3 May 2002 19:10:01 UTC