Commit bcfa6ef5 authored by Michael Sweet's avatar Michael Sweet

Update/fix documentation.

Add mxmlNewOpaquef and mxmlSetOpaquef functions.

Fix discussion writing code to look for opaque strings.

Fix dependencies for documentation generation.
parent 48c3c625
......@@ -11,6 +11,8 @@
- The mxmldoc utility now supports the `SOURCE_DATE_EPOCH` environment
variable for reproducible builds (Issue #193)
- The mxmldoc utility now supports Markdown (Issue #194)
- Added `mxmlNewOpaquef` and `mxmlSetOpaquef` functions to add and set formatted
opaque string values.
# Changes in Mini-XML 2.10
......
......@@ -360,7 +360,10 @@ testmxml.o: mxml.h
# mxml.xml
#
mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c)
mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c) \
doc/body.man doc/body.md \
doc/docset.css doc/docset.header \
doc/reference.header
echo Generating API documentation...
$(RM) mxml.xml
./mxmldoc-static --header doc/reference.header \
......@@ -390,13 +393,9 @@ mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c)
# mxml.epub
#
mxml.epub: mxml.xml
mxml.epub: mxml.xml doc/body.md doc/mxml-cover.png
echo Generating EPUB API documentation...
./mxmldoc-static --header doc/docset.header \
--body doc/body.md \
--docversion @VERSION@ --author "Michael R Sweet" \
--copyright "Copyright 2003-2017, All Rights Reserved." \
--title "Mini-XML API Reference" \
./mxmldoc-static --body doc/body.md \
--coverimage doc/mxml-cover.png \
--epub mxml.epub mxml.xml
......
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -92,11 +92,11 @@ mxmlElementDeleteAttr(mxml_node_t *node,/* I - Element */
/*
* 'mxmlElementGetAttr()' - Get an attribute.
*
* This function returns NULL if the node is not an element or the
* This function returns @code NULL@ if the node is not an element or the
* named attribute does not exist.
*/
const char * /* O - Attribute value or NULL */
const char * /* O - Attribute value or @code NULL@ */
mxmlElementGetAttr(mxml_node_t *node, /* I - Element node */
const char *name) /* I - Name of attribute */
{
......
......@@ -50,10 +50,10 @@ mxmlEntityAddCallback(
/*
* 'mxmlEntityGetName()' - Get the name that corresponds to the character value.
*
* If val does not need to be represented by a named entity, NULL is returned.
* If val does not need to be represented by a named entity, @code NULL@ is returned.
*/
const char * /* O - Entity name or NULL */
const char * /* O - Entity name or @code NULL@ */
mxmlEntityGetName(int val) /* I - Character value */
{
switch (val)
......
This diff is collapsed.
......@@ -28,7 +28,7 @@
* @since Mini-XML 2.7@
*/
const char * /* O - CDATA value or NULL */
const char * /* O - CDATA value or @code NULL@ */
mxmlGetCDATA(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -56,7 +56,7 @@ mxmlGetCDATA(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
const void * /* O - Custom value or NULL */
const void * /* O - Custom value or @code NULL@ */
mxmlGetCustom(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -89,7 +89,7 @@ mxmlGetCustom(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
const char * /* O - Element name or NULL */
const char * /* O - Element name or @code NULL@ */
mxmlGetElement(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -116,7 +116,7 @@ mxmlGetElement(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
mxml_node_t * /* O - First child or NULL */
mxml_node_t * /* O - First child or @code NULL@ */
mxmlGetFirstChild(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -177,7 +177,7 @@ mxmlGetInteger(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
mxml_node_t * /* O - Last child or NULL */
mxml_node_t * /* O - Last child or @code NULL@ */
mxmlGetLastChild(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -230,7 +230,7 @@ mxmlGetNextSibling(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
const char * /* O - Opaque string or NULL */
const char * /* O - Opaque string or @code NULL@ */
mxmlGetOpaque(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -263,7 +263,7 @@ mxmlGetOpaque(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
mxml_node_t * /* O - Parent node or NULL */
mxml_node_t * /* O - Parent node or @code NULL@ */
mxmlGetParent(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -289,7 +289,7 @@ mxmlGetParent(mxml_node_t *node) /* I - Node to get */
* @since Mini-XML 2.7@
*/
mxml_node_t * /* O - Previous node or NULL */
mxml_node_t * /* O - Previous node or @code NULL@ */
mxmlGetPrevSibling(mxml_node_t *node) /* I - Node to get */
{
/*
......@@ -344,12 +344,12 @@ mxmlGetReal(mxml_node_t *node) /* I - Node to get */
* 'mxmlGetText()' - Get the text value for a node or its first child.
*
* @code NULL@ is returned if the node (or its first child) is not a text node.
* The "whitespace" argument can be NULL.
* The "whitespace" argument can be @code NULL@.
*
* @since Mini-XML 2.7@
*/
const char * /* O - Text string or NULL */
const char * /* O - Text string or @code NULL@ */
mxmlGetText(mxml_node_t *node, /* I - Node to get */
int *whitespace) /* O - 1 if string is preceded by whitespace, 0 otherwise */
{
......
......@@ -62,10 +62,12 @@ mxmlIndexDelete(mxml_index_t *ind) /* I - Index to delete */
/*
* 'mxmlIndexEnum()' - Return the next node in the index.
*
* Nodes are returned in the sorted order of the index.
* You should call @link mxmlIndexReset@ prior to using this function to get
* the first node in the index. Nodes are returned in the sorted order of the
* index.
*/
mxml_node_t * /* O - Next node or NULL if there is none */
mxml_node_t * /* O - Next node or @code NULL@ if there is none */
mxmlIndexEnum(mxml_index_t *ind) /* I - Index to enumerate */
{
/*
......@@ -89,13 +91,13 @@ mxmlIndexEnum(mxml_index_t *ind) /* I - Index to enumerate */
/*
* 'mxmlIndexFind()' - Find the next matching node.
*
* You should call mxmlIndexReset() prior to using this function for
* You should call @link mxmlIndexReset@ prior to using this function for
* the first time with a particular set of "element" and "value"
* strings. Passing NULL for both "element" and "value" is equivalent
* to calling mxmlIndexEnum().
* strings. Passing @code NULL@ for both "element" and "value" is equivalent
* to calling @link mxmlIndexEnum@.
*/
mxml_node_t * /* O - Node or NULL if none found */
mxml_node_t * /* O - Node or @code NULL@ if none found */
mxmlIndexFind(mxml_index_t *ind, /* I - Index to search */
const char *element, /* I - Element name to find, if any */
const char *value) /* I - Attribute value, if any */
......@@ -297,7 +299,7 @@ mxmlIndexGetCount(mxml_index_t *ind) /* I - Index of nodes */
* 'mxmlIndexNew()' - Create a new index.
*
* The index will contain all nodes that contain the named element and/or
* attribute. If both "element" and "attr" are NULL, then the index will
* attribute. If both "element" and "attr" are @code NULL@, then the index will
* contain a sorted list of the elements in the node tree. Nodes are
* sorted by element name and optionally by attribute value if the "attr"
* argument is not NULL.
......@@ -305,8 +307,8 @@ mxmlIndexGetCount(mxml_index_t *ind) /* I - Index of nodes */
mxml_index_t * /* O - New index */
mxmlIndexNew(mxml_node_t *node, /* I - XML node tree */
const char *element, /* I - Element to index or NULL for all */
const char *attr) /* I - Attribute to index or NULL for none */
const char *element, /* I - Element to index or @code NULL@ for all */
const char *attr) /* I - Attribute to index or @code NULL@ for none */
{
mxml_index_t *ind; /* New index */
mxml_node_t *current, /* Current node in index */
......@@ -457,11 +459,11 @@ mxmlIndexNew(mxml_node_t *node, /* I - XML node tree */
* 'mxmlIndexReset()' - Reset the enumeration/find pointer in the index and
* return the first node in the index.
*
* This function should be called prior to using mxmlIndexEnum() or
* mxmlIndexFind() for the first time.
* This function should be called prior to using @link mxmlIndexEnum@ or
* @link mxmlIndexFind@ for the first time.
*/
mxml_node_t * /* O - First node or NULL if there is none */
mxml_node_t * /* O - First node or @code NULL@ if there is none */
mxmlIndexReset(mxml_index_t *ind) /* I - Index to reset */
{
#ifdef DEBUG
......@@ -537,8 +539,8 @@ index_compare(mxml_index_t *ind, /* I - Index */
static int /* O - Result of comparison */
index_find(mxml_index_t *ind, /* I - Index */
const char *element, /* I - Element name or NULL */
const char *value, /* I - Attribute value or NULL */
const char *element, /* I - Element name or @code NULL@ */
const char *value, /* I - Attribute value or @code NULL@ */
mxml_node_t *node) /* I - Node */
{
int diff; /* Difference */
......
This diff is collapsed.
......@@ -24,22 +24,22 @@
* 'mxmlFindElement()' - Find the named element.
*
* The search is constrained by the name, attribute name, and value; any
* NULL names or values are treated as wildcards, so different kinds of
* @code NULL@ names or values are treated as wildcards, so different kinds of
* searches can be implemented by looking for all elements of a given name
* or all elements with a specific attribute. The descend argument determines
* whether the search descends into child nodes; normally you will use
* MXML_DESCEND_FIRST for the initial search and MXML_NO_DESCEND to find
* additional direct descendents of the node. The top node argument
* @code MXML_DESCEND_FIRST@ for the initial search and @code MXML_NO_DESCEND@
* to find additional direct descendents of the node. The top node argument
* constrains the search to a particular node's children.
*/
mxml_node_t * /* O - Element node or NULL */
mxml_node_t * /* O - Element node or @code NULL@ */
mxmlFindElement(mxml_node_t *node, /* I - Current node */
mxml_node_t *top, /* I - Top node */
const char *name, /* I - Element name or NULL for any */
const char *attr, /* I - Attribute name, or NULL for none */
const char *value, /* I - Attribute value, or NULL for any */
int descend) /* I - Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST */
const char *element, /* I - Element name or @code NULL@ for any */
const char *attr, /* I - Attribute name, or @code NULL@ for none */
const char *value, /* I - Attribute value, or @code NULL@ for any */
int descend) /* I - Descend into tree - @code MXML_DESCEND@, @code MXML_NO_DESCEND@, or @code MXML_DESCEND_FIRST@ */
{
const char *temp; /* Current attribute value */
......@@ -69,7 +69,7 @@ mxmlFindElement(mxml_node_t *node, /* I - Current node */
if (node->type == MXML_ELEMENT &&
node->value.element.name &&
(!name || !strcmp(node->value.element.name, name)))
(!element || !strcmp(node->value.element.name, element)))
{
/*
* See if we need to check for an attribute...
......@@ -120,7 +120,7 @@ mxmlFindElement(mxml_node_t *node, /* I - Current node */
* @since Mini-XML 2.7@
*/
mxml_node_t * /* O - Found node or NULL */
mxml_node_t * /* O - Found node or @code NULL@ */
mxmlFindPath(mxml_node_t *top, /* I - Top node */
const char *path) /* I - Path to element */
{
......@@ -198,14 +198,14 @@ mxmlFindPath(mxml_node_t *top, /* I - Top node */
* 'mxmlWalkNext()' - Walk to the next logical node in the tree.
*
* The descend argument controls whether the first child is considered
* to be the next node. The top node argument constrains the walk to
* to be the next node. The top node argument constrains the walk to
* the node's children.
*/
mxml_node_t * /* O - Next node or NULL */
mxml_node_t * /* O - Next node or @code NULL@ */
mxmlWalkNext(mxml_node_t *node, /* I - Current node */
mxml_node_t *top, /* I - Top node */
int descend) /* I - Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST */
int descend) /* I - Descend into tree - @code MXML_DESCEND@, @code MXML_NO_DESCEND@, or @code MXML_DESCEND_FIRST@ */
{
if (!node)
return (NULL);
......@@ -236,14 +236,14 @@ mxmlWalkNext(mxml_node_t *node, /* I - Current node */
* 'mxmlWalkPrev()' - Walk to the previous logical node in the tree.
*
* The descend argument controls whether the previous node's last child
* is considered to be the previous node. The top node argument constrains
* is considered to be the previous node. The top node argument constrains
* the walk to the node's children.
*/
mxml_node_t * /* O - Previous node or NULL */
mxml_node_t * /* O - Previous node or @code NULL@ */
mxmlWalkPrev(mxml_node_t *node, /* I - Current node */
mxml_node_t *top, /* I - Top node */
int descend) /* I - Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST */
int descend) /* I - Descend into tree - @code MXML_DESCEND@, @code MXML_NO_DESCEND@, or @code MXML_DESCEND_FIRST@ */
{
if (!node || node == top)
return (NULL);
......
......@@ -193,6 +193,50 @@ mxmlSetOpaque(mxml_node_t *node, /* I - Node to set */
}
/*
* 'mxmlSetOpaquef()' - Set the value of an opaque string node to a formatted string.
*
* The node is not changed if it (or its first child) is not an opaque node.
*
* @since Mini-XML 2.11@
*/
int /* O - 0 on success, -1 on failure */
mxmlSetOpaquef(mxml_node_t *node, /* I - Node to set */
const char *format, /* I - Printf-style format string */
...) /* I - Additional arguments as needed */
{
va_list ap; /* Pointer to arguments */
/*
* Range check input...
*/
if (node && node->type == MXML_ELEMENT &&
node->child && node->child->type == MXML_OPAQUE)
node = node->child;
if (!node || node->type != MXML_OPAQUE || !format)
return (-1);
/*
* Free any old string value and set the new value...
*/
if (node->value.opaque)
free(node->value.opaque);
va_start(ap, format);
node->value.opaque = _mxml_strdupf(format, ap);
va_end(ap);
return (0);
}
/*
* 'mxmlSetReal()' - Set the value of a real number node.
*
......
......@@ -211,7 +211,7 @@ extern const char *mxmlEntityGetName(int val);
extern int mxmlEntityGetValue(const char *name);
extern void mxmlEntityRemoveCallback(mxml_entity_cb_t cb);
extern mxml_node_t *mxmlFindElement(mxml_node_t *node, mxml_node_t *top,
const char *name, const char *attr,
const char *element, const char *attr,
const char *value, int descend);
extern mxml_node_t *mxmlFindPath(mxml_node_t *node, const char *path);
extern const char *mxmlGetCDATA(mxml_node_t *node);
......@@ -250,11 +250,14 @@ extern mxml_node_t *mxmlNewCustom(mxml_node_t *parent, void *data,
extern mxml_node_t *mxmlNewElement(mxml_node_t *parent, const char *name);
extern mxml_node_t *mxmlNewInteger(mxml_node_t *parent, int integer);
extern mxml_node_t *mxmlNewOpaque(mxml_node_t *parent, const char *opaque);
extern mxml_node_t *mxmlNewOpaquef(mxml_node_t *parent, const char *format, ...)
# ifdef __GNUC__
__attribute__ ((__format__ (__printf__, 2, 3)))
# endif /* __GNUC__ */
;
extern mxml_node_t *mxmlNewReal(mxml_node_t *parent, double real);
extern mxml_node_t *mxmlNewText(mxml_node_t *parent, int whitespace,
const char *string);
extern mxml_node_t *mxmlNewTextf(mxml_node_t *parent, int whitespace,
const char *format, ...)
extern mxml_node_t *mxmlNewText(mxml_node_t *parent, int whitespace, const char *string);
extern mxml_node_t *mxmlNewTextf(mxml_node_t *parent, int whitespace, const char *format, ...)
# ifdef __GNUC__
__attribute__ ((__format__ (__printf__, 3, 4)))
# endif /* __GNUC__ */
......@@ -289,6 +292,11 @@ extern int mxmlSetElement(mxml_node_t *node, const char *name);
extern void mxmlSetErrorCallback(mxml_error_cb_t cb);
extern int mxmlSetInteger(mxml_node_t *node, int integer);
extern int mxmlSetOpaque(mxml_node_t *node, const char *opaque);
extern int mxmlSetOpaquef(mxml_node_t *node, const char *format, ...)
# ifdef __GNUC__
__attribute__ ((__format__ (__printf__, 2, 3)))
# endif /* __GNUC__ */
;
extern int mxmlSetReal(mxml_node_t *node, double real);
extern int mxmlSetText(mxml_node_t *node, int whitespace,
const char *string);
......
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment