Mini-XML 程序员开发手册,Version 2.5

目录

序言

• 本文结构
• 词法约定
• 缩略语
• 其他参考
• 法律信息

构建，安装，以及打包Mini-XML

• 编译 Mini-XML
  • 使用 Visual C++ 进行编译
  • 使用命令行工具进行编译
• 安装 Mini-XML
• 创建 Mini-XML 包

Mini-XML 入门

• 基础知识
• 节点
• 创建 XML 文档
• 加载 XML
• 保存 XML
  • 控制自动输出换行
• 搜索和遍历节点

更多的 Mini-XML 编程技术

• 加载回调函数
• 保存回调函数
• 用户定义数据类型
• 改变节点的值
• 格式化文本
• 索引
• SAX (流方式解析) 加载文档

使用 mxmldoc 工具

• 基础知识
• 为你的代码添加注释
• 标题、分段名和简介

Mini-XML 许可信息

发行说明库参考手册

• 目录
• 函数
  • mxmlAdd
  • mxmlDelete
  • mxmlElementDeleteAttr
  • mxmlElementGetAttr
  • mxmlElementSetAttr
  • mxmlElementSetAttrf
  • mxmlEntityAddCallback
  • mxmlEntityGetName
  • mxmlEntityGetValue
  • mxmlEntityRemoveCallback
  • mxmlFindElement
  • mxmlIndexDelete
  • mxmlIndexEnum
  • mxmlIndexFind
  • mxmlIndexNew
  • mxmlIndexReset
  • mxmlLoadFd
  • mxmlLoadFile
  • mxmlLoadString
  • mxmlNewCDATA
  • mxmlNewCustom
  • mxmlNewElement
  • mxmlNewInteger
  • mxmlNewOpaque
  • mxmlNewReal
  • mxmlNewText
  • mxmlNewTextf
  • mxmlNewXML
  • mxmlRelease
  • mxmlRemove
  • mxmlRetain
  • mxmlSAXLoadFd
  • mxmlSAXLoadFile
  • mxmlSAXLoadString
  • mxmlSaveAllocString
  • mxmlSaveFd
  • mxmlSaveFile
  • mxmlSaveString
  • mxmlSetCDATA
  • mxmlSetCustom
  • mxmlSetCustomHandlers
  • mxmlSetElement
  • mxmlSetErrorCallback
  • mxmlSetInteger
  • mxmlSetOpaque
  • mxmlSetReal
  • mxmlSetText
  • mxmlSetTextf
  • mxmlSetWrapMargin
  • mxmlWalkNext
  • mxmlWalkPrev
• 类型定义(typedef)
  • mxml_attr_t
  • mxml_custom_destroy_cb_t
  • mxml_custom_load_cb_t
  • mxml_custom_save_cb_t
  • mxml_custom_t
  • mxml_element_t
  • mxml_error_cb_t
  • mxml_index_t
  • mxml_load_cb_t
  • mxml_node_t
  • mxml_save_cb_t
  • mxml_sax_cb_t
  • mxml_sax_event_t
  • mxml_text_t
  • mxml_value_t
• 结构(struct)
  • mxml_attr_s
  • mxml_custom_s
  • mxml_element_s
  • mxml_index_s
  • mxml_node_s
  • mxml_text_s
• 联合(union)
  • mxml_value_u
• Constants
  • mxml_sax_event_e
  • mxml_type_e

XML方案 (用于自动化文档生成工具 mxmldoc)

序言

这份程序员参考手册描述了 Mini-XML 2.5版本,一个小型的 XML 解析库，使用它可以使你的C或者C++应用程序方便的进行XML数据文件的读写

Mini-XML 最初是为了Gutenprint 项目而开发，目的是为了替换既大又笨重的libxml2 库， 想要实现一个小型且易于使用的一些东西. 它开始于2003年6月的一个早晨，当时罗伯特发表了下面几句话到开发者列表：

"这真是糟糕，我们需要libxml2,但反复看来，我们的XML解析器仅需要我们可以操作的一小部分。"

我做了以下回复:

"考虑到你使用XML仅在一个有限的范围中，那么只使用几百行代码来编写一个微型XML (mini-XML) API，应该是很简单的。"

我接受了这个挑战，用了两天的时间进行疯狂的编码，并且公开发布了第一个mini-XML版本，总共是696行代码。然后，罗伯特迅速把mini-XML整合到 Gutenprint 中，并且移除了libxml2库

感谢很多不同的开发者给我的回馈和支持， 从那以后，Mini-XML逐渐发展为一个提供更多完整的XML实现，当前已经高达3441行代码，但已经可以和103893行代码的libxml2 2.6.9版本相比较了。

除了Gutenprint ，mini-XML当前已经应用于以下的项目/应用软件:

• Common UNIX Printing System
• CUPS Driver Development Kit
• ZynAddSubFX

如果您希望将您的项目添加到此列表或者从此列表中删除，或者如果您有任何意见和想法，或者想要发布关于使用mini-XML的经验，请给我发电子邮件（ mxml@easysw.com ）

本文档组织结构

本手册由以下章节和附录组成:

• 第一章,"构建，安装，以及打包Mini-XML",关于mini-XML在编译、安装以及打包方面的说明.
• 第二章,"Mini-XML 入门",如何在你的应用程序中使用mini-XML.
• 第三章,"更多的 Mini-XML 编程技术展示了使用mini-XML库的更多的方法。
• 第四章,"使用 mxmldoc 工具",描述如何使用mxmldoc(1) 程序来生成文档.
• 附录 A,"Mini-XML 许可信息 ",使用和发布mini-XML的条款及条件。
• 附录 B,"发行说明",列出了每次mini-XML发布版本的改变信息.
• 附录 C,"库参考手册",包含了关于mini-XML的完整参考信息,使用 mxmldoc生成.
• 附录 D,"XML方案",显示了 mxmldoc 生成XML文件时使用的 XML 方案.

词法约定

在这篇手册中使用了一些字体和风格的约定.下面是一些例子含义和使用说明:

lpstat
lpstat(1)

命令名称;如果在一章中第一次提及这个系统命令或者函数，则后面跟随手册页编号。

译者：上面指Linux 的manpages 手册，使用man命令查看。Z.F

/var
/usr/share/cups/data/testprint.ps

文件或者目录.

Request ID is Printer-123

屏幕输出.

lp -d printer filename ENTER

用户输入的文字，特殊键如ENTER 总是使用大写.

12.3

文本中的数字，使用(.)来表示小数点.

缩略词

下面是在本手册中使用的缩略词:

Gb

GB,即 1073741824 字节，1*1024*1024*1024 字节

kb

即 1024 字节，1*1024 字节

Mb

兆,or 1048576 bytes,1*1024*1024 字节

UTF-8,UTF-16

统一的字符编码标准,8-位 或 16-位

W3C

万维网联盟

XML

可扩展标记语言

其他参考

The Unicode Standard,Version 4.0,Addison-Wesley,ISBN 0-321-18578-1

定义了用于XML的Unicode字符集.

Extensible Markup Language (XML) 1.0 (Third Edition)

W3C制定的XML标准.

法律资料

The Mini-XML library is copyright 2003-2008 by Michael Sweet.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License,or (at your option) any later version.

This library 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. See the GNU Library General Public License for more details.

构建，安装，以及打包Mini-XML

这一章描述了如何在你的系统上使用源码包构建，安装以及打包Mini-XML,你将需要一个ANSI/ISO-C兼容的C编译器来构建Mini-XML,GCC可以工作，这也是大多数厂家的C编译器。如果你需要在Windows平台上构建， 我们建议使用Virtual C++环境和解决方案文件.对于其他的操作系统，你在C编译器之外需要一个POSIX兼容的shell和make程序..

编译 Mini-XML

Mini-XML 同时具备基于 autoconf的配置脚本和Virtual C++的解决方案，可以用来编译库和关联的其他工具.

使用 Visual C++ 编译

打开在目录 vcnet 下的 mxml.sln 解决方案. 选择需要构建的配置,"Debug" (缺省选项) 或者 "Release",并且 从 Build 菜单中选择 Build Solution项.

