RE: [wss] Schema examples in text

["Hallam-Baker, Phillip" <pbaker@verisign.com>]

Anthony Nadalin wrote:
> I have not heard an over a lot of votes for or  against the 
> proposal to use
> schema in place of the current examples. We need to take a 
> vote on this as
> it will take a somewhat large effort to do this change.
 


I did the SAML core spec where we have fragments in the text, my
conclusion is

1) It is a great help to people reading the specification
2) It is a complete and utter pain without automated tools
3) I have some tools for processing XML which could probably
	be modified for Word that I wrote for doing XKMS.

To modify them what I need is some definitive description of
how to link to an external file using Word.

The scheme I suggest is to take the schema and put it through
the parsing tool to create a series of fragments based on
XML comments, i.e the fragment:

	<!-- MessageAbstractType -->
	<complexType name="MessageAbstractType" abstract="true">
		<sequence>
			<element ref="ds:Signature" minOccurs="0"/>
			<element ref="xkms:OpaqueClientData"
minOccurs="0"/>
		</sequence>
	</complexType>
	<!-- /MessageAbstractType -->
	<!-- OpaqueClientData -->
	<element name="OpaqueClientData"
type="xkms:OpaqueClientDataType"/>
	<complexType name="OpaqueClientDataType">
		<sequence minOccurs="0" maxOccurs="unbounded">
			<element ref="xkms:OpaqueData" minOccurs="0"/>
		</sequence>
	</complexType>
	<element name="OpaqueData" type="base64Binary"/>
	<!-- /OpaqueClientData -->

Would be written out to two files, MessageAbstractType.html and
OpaqueClientData.html with appropriate lexical transformations
(already coded).

Then the word file would link to the html fragments.

We would do the same thing again with examples.

Another advantage of this approach is that by using the validating
reader I ensure that every example is correct (or at least matches
.NET's idea of correct, although at this point .NET has proved 
more accurate than xmlSpy.)

Only downside is that the tool requires the .NET framework.

		Phill

Attachment: smime.p7s
Description: application/pkcs7-signature