diff options
Diffstat (limited to 'man/man3')
| -rw-r--r-- | man/man3/cmark.3 | 135 |
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 |