使用命令行工具编译

在你的系统上键入下面的命令来配置Mini-XML源代码:

    ./configure ENTER

缺省的安装前缀是 /usr/local,这可以被覆盖使用 --prefix 选项:

    ./configure --prefix=/foo ENTER

其他配置选项可以使用命令--help 选项进行查看:

    ./configure --help ENTER

当你配置完毕,使用make(1)程序来构建并且运行测试程序来校验是否工作正常，如下：

    make ENTER

安装 Mini-XML

如果你使用 Visual C++,分别拷贝 mxml.lib 和 mxml.h 文件到 Visual C++ lib 和 include 目录.

否则,使用make 命令和install参数来安装Mini-XML到配置的目录中:

    make install ENTER

创建 Mini-XML 包

Mini-XML 包含两个文件可以被用来创建二进制发行包.第一个文件是 mxml.spec 可以被使用通过rpmbuild(8) 软件来创建Red Hat 包管理器("RPM")的发行包，通常用于Linux平台. rpmbuild 可以自己进行软件编译,你可以为它提供一个Mini-XML 的tar文件来编译整个包，使用以下命令:

    rpmbuild -ta mxml-version.tar.gz ENTER

第二个文件是 mxml.list被用于epm(1) 程序创建不同格式的软件包.epm 程序可以从以下网址获得:

    http://www.easysw.com/epm/

使用make 命令通过 epm 目标 来构建一个针对你的系统的便携的本地包:

    make epm ENTER

为了你方便,这些包保存在子目录 dist 中.便携包利用脚本和tar文件安装软件到目标系统中.在展开包文件后,使用 mxml.install脚本来安装这个软件.

这些本地包可以是本地操作系统的原生格式:红帽Linux 的RPM,Debian Linux的DPKG,Solaris的PKG,等等.使用相应的命令来安装这些原生包.

Mini-XML 入门

这一章描述了如何写一个程序使用Mini-XML来访问XML文件中的数据.Mini-XML提供了以下功能:

• 在内存中创建和管理XML文档的函数.
• 读UTF-8和UTF-16 编码的XML文件和字符串.
• 写UTF-8 编码的XML文件和字符串.
• 支持任意的元素名称，属性以及属性值，没有任何其他限制，仅受限于有效内存.
• 支持整形、浮点、自定义("CDATA")和文本数据类型在"叶"节点.
• 提供"查找"、"索引"、以及"步进"函数可以很简单的访问XML文档中的数据.

Mini-XML 不进行基于"XML方案(SCHEMA)"文件或者其他内容源定义信息的校验和其他类型的处理,也不支持其他组织所要求的XML规范.

基础知识

Mini-XML 提供的一个你需要包含的头文件:

    #include <mxml.h>

把Mini-XML库连接到你的应用程序使用-lmxml 选项:

    gcc -o myprogram myprogram.c -lmxml ENTER

如果你已经安装pkg-config(1) 软件,你可以使用它来为你的安装确定适当的编译和连接选项:

    pkg-config --cflags mxml ENTER
    pkg-config --libs mxml ENTER

节点

每一块XML文件中的信息片断(元素、文本、数字)是一个存储在内存中的"节点(nodes)" .节点使用mxml_node_t 结构进行定义. 它的type 成员变量定义了节点类型（element,integer,opaque,real,or text) 决定了需要从联合(union)类型的成员变量value 中获取的值.

每一个节点总是有一个成员变量:user_data 可以允许你为每一个节点关联你需要的应用数据.

新的节点可以使用以下函数进行创建 mxmlNewElement, mxmlNewInteger, mxmlNewOpaque, mxmlNewReal, mxmlNewText mxmlNewTextf mxmlNewXML . 只有 elements 可以拥有子节点，顶级节点必须是一个 element,通常是<?xml version="1.0"?> 使用mxmlNewXML()函数创建的节点.

每个节点都有一些关联节点的指针，上(parent),下(child),左(prev),and 右(next) 相对应于当前节点. 如果你有一个XML文件如下所示:

    <?xml version="1.0"?>
    <data>
        <node>val1</node>
        <node>val2</node>
        <node>val3</node>
        <group>
            <node>val4</node>
            <node>val5</node>
            <node>val6</node>
        </group>
        <node>val7</node>
        <node>val8</node>
    </data>

那么在内存中的文件节点树看上去如下所示:

    ?xml
      |
    data
      |
    node - node - node - group - node - node
      |      |      |      |       |      |
    val1   val2   val3     |     val7   val8
                           |
                         node - node - node
                           |      |      |
                         val4   val5   val6

这里"-"指向下一个节点，"|"指向第一个子节点。

当你使用完毕这些XML数据后，使用函数mxmlDelete 来释放指定节点或者整个XML树节点和它下面所有子节点的内存:

    mxmlDelete(tree);

创建 XML 文档

你可以在内存中创建和更新XML文档，使用mxmlNew 一系列函数. 下面的代码将创建上一章描述的XML文档:

    mxml_node_t *xml;    /* <?xml ... ?> */
    mxml_node_t *data;   /* <data> */
    mxml_node_t *node;   /* <node> */
    mxml_node_t *group;  /* <group> */

    xml = mxmlNewXML("1.0");

    data = mxmlNewElement(xml,"data");

        node = mxmlNewElement(data,"node");
        mxmlNewText(node,"val1");
        node = mxmlNewElement(data,"val2");
        node = mxmlNewElement(data,"val3");

        group = mxmlNewElement(data,"group");

            node = mxmlNewElement(group,"node");
            mxmlNewText(node,"val4");
            node = mxmlNewElement(group,"val5");
            node = mxmlNewElement(group,"val6");

        node = mxmlNewElement(data,"val7");
        node = mxmlNewElement(data,"val8");

我们首先使用mxmlNewXML函数来创建所有XML文件都需要的标头 <?xml version="1.0"?> :

    xml = mxmlNewXML("1.0");

然后我们使用mxmlNewElement函数来创建本文件使用的<data>节点.第一个参数指定了父节点(xml) ，第二个参数是元素名 (data):

    data = mxmlNewElement(xml,"data");

每个在本文件中<node>...</node>之间的部分使用函数mxmlNewElement 和 mxmlNewText来创建. mxmlNewText 的第一个参数指定了父节点 (node).第二个参数指定了是否在文本之前添加空白字符，在本例中使用0或者false.最后一个参数指定了需要添加的实际文本:

    node = mxmlNewElement(data,"node");
    mxmlNewText(node,"val1");

在内存中的XML结果可以被保存或者进行其他处理，就像一个从磁盘或者字符串中读取的文档一样.

加载XML

你可以加载一个XML文件使用函数mxmlLoadFile :

    FILE *fp;
    mxml_node_t *tree;

    fp = fopen("filename.xml","r");
    tree = mxmlLoadFile(NULL,fp,MXML_TEXT_CALLBACK);
    fclose(fp);

第一个参数如果有的话则指定了一个存在的XML父节点.一般你将这个参数等于NULL,除非你想要连接多个XML源. 如果此参数等于NULL，那么指定的XML文件必须是一个完整的XML文档，文档头部要包含?xml元素.

第二个参数指定了一个标准的文件流，使用 fopen() 或者 popen()进行打开. 你也可以使用stdin，如果你想要实现一个XML过滤器程序.

第三个参数指定了一个回调函数用于一个新的XML元素节点直接返回的子节点的值类型: MXML_CUSTOM,MXML_IGNORE,MXML_INTEGER,MXML_OPAQUE,MXML_REAL,or MXML_TEXT. 加载回调函数的细节在第三章做了详细描述. 示例代码使用 MXML_TEXT_CALLBACK 常量指定文档中所有的数据节点都包含使用以空格字符分割的文本的值. 其他标准的回调还有MXML_IGNORE_CALLBACK,MXML_INTEGER_CALLBACK,MXML_OPAQUE_CALLBACK,和MXML_REAL_CALLBACK.

