_XML_ Library
=============

Basic XML Data Types
====================

Document:
       This structure represents an XML document.  The only useful part is
       the document-element, which contains all the content.  The rest of
       of the structure contains DTD information, which isn't supported,
       and processing-instructions.

Element:
       Each pair of start/end tags and everything in between is an element.
       It has the following pieces:
              a name
              attributes
              contents including sub-elements
Xexpression:
       S-expression representations of XML data.

The end of this document has more details.

Functions
=========

> read-xml : [Input-port] -> Document
       reads in an XML document from the given or current input port
       XML documents contain exactly one element.  It throws an xml-read:error
       if there isn't any element or if there are more than one element.

> write-xml : Document [Output-port] -> Void
       writes a document to the given or current output port, currently
       ignoring everything except the document's root element.

> write-xml/content : Content [Output-port] -> Void
       writes a document's contents to the given or current output port

> display-xml : Document [Output-port] -> Void
       just like write-xml, but newlines and indentation make the output more
       readable, though less technically correct when white space is
       significant.

> display-xml/content : Content [Output-port] -> Void
       just like write-xml/content, but with indentation and newlines

> xml->xexpr : Content -> Xexpr
       converts the interesting part of an XML document into an Xexpression

> xexpr->xml : Xexpr -> Content
       converts an Xexpression into the interesting part of an XML document

Parameters
==========

> empty-tag-shorthand : Bool
       Default: #t
       This determines if the output functions should use the <empty/> tag
       notation instead of writing <empty></empty>.  The first form is the
       preferred XML notation.  However, it's not part of HTML, so this
       parameter provides backward compatability.

Exceptions
==========

> xml-read:error is thrown by read-xml if the document is not well formed.
  (define-struct (xml-read:error struct:exn) ())

Examples
========

Reading an Xexpression:
       (xml->xexpr (document-element (read-xml input-port)))

Writing an Xexpression:
       (write-xml/content (xexpr->xml `(html (head (title ,banner))
					     (body ((bgcolor "white"))
						   ,text)))
			  output-port)

What this Library Doesn't Provide
=================================

       Document Type Declaration (DTD) processing
       Reading documents with internal DTDs will raise an error
       Writing or displaying document headers
       Validation
       Proper reading of white space
       Reading user-defined entites
       Unicode support

XML Datatype Details
====================

Note: Users of the XML collection don't need to know most of these definitions.

Note: Xexpr is the only important one to understand.  Even then,
      Processing-instructions may be ignored.

> Xexpr ::= String
         |  (list* Symbol (listof (list Symbol String)) (list Xexpr))
         |  (cons Symbol (listof Xexpr)) ;; an element with no attributes
         |  Symbol ;; symbolic entities such as &nbsp;
         |  Number ;; numeric entities like &20;
         |  Comment
         |  Processing-instruction

> Processing-instruction ::= (make-pi Location Location String (list String))
  (define-struct (pi struct:source) (target-name instruction))

> Document ::= (make-document Prolog Element (listof Processing-instruction))
  (define-struct document (prolog element misc))

> Element ::= (make-element Location Location
			    Symbol
			    (listof Attribute)
			    (listof Content))
  (define-struct (element struct:source) (name attributes content))

> Attribute ::= (make-attribute Location Location Symbol String)
  (define-struct (attribute struct:source) (name value))

> Content ::= Pcdata
           |  Element
           |  Entity
           |  Comment
           |  Processing-instruction

> Pcdata ::= (make-pcdata Location Location String)
  (define-struct (pcdata struct:source) (string))

> Entity ::= (make-entity (U Nat Symbol))
  (define-struct entity (text))

> Comment ::= (make-comment String)
  (define-struct comment (text))

> Source ::= (make-source Location Location)
  (define-struct source (start stop))

> Location ::= Nat
            |  Symbol

Note: The following structures are neither fully supported nor very useful:

> Prolog ::= (make-prolog XMLDeclare (listof Processing-instruction) DocType
			  (listof Processing-instruction))
  (define-struct prolog (xml before-dtd dtd before-element))

> XMLDeclare ::= (make-xmlD String (U String #f) (U String #f))
              |  #f
  (define-struct xmlD (version encoding standalone))

> DocType ::= (make-doctype String ExtID Dtd)
           |  #f
  (define-struct doctype (root ext-id dtd))

> ExtID ::= (make-ext String String)
         |  #f
  (define-struct ext (location file-name))

> Dtd ::= (make-int (listof Char))
       |  #f
  (define-struct int (content))
