xs3p

Release Notes for xs3p

Customisation

The xs3p stylesheet can be customised through its global parameters, which are listed below.

title

You can specify your own title for the document, rather than using the default one.

sortByComponent

If this parameter is set to "true", the schema components are presented sorted by type and name. Otherwise, they are presented in the order that they appear in the schema. By default, this parameter is set to "true."

useJavaScript

The generated XHTML document uses JavaScript to hide some details like the underlying schema component XML representation, which can be made to appear with a button press. Since some people have ideological objections to JavaScript, this feature can be turned off. If this parameter is set to "true", JavaScript will be used in the generated documentation. Otherwise, it won't. By default, this parameter is set to "true."

printAllSuperTypes

The type hierarchy of a global type definition is displayed in its section. If this parameter is set to "true", all super-types of the current type are shown in the type hierarchy. Otherwise, only the immediate parent type is displayed. By default, this parameter is set to "true."

printAllSubTypes

This parameter has a similar concept asprintAllSuperTypes. If it is set to "true", all sub-types of the current type are shown in the type hierarchy. Otherwise, only the direct sub-types are displayed. By default, this parameter is set to "true."

printLegend

If this parameter is set to "true", the Legend section is included. Otherwise, it isn't. By default, this parameter is set to "true."

printGlossary

If this parameter is set to "true", the Glossary section is included. Otherwise, it isn't. By default, this parameter is set to "true."

printNSPrefixes

If this parameter is set to "true", namespace information is provided when displaying sample instances and references. This is done by providing a prefix in front of tags and references, which when clicked, will take the user to the declared namespace. The prefix matches the prefix in the namespace declaration in the schema. If not set to "true", namespace prefixes are not displayed. By default, this parameter is set to "true."

printNSPrefixes

If this parameter is set to "true", namespace information is provided when displaying sample instances and references. This is done by providing a prefix in front of tags and references, which when clicked, will take the user to the declared namespace. The prefix matches the prefix in the namespace declaration in the schema. If not set to "true", namespace prefixes are not displayed. By default, this parameter is set to "true."

Constraints

(Translation: things that are not likely to be fixed)

• xs3p assumes that the input schema is valid with regards to the W3C recommendation. It does not do schema validity checking. This means that if the schema is not valid, it may generate erroneous output, such as the case when there are more than one schema component of the same type with the same name.
• In the generated XHTML documents, JavaScript code is placed inside XML comments, although strictly speaking, they should be placed inside CDATA sections. This is because current browsers do not support CDATA sections.
• xs3p cannot handle two dashes (--) inside the documentation elements of local schema components with JavaScript turned on. The reason is that the contents of thesedocumentation elements are displayed in a pop-up window using JavaScript. The JavaScript code is placed within an XML comment, which does not permit two dashes in it

Known Issues

(Translation: things that might be fixed eventually)

• xs3p does not handle inherited wildcards intelligently. If a type has a wildcard as well as one of its ancestors, both wildcards will be displayed.
• There is a similar problem for simple type restrictions. All inherited facets are displayed, even though a facet might be further restricted in a sub-type.
• Recursion is a hairy problem for xs3p. It can detect recursive group references, e.g.
  <xsd:group name="x">
<xsd:sequence>
<xsd:group ref="y"/>
</xsd:sequence>
</xsd:group>
<xsd:group name="y">
<xsd:sequence>
<xsd:element name="a" type="xs:string"/>
<xsd:element name="b" type="xs:string"/>
<xsd:group ref="x"/>
</xsd:sequence>
</xsd:group>
But not recursive type definitions nor attribute group references, e.g.
  <xsd:simpleType name="x">
<xsd:restriction base="x"/>
</xsd:simpleType>
<xsd:attributeGroup name="y">
<xsd:attribute name="a" type="xs:string"/>
<xsd:attribute name="b" type="xs:string"/>
<xsd:attributeGroup ref="x"/>
</xsd:attributeGroup>
The latter definitely is not schema-valid. However, instead of detecting the case and reporting an error, the case causes a nasty stack overflow.