diff --git a/Makefile.in b/Makefile.in index f6180b8..52bcbb1 100644 --- a/Makefile.in +++ b/Makefile.in @@ -82,7 +82,7 @@ DOCFILES = doc/mxml.html doc/mxmldoc.xsd README.md COPYING CHANGES.md PUBLIBOBJS = mxml-attr.o mxml-entity.o mxml-file.o mxml-get.o \ mxml-index.o mxml-node.o mxml-search.o mxml-set.o LIBOBJS = $(PUBLIBOBJS) mxml-private.o mxml-string.o -OBJS = mxmldoc.o testmxml.o zipc.o $(LIBOBJS) +OBJS = mmd.o mxmldoc.o testmxml.o zipc.o $(LIBOBJS) ALLTARGETS = $(LIBMXML) mxmldoc testmxml mxml.xml @MXML_EPUB@ CROSSTARGETS = $(LIBMXML) mxmldoc TARGETS = $(@TARGETS@) @@ -293,16 +293,17 @@ libmxml.1.dylib: $(LIBOBJS) # mxmldoc # -mxmldoc: $(LIBMXML) mxmldoc.o @ZIPC@ +mxmldoc: $(LIBMXML) mxmldoc.o mmd.o @ZIPC@ echo Linking $@... - $(CC) -L. $(LDFLAGS) -o $@ mxmldoc.o @ZIPC@ -lmxml $(LIBS) + $(CC) -L. $(LDFLAGS) -o $@ mxmldoc.o mmd.o @ZIPC@ -lmxml $(LIBS) -mxmldoc-static: libmxml.a mxmldoc.o @ZIPC@ +mxmldoc-static: libmxml.a mxmldoc.o mmd.o @ZIPC@ echo Linking $@... - $(CC) $(LDFLAGS) -o $@ mxmldoc.o @ZIPC@ libmxml.a $(LIBS) + $(CC) $(LDFLAGS) -o $@ mxmldoc.o mmd.o @ZIPC@ libmxml.a $(LIBS) -mxmldoc.o: mxml.h zipc.h +mxmldoc.o: mxml.h zipc.h mmd.h zipc.o: zipc.h +mmd.o: mmd.h # @@ -354,18 +355,14 @@ mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c) --title "Mini-XML API Reference" \ mxml.xml mxml.h $(PUBLIBOBJS:.o=.c) >doc/reference.html ./mxmldoc-static --man mxml --title "Mini-XML API" \ - --intro doc/intro.man --footer doc/footer.man \ - --author "Michael R Sweet" \ - --copyright "Copyright 2003-2017, All Rights Reserved." \ + --body doc/body.man --footer doc/footer.man \ mxml.xml >doc/mxml.man if test "x`uname`" = xDarwin; then \ ./mxmldoc-static --docset org.msweet.mxml.docset \ --docversion @VERSION@ --feedname org.msweet.mxml \ --feedurl https://michaelrsweet.github.io/mxml/org.msweet.mxml.atom \ - --header doc/docset.header --intro doc/docset.intro \ - --css doc/docset.css --author "Michael R Sweet" \ - --copyright "Copyright 2003-2017, All Rights Reserved." \ - --title "Mini-XML API Reference" \ + --header doc/docset.header --body doc/body.md \ + --css doc/docset.css \ mxml.xml || exit 1; \ $(RM) org.msweet.mxml.atom; \ xcrun docsetutil package --output org.msweet.mxml.xar \ @@ -382,7 +379,7 @@ mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c) mxml.epub: mxml.xml echo Generating EPUB API documentation... ./mxmldoc-static --header doc/docset.header \ - --intro doc/docset.intro --css doc/docset.css \ + --body doc/body.md \ --docversion @VERSION@ --author "Michael R Sweet" \ --copyright "Copyright 2003-2017, All Rights Reserved." \ --title "Mini-XML API Reference" \ diff --git a/doc/intro.man b/doc/body.man similarity index 100% rename from doc/intro.man rename to doc/body.man diff --git a/doc/body.md b/doc/body.md new file mode 100644 index 0000000..6afa7f6 --- /dev/null +++ b/doc/body.md @@ -0,0 +1,144 @@ +--- +title: Mini-XML API Reference +author: Michael R Sweet +copyright: Copyright (c) 2003-2017, All Rights Reserved. +docversion: 2.11 +... + +# Introduction + +Mini-XML is a small XML parsing library that you can use to read XML data files +or strings in your application without requiring large non-standard libraries. +Mini-XML provides the following functionality: + +- Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files and + strings. +- Data is stored in a linked-list tree structure, preserving the XML data + hierarchy. +- SAX (streamed) reading of XML files and strings to minimize memory usage. +- Supports arbitrary element names, attributes, and attribute values with no + preset limits, just available memory. +- Supports integer, real, opaque ("cdata"), and text data types in "leaf" + nodes. +- Functions for creating and managing trees of data. +- "Find" and "walk" functions for easily locating and navigating trees of + data. + +Mini-XML doesn't do validation or other types of processing on the data based +upon schema files or other sources of definition information. + +# Using Mini-XML + +Mini-XML provides a single header file which you include: + + #include + +Nodes are defined by the `mxml_node_t` structure; the "type" member defines the +node type (element, integer, opaque, real, or text) which determines which value +you want to look at in the "value" union. New nodes can be created using the +`mxmlNewElement`, `mxmlNewInteger`, `mxmlNewOpaque`, `mxmlNewReal`, and +`mxmlNewText` functions. Only elements can have child nodes, and the top node +must be an element, usually "?xml". + +You load an XML file using the `mxmlLoadFile` function: + + FILE *fp; + mxml_node_t *tree; + + fp = fopen("filename.xml", "r"); + tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK); + fclose(fp); + +Similarly, you save an XML file using the `mxmlSaveFile` function: + + FILE *fp; + mxml_node_t *tree; + + fp = fopen("filename.xml", "w"); + mxmlSaveFile(tree, fp, MXML_NO_CALLBACK); + fclose(fp); + +The `mxmlLoadString`, `mxmlSaveAllocString`, and `mxmlSaveString` functions +load XML node trees from and save XML node trees to strings: + + char buffer[8192]; + char *ptr; + mxml_node_t *tree; + + ... + tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK); + + ... + mxmlSaveString(tree, buffer, sizeof(buffer), + MXML_NO_CALLBACK); + + ... + ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK); + +You can find a named element/node using the `mxmlFindElement` function: + + mxml_node_t *node = mxmlFindElement(tree, tree, "name", + "attr", "value", + MXML_DESCEND); + +The "name", "attr", and "value" arguments can be passed as `NULL` to act as +wildcards, e.g.: + + /* Find the first "a" element */ + node = mxmlFindElement(tree, tree, "a", NULL, NULL, + MXML_DESCEND); + + /* Find the first "a" element with "href" attribute */ + node = mxmlFindElement(tree, tree, "a", "href", NULL, + MXML_DESCEND); + + /* Find the first "a" element with "href" to a URL */ + node = mxmlFindElement(tree, tree, "a", "href", + "http://www.easysw.com/~mike/mxml/", + MXML_DESCEND); + + /* Find the first element with a "src" attribute*/ + node = mxmlFindElement(tree, tree, NULL, "src", NULL, + MXML_DESCEND); + + /* Find the first element with a "src" = "foo.jpg" */ + node = mxmlFindElement(tree, tree, NULL, "src", + "foo.jpg", MXML_DESCEND); + +You can also iterate with the same function: + + mxml_node_t *node; + + for (node = mxmlFindElement(tree, tree, "name", NULL, + NULL, MXML_DESCEND); + node != NULL; + node = mxmlFindElement(node, tree, "name", NULL, + NULL, MXML_DESCEND)) + { + ... do something ... + } + +The `mxmlFindPath` function finds the (first) value node under a specific +element using a "path": + + mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar"); + +The `mxmlGetInteger`, `mxmlGetOpaque`, `mxmlGetReal`, and `mxmlGetText` +functions retrieve the value from a node: + + mxml_node_t *node; + + int intvalue = mxmlGetInteger(node); + + const char *opaquevalue = mxmlGetOpaque(node); + + double realvalue = mxmlGetReal(node); + + int whitespacevalue; + const char *textvalue = mxmlGetText(node, &whitespacevalue); + +Finally, once you are done with the XML data, use the `mxmlDelete` function to +recursively free the memory that is used for a particular node or the entire +tree: + + mxmlDelete(tree); diff --git a/doc/docset.css b/doc/docset.css index e9e785a..677dcc6 100644 --- a/doc/docset.css +++ b/doc/docset.css @@ -21,7 +21,6 @@ pre { pre.example { background: white; border: dotted thin #999999; - margin-left: 36pt; padding: 10px; } diff --git a/doc/mxml.man b/doc/mxml.man index 1a47e2d..5f7a803 100644 --- a/doc/mxml.man +++ b/doc/mxml.man @@ -1,4 +1,4 @@ -.TH mxml 3 "Mini-XML API" "04/08/17" "Mini-XML API" +.TH mxml 3 "Mini-XML API" "04/11/17" "Mini-XML API" .SH NAME mxml \- Mini-XML API .SH INCLUDE FILE diff --git a/doc/mxmldoc.man b/doc/mxmldoc.man index 10c5ab0..a5f3680 100644 --- a/doc/mxmldoc.man +++ b/doc/mxmldoc.man @@ -11,7 +11,7 @@ .\" .\" https://michaelrsweet.github.io/mxml .\" -.TH mxmldoc 1 "Mini-XML" "6 April 2017" "Michael Sweet" +.TH mxmldoc 1 "Mini-XML" "11 April 2017" "Michael R Sweet" .SH NAME mxmldoc \- mini-xml documentation generator .SH SYNOPSIS @@ -25,14 +25,14 @@ mxmldoc \- mini-xml documentation generator .B mxmldoc [ \-\-author .I author +] [ \-\-body +.I bodyfile ] [ \-\-copyright .I copyright ] [ \-\-footer .I footerfile ] [ \-\-header .I headerfile -] [ \-\-intro -.I introfile ] [ \-\-section .I section ] [ \-\-title @@ -49,6 +49,8 @@ mxmldoc \- mini-xml documentation generator .I directory.docset [ \-\-author .I author +] [ \-\-body +.I bodyfile ] [ \-\-copyright .I copyright ] [ \-\-docversion @@ -61,8 +63,6 @@ mxmldoc \- mini-xml documentation generator .I footerfile ] [ \-\-header .I headerfile -] [ \-\-intro -.I introfile ] [ \-\-section .I section ] [ \-\-title @@ -87,14 +87,14 @@ mxmldoc \- mini-xml documentation generator .I basename [ \-\-author .I author +] [ \-\-body +.I bodyfile ] [ \-\-copyright .I copyright ] [ \-\-footer .I footerfile ] [ \-\-header .I headerfile -] [ \-\-intro -.I introfile ] [ \-\-section .I section ] [ \-\-title @@ -108,14 +108,14 @@ mxmldoc \- mini-xml documentation generator .B mxmldoc [ \-\-author .I author +] [ \-\-body +.I bodyfile ] [ \-\-copyright .I copyright ] [ \-\-footer .I footerfile ] [ \-\-header .I headerfile -] [ \-\-intro -.I introfile ] \-\-man .I manpage [ \-\-section @@ -134,6 +134,8 @@ mxmldoc \- mini-xml documentation generator .I filename.epub [ \-\-author .I author +] [ \-\-body +.I bodyfile ] [ \-\-copyright .I copyright ] [ \-\-docversion @@ -146,8 +148,6 @@ mxmldoc \- mini-xml documentation generator .I footerfile ] [ \-\-header .I headerfile -] [ \-\-intro -.I introfile ] [ \-\-section .I section ] [ \-\-title @@ -180,6 +180,10 @@ Guide which is available at "http://www.cups.org/doc/spec-cmp.html". .br Specifies the name of the documentation author. .TP 5 +\-\-body bodyfile +.br +Inserts the specified file between the table of contents and references. +.TP 5 \-\-copyright "copyright text" .br Specifies the copyright text to use. @@ -219,10 +223,6 @@ one for the body. .br Inserts the specified file at the top of the output documentation. .TP 5 -\-\-intro introfile -.br -Inserts the specified file before the table of contents. -.TP 5 \-\-man manpage .br Generated a man page instead of HTML documentation. diff --git a/doc/reference.html b/doc/reference.html index 3957ae5..273db59 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -9,7 +9,7 @@