函数mxmlLoadString 可以从一个字符串中载入XML节点树:

    char buffer[8192];
    mxml_node_t *tree;

    ...
    tree = mxmlLoadString(NULL,buffer,MXML_TEXT_CALLBACK);

第一个和第三个参数和mxmlLoadFile()用法一样. 第二个参数指定了指定了字符串或者字符缓冲区用于加载XML，当父节点参数为NULL时内容必须为完整的XML文档，包括XML头?xml元素.

保存 XML

你可以保存XML文件使用mxmlSaveFile 函数:

    FILE *fp;
    mxml_node_t *tree;

    fp = fopen("filename.xml","w");
    mxmlSaveFile(tree,MXML_NO_CALLBACK);
    fclose(fp);

第一个参数为想要保存的XML节点树,一般应该是一个指向你的XML文档顶级节点?xml的节点指针.

第二个单数是一个标准文件流，使用fopen() 或者 popen()来打开. 你也可以使用stdout 如果你想要实现一个XML过滤器程序.

第三个参数是一个空白回调函数用来控制保存文件时插入的"空白"字符."空白回调"的详细信息参见第三章. 以上的示例代码使用了MXML_NO_CALLBACK常量来指定不需要特别的空白处理.

函数mxmlSaveAllocString,和mxmlSaveString 保存XML节点树到一个字符串中:

    char buffer[8192];
    char *ptr;
    mxml_node_t *tree;

    ...
    mxmlSaveString(tree,sizeof(buffer),MXML_NO_CALLBACK);

    ...
    ptr = mxmlSaveAllocString(tree,MXML_NO_CALLBACK);

第一个和最后一个参数的用法和函数mxmlSaveFile()一样. 函数mxmlSaveString 给出了一个指针和长度的参数来保存XML文档到一个固定大小的缓冲区中。,mxmlSaveAllocString() 返回了使用malloc分配的一个字符串缓冲区malloc().

自动折行控制

当我们保存XML文档时,Mini-XML一般在第75列进行折行，因为这样在终端下最易读. 函数mxmlSetWrapMargin 可以覆盖缺省的折行界限:

    /* 设置自动折行到 132 列*/
    mxmlSetWrapMargin(132);

    /* 取消自动折行*/
    mxmlSetWrapMargin(0);

搜索和遍历节点

函数mxmlWalkPrev and mxmlWalkNext可以被用来遍历XML节点树:

    mxml_node_t *node;
    
    node = mxmlWalkPrev(current,tree,MXML_DESCEND);

    node = mxmlWalkNext(current,MXML_DESCEND);

另外,你可以搜索一个命名的XML元素/节点,使用函数mxmlFindElement:

    mxml_node_t *node;
    
    node = mxmlFindElement(tree,"name","attr","value",MXML_DESCEND);

参数name,attr,和value 可以被设置为NULL作为全部匹配,e.g.:

    /* 搜索第一个 "a" 元素*/
    node = mxmlFindElement(tree,"a",NULL,MXML_DESCEND);

    /* 搜索第一个"a" 元素并包含"href"属性*/
    node = mxmlFindElement(tree,"href",MXML_DESCEND);

    /* 搜索第一个"a" 元素并且包含"href"属性等于给出的URL */
    node = mxmlFindElement(tree,"http://www.easysw.com/",MXML_DESCEND);

    /* 搜索第一个包含"src"属性的XML元素*/
    node = mxmlFindElement(tree,"src",MXML_DESCEND);

    /* 搜索第一个包含"src"= "foo.jpg"属性的XML元素 */
    node = mxmlFindElement(tree,"foo.jpg",MXML_DESCEND);

你也可以使用同样的功能进行遍历:

    mxml_node_t *node;

    for (node = mxmlFindElement(tree,MXML_DESCEND);
         node != NULL;
         node = mxmlFindElement(node,MXML_DESCEND))
    {
      ... do something ...
    }

参数MXML_DESCEND可以是下面三个常量之一:

• MXML_NO_DESCEND 含义是不查看任何的子节点在XML元素层次中，仅查看同级的伙伴节点或者父节点直到到达顶级节点或者给出的树的顶级节点.

  "group"节点的上一个节点时它左面的"node"子节点,下一个节点是"group"右面的"node"子节点..

• MXML_DESCEND_FIRST含义是向下搜索到一个节点的第一个匹配子节点，但不再继续向下搜索。你一般使用于遍历一个父节点的直接的子节点。,如：在上面的例子中的所有在"?xml"父节点下的所有的"node"和"group"子节点。.

  这个模式仅适用于搜索(search)功能，遍历功能(walk)对待它和 MXML_DESCEND 一样，因为每次调用都是首次调用。

• MXML_DESCEND含义是一直向下直到树的根部. "group"节点的上一个节点将是"val3"节点，下一个节点将是"group"的下面的第一个子节点。

  如果你要使用函数mxmlWalkNext()从根结点"?xml" 遍历到整个树的结束,那么这个顺序将如下所示：

  ?xml data node val1 node val2 node val3 group node val4 node val5 node val6 node val7 node val8

  如果你从"val8"开始并使用函数mxmlWalkPrev()进行遍历,这个顺序将是反的，结束于"?xml"节点.

更多的 Mini-XML 编程技术

这一章显示了更多的在你的应用程序中使用Mini-XML的方法。

Load Callbacks

第二章 介绍了函数mxmlLoadFile() 和mxmlLoadString() . 这些函数的最后一个参数是一个回调函数，决定了在一个XML文档中每个数据节点的值的类型。

Mini-XML 为简单XML数据文件定义了几个标准的回调函数：

• MXML_INTEGER_CALLBACK - 所有的数据节点包含以空格分割的整数。
• MXML_OPAQUE_CALLBACK - 所有的数据节点包含"不透明"字符串（CDATA）。
• MXML_REAL_CALLBACK - 所有的数据节点包含以空格分割的浮点数。
• MXML_TEXT_CALLBACK - 所有的数据节点包含以空格分割的文本字符串。

你可以为更复杂的XML文档提供你自己的回调函数。你的回调函数将接收到一个到当前XML元素节点的指针并且必须为这个XML元素节点返回一个直接子节点的值类型: MXML_INTEGER,或MXML_TEXT.这个函数在这个XML元素和它的全部属性被读取以后被调用，所以你可以查看这个XML元素的名称、属性以及属性的值来决定适当的返回值类型。

下面的回调函数查看一个名称为"type"的属性或者XML元素的名字来决定它的子节点的值类型：

    mxml_type_t
    type_cb(mxml_node_t *node)
    {
      const char *type;

     /*
      * 你可以查看属性和/或使用XML元素名，所在层次，等等
      */

      type = mxmlElementGetAttr(node,"type");
      if (type == NULL)
	type = node->value.element.name;

      if (!strcmp(type,"integer"))
	return (MXML_INTEGER);
      else if (!strcmp(type,"opaque"))
	return (MXML_OPAQUE);
      else if (!strcmp(type,"real"))
	return (MXML_REAL);
      else
	return (MXML_TEXT);
    }

要使用这个回调函数，只需要在你调用任何加载函数时简单的使用它的名字：

    FILE *fp;
    mxml_node_t *tree;

    fp = fopen("filename.xml",type_cb);
    fclose(fp);

保存回调

第二章 也介绍了mxmlSaveFile(), mxmlSaveString(),和mxmlSaveAllocString() 函数。这些函数的最后一个参数是一个回调函数被用来自动在一个XML文档中添加空白字符。

你的回调函数将在每个XML元素被调用四次，传入参数为一个到这个节点的指针和一个"where"的值：MXML_WS_BEFORE_OPEN,MXML_WS_AFTER_OPEN,MXML_WS_BEFORE_CLOSE,或者MXML_WS_AFTER_CLOSE。如果不需要插入空白字符这个回调函数将返回 NULL，否则返回字符串（空白、跳格、回车和换行）将被插入。

