Read Me

Document an XSD as HTML. 

Intro
-----
The stylesheet takes the documentation tags from an
XSD and presents them in a readable format with abundant links to
browse the documentation from parent to attribute and to child and
back to parent.

The main feature is that the documentation of the XSD may be
written in HTML and it will be presented as such in the
final HTML document.

This also serves as a good tutorial of a lot of the features of XSLT
- if of course you read the comments.

Usage
-----
1) Add a reference to the stylesheet in the XSD being documented e.g.
   add this just before the "xs:schema" tag in the XSD assuming the stylesheet
   resides in the same directory as the XSD.
  <?xml-stylesheet type="text/xsl"  href="xsd-doc.xslt"?>

2) Open the XSD in a web browser. The stylesheet will cause the XSD documentation
   to be displayed.

Details
-------
This stylesheet documents an XSD like this:

  0) Display a linked table of contents e.g. 
      Elements
      Attributes
      Structure
      Simple Types
    
  1) Display all the elements in a table of two columns:

     The first column is the element name linked to its place 
     in the overall XSD structure.

     The second column contains the element's documentation.

     Elements appear in the table in the same order as they 
     appear in the XSD.
  
  2) Display all the attributes in a table of two columns:

    The first column contains the attribute name followed
     by the encapsulating element e.g.
     "Age - Person" which means Age attribute of Person element.
     The name is linked to the attribute's place in the overall XSD structure.

     The second column contains the attribute's documentation. It also includes 
     information on the attribute's type and whther the attribute is compulsory or 
     not. If the attribute use a pattern to restrict its values then that is shown.
     If it uses an enumeration of values as the restriction, then the possible 
     values are shown.

     Attributes are sorted by
     a) by their name in alphabetic order
     and then by
     b) the order of their encapsulating element's appearance in the XSD
     e.g. "Name - Person" appears before "Name - Animal" in the table 'cos the element Person appears before
         the element Animal in the XSD.
         I find this order more useful than sorting by "b) the alphabetic order of the encapsulating element's name".

  3) Display the entire XSD structure - so for each element, display:
      a) The element's documentation
      b) A table of its attibutes along with their documentation.
      c) A table of its child elements (linked) along with documentation of the child's
         special relationship to the parent IF ANY.
      d) A table of links to its parents.

  4) Display a table containing info on top-level simple types. Two columns Name and Doc.

  5) A footnote relating to the "IF ANY" part of 3c above.

 Notes
 -----
 1) Including the text "NOT USED" exactly as shown but without the quotes in the documentation 
 for an element or an attribute prevents the element or attribute from being displayed.