diff --git a/doc/mxml.man b/doc/mxml.man index c4f6fba..ee86c9c 100644 --- a/doc/mxml.man +++ b/doc/mxml.man @@ -232,34 +232,58 @@ MXML_TEXT .br Text fragment .SH FUNCTIONS -.SS mxmlAdd - +.SS index_sort +Sort the nodes in the index... .PP .nf -void mxmlAdd ( +void index_sort ( + mxml_index_t *ind, + int left, + int right +); +.fi +.PP +This function implements the classic quicksort algorithm... +.SS mxmlAdd +Add a node to a tree. +.PP +.nf +void mxmlAdd ( mxml_node_t *parent, int where, mxml_node_t *child, mxml_node_t *node ); .fi +.PP +Adds the specified node to the parent. If the child argument is not +\fBNULL\fR, puts the new node before or after the specified child depending +on the value of the where argument. If the child argument is \fBNULL\fR, +puts the new node at the beginning of the child list (\fBMXML_ADD_BEFORE\fR) +or at the end of the child list (\fBMXML_ADD_AFTER\fR). The constant +\fBMXML_ADD_TO_PARENT\fR can be used to specify a \fBNULL\fR child pointer. .SS mxmlDelete - +Delete a node and all of its children. .PP .nf -void mxmlDelete ( +void mxmlDelete ( mxml_node_t *node ); .fi +.PP +If the specified node has a parent, this function first removes the +node from its parent using the \fImxmlRemove\fR function. .SS mxmlElementDeleteAttr - +Delete an attribute. .PP .nf -void mxmlElementDeleteAttr ( +void mxmlElementDeleteAttr ( mxml_node_t *node, const char *name ); .fi +.PP + .SS mxmlElementGetAttr Get an attribute. .PP @@ -298,26 +322,38 @@ int mxmlElementGetAttrCount ( .PP .SS mxmlElementSetAttr -Node +Set an attribute. .PP .nf -void mxmlElementSetAttr ( +void mxmlElementSetAttr ( mxml_node_t *node, const char *name, const char *value ); .fi +.PP +If the named attribute already exists, the value of the attribute +is replaced by the new string value. The string value is copied +into the element node. This function does nothing if the node is +not an element. .SS mxmlElementSetAttrf -Range check input... +Set an attribute with a formatted value. .PP .nf -void mxmlElementSetAttrf ( +void mxmlElementSetAttrf ( mxml_node_t *node, const char *name, const char *format, ... ); .fi +.PP +If the named attribute already exists, the value of the attribute +is replaced by the new formatted string. The formatted string value is +copied into the element node. This function does nothing if the node +is not an element. + + .SS mxmlEntityAddCallback Add a callback to convert entities to Unicode. .PP @@ -348,10 +384,10 @@ int mxmlEntityGetValue ( The entity name can also be a numeric constant. -1 is returned if the name is not known. .SS mxmlEntityRemoveCallback -Global data +Remove a callback. .PP .nf -void mxmlEntityRemoveCallback ( +void mxmlEntityRemoveCallback ( mxml_entity_cb_t cb ); .fi @@ -472,7 +508,7 @@ has no children. .SS mxmlGetNextSibling -Return the node type... + .PP .nf mxml_node_t * mxmlGetNextSibling ( @@ -579,10 +615,10 @@ void * mxmlGetUserData ( .PP .SS mxmlIndexDelete - +Delete an index. .PP .nf -void mxmlIndexDelete ( +void mxmlIndexDelete ( mxml_index_t *ind ); .fi @@ -867,13 +903,16 @@ is deleted via \fImxmlDelete\fR. .SS mxmlRemove -Create the node and set the text value... +Remove a node from its parent. .PP .nf -void mxmlRemove ( +void mxmlRemove ( mxml_node_t *node ); .fi +.PP +This function does not free memory used by the node - use \fImxmlDelete\fR +for that. This function does nothing if the node has no parent. .SS mxmlRetain Retain a node. .PP @@ -1067,14 +1106,20 @@ The node is not changed if it (or its first child) is not a custom node. .SS mxmlSetCustomHandlers -Read the XML data... +Set the handling functions for custom data. .PP .nf -void mxmlSetCustomHandlers ( +void mxmlSetCustomHandlers ( mxml_custom_load_cb_t load, mxml_custom_save_cb_t save ); .fi +.PP +The load function accepts a node pointer and a data string and must +return 0 on success and non-zero on error. +.PP +The save function accepts a node pointer and must return a malloc'd +string on success and \fBNULL\fR on error. .SS mxmlSetElement Set the name of an element node. .PP @@ -1087,10 +1132,10 @@ int mxmlSetElement ( .PP The node is not changed if it is not an element node. .SS mxmlSetErrorCallback -Global data +Set the error message callback. .PP .nf -void mxmlSetErrorCallback ( +void mxmlSetErrorCallback ( mxml_error_cb_t cb ); .fi @@ -1178,13 +1223,17 @@ int mxmlSetUserData ( .PP .SS mxmlSetWrapMargin -Global data +Set the wrap margin when saving XML data. .PP .nf -void mxmlSetWrapMargin ( +void mxmlSetWrapMargin ( int column ); .fi +.PP +Wrapping is disabled when "column" is 0. + + .SS mxmlWalkNext Walk to the next logical node in the tree. .PP @@ -1213,6 +1262,16 @@ mxml_node_t * mxmlWalkPrev ( The descend argument controls whether the previous node's last child is considered to be the previous node. The top node argument constrains the walk to the node's children. +.SS mxml_free +Free the memory used by a node. +.PP +.nf +void mxml_free ( + mxml_node_t *node +); +.fi +.PP +Note: Does not free child nodes, does not remove from parent. .SH TYPES .SS mxml_custom_destroy_cb_t Custom data destructor diff --git a/doc/reference.html b/doc/reference.html index 4ff8ced..6f041d5 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -158,7 +158,7 @@ table.list td { padding: 5px 2px 5px 10px; text-align: left; vertical-align: top; - width: 100%; + width: 80%; } h1.title { } @@ -176,6 +176,7 @@ h3.title {

Contents