下面的空白回调可以被用来为XHTML输出添加空白字符，来使它在一般的文本编辑器中更加易读：

    const char *
    whitespace_cb(mxml_node_t *node,int where)
    {
      const char *name;

     /*
      * 我们可以在任何XML元素之前或之后有条件的添加换行。这些是一些常见的HTML元素。
      */

      name = node->value.element.name;

      if (!strcmp(name,"html") ||
          !strcmp(name,"head") ||
          !strcmp(name,"body") ||
	  !strcmp(name,"pre") ||
          !strcmp(name,"p") ||
	  !strcmp(name,"h1") ||
          !strcmp(name,"h2") ||
          !strcmp(name,"h3") ||
	  !strcmp(name,"h4") ||
          !strcmp(name,"h5") ||
          !strcmp(name,"h6"))
      {
       /*
	* 在打开之前和关闭之后时换行。
	*/

	if (where == MXML_WS_BEFORE_OPEN ||
            where == MXML_WS_AFTER_CLOSE)
	  return ("/n");
      }
      else if (!strcmp(name,"dl") ||
               !strcmp(name,"ol") ||
               !strcmp(name,"ul"))
      {
       /*
	* 在列表元素前后都添加换行。
	*/

	return ("/n");
      }
      else if (!strcmp(name,"dd") ||
               !strcmp(name,"dt") ||
               !strcmp(name,"li"))
      {
       /*
	* 添加一个"跳格"在<li>,* <dd>,* 和 <dt>之前,以及一个换行在他们后面...
	*/

	if (where == MXML_WS_BEFORE_OPEN)
	  return ("/t");
	else if (where == MXML_WS_AFTER_CLOSE)
	  return ("/n");
      }

     /*
      * 如果不需要添加空白字符则返回NULL。
      */

      return (NULL);
    }

要使用这些回调函数，只需要在你调用任何保存函数时简单使用它的名字：

    FILE *fp;
    mxml_node_t *tree;

    fp = fopen("filename.xml",whitespace_cb);
    fclose(fp);

用户定义数据类型

Mini-XML 支持通过全局的载入和保存回调函数使用自定义数据类型。 每次只能有一组回调函数被同时激活，然而你的回调函数可以为支持多种所需要的自定义数据类型来保存更多的信息。 节点类型 MXML_CUSTOM 表示一个自定义数据内容的节点。

加载回调接收一个到当前数据节点的指针和一个不透明字符串数据从XML源中并且将字符集转换为UTF-8编码。例如：如果我们想要支持定制的日期/时间类型并且编码为"yyyy-mm-ddThh:mm:ssZ" (ISO 格式),那么加载回调函数如下所示：

    typedef struct
    {
      unsigned      year,/* Year */
                    month,/* Month */
                    day,/* Day */
                    hour,/* Hour */
                    minute,/* Minute */
                    second;  /* Second */
      time_t        unix;    /* UNIX time */
    } iso_date_time_t;

    int
    load_custom(mxml_node_t *node,const char *data)
    {
      iso_date_time_t *dt;
      struct tm tmdata;

     /*
      * 分配数据结构...
      */

      dt = calloc(1,sizeof(iso_date_time_t));

     /*
      * 尝试从数据字符串中读取6个无符号整数..
      */

      if (sscanf(data,"%u-%u-%uT%u:%u:%uZ",&(dt->year),&(dt->month),&(dt->day),&(dt->hour),&(dt->minute),&(dt->second)) != 6)
      {
       /*
        * 如果不能读取到数字，释放分配的结构并返回一个错误...
        */

        free(dt);

        return (-1);
      }

     /*
      * 数据范围检查...
      */

      if (dt->month <1 || dt->month > 12 ||
          dt->day  <1 || dt->day > 31 ||
          dt->hour  <0 || dt->hour > 23 ||
          dt->minute  <0 || dt->minute > 59 ||
          dt->second  <0 || dt->second > 59)
      {
       /*
        * 如果日期信息超出范围...
        */

        free(dt);

        return (-1);
      }

     /*
      * 转换ISO时间到以秒为单位的UNIX时间...
      */

      tmdata.tm_year = dt->year - 1900;
      tmdata.tm_mon  = dt->month - 1;
      tmdata.tm_day  = dt->day;
      tmdata.tm_hour = dt->hour;
      tmdata.tm_min  = dt->minute;
      tmdata.tm_sec  = dt->second;

      dt->unix = gmtime(&tmdata);

     /*
      * 设置自定义节点数据指针和销毁函数指针...
      */

      node->value.custom.data    = dt;
      node->value.custom.destroy = free;

     /*
      * 返回没有错误...
      */

      return (0);
    }

这个函数成功时返回0，当不能正确解码自定义数据或者数据内容错误时返回-1。自定义数据节点包含一个void 指针用来保存这个节点已经分配的自定义数据，还有一个指向销毁函数的指针用于当节点被删除时释放自定义数据。

保存回调接收一个节点指针并且返回一个包含自定义数据值的已经分配的字符串。下面的保存回调函数可以被用来保存我们的ISO日期/时间类型：

    char *
    save_custom(mxml_node_t *node)
    {
      char data[255];
      iso_date_time_t *dt;


      dt = (iso_date_time_t *)node->custom.data;

      snprintf(data,sizeof(data),"%04u-%02u-%02uT%02u:%02u:%02uZ",dt->year,dt->month,dt->day,dt->hour,dt->minute,dt->second);

      return (strdup(data));
    }

你可以注册这些回调函数使用mxmlSetCustomHandlers() 函数：

    mxmlSetCustomHandlers(load_custom,save_custom);

改变节点的值

到现在为止所有的例子集中描述了如何创建和加载新的XML数据节点。然而，许多的应用程序在它们的工作中需要操纵或者改变节点，所以Mini-XML提供了一些函数来安全的改变节点的值并且不会发生内存泄漏。

已有的节点可以被改变通过使用函数mxmlSetElement(), mxmlSetInteger(), mxmlSetOpaque(), mxmlSetReal(), mxmlSetText(),和 mxmlSetTextf()。例如：使用下面的函数调用可以改变一个文本节点到包含字符串"new"并且具有前导的空白字符：

    mxml_node_t *node;

    mxmlSetText(node,1,"new");

格式化的文本

mxmlNewTextf()和mxmlSetTextf() 函数分别是创建和改变文本节点，使用printf-风格的格式字符串和参数。例如：使用下面的函数调用来创建一个新的文本节点包含一个构造的文件名：

    mxml_node_t *node;


    node = mxmlNewTextf(node,"%s/%s",path,filename);

索引

Mini-XML 提供了一些函数来管理节点的索引。当前的实现提供了同样的功能就像 mxmlFindElement()一样。使用索引优势是可以使搜索和枚举XML元素显著加快。唯一不利的是每个索引都是一个关于这个XML文档的静态快照，所以索引不适合当相对于它的搜索操作，XML数据更加频繁更新时的情况。上面的创建一个索引近似相当于遍历这个XML文档树。在索引中的节点被按照XML元素名和它的参数值进行排序。

这些索引被保存在mxml_index_t 结构中。用mxmlIndexNew()函数可以创建一个新的索引：

    mxml_node_t *tree;
    mxml_index_t *ind;

    ind = mxmlIndexNew(tree,"element","attribute");

第一个参数是需要进行索引的XML节点树。通常是一个指向?xml元素的节点。

第二个参数包含了需要进行索引的XML元素；使用NULL值将按照字母顺序索引所有的XML元素节点。

第三个参数包含了需要进行索引的属性；使用NULL将使只有XML元素名字被索引。

当索引被建立后，函数mxmlIndexEnum(), mxmlIndexFind(),and mxmlIndexReset()可以被用来访问索引中的节点。函数mxmlIndexReset()被用来重置在索引中的"当前"节点指针，允许你在同一个索引中进行新的搜索和枚举遍历。典型应用是你将在你调用函数mxmlIndexEnum() 和mxmlIndexFind()之前调用这个函数。

函数mxmlIndexEnum() 用来枚举在索引中的每一个节点，可以在一个循环中使用，如下所示：

    mxml_node_t *node;

    mxmlIndexReset(ind);

    while ((node = mxmlIndexEnum(ind)) != NULL)
    {
      // do something with node
    }

函数mxmlIndexFind() 定位下一次在索引中出现的XML元素名和属性值。它可以被用于发现在索引中的所有匹配的XML元素，如下所示：

    mxml_node_t *node;

    mxmlIndexReset(ind);

    while ((node = mxmlIndexFind(ind,"attr-value"))
                != NULL)
    {
      // do something with node
    }

第二和第三个参数分别表示XML元素名和属性值。使用 NULL指针用来返回索引中所有的XML元素或者属性。如果XML元素名和属性值同时为NULL则相当于调用函数mxmlIndexEnum。

当我们使用完这个索引后，使用函数mxmlIndexDelete() 来删除它:

    mxmlIndexDelete(ind);

SAX (流方式解析) 加载文档

Mini-XML支持一个关于简单XML API (SAX)的实现，以允许你通过节点流的方式加载和处理XML文档。另外允许你处理任何大小的XML文件，Mini-XML的实现也允许你为下一步的处理而只在内存中保留XML文档的一部分。

The mxmlSAXLoadFd, mxmlSAXLoadFile,和mxmlSAXLoadString 函数提供了SAX加载的API。每个函数工作起来就象 mxmlLoad 函数一样，但是使用一个回调函数来处理它读到的每一个节点。

回调函数接收到一个节点，一个事件代码和一个你提供的用户数据指针：

    void
    sax_cb(mxml_node_t *node,mxml_sax_event_t event,void *data)
    {
      ... do something ...
    }

事件(event)将是下面的其中一个：

• MXML_SAX_CDATA - CDATA 正在被读取
• MXML_SAX_COMMENT - 一个注释正在被读取
• MXML_SAX_DATA - 数据(custom,or text) 正在被读取
• MXML_SAX_DIRECTIVE - 一个处理指令正在被读取
• MXML_SAX_ELEMENT_OPEN - 一个"打开"元素节点正在被读取，如(<element>)
• MXML_SAX_ELEMENT_CLOSE - 一个"关闭"元素节点正在被读取，如(</element>)

XML元素将被 释放 在一个"关闭"元素被处理后。所有其他的节点在他们被处理后都被释放。SAX回调函数可以 保留 这个节点，通过调用函数mxmlRetain 。例如：下面的SAX回调函数将保留所有的节点，就像一个普通的内存加载一样：

    void
    sax_cb(mxml_node_t *node,void *data)
    {
      if (event != MXML_SAX_ELEMENT_CLOSE)
        mxmlRetain(node);
    }

更多的典型SAX回调函数将只保留后面需要处理的这个XML文档的一小部分。例如，下面的SAX回调函数将保留一个XHTML文件的标题和头部信息。它总是保留一个XML元素（父节点）就像<html>,<head>,和 <body>,并处理指令节点就像 <?xml ... ?> 和<!DOCTYPE ... >：

    void
    sax_cb(mxml_node_t *node,void *data)
    {
      if (event == MXML_SAX_ELEMENT_OPEN)
      {
       /*
        * 保留标题和头部
        */

        char *name = node->value.element.name;

        if (!strcmp(name,"html") ||
            !strcmp(name,"head") ||
            !strcmp(name,"title") ||
            !strcmp(name,"body") ||
            !strcmp(name,"h1") ||
            !strcmp(name,"h2") ||
            !strcmp(name,"h3") ||
            !strcmp(name,"h4") ||
            !strcmp(name,"h5") ||
            !strcmp(name,"h6"))
          mxmlRetain(node);
      }
      else if (event == MXML_SAX_DIRECTIVE)
        mxmlRetain(node);
      else if (event == MXML_SAX_DATA &&
               node->parent->ref_count > 1)
      {
       /*
        * 如果父节点被保留，那么这个数据节点最好是也被保留。
        */

        mxmlRetain(node);
      }
    }

这个结果框架文档树可以被搜素就像一个使用函数mxmlLoad 加载的一样。例如，一个过滤器程序用来从标准输入(stdin)中读取一个XHTML文档，并显示在文档中的标题和标头，如下所示：

    mxml_node_t *doc,*title,*body,*heading;

    doc = mxmlSAXLoadFd(NULL,MXML_TEXT_CALLBACK,sax_cb,NULL);

    title = mxmlFindElement(doc,doc,"title",MXML_DESCEND);

    if (title)
      print_children(title);

    body = mxmlFindElement(doc,"body",MXML_DESCEND);

    if (body)
    {
      for (heading = body->child;
           heading;
           heading = heading->next)
        print_children(heading);
    }

使用mxmldoc 工具

这一章描述了如何使用mxmldoc(1) 程序自动从c和c++源文件中生成文档。

基础知识

最初开发是用来生成Mini-XML 和CUPS API的文档，现在mxmldoc是一个通用工具实现了扫描C和C++源文件以生成HTML和man手册页文档与一个描述这些源文件中的函数、类型和宏的定义的XML文件。不像一些流行的文档生成工具如Doxygen 或 Javadoc,mxmldoc使用"在线"注释并不是注释头文件，允许更加自然的代码文档。

缺省情况下，mxmldoc 生成HTML文档个，例如：下面的命令将扫描所有的在当前目录下的C源代码和头文件并生成一个HTML文档文件叫 filename.html:

    mxmldoc *.h *.c >filename.html ENTER

你也可以指定创建一个包含所有源文件信息的XML文件。例如，下面的命令创建一个XML文件 filename.xml并添加到这个HTML文件中：

    mxmldoc filename.xml *.h *.c >filename.html ENTER

--no-output 选项关闭标准的HTML输出：

    mxmldoc --no-output filename.xml *.h *.c ENTER

你可以再次运行mxmldoc通过这个XML文件来生成HTML文档：

    mxmldoc filename.xml >filename.html ENTER

--man filename 选项来告诉mxmldoc创建一个手册页(man page)代替HTML文档，例如：

    mxmldoc --man filename filename.xml / >filename.man ENTER

    mxmldoc --man filename *.h *.c / >filename.man ENTER

    mxmldoc --man filename filename.xml *.h *.c / >filename.man ENTER

注释你的代码

在上面已经提到，mxmldoc 查看在线注释来描述你源文件中的函数、类型以及常量。Mxmldoc 将为你源文件中"所有"公开的命名生成文档，所有以下划线开始的名称和被使用@private@ 指令注解的名称被认为是“私有”的而不生成文档。

出现在函数或者类型定义前面的注释被用来生出这个函数或者类型的文档。出现在参数、定义、返回类型或者变量定义被用来生成它们的注释。例如：下列代码片断定义一个包含key/vaue的结构以及一个创建这个结构的新实例的函数：

    /* A key/value pair. This is used with the
       dictionary structure. */

    struct keyval
    {
      char *key; /* Key string */
      char *val; /* Value string */
    };

    /* Create a new key/value pair. */

    struct keyval * /* New key/value pair */
    new_keyval(
        const char *key,/* Key string */
	const char *val) /* Value string */
    {
      ...
    }

Mxmldoc 总是知道并从注释字符串中移除多余的(*)号，所以下面的这个注释字符串：

    /*
     * Compute the value of PI.
     *
     * The function connects to an Internet server
     * that streams audio of mathematical monks
     * chanting the first 100 digits of PI.
     */

将被显示为：

    Compute the value of PI.

    The function connects to an Internet server
    that streams audio of mathematical monks
    chanting the first 100 digits of PI.

注释中也可以包含@name ...@ 这样的特殊指令字符串：

• @deprecated@ - 标识一个条目为不支持并阻止它的使用
• @private@ - 标识一个条目为为私有的所以它将不被包含在文档中。
• @since ...@ - 标识一个条目为为从一个特别重要的发布更新。从@since到@间的文本在文档中将被高亮显示，如： @since CUPS 1.3@。

标题、分段名和简介

Mxmldoc 也提供了一些选项来设置生成的文档中的标题、分段名和简介。The --title text 选项指定了文档的标题。标题字符串通常放在引号内：

    mxmldoc filename.xml / --title "My Famous Documentation" / >filename.html ENTER

