mxml.html

minixml2.5最新的版本。 嵌入式xml 解析、查找、生成、遍历 功能,全部实现是标准c,移植很容易。 最新的2.5

        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)
      {
       /*
        * If the parent was retained, then retain
        * this data node as well.
        */

        mxmlRetain(node);
      }
    }
</PRE>
<P>The resulting skeleton document tree can then be searched just like
 one loaded using the <TT>mxmlLoad</TT> functions. For example, a filter
 that reads an XHTML document from stdin and then shows the title and
 headings in the document would look like:</P>
<PRE>
    mxml_node_t *doc, *title, *body, *heading;

    doc = mxmlSAXLoadFd(NULL, 0,
                        MXML_TEXT_CALLBACK,
                        <B>sax_cb</B>, NULL);

    title = mxmlFindElement(doc, doc, &quot;title&quot;,
                            NULL, NULL,
                            MXML_DESCEND);

    if (title)
      print_children(title);

    body = mxmlFindElement(doc, doc, &quot;body&quot;,
                           NULL, NULL,
                           MXML_DESCEND);

    if (body)
    {
      for (heading = body-&gt;child;
           heading;
           heading = heading-&gt;next)
        print_children(heading);
    }
</PRE>
<HR NOSHADE>
<H1 align="right"><A name="MXMLDOC"><IMG align="right" alt="4" height="100"
hspace="10" src="4.gif" width="100"></A>Using the mxmldoc Utility</H1>
<P>This chapter describes how to use <TT>mxmldoc(1)</TT> program to
 automatically generate documentation from C and C++ source files.</P>
<H2><A NAME="5_1">The Basics</A></H2>
<P>Originally developed to generate the Mini-XML and CUPS API
 documentation, <TT>mxmldoc</TT> is now a general-purpose utility which
 scans C and C++ source files to produce HTML and man page documentation
 along with an XML file representing the functions, types, and
 definitions in those source files. Unlike popular documentation
 generators like Doxygen or Javadoc, <TT>mxmldoc</TT> uses in-line
 comments rather than comment headers, allowing for more &quot;natural&quot; code
 documentation.</P>
<P>By default, <TT>mxmldoc</TT> produces HTML documentation. For
 example, the following command will scan all of the C source and header
 files in the current directory and produce a HTML documentation file
 called<VAR> filename.html</VAR>:</P>
<PRE>
    <KBD>mxmldoc *.h *.c &gt;filename.html ENTER</KBD>
</PRE>
<P>You can also specify an XML file to create which contains all of the
 information from the source files. For example, the following command
 creates an XML file called<VAR> filename.xml</VAR> in addition to the
 HTML file:</P>
<PRE>
    <KBD>mxmldoc filename.xml *.h *.c &gt;filename.html ENTER</KBD>
</PRE>
<P>The <TT>--no-output</TT> option disables the normal HTML output:</P>
<PRE>
    <KBD>mxmldoc --no-output filename.xml *.h *.c ENTER</KBD>
</PRE>
<P>You can then run <TT>mxmldoc</TT> again with the XML file alone to
 generate the HTML documentation:</P>
<PRE>
    <KBD>mxmldoc filename.xml &gt;filename.html ENTER</KBD>
</PRE>
<P>The <TT>--man filename</TT> option tells <TT>mxmldoc</TT> to create a
 man page instead of HTML documentation, for example:</P>
<PRE>
    <KBD>mxmldoc --man filename filename.xml \
        &gt;filename.man ENTER</KBD>

    <KBD>mxmldoc --man filename *.h *.c \
        &gt;filename.man ENTER</KBD>

    <KBD>mxmldoc --man filename filename.xml *.h *.c \
        &gt;filename.man ENTER</KBD>
</PRE>
<H2><A NAME="5_2">Commenting Your Code</A></H2>
<P>As noted previously, <TT>mxmldoc</TT> looks for in-line comments to
 describe the functions, types, and constants in your code. <TT>Mxmldoc</TT>
 will document all public names it finds in your source files - any
 names starting with the underscore character (_) or names that are
 documented with the <A HREF="#ATDIRECTIVES">@private@</A> directive are
 treated as private and are undocumented.</P>
<P>Comments appearing directly before a function or type definition are
 used to document that function or type. Comments appearing after
 argument, definition, return type, or variable declarations are used to
 document that argument, definition, return type, or variable. For
 example, the following code excerpt defines a key/value structure and a
 function that creates a new instance of that structure:</P>
