<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = standard xml module guide - appendix i                             = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="xml" number="i">
  <title>Standard xml reference</title>

  <p>
  This appendix is a reference of the <afnix/> standard xml module.
  </p>

  <table>
    <title>Standard xml module</title>
    <thead>
      <tr><td>Symbol</td> <td>Description</td></tr>
    </thead>
    <tbody>
      <tr><td>afnix-xml</td><td>module</td></tr>
      <tr><td>afnix:xml</td><td>nameset</td></tr>
    </tbody>
  </table>

  <!-- =================================================================== -->
  <!-- = xml node object                                                 = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlNode</name>

    <!-- synopsis -->
    <p>
    The <code>XmlNode</code> class is the base class used to represent
    the xml tree. The tree is built as a vector of nodes. Each node owns 
    as well its parent node. Walking in the tree is achieved by taking
    the child node and then moving to the child and/or next node. The
    node also manages an empty flags. It the empty flag is set, it is
    an error to add child nodes.
    </p>

    <!-- predicate -->
    <pred>node-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>write</name>
      <retn>none</retn>
      <args>none|Stream|Buffer</args>
      <p>
      The <code>write</code> method write the node contents as well as
      the child nodes to an output stream argument or a buffer. When
      node is written, the method attempts to use the stream encoding
      in such way that the contents fits into the requested output
      encoding. Without argument, the node is written to the
      interpreter output stream. with one argument, the node is
      written to the specified stream or buffer.
      </p>
    </method>

    <method>
      <name>name-p</name>
      <retn>Boolean</retn>
      <args>String</args>
      <p>
      The <code>name-p</code> predicate checks if the name matches the
      node name. Care should be taken that not all node have a name,
      and in such case, the false value is returned. This method is
      useful when the node is a tag.
      </p>
    </method>

    <method>
      <name>parse</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>parse</code> method parses the string argument and
      adds the results as a set of child node to the calling node. If
      the node is an empty node, the method will almost fail. This
      method should be used when an attempt is made to add some text
      that may contain some xml tags.
      </p>
    </method>

    <method>
      <name>get-parent</name>
      <retn>XmlNode</retn>
      <args>none</args>
      <p>
      The <code>get-parent</code> method returns the parent node. If
      the node is the root node, nil is returned.
      </p>
    </method>

    <method>
      <name>set-parent</name>
      <retn>none</retn>
      <args>XmlNode</args>
      <p>
      The <code>set-parent</code> method sets the parent node.
      </p>
    </method>

    <method>
      <name>add-child</name>
      <retn>none</retn>
      <args>XmlNode</args>
      <p>
      The <code>add-child</code> method adds a node argument as a
      child node to the calling node.
      </p>
    </method>

    <method>
      <name>get-child</name>
      <retn>XmlNode</retn>
      <args>Integer String</args>
      <p>
      The <code>t-child</code> method returns a child node by index or
      by name. If the calling argument is an integer, the node is
      returned by index. If the calling argument is a string, the node
      is returned by name. If the node cannot be found, nil is returned
      raised.
      </p>
    </method>

    <method>
      <name>nil-child-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>nil-child-p</code> predicate returns true if the node
      does not have a child node.
      </p>
    </method>

    <method>
      <name>lookup-child</name>
      <retn>XmlNode</retn>
      <args>String</args>
      <p>
      The <code>lookup-child</code> method returns a child node by
      name. Unlike the <code>get-child</code> method, the method
      raises an exception if the node cannot be found.
      </p>
    </method>

    <method>
      <name>child-length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>child-length</code> method returns the number of
      children nodes.
      </p>
    </method>

    <method>
      <name>get-source-line</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-source-line</code> method returns the node source
      line number if any.
      </p>
    </method>

    <method>
      <name>set-source-line</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-source-line</code> method sets the node source
      line number.
      </p>
    </method>

    <method>
      <name>get-source-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-source-name</code> method returns the node source
      name if any.
      </p>
    </method>

    <method>
      <name>set-source-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-source-name</code> method sets the node source
      name.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml tag object                                                  = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlTag</name>

    <!-- synopsis -->
    <p>
    The <code>XmlTag</code> class is the base class used to represent
    a xml tag. A tag is defined with a name and an attribute list. The
    tag is derived from the xml node class and is not marked empty by
    default.
    </p>

    <!-- predicate -->
    <pred>tag-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

   <!-- constructors -->
    <ctor>
      <name>XmlTag</name>
      <args>String</args>
      <p>
      The <code>XmlTag</code> constructor creates a tag node. The node
      is not marked empty.
      </p>
    </ctor>

    <ctor>
      <name>XmlTag</name>
      <args>String Boolean</args>
      <p>
      The <code>XmlTag</code> constructor creates a tag node. The
      first argument is the tag name. The second argument is the empty
      flag.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the tag name.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the tag name.
      </p>
    </method>

    <method>
      <name>add-attribute</name>
      <retn>none</retn>
      <args>Property</args>
      <p>
      The <code>add-attribute</code> method adds a new attribute to
      the tag. The attribute must be new for this method to
      succeed. In doubt, the <code>set-attribute</code> is
      preferable.
      </p>
    </method>

    <method>
      <name>set-attribute</name>
      <retn>none</retn>
      <args>String Literal</args>
      <p>
      The <code>set-attribute</code> method sets an attribute to
      the tag. The first argument is the attribute name. The second
      argument is the attribute value. If the attribute already exists,
      the old value is replaced with the new one.
      </p>
    </method>

    <method>
      <name>get-attribute</name>
      <retn>Property</retn>
      <args>Integer|String</args>
      <p>
      The <code>get-attribute</code> method returns a tag attribute in
      the form o a property object. With an integer object, the
      attribute is returned by index. With a string object, the
      property is return by name. If the property is not found, nil is
      returned.
      </p>
    </method>

    <method>
      <name>get-attribute-value</name>
      <retn>String</retn>
      <args>String</args>
      <p>
      The <code>get-attribute-value</code> method returns a tag
      attribute value by name. The string argument is the attribute
      name. If the property is not found, an exception is raised.
      </p>
    </method>

    <method>
      <name>lookup-attribute</name>
      <retn>Property</retn>
      <args>String</args>
      <p>
      The <code>lookup-attribute</code> method returns a tag
      attribute by name in the form of a property. The string argument
      is the attribute name. If the property is not found, an
      exception is raised.
      </p>
    </method>

    <method>
      <name>attribut-length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>attribute-length</code> method returns the number of
      attributes.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml text object                                                 = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlText</name>

    <!-- synopsis -->
    <p>
    The <code>XmlText</code> class is the xml text node. A text node
    is directly built by the xml reader and the content placed into a
    string. By definition, a text node is an empty node.
    </p>

    <!-- predicate -->
    <pred>text-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlText</name>
      <args>none</args>
      <p>
      The <code>XmlText</code> constructor creates a default text
      node. By definition, a text node is an empty node.
      </p>
    </ctor>

    <ctor>
      <name>XmlText</name>
      <args>String</args>
      <p>
      The <code>XmlText</code> constructor creates a text node with the
      string argument.  
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-xval</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-xval</code> method sets the text node value.
      </p>
    </method>

    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the text node value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml data object                                                 = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlData</name>

    <!-- synopsis -->
    <p>
    The <code>XmlData</code> class is the xml cdata node. A data node
    differs from the text node in the sense that the data node
    contains characters that could be reserved characters such like
    markup delimiters. The data node is most of the time used to hold
    text used for scripting. The data node is an empty node.
    </p>

    <!-- predicate -->
    <pred>data-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlData</name>
      <args>none</args>
      <p>
      The <code>XmlData</code> constructor creates a default data
      node. By definition, a data node is an empty node.
      </p>
    </ctor>

    <ctor>
      <name>XmlData</name>
      <args>String</args>
      <p>
      The <code>XmlData</code> constructor creates a data node with the
      string argument.  
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-xval</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-xval</code> method sets the data node value.
      </p>
    </method>

    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the data node value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml comment object                                              = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlComment</name>

    <!-- synopsis -->
    <p>
    The <code>XmlComment</code> class is the xml comment node. The
    comment node is a special node that holds the comment text. The
    comment node is an empty node.
    </p>

    <!-- predicate -->
    <pred>comment-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlComment</name>
      <args>none</args>
      <p>
      The <code>XmlComment</code> constructor creates a default comment
      node. By definition, a comment node is an empty node.
      </p>
    </ctor>

    <ctor>
      <name>XmlComment</name>
      <args>String</args>
      <p>
      The <code>XmlComment</code> constructor creates a comment node with the
      string argument.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-xval</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-xval</code> method sets the comment node value.
      </p>
    </method>

    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the comment node value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml doctype object                                              = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlDoctype</name>

    <!-- synopsis -->
    <p>
    The <code>XmlDoctype</code> class is the xml document type node.
    In its simplest form, the document type has just a name which acts
    the starting tag for the document. The document type can also be
    associated with a system or a public identifier. Note also that a
    local root node can be attached to this node.
    </p>

    <!-- predicate -->
    <pred>doctype-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlDoctype</name>
      <args>String</args>
      <p>
      The <code>XmlDoctype</code> constructor creates a document type
      with a starting tag name as the string argument. This is the
      simplest form of a document type definition.
      </p>
    </ctor>

    <ctor>
      <name>XmlDoctype</name>
      <args>String String</args>
      <p>
      The <code>XmlDoctype</code> constructor creates a document type
      with a starting tag name and a system identifier. The first
      string argument is the tag name. The second argument is the
      system identifier.
      </p>
    </ctor>

    <ctor>
      <name>XmlDoctype</name>
      <args>String String String</args>
      <p>
      The <code>XmlDoctype</code> constructor creates a document type
      with a starting tag name, a public and a system identifier. The first
      string argument is the tag name. The second argument is the
      public identifier. The third argument is the system identifier.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args> 
      <p>
      The <code>get-xval</code> method returns the document type
      starting tag name.
      </p>
    </method>

    <method>
      <name>get-public-id</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-public-id</code> method returns the document type
      public identifier.
      </p>
    </method>

    <method>
      <name>get-system-id</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-system-id</code> method returns the document type
      system identifier.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml processing object                                           = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlPi</name>

    <!-- synopsis -->
    <p>
    The <code>XmlPi</code> class is the xml processing node. The
    processing node is a tag node. Although a processing node is seen
    as tag with attributes, the specification describes the processing
    node as a special tag with a string value. The processing node is
    an empty node.
    </p>

    <!-- predicate -->
    <pred>pi-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlTag</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlPi</name>
      <args>String</args>
      <p>
      The <code>XmlPi</code> constructor creates a processing node with the
      name string argument.
      </p>
    </ctor>

    <ctor>
      <name>XmlPi</name>
      <args>String String</args>
      <p>
      The <code>XmlPi</code> constructor creates a processing node with the
      name string argument and the string value. The first argument is
      the tag name. The second argument is the processing node value.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-xval</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-xval</code> method sets the processing node value.
      </p>
    </method>

    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the processing node value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml declaration object                                          = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlDecl</name>

    <!-- synopsis -->
    <p>
    The <code>XmlDecl</code> class is the xml declaration node. The
    declaration node is a processing node. A declaration node is
    defined with a version id, an encoding string and a standalone
    flag. Each value is represented by an attribute at the tag level.
    </p>

    <!-- predicate -->
    <pred>decl-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlPi</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlDecl</name>
      <args>none</args>
      <p>
      The <code>XmlDecl</code> constructor creates a default
      declaration node. By default, the declaration node is set with
      the xml version 1.0, the UTF-8 encoding and the standalone flag
      is not set.
      </p>
    </ctor>

    <ctor>
      <name>XmlDecl</name>
      <args>String</args>
      <p>
      The <code>XmlDecl</code> constructor creates a declaration
      node with a version. The string argument is the xml version
      version which must be a supported one.
      </p>
    </ctor>

    <ctor>
      <name>XmlDecl</name>
      <args>String String</args>
      <p>
      The <code>XmlDecl</code> constructor creates a declaration
      node with a version and an encoding. The string argument is the
      xml version version which must be a supported one. The second
      argument is the xml encoding.
      </p>
    </ctor>

    <ctor>
      <name>XmlDecl</name>
      <args>String String String</args>
      <p>
      The <code>XmlDecl</code> constructor creates a declaration
      node with a version, an encoding and a standalone flag. The
      string argument is the xml version version which must be a
      supported one. The second argument is the xml encoding. The
      third argument is the standalone flag.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = xml reference object                                            = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlRef</name>

    <!-- synopsis -->
    <p>
    The <code>XmlRef</code> class is the xml reference node
    class. This class is a base class which cannot be instantiated
    directly. The class is designed to hold reference, the only
    element which is in common is the string representation.
    </p>

    <!-- predicate -->
    <pred>ref-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>set-xref</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-xref</code> method sets the node reference name.
      </p>
    </method>

    <method>
      <name>get-xref</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xref</code> method returns the node reference name.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml character reference object                                  = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlCref</name>

    <!-- synopsis -->
    <p>
    The <code>XmlCref</code> class is the xml character reference node
    class. Normally this class should only be used when building a xml
    tree manually. During a parsing process, the character reference is
    automatically expanded.
    </p>

    <!-- predicate -->
    <pred>cref-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlRef</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlCref</name>
      <args>none</args>
      <p>
      The <code>XmlCref</code> constructor creates a default
      character reference those value is the null character.
      </p>
    </ctor>

    <!-- constructors -->
    <ctor>
      <name>XmlCref</name>
      <args>Character|Integer</args>
      <p>
      The <code>XmlCref</code> constructor creates a character
      reference those value is the character or integer argument.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-value</name>
      <retn>none</retn>
      <args>Character|Integer</args>
      <p>
      The <code>set-value</code> method sets the character reference
      value by character or integer.
      </p>
    </method>

    <method>
      <name>get-value</name>
      <retn>Character</retn>
      <args>none</args>
      <p>
      The <code>get-value</code> method returns the character
      reference value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml entity reference object                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlEref</name>

    <!-- synopsis -->
    <p>
    The <code>XmlEref</code> class is the xml entity reference node
    class. The entity reference is defined with a reference name.
    </p>

    <!-- predicate -->
    <pred>eref-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlRef</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlEref</name>
      <args>none</args>
      <p>
      The <code>XmlCref</code> constructor creates an empty 
      entity reference.
      </p>
    </ctor>

    <!-- constructors -->
    <ctor>
      <name>XmlCref</name>
      <args>String</args>
      <p>
      The <code>XmlEref</code> constructor creates an entity
      reference those value is the string argument.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = xml section node object                                         = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlSection</name>

    <!-- synopsis -->
    <p>
    The <code>XmlSection</code> class is the xml section type node. A
    section node is used to model conditional section that are part of
    a dtd. The section value is a string that is evaluated by the xml
    processor. Most of the time, it is a parameter entity reference
    which corresponds to the keyword INCLUDE or IGNORE , but it could
    be anything else. A node is also attached to this section.
    </p>

    <!-- predicate -->
    <pred>section-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>xmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlSection</name>
      <args>String</args>
      <p>
      The <code>XmlSection</code> constructor creates a xml section
      node by value.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the section node value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml attribute list object                                       = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlAttlist</name>

    <!-- synopsis -->
    <p>
    The <code>XmlAttlist</code> class is the xml attribute list node
    class. A xml attribute list  is primarily defined with two
    names. The first name is the element and the second name is the
    attribute name. There are 3 types of attribute list. The string
    type, the token type and the enumeration type. The class manages
    each type by associating a type descriptor which is detected at
    construction.
    </p>

    <!-- predicate -->
    <pred>attlist-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlAttlist</name>
      <args>String String</args>
      <p>
      The <code>XmlAttlist</code> constructor creates an attribute list
      by element name and attribute name. The first argument is the
      element name. The second argument is the attribute name.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-element-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-element-name</code> method sets the attribute list
      element name.
      </p>
    </method>
      
    <method>
      <name>get-element-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-element-name</code> method returns the attribute list
      element name.
      </p>
    </method>

    <method>
      <name>set-attribute-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-attribute-name</code> method sets the attribute list
      name.
      </p>
    </method>
      
    <method>
      <name>get-attribute-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-attribute-name</code> method returns the attribute list
      name.
      </p>
    </method>

    <method>
      <name>set-type</name>
      <retn>none</retn>
      <args>String | Vector Boolean</args>
      <p>
      The <code>set-type</code> method set the attribute type by
      string or enumeration vector. In its first form, the attribute
      type is defined by a string. The type can be either, "CDATA",
      "ID", "IDREF", "IDREFS", "ENTITY", "ENTITIES", "NMTOKEN" or
      "NMTOKENS". In the second form, the attribute type is an
      enumeration those values are defined in the argument vector. The
      boolean argument controls the notation flag for that enumeration.
      </p>
    </method>

    <method>
      <name>set-default</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-default</code> method set the attribute value by
      string. The string can be any value or the special value
      "#IMPLIED" and "#REQUIRED". If the default value is fixed, the
      <code>set-fixed</code> is the preferred method. 
      </p>
    </method>

    <method>
      <name>set-fixed</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-fixed</code> method set the fixed attribute
      default value by string. 
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml root node object                                            = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlRoot</name>

    <!-- synopsis -->
    <p>
    The <code>XmlRoot</code> class is the top level root instantiated
    by the xml reader when starting to parse a stream. There should be
    only one root node in a tree. The root node does not have a parent
    node.
    </p>

    <!-- predicate -->
    <pred>root-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>xmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlRoot</name>
      <args>none</args>
      <p>
      The <code>XmlRoot</code> constructor creates a default xml root
      node which is empty.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = xml document object                                             = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlDocument</name>

    <!-- synopsis -->
    <p>
    The <code>XmlDocument</code> class is the xml document class.
    The document class is the root document class that maintains a
    xml document along with its associated tree and other useful
    information. Generally the class is constructed with a file name or
    a name and an input stream that is used for parsing the input data.
    The document can also be designed by constructing manually the
    document tree. In that case, the document name must be set explicitly.
    </p>

    <!-- predicate -->
    <pred>document-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Nameable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlDocument</name>
      <args>none</args>
      <p>
      The <code>XmlDocument</code> constructor creates a default xml
      document.
      </p>
    </ctor>

    <ctor>
      <name>XmlDocument</name>
      <args>String</args>
      <p>
      The <code>XmlDocument</code> constructor creates a xml document
      by parsing the file. The file name is the string argument.
      </p>
    </ctor>

    <ctor>
      <name>XmlDocument</name>
      <args>String Input</args>
      <p>
      The <code>XmlDocument</code> constructor creates a xml document
      by name and by parsing the input stream. The first argument is
      the xml document name. The second argument is the input stream
      to parse.
      </p>
    </ctor>

    <ctor>
      <name>XmlDocument</name>
      <args>String XmlRoot</args>
      <p>
      The <code>XmlDocument</code> constructor creates a xml document
      by name and root node. The first argument is the xml document
      name. The second argument is the xml root node.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the xml document name. The
      <code>get-name</code> method is also available from the
      <code>nameable</code> interface.
      </p>
    </method>
      
    <method>
      <name>get-root</name>
      <retn>none</retn>
      <args>XmlRoot</args>
      <p>
      The <code>get-root</code> method returns the document xml root
      node.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml element object                                              = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlElement</name>

    <!-- synopsis -->
    <p>
    The <code>XmlElement</code> class is the xml element class
    node. A xml element is represented with a name and a value. It is
    during the processing phase that the element value is
    interpreted. An element is built with a name and a value.
    </p>

    <!-- predicate -->
    <pred>element-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlElement</name>
      <args>String String</args>
      <p>
      The <code>XmlElement</code> constructor creates a xml element by
      name and value. The first argument is the element name. The
      second argument is the argument value.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the xml element name.
      </p>
    </method>
      
    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the element name.
      </p>
    </method>

    <method>
      <name>set-xval</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-xval</code> method sets the xml element value.
      </p>
    </method>
      
    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the element value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml entity object                                               = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlEntity</name>

    <!-- synopsis -->
    <p>
    The <code>XmlEntity</code> class is the base class for the xml
    entity representation. A xml entity can be either a general entity
    or a parameter entity. They differ initially with the presence of
    the '%' character. Both entity model have a name which is path of
    the base class.
    </p>

    <!-- predicate -->
    <pred>entity-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlNode</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the entity name.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the entity name.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml general entity object                                       = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlGe</name>

    <!-- synopsis -->
    <p>
    The <code>XmlGe</code> class is the xml general entity node.
    In its simplest form, the general entity has a name and a
    value. The entity type can also be associated with a system or a
    public identifier with or without an extra type name.
    </p>

    <!-- predicate -->
    <pred>ge-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlEntity</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlGe</name>
      <args>String String</args>
      <p>
      The <code>XmlGe</code> constructor creates a xml entity by
      name and value. The first argument is the entity name. The
      second argument is the entity value. Most of the time, the
      entity value is a parameter entity.
      </p>
    </ctor>

    <ctor>
      <name>XmlGe</name>
      <args>String String String</args>
      <p>
      The <code>XmlGe</code> constructor creates a xml entity by
      name and identifier. The first argument is the entity name. The
      second argument is the entity public identifier. The third
      argument is the entity system identifier.
      </p>
    </ctor>

    <ctor>
      <name>XmlGe</name>
      <args>String String String String</args>
      <p>
      The <code>XmlGe</code> constructor creates a xml entity by
      name, identifier and data type. The first argument is the entity
      name. The second argument is the entity public identifier. the
      third argument is the entity system identifier. The fourth
      argument is the entity type name.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the entity value.
      </p>
    </method>

    <method>
      <name>get-data</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-data</code> method returns the entity data type.
      </p>
    </method>

    <method>
      <name>get-public-id</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-public-id</code> method returns the entity public
      identifier.
      </p>
    </method>

    <method>
      <name>get-system-id</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-system-id</code> method returns the entity system
      identifier.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml parameter entity object                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlPe</name>

    <!-- synopsis -->
    <p>
    The <code>XmlPe</code> class is the xml parameter entity node. In
    its simplest form, the parameter entity has a name and a
    value. The entity type can also be associated with a system or a
    public identifier.
    </p>

    <!-- predicate -->
    <pred>ge-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlEntity</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlPe</name>
      <args>String String</args>
      <p>
      The <code>XmlGe</code> constructor creates a xml entity by
      name and value. The first argument is the entity name. The
      second argument is the entity value.
      </p>
    </ctor>

    <ctor>
      <name>XmlPe</name>
      <args>String String String</args>
      <p>
      The <code>XmlGe</code> constructor creates a xml entity by
      name and identifier. The first argument is the entity name. The
      second argument is the entity public identifier. The third
      argument is the entity system identifier.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-xval</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-xval</code> method returns the entity value.
      </p>
    </method>

    <method>
      <name>get-public-id</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-public-id</code> method returns the entity public
      identifier.
      </p>
    </method>

    <method>
      <name>get-system-id</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-system-id</code> method returns the entity system
      identifier.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = xml reader entity object                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XmlReader</name>

    <!-- synopsis -->
    <p>
    The <code>XmlReader</code> class is the xml parser that operates
    on an input stream. The reader creates a tree of nodes by reading
    the input stream and returns the root node when an end-of-stream
    is reached. Multiple read can be done sequentially. If the reset
    method is not called between multiple read passes, the reader will
    accumulate the nodes in the current tree.
    </p>

    <!-- predicate -->
    <pred>reader-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>XmlReader</name>
      <args>none</args>
      <p>
      The <code>XmlReader</code> constructor creates a default xml reader.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method resets the xml reader. In
      particular, the root node is restored to the nil node.
      </p>
    </method>

    <method>
      <name>parse</name>
      <retn>none</retn>
      <args>Input|String</args>
      <p>
      The <code>parse</code> method parses an input stream or a file.
      During the parsing process, the root node is filled with the
      parsed nodes.
      </p>
    </method>

    <method>
      <name>get-root</name>
      <retn>XmlRoot</retn>
      <args>none</args>
      <p>
      The <code>get-root</code> method returns the parsed root node.
      </p>
    </method>

    <method>
      <name>get-node</name>
      <retn>XmlNode</retn>
      <args>String</args>
      <p>
      The <code>get-node</code> method parse a string and returns a node.
      </p>
    </method>
  </object>
</appendix>