--section name 选项指定了文档的分段名。对于HTML文档，这个名字放在一个HTML注释块中，如下所示：

    <!-- SECTION: name -->

对于手册页(man pages),分段名通常是一个数字("3")，或者是一个数字后面跟着厂商名如("3acme")。这个分段名被使用在手册页(man pages)中的.TH指令里：

    .TH mylibrary 3acme "My Title" ...

缺省手册页(man pages)的分段名输出是"3"。对于HTML输出没有缺省的分段名。

最后，--intro filename 选项指定了一个文件来嵌入到在标题和分段名之后和生成文档的前面。对于HTML文档，这个文件必须兼容HTML并且不能使用DOCTYPE,html,and body元素。.对于手册页文档，这个文件必须兼容有效的nroff(1) 文本.

Mini-XML 许可信息

The Mini-XML library and included programs are provided under the terms of the GNU Library General Public License (LGPL) with the following exceptions:

1. Static linking of applications to the Mini-XML library does not constitute a derivative work and does not require the author to provide source code for the application,use the shared Mini-XML libraries,or link their applications against a user-supplied version of Mini-XML.

   If you link the application to a modified version of Mini-XML,then the changes to Mini-XML must be provided under the terms of the LGPL in sections 1,2,and 4.

2. You do not have to provide a copy of the Mini-XML license with programs that are linked to the Mini-XML library,nor do you have to identify the Mini-XML license in your program or documentation as required by section 6 of the LGPL.

GNU LIBRARY GENERAL PUBLIC LICENSE

Version 2,June 1991
Copyright (C) 1991 Free Software Foundation,Inc.
59 Temple Place - Suite 330,Boston,MA 02111-1307,USA
Everyone is permitted to copy and distribute verbatim copies of this license document,but changing it is not allowed.
[This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.]

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast,the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.

This license,the Library General Public License,applies to some specially designated Free Software Foundation software,and to any other libraries whose authors decide to use it. You can use it for your libraries,too.

When we speak of free software,we are referring to freedom,not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish),that you receive source code or can get it if you want it,that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights,we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library,or if you modify it.

For example,if you distribute copies of the library,whether gratis or for a fee,you must give the recipients all the rights that we gave you. You must make sure that they,too,receive or can get the source code. If you link a program with the library,you must provide complete object files to the recipients so that they can relink them with the library,after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

Our method of protecting your rights has two steps: (1) copyright the library,and (2) offer you this license which gives you legal permission to copy,distribute and/or modify the library.

Also,for each distributor's protection,we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on,we want its recipients to know that what they have is not the original version,so that any problems introduced by others will not reflect on the original authors' reputations.

Finally,any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses,thus in effect transforming the program into proprietary software. To prevent this,we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

Most GNU software,including some libraries,is covered by the ordinary GNU General Public License,which was designed for utility programs. This license,the GNU Library General Public License,applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full,and don't assume that anything in it is the same as in the ordinary license.

The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library,without changing the library,is in some sense simply using the library,and is analogous to running a utility program or application program. However,in a textual and legal sense,the linked executable is a combined work,a derivative of the original library,and the ordinary General Public License treats it as such.

Because of this blurred distinction,using the ordinary General Public License for libraries did not effectively promote software sharing,because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.

However,unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries,while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files,but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.

The precise terms and conditions for copying,distribution and modification follow. Pay close attention to the difference between a "work based on the libary" and a "work that uses the library". The former contains code derived from the library,while the latter only works together with the library.

Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.

TERMS AND CONDITIONS FOR COPYING,DISTRIBUTION AND MODIFICATION

0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you".

A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.

The "Library",below,refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say,a work containing the Library or a portion of it,either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter,translation is included without limitation in the term "modification".)

"Source code" for a work means the preferred form of the work for making modifications to it. For a library,complete source code means all the source code for all modules it contains,plus any associated interface definition files,plus the scripts used to control compilation and installation of the library.

Activities other than copying,distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted,and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.

1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it,in any medium,provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.

You may charge a fee for the physical act of transferring a copy,and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Library or any portion of it,thus forming a work based on the Library,and copy and distribute such modifications or work under the terms of Section 1 above,provided that you also meet all of these conditions:

a) The modified work must itself be a software library.

b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.

c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.

d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility,other than as an argument passed when the facility is invoked,then you must make a good faith effort to ensure that,in the event an application does not supply such function or table,the facility still operates,and performs whatever part of its purpose remains meaningful.

(For example,a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore,Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it,the square root function must still compute square roots.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library,and can be reasonably considered independent and separate works in themselves,then this License,and its terms,do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library,the distribution of the whole must be on the terms of this License,whose permissions for other licensees extend to the entire whole,and thus to each and every part regardless of who wrote it.

Thus,it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather,the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.

In addition,mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this,you must alter all the notices that refer to this License,so that they refer to the ordinary GNU General Public License,version 2,instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared,then you can specify that version instead if you wish.) Do not make any other change in these notices.

Once this change is made in a given copy,it is irreversible for that copy,so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.

This option is useful when you wish to copy part of the code of the Library into a program that is not a library.

4. You may copy and distribute the Library (or a portion or derivative of it,under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code,which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.

If distribution of object code is made by offering access to copy from a designated place,then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code,even though third parties are not compelled to copy the source along with the object code.

5. A program that contains no derivative of any portion of the Library,but is designed to work with the Library by being compiled or linked with it,is called a "work that uses the Library". Such a work,in isolation,is not a derivative work of the Library,and therefore falls outside the scope of this License.

However,linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library),rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.

When a "work that uses the Library" uses material from a header file that is part of the Library,the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library,or if the work is itself a library. The threshold for this to be true is not precisely defined by law.

If such an object file uses only numerical parameters,data structure layouts and accessors,and small macros and small inline functions (ten lines or less in length),then the use of the object file is unrestricted,regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)

Otherwise,if the work is a derivative of the Library,you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6,whether or not they are linked directly with the Library itself.

6. As an exception to the Sections above,you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library,and distribute that work under terms of your choice,provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.

You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices,you must include the copyright notice for the Library among them,as well as a reference directing the user to the copy of this License. Also,you must do one of these things:

a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and,if the work is an executable linked with the Library,with the complete machine-readable "work that uses the Library",as object code and/or source code,so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)

b) Accompany the work with a written offer,valid for at least three years,to give the same user the materials specified in Subsection 6a,above,for a charge no more than the cost of performing this distribution.

c) If distribution of the work is made by offering access to copy from a designated place,offer equivalent access to copy the above specified materials from the same place.

d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.

For an executable,the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However,as a special exception,the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler,kernel,and so on) of the operating system on which the executable runs,unless that component itself accompanies the executable.

It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.

7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License,and distribute such a combined library,provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted,and provided that you do these two things:

a) Accompany the combined library with a copy of the same work based on the Library,uncombined with any other library facilities. This must be distributed under the terms of the Sections above.

b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library,and explaining where to find the accompanying uncombined form of the same work.

8. You may not copy,modify,sublicense,link with,or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy,or distribute the Library is void,and will automatically terminate your rights under this License. However,parties who have received copies,or rights,from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

9. You are not required to accept this License,since you have not signed it. However,nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore,by modifying or distributing the Library (or any work based on the Library),you indicate your acceptance of this License to do so,and all its terms and conditions for copying,distributing or modifying the Library or works based on it.

10. Each time you redistribute the Library (or any work based on the Library),the recipient automatically receives a license from the original licensor to copy,distribute,link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

11. If,as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues),conditions are imposed on you (whether by court order,agreement or otherwise) that contradict the conditions of this License,they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations,then as a consequence you may not distribute the Library at all. For example,if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you,then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any particular circumstance,the balance of the section is intended to apply,and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces,the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries,so that distribution is permitted only in or among countries not thus excluded. In such case,this License incorporates the limitation as if written in the body of this License.

13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version,but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version",you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number,you may choose any version ever published by the Free Software Foundation.