<PRE>
    /* 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 */
    {
      ...
    }
</PRE>
<P><TT>Mxmldoc</TT> also knows to remove extra asterisks (*) from the
 comment string, so the comment string:</P>
<PRE>
    /*
     * 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.
     */
</PRE>
<P>will be shown as:</P>
<PRE>
    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.
</PRE>
<P><A name="ATDIRECTIVES">Comments</A> can also include the following
 special <TT>@name ...@</TT> directive strings:</P>
<UL>
<LI><TT>@deprecated@</TT> - flags the item as deprecated to discourage
 its use</LI>
<LI><TT>@private@</TT> - flags the item as private so it will not be
 included in the documentation</LI>
<LI><TT>@since ...@</TT> - flags the item as new since a particular
 release. The text following the <TT>@since</TT> up to the closing <TT>@</TT>
 is highlighted in the generated documentation, e.g. <TT>@since CUPS
 1.3@</TT>.</LI>
</UL>

<!-- NEED 10 -->
<H2><A NAME="5_3">Titles, Sections, and Introductions</A></H2>
<P><TT>Mxmldoc</TT> also provides options to set the title, section, and
 introduction text for the generated documentation. The <TT>--title text</TT>
 option specifies the title for the documentation. The title string is
 usually put in quotes:</P>
<PRE>
    <KBD>mxmldoc filename.xml \
        --title &quot;My Famous Documentation&quot; \
        &gt;filename.html ENTER</KBD>
</PRE>
<P>The <TT>--section name</TT> option specifies the section for the
 documentation. For HTML documentation, the name is placed in a HTML
 comment such as:</P>
<PRE>
    &lt;!-- SECTION: name --&gt;
</PRE>
<P>For man pages, the section name is usually just a number (&quot;3&quot;), or a
 number followed by a vendor name (&quot;3acme&quot;). The section name is used in
 the <TT>.TH</TT> directive in the man page:</P>
<PRE>
    .TH mylibrary 3acme &quot;My Title&quot; ...
</PRE>
<P>The default section name for man page output is &quot;3&quot;. There is no
 default section name for HTML output.</P>
<P>Finally, the <TT>--intro filename</TT> option specifies a file to
 embed after the title and section but before the generated
 documentation. For HTML documentation, the file must consist of valid
 HTML without the usual <TT>DOCTYPE</TT>, <TT>html</TT>, and <TT>body</TT>
 elements. For man page documentation, the file must consist of valid <TT>
nroff(1)</TT> text.</P>
<HR NOSHADE>
<H1 align="right"><A name="LICENSE"><IMG align="right" alt="A" height="100"
hspace="10" src="A.gif" width="100"></A>Mini-XML License</H1>
<P>The Mini-XML library and included programs are provided under the
 terms of the GNU Library General Public License (LGPL) with the
 following exceptions:</P>
<OL>
<LI>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.
<P><I>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.</I></P>
</LI>
<LI>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.</LI>
</OL>
<P align="center"><B>GNU LIBRARY GENERAL PUBLIC LICENSE</B></P>
<P align="center">Version 2, June 1991
<BR> Copyright (C) 1991 Free Software Foundation, Inc.
<BR> 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
<BR> Everyone is permitted to copy and distribute verbatim copies of
 this license document, but changing it is not allowed.
<BR> [This is the first released version of the library GPL. It is
 numbered 2 because it goes with version 2 of the ordinary GPL.]</P>
<P><B>Preamble</B></P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>The precise terms and conditions for copying, distribution and
 modification follow. Pay close attention to the difference between a
 &quot;work based on the libary&quot; and a &quot;work that uses the library&quot;. The
 former contains code derived from the library, while the latter only
 works together with the library.</P>
<P>Note that it is possible for a library to be covered by the ordinary
 General Public License rather than by this special one.</P>
<P align="center"><B>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
 MODIFICATION</B></P>
<P><STRONG>0.</STRONG> 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 &quot;this License&quot;). Each
 licensee is addressed as &quot;you&quot;.</P>
<P>A &quot;library&quot; 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.</P>
<P>The &quot;Library&quot;, below, refers to any such software library or work
 which has been distributed under these terms. A &quot;work based on the
 Library&quot; means either the Library or any derivative work under
 copyright law: that is to say, a work