summaryrefslogtreecommitdiff
path: root/man/man3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3')
-rw-r--r--man/man3/cmark.3135
1 files changed, 74 insertions, 61 deletions
diff --git a/man/man3/cmark.3 b/man/man3/cmark.3
index c685dae..0372d28 100644
--- a/man/man3/cmark.3
+++ b/man/man3/cmark.3
@@ -13,9 +13,9 @@ Simple Interface
\fIchar *\f[] \fBcmark_markdown_to_html\f[](\fIconst char *text\f[], \fIsize_t len\f[], \fIint options\f[])
\&.PP
-Convert \ef[I]text\ef[] (assumed to be a UTF\-8 encoded string with length
-\ef[I]len\ef[] from CommonMark Markdown to HTML, returning a null\-terminated,
-UTF\-8\-encoded string.
+Convert \ef[I]text\ef[] (assumed to be a UTF\-8 encoded string with
+length \ef[I]len\ef[] from CommonMark Markdown to HTML, returning a
+null\-terminated, UTF\-8\-encoded string.
\&.SS
Node Structure
@@ -28,8 +28,8 @@ Creating and Destroying Nodes
\&.PP
Creates a new node of type \ef[I]type\ef[]. Note that the node may have
-other required properties, which it is the caller's responsibility
-to assign.
+other required properties, which it is the caller's responsibility to
+assign.
.PP
\fIvoid\f[] \fBcmark_node_free\f[](\fIcmark_node *node\f[])
@@ -51,8 +51,8 @@ there is none.
\fIcmark_node*\f[] \fBcmark_node_previous\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the previous node in the sequence after \ef[I]node\ef[], or NULL if
-there is none.
+Returns the previous node in the sequence after \ef[I]node\ef[], or NULL
+if there is none.
.PP
\fIcmark_node*\f[] \fBcmark_node_parent\f[](\fIcmark_node *node\f[])
@@ -64,29 +64,32 @@ Returns the parent of \ef[I]node\ef[], or NULL if there is none.
\fIcmark_node*\f[] \fBcmark_node_first_child\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the first child of \ef[I]node\ef[], or NULL if \ef[I]node\ef[] has no children.
+Returns the first child of \ef[I]node\ef[], or NULL if \ef[I]node\ef[]
+has no children.
.PP
\fIcmark_node*\f[] \fBcmark_node_last_child\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the last child of \ef[I]node\ef[], or NULL if \ef[I]node\ef[] has no children.
+Returns the last child of \ef[I]node\ef[], or NULL if \ef[I]node\ef[]
+has no children.
\&.SS
Iterator
\&.PP
An iterator will walk through a tree of nodes, starting from a root
node, returning one node at a time, together with information about
-whether the node is being entered or exited. The iterator will
-first descend to a child node, if there is one. When there is no
-child, the iterator will go to the next sibling. When there is no
-next sibling, the iterator will return to the parent (but with
-a \ef[I]cmark_event_type\ef[] of \ef[C]CMARK_EVENT_EXIT\ef[]). The iterator will
-return \ef[C]CMARK_EVENT_DONE\ef[] when it reaches the root node again.
-One natural application is an HTML renderer, where an \ef[C]ENTER\ef[] event
-outputs an open tag and an \ef[C]EXIT\ef[] event outputs a close tag.
-An iterator might also be used to transform an AST in some systematic
-way, for example, turning all level\-3 headers into regular paragraphs.
+whether the node is being entered or exited. The iterator will first
+descend to a child node, if there is one. When there is no child, the
+iterator will go to the next sibling. When there is no next sibling, the
+iterator will return to the parent (but with a
+\ef[I]cmark_event_type\ef[] of \ef[C]CMARK_EVENT_EXIT\ef[]). The
+iterator will return \ef[C]CMARK_EVENT_DONE\ef[] when it reaches the
+root node again. One natural application is an HTML renderer, where an
+\ef[C]ENTER\ef[] event outputs an open tag and an \ef[C]EXIT\ef[] event
+outputs a close tag. An iterator might also be used to transform an AST
+in some systematic way, for example, turning all level\-3 headers into
+regular paragraphs.
\&.IP
\&.nf
\ef[C]
@@ -105,8 +108,8 @@ usage_example(cmark_node *root) {
\ef[]
\&.fi
\&.PP
-Iterators will never return \ef[C]EXIT\ef[] events for leaf nodes, which are nodes
-of type:
+Iterators will never return \ef[C]EXIT\ef[] events for leaf nodes, which
+are nodes of type:
\&.IP \e[bu] 2
CMARK_NODE_HTML
\&.IP \e[bu] 2
@@ -124,15 +127,16 @@ CMARK_NODE_CODE
\&.IP \e[bu] 2
CMARK_NODE_INLINE_HTML
\&.PP
-Nodes must only be modified after an \ef[C]EXIT\ef[] event, or an \ef[C]ENTER\ef[] event for
-leaf nodes.
+Nodes must only be modified after an \ef[C]EXIT\ef[] event, or an
+\ef[C]ENTER\ef[] event for leaf nodes.
.PP
\fIcmark_iter*\f[] \fBcmark_iter_new\f[](\fIcmark_node *root\f[])
\&.PP
-Creates a new iterator starting at \ef[I]root\ef[]. The current node and event
-type are undefined until \ef[C]cmark_iter_next\ef[] is called for the first time.
+Creates a new iterator starting at \ef[I]root\ef[]. The current node and
+event type are undefined until \ef[C]cmark_iter_next\ef[] is called for
+the first time.
.PP
\fIvoid\f[] \fBcmark_iter_free\f[](\fIcmark_iter *iter\f[])
@@ -144,8 +148,9 @@ Frees the memory allocated for an iterator.
\fIcmark_event_type\f[] \fBcmark_iter_next\f[](\fIcmark_iter *iter\f[])
\&.PP
-Advances to the next node and returns the event type (\ef[C]CMARK_EVENT_ENTER\ef[],
-\ef[C]CMARK_EVENT_EXIT\ef[] or \ef[C]CMARK_EVENT_DONE\ef[]).
+Advances to the next node and returns the event type
+(\ef[C]CMARK_EVENT_ENTER\ef[], \ef[C]CMARK_EVENT_EXIT\ef[] or
+\ef[C]CMARK_EVENT_DONE\ef[]).
.PP
\fIcmark_node*\f[] \fBcmark_iter_get_node\f[](\fIcmark_iter *iter\f[])
@@ -186,14 +191,15 @@ Returns the user data of \ef[I]node\ef[].
\fIint\f[] \fBcmark_node_set_user_data\f[](\fIcmark_node *node\f[], \fIvoid *user_data\f[])
\&.PP
-Sets arbitrary user data for \ef[I]node\ef[]. Returns 1 on success,
-0 on failure.
+Sets arbitrary user data for \ef[I]node\ef[]. Returns 1 on success, 0 on
+failure.
.PP
\fIcmark_node_type\f[] \fBcmark_node_get_type\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the type of \ef[I]node\ef[], or \ef[C]CMARK_NODE_NONE\ef[] on error.
+Returns the type of \ef[I]node\ef[], or \ef[C]CMARK_NODE_NONE\ef[] on
+error.
.PP
\fIconst char*\f[] \fBcmark_node_get_type_string\f[](\fIcmark_node *node\f[])
@@ -212,60 +218,64 @@ Returns the string contents of \ef[I]node\ef[], or NULL if none.
\fIint\f[] \fBcmark_node_set_literal\f[](\fIcmark_node *node\f[], \fIconst char *content\f[])
\&.PP
-Sets the string contents of \ef[I]node\ef[]. Returns 1 on success,
-0 on failure.
+Sets the string contents of \ef[I]node\ef[]. Returns 1 on success, 0 on
+failure.
.PP
\fIint\f[] \fBcmark_node_get_header_level\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the header level of \ef[I]node\ef[], or 0 if \ef[I]node\ef[] is not a header.
+Returns the header level of \ef[I]node\ef[], or 0 if \ef[I]node\ef[] is
+not a header.
.PP
\fIint\f[] \fBcmark_node_set_header_level\f[](\fIcmark_node *node\f[], \fIint level\f[])
\&.PP
-Sets the header level of \ef[I]node\ef[], returning 1 on success and 0 on error.
+Sets the header level of \ef[I]node\ef[], returning 1 on success and 0
+on error.
.PP
\fIcmark_list_type\f[] \fBcmark_node_get_list_type\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the list type of \ef[I]node\ef[], or \ef[C]CMARK_NO_LIST\ef[] if \ef[I]node\ef[]
-is not a list.
+Returns the list type of \ef[I]node\ef[], or \ef[C]CMARK_NO_LIST\ef[] if
+\ef[I]node\ef[] is not a list.
.PP
\fIint\f[] \fBcmark_node_set_list_type\f[](\fIcmark_node *node\f[], \fIcmark_list_type type\f[])
\&.PP
-Sets the list type of \ef[I]node\ef[], returning 1 on success and 0 on error.
+Sets the list type of \ef[I]node\ef[], returning 1 on success and 0 on
+error.
.PP
\fIcmark_delim_type\f[] \fBcmark_node_get_list_delim\f[](\fIcmark_node *node\f[])
\&.PP
-Returns the list delimiter type of \ef[I]node\ef[], or \ef[C]CMARK_NO_DELIM\ef[] if \ef[I]node\ef[]
-is not a list.
+Returns the list delimiter type of \ef[I]node\ef[], or
+\ef[C]CMARK_NO_DELIM\ef[] if \ef[I]node\ef[] is not a list.
.PP
\fIint\f[] \fBcmark_node_set_list_delim\f[](\fIcmark_node *node\f[], \fIcmark_delim_type delim\f[])
\&.PP
-Sets the list delimiter type of \ef[I]node\ef[], returning 1 on success and 0
-on error.
+Sets the list delimiter type of \ef[I]node\ef[], returning 1 on success
+and 0 on error.
.PP
\fIint\f[] \fBcmark_node_get_list_start\f[](\fIcmark_node *node\f[])
\&.PP
-Returns starting number of \ef[I]node\ef[], if it is an ordered list, otherwise 0.
+Returns starting number of \ef[I]node\ef[], if it is an ordered list,
+otherwise 0.
.PP
\fIint\f[] \fBcmark_node_set_list_start\f[](\fIcmark_node *node\f[], \fIint start\f[])
\&.PP
-Sets starting number of \ef[I]node\ef[], if it is an ordered list. Returns 1
-on success, 0 on failure.
+Sets starting number of \ef[I]node\ef[], if it is an ordered list.
+Returns 1 on success, 0 on failure.
.PP
\fIint\f[] \fBcmark_node_get_list_tight\f[](\fIcmark_node *node\f[])
@@ -289,8 +299,8 @@ Returns the info string from a fenced code block, or NULL if none.
\fIint\f[] \fBcmark_node_set_fence_info\f[](\fIcmark_node *node\f[], \fIconst char *info\f[])
\&.PP
-Sets the info string in a fenced code block, returning 1 on
-success and 0 on failure.
+Sets the info string in a fenced code block, returning 1 on success and
+0 on failure.
.PP
\fIconst char*\f[] \fBcmark_node_get_url\f[](\fIcmark_node *node\f[])
@@ -302,8 +312,8 @@ Gets the URL of a link or image \ef[I]node\ef[], or NULL if none.
\fIint\f[] \fBcmark_node_set_url\f[](\fIcmark_node *node\f[], \fIconst char *url\f[])
\&.PP
-Sets the URL of a link or image \ef[I]node\ef[]. Returns 1 on success,
-0 on failure.
+Sets the URL of a link or image \ef[I]node\ef[]. Returns 1 on success, 0
+on failure.
.PP
\fIconst char*\f[] \fBcmark_node_get_title\f[](\fIcmark_node *node\f[])
@@ -349,27 +359,29 @@ Tree Manipulation
\fIvoid\f[] \fBcmark_node_unlink\f[](\fIcmark_node *node\f[])
\&.PP
-Unlinks a \ef[I]node\ef[], removing it from the tree, but not freeing its
-memory. (Use \ef[I]cmark_node_free\ef[] for that.)
+Unlinks a \ef[I]node\ef[], removing it from the tree, but not freeing
+its memory. (Use \ef[I]cmark_node_free\ef[] for that.)
.PP
\fIint\f[] \fBcmark_node_insert_before\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[])
\&.PP
-Inserts \ef[I]sibling\ef[] before \ef[I]node\ef[]. Returns 1 on success, 0 on failure.
+Inserts \ef[I]sibling\ef[] before \ef[I]node\ef[]. Returns 1 on success,
+0 on failure.
.PP
\fIint\f[] \fBcmark_node_insert_after\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[])
\&.PP
-Inserts \ef[I]sibling\ef[] after \ef[I]node\ef[]. Returns 1 on success, 0 on failure.
+Inserts \ef[I]sibling\ef[] after \ef[I]node\ef[]. Returns 1 on success,
+0 on failure.
.PP
\fIint\f[] \fBcmark_node_prepend_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[])
\&.PP
-Adds \ef[I]child\ef[] to the beginning of the children of \ef[I]node\ef[].
-Returns 1 on success, 0 on failure.
+Adds \ef[I]child\ef[] to the beginning of the children of
+\ef[I]node\ef[]. Returns 1 on success, 0 on failure.
.PP
\fIint\f[] \fBcmark_node_append_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[])
@@ -441,8 +453,8 @@ Finish parsing and return a pointer to a tree of nodes.
\fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[], \fIint options\f[])
\&.PP
-Parse a CommonMark document in \ef[I]buffer\ef[] of length \ef[I]len\ef[].
-Returns a pointer to a tree of nodes.
+Parse a CommonMark document in \ef[I]buffer\ef[] of length
+\ef[I]len\ef[]. Returns a pointer to a tree of nodes.
.PP
\fIcmark_node *\f[] \fBcmark_parse_file\f[](\fIFILE *f\f[], \fIint options\f[])
@@ -543,7 +555,8 @@ Normalize tree by consolidating adjacent text nodes.
.fi
\&.PP
-Convert straight quotes to curly, \-\-\- to em dashes, \-\- to en dashes.
+Convert straight quotes to curly, \-\-\- to em dashes, \-\- to en
+dashes.
.PP
.nf
@@ -555,8 +568,8 @@ Convert straight quotes to curly, \-\-\- to em dashes, \-\- to en dashes.
.fi
\&.PP
-Validate UTF\-8 in the input before parsing, replacing illegal
-sequences with the replacement character U+FFFD.
+Validate UTF\-8 in the input before parsing, replacing illegal sequences
+with the replacement character U+FFFD.
\&.SS
Version information
@@ -580,8 +593,8 @@ In hexadecimal format, the number 0x010203 represents version 1.2.3.
\fIconst char *\f[] \fBcmark_version_string\f[](\fI\f[])
\&.PP
-The library version string for runtime checks. Also available as
-macro CMARK_VERSION_STRING for compile time checks.
+The library version string for runtime checks. Also available as macro
+CMARK_VERSION_STRING for compile time checks.
\&.SH
AUTHORS