14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these,write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation,write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,THERE IS NO WARRANTY FOR THE LIBRARY,TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND,EITHER EXPRESSED OR IMPLIED,INCLUDING,BUT NOT LIMITED TO,THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE,YOU ASSUME THE COST OF ALL NECESSARY SERVICING,REPAIR OR CORRECTION.

16. IN NO EVENT UNLESS required BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER,OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE,BE LIABLE TO YOU FOR DAMAGES,INCLUDING ANY GENERAL,SPECIAL,INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library,and you want it to be of the greatest possible use to the public,we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or,alternatively,under the terms of the ordinary General Public License).

To apply these terms,attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the library's name and an idea of what it does.
Copyright (C) year name of author

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License,or (at your option) any later version.

This library 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. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not,write to the Free Software Foundation,Inc.,59 Temple Place,Suite 330,MA 02111-1307 USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school,if any,to sign a "copyright disclaimer" for the library,if necessary. Here is a sample; alter the names:

Yoyodyne,hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker.

signature of Ty Coon,1 April 1990 Ty Coon,President of Vice

That's all there is to it!

发行说明

Changes in Mini-XML 2.5

• The mxmldoc program now makes greater use of CSS and supports a --css option to embed an alternate stylesheet.
• The mxmldoc program now supports --header and --footer options to insert documentation content before and after the generated content.
• The mxmldoc program now supports a --framed option to generate framed HTML output.
• The mxmldoc program now creates a table of contents including any headings in the --intro file when generating HTML output.
• The man pages and man page output from mxmldoc did not use "/-" for dashes (STR #68)
• The debug version of the Mini-XML DLL could not be built (STR #65)
• Processing instructions and directives did not work when not at the top level of a document (STR #67)
• Spaces around the "=" in attributes were not supported (STR #67)

Changes in Mini-XML 2.4

• Fixed shared library build problems on HP-UX and Mac OS X.
• The mxmldoc program did not output argument descriptions for functions properly.
• All global settings (custom,error,and entity callbacks and the wrap margin) are now managed separately for each thread.
• Added mxmlElementDeleteAttr() function (STR #59)
• mxmlElementSetAttrf() did not work (STR #57)
• mxmlLoad*() incorrectly treated declarations as parent elements (STR #56)
• mxmlLoad*() incorrectly allowed attributes without values (STR #47)
• Fixed Visual C++ build problems (STR #49)
• mxmlLoad*() did not return NULL when an element contained an error (STR #46)
• Added support for the apos character entity (STR #54)
• Fixed whitespace detection with Unicode characters (STR #48)
• mxmlWalkNext() and mxmlWalkPrev() did not work correctly when called with a node with no children as the top node (STR #53)

Changes in Mini-XML 2.3

• Added two exceptions to the LGPL to support static linking of applications against Mini-XML
• The mxmldoc utility can now generate man pages,too.
• Added a mxmlNewXML() function
• Added a mxmlElementSetAttrf() function (STR #43)
• Added a snprintf() emulation function for the test program (STR #32)
• Added the _CRT_SECURE_NO_DEPRECATE definition when building on VC++ 2005 (STR #36)
• mxmlLoad*() did not detect missing > characters in elements (STR #41)
• mxmlLoad*() did not detect missing close tags at the end of an XML document (STR #45)
• Added user_data and ref_count members to mxml_node_t structure
• Added mxmlReleaseNode() and mxmlRetainNode() APIs for reference-counted nodes
• Added mxmlSetWrapMargin() to control the wrapping of XML output
• Added conditional check for EINTR error code for certain Windows compilers that do not define it (STR #33)
• The mxmldoc program now generates correct HTML 4.0 output - prevIoUsly it generated invalid XHTML
• The mxmldoc program now supports "@deprecated@,"@private@",and "@since version@" comments
• Fixed function and enumeration type bugs in mxmldoc
• Fixed the XML schema for mxmldoc
• The mxmldoc program now supports --intro,--section,and --title options
• The mxmlLoad*() functions could leak a node on an error (STR #27)
• The mxml_vsnprintf() function could get in an infinite loop on a buffer overflow (STR #25)
• Added new mxmlNewCDATA() and mxmlSetCDATA() functions to create and set CDATA nodes,which are really just special element nodes
• Added new MXML_IGNORE type and MXML_IGNORE_CB callback to ignore non-element nodes,e.g. whitespace
• mxmlLoad*() did not treat custom data as opaque,so whitespace characters would be lost

Changes in Mini-XML 2.2.2

• mxmlLoad*() did not treat custom data as opaque,so whitespace characters would be lost.

Changes in Mini-XML 2.2.1

• mxmlLoadFd(),mxmlLoadFile(),and mxmlLoadString() now correctly return NULL on error (STR #21)
• mxmlNewInteger(),mxmlNewOpaque(),mxmlNewReal(),mxmlNewText(),and mxmlNewTextf() incorrectly required a parent node (STR #22)
• Fixed an XML output bug in mxmldoc.
• The "make install" target now uses the install command to set the proper permissions on UNIX/Linux/OSX.
• Fixed a MingW/Cygwin compilation problem (STR #18)

Changes in Mini-XML 2.2

• Added shared library support (STR #17)
• mxmlLoad*() now returns an error when an XML stream contains illegal control characters (STR #10)
• mxmlLoad*() now returns an error when an element contains two attributes with the same name in conformance with the XML spec (STR #16)
• Added support for CDATA (STR #14,STR #15)
• Updated comment and processing instruction handling - no entity support per XML specification.
• Added checking for invalid comment termination ("--->" is not allowed)

Changes in Mini-XML 2.1

• Added support for custom data nodes (STR #6)
• Now treat UTF-8 sequences which are longer than necessary as an error (STR #4)
• Fixed entity number support (STR #8)
• Fixed mxmlLoadString() bug with UTF-8 (STR #7)
• Fixed entity lookup bug (STR #5)
• Added mxmlLoadFd() and mxmlSaveFd() functions.
• Fixed multi-word UTF-16 handling.

Changes in Mini-XML 2.0

• New programmers manual.
• Added Visual C++ project files for Microsoft Windows users.
• Added optimizations to mxmldoc,mxmlSaveFile(),and mxmlIndexNew() (STR #2)
• mxmlEntityAddCallback() now returns an integer status (STR #2)
• Added UTF-16 support (input only; all output is UTF-8)
• Added index functions to build a searchable index of XML nodes.
• Added character entity callback interface to support additional character entities beyond those defined in the XHTML specification.
• Added support for XHTML character entities.
• The mxmldoc utility now produces XML output which conforms to an updated XML schema,described in the file "doc/mxmldoc.xsd".
• Changed the whitespace callback interface to return strings instead of a single character,allowing for greater control over the formatting of XML files written using Mini-XML. THIS CHANGE WILL REQUIRE CHANGES TO YOUR 1.x CODE IF YOU USE WHITESPACE CALLBACKS.
• The mxmldoc utility now produces XML output which conforms to an updated XML schema,allowing for greater control over the formatting of XML files written using Mini-XML. THIS CHANGE WILL REQUIRE CHANGES TO YOUR 1.x CODE IF YOU USE WHITESPACE CALLBACKS.
• The mxmldoc utility is now capable of documenting C++ classes,functions,and structures,and correctly handles C++ comments.
• Added new modular tests for mxmldoc.
• Updated the mxmldoc output to be more compatible with embedding in manuals produced with HTMLDOC.
• The makefile incorrectly included a "/" separator between the destination path and install path. This caused problems when building and installing with MingW.

Changes in Mini-XML 1.3

• Fixes for mxmldoc.
• Added support for reading standard HTML entity names.
• mxmlLoadString/File() did not decode character entities in element names,attribute names,or attribute values.
• mxmlLoadString/File() would crash when loading non- conformant XML data under an existing parent (top) node.
• Fixed several bugs in the mxmldoc utility.
• Added new error callback function to catch a variety of errors and log them to someplace other than stderr.
• The mxmlElementSetAttr() function now allows for NULL attribute values.
• The load and save functions now properly handle quoted element and attribute name strings properly,e.g. for !DOCTYPE declarations.

Changes in Mini-XML 1.2

• Added new "set" methods to set the value of a node.
• Added new formatted text methods mxmlNewTextf() and mxmlSetTextf() to create/set a text node value using printf-style formats.
• Added new standard callbacks for use with the mxmlLoad functions.
• Updated the HTML documentation to include examples of the walk and load function output.
• Added --with/without-ansi configure option to control the strdup() function check.
• Added --with/without-snprintf configure option to control the snprintf() and vsnprintf() function checks.

Changes in Mini-XML 1.1.2

• The mxml(3) man page wasn't updated for the string functions.
• mxmlSaveString() returned the wrong number of characters.
• mxml_add_char() updated the buffer pointer in the wrong place.

Changes in Mini-XML 1.1.1

• The private mxml_add_ch() function did not update the start-of-buffer pointer which could cause a crash when using mxmlSaveString().
• The private mxml_write_ws() function called putc() instead of using the proper callback which could cause a crash when using mxmlSaveString().
• Added a mxmlSaveAllocString() convenience function for saving an XML node tree to an allocated string.

Changes in Mini-XML 1.1

• The mxmlLoadFile() function now uses dynamically allocated string buffers for element names,and attribute values. PrevIoUsly they were capped at 16383,255,and 255 bytes,respectively.
• Added a new mxmlLoadString() function for loading an XML node tree from a string.
• Added a new mxmlSaveString() function for saving an XML node tree to a string.
• Add emulation of strdup() if the local platform does not provide the function.

Changes in Mini-XML 1.0

• The mxmldoc program now handles function arguments,structures,unions,enumerations,classes,and typedefs properly.
• Documentation provided via mxmldoc and more in-line comments in the code.
• Added man pages and packaging files.

Changes in Mini-XML 0.93

• New mxmldoc example program that is also used to create and update code documentation using XML and produce HTML reference pages.
• Added mxmlAdd() and mxmlRemove() functions to add and remove nodes from a tree. This provides more flexibility over where the nodes are inserted and allows nodes to be moved within the tree as needed.
• mxmlLoadFile() now correctly handles comments.
• mxmlLoadFile() now supports the required "gt","quot",and "nbsp" character entities.
• mxmlSaveFile() now uses newlines as whitespace when valid to do so.
• mxmlFindElement() now also takes attribute name and attribute value string arguments to limit the search to specific elements with attributes and/or values.NULL pointers can be used as "wildcards".
• Added uninstall target to makefile,and auto-reconfig if Makefile.in or configure.in are changed.
• mxmlFindElement(),mxmlWalkNext(),and mxmlWalkPrev() now all provide "descend" arguments to control whether they descend into child nodes in the tree.
• Fixed some whitespace issues in mxmlLoadFile().
• Fixed Unicode output and whitespace issues in mxmlSaveFile().
• mxmlSaveFile() now supports a whitespace callback to provide more human-readable XML output under program control.

Changes in Mini-XML 0.92

• mxmlSaveFile() didn't return a value on success.

Changes in Mini-XML 0.91

• mxmlWalkNext() would go into an infinite loop.

@L_24_301@

• Initial public release.

XML Schema

这个附录提供了mxmldoc程序生成XML文件时使用的XML schema。这个schema 的在线版本参见：

    http://www.easysw.com/~mike/mxmldoc.xsd

mxmldoc.xsd

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:annotation>
    <xsd:documentation xml:lang="en">
      Mini-XML 2.3 documentation schema for mxmldoc output.
      Copyright 2003-2007 by Michael Sweet.
    </xsd:documentation>
  </xsd:annotation>

  <!-- basic element definitions -->
  <xsd:element name="argument" type="argumentType"/>
  <xsd:element name="class" type="classType"/>
  <xsd:element name="constant" type="constantType"/>
  <xsd:element name="description" type="xsd:string"/>
  <xsd:element name="enumeration" type="enumerationType"/>
  <xsd:element name="function" type="functionType"/>
  <xsd:element name="mxmldoc" type="mxmldocType"/>
  <xsd:element name="namespace" type="namespaceType"/>
  <xsd:element name="returnvalue" type="returnvalueType"/>
  <xsd:element name="seealso" type="identifierList"/>
  <xsd:element name="struct" type="structType"/>
  <xsd:element name="typedef" type="typedefType"/>
  <xsd:element name="type" type="xsd:string"/>
  <xsd:element name="union" type="unionType"/>
  <xsd:element name="variable" type="variableType"/>

  <!-- descriptions of complex elements -->
  <xsd:complexType name="argumentType">
    <xsd:sequence>
      <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
    <xsd:attribute name="default" type="xsd:string" use="optional"/>
    <xsd:attribute name="name" type="identifier" use="required"/>
    <xsd:attribute name="direction" type="direction" use="optional"
     default="I"/>
  </xsd:complexType>

  <xsd:complexType name="classType">
    <xsd:sequence>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
      <xsd:choice minOccurs="0" maxOccurs="unbounded">
	<xsd:element ref="class"/>
	<xsd:element ref="enumeration"/>
	<xsd:element ref="function"/>
	<xsd:element ref="struct"/>
	<xsd:element ref="typedef"/>
	<xsd:element ref="union"/>
	<xsd:element ref="variable"/>
      </xsd:choice>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
    <xsd:attribute name="parent" type="xsd:string" use="optional"/>
  </xsd:complexType>

  <xsd:complexType name="constantType">
    <xsd:sequence>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <xsd:complexType name="enumerationType">
    <xsd:sequence>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
      <xsd:element ref="constant" minOccurs="1" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <xsd:complexType name="functionType">
    <xsd:sequence>
      <xsd:element ref="returnvalue" minOccurs="0" maxOccurs="1"/>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
      <xsd:element ref="argument" minOccurs="1" maxOccurs="unbounded"/>
      <xsd:element ref="seealso" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
    <xsd:attribute name="scope" type="scope" use="optional"/>
  </xsd:complexType>

  <xsd:complexType name="mxmldocType">
    <xsd:choice minOccurs="0" maxOccurs="unbounded">
      <xsd:element ref="class"/>
      <xsd:element ref="enumeration"/>
      <xsd:element ref="function"/>
      <xsd:element ref="namespace"/>
      <xsd:element ref="struct"/>
      <xsd:element ref="typedef"/>
      <xsd:element ref="union"/>
      <xsd:element ref="variable"/>
    </xsd:choice>
  </xsd:complexType>

  <xsd:complexType name="namespaceType">
    <xsd:sequence>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
      <xsd:choice minOccurs="0" maxOccurs="unbounded">
	<xsd:element ref="class"/>
	<xsd:element ref="enumeration"/>
	<xsd:element ref="function"/>
	<xsd:element ref="struct"/>
	<xsd:element ref="typedef"/>
	<xsd:element ref="union"/>
	<xsd:element ref="variable"/>
      </xsd:choice>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <xsd:complexType name="returnvalueType">
    <xsd:sequence>
      <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:complexType name="structType">
    <xsd:sequence>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
      <xsd:choice minOccurs="0" maxOccurs="unbounded">
	<xsd:element ref="variable"/>
	<xsd:element ref="function"/>
      </xsd:choice>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <xsd:complexType name="typedefType">
    <xsd:sequence>
      <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <xsd:complexType name="unionType">
    <xsd:sequence>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
      <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <xsd:complexType name="variableType">
    <xsd:sequence>
      <xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
      <xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="identifier" use="required"/>
  </xsd:complexType>

  <!-- data types -->
  <xsd:simpleType name="direction">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="I"/>
      <xsd:enumeration value="O"/>
      <xsd:enumeration value="IO"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="identifier">
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="identifierList">
    <xsd:list itemType="identifier"/>
  </xsd:simpleType>

  <xsd:simpleType name="scope">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value=""/>
      <xsd:enumeration value="private"/>
      <xsd:enumeration value="protected"/>
      <xsd:enumeration value="public"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>