From cc2843b8cb769f0fa60c45a2e0f8f781dff9e845 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sat, 13 Dec 2014 20:46:16 -0800 Subject: Write API docs in cmark.h using markdown. `man/make_man_page.py` now converts using cmark. --- man/make_man_page.py | 26 ++++++++-- man/man3/cmark.3 | 134 +++++++++++++++++++++++++-------------------------- src/cmark.h | 28 +++++------ 3 files changed, 103 insertions(+), 85 deletions(-) diff --git a/man/make_man_page.py b/man/make_man_page.py index 01a1c6f..34383fb 100644 --- a/man/make_man_page.py +++ b/man/make_man_page.py @@ -12,8 +12,28 @@ # That's about it! -import sys, re, os +import sys, re, os, platform from datetime import date +from ctypes import CDLL, c_char_p, c_long, c_void_p + +sysname = platform.system() + +if sysname == 'Darwin': + cmark = CDLL("build/src/libcmark.dylib") +else: + cmark = CDLL("build/src/libcmark.so") + +parse_document = cmark.cmark_parse_document +parse_document.restype = c_void_p +parse_document.argtypes = [c_char_p, c_long] + +render_man = cmark.cmark_render_man +render_man.restype = c_char_p +render_man.argtypes = [c_void_p] + +def md2man(text): + return render_man(parse_document(text, len(text))) + comment_start_re = re.compile('^\/\*\* ?') comment_delim_re = re.compile('^[/ ]\** ?') @@ -87,14 +107,14 @@ with open(sourcefile, 'r') as cmarkh: mdlines.append('.RE\n\\f[]\n.fi\n') if len(mdlines) > 0 and mdlines[-1] != '\n': mdlines.append('\n') - mdlines.append('.PP\n') mdlines += chunk + mdlines.append('\n') chunk = [] sig = [] elif oldstate == 'man' and state != 'signature': if len(mdlines) > 0 and mdlines[-1] != '\n': mdlines.append('\n') - mdlines += chunk # add man chunk + mdlines += md2man(''.join(chunk)) # add man chunk chunk = [] mdlines.append('\n') diff --git a/man/man3/cmark.3 b/man/man3/cmark.3 index 5f6d296..5228cf1 100644 --- a/man/man3/cmark.3 +++ b/man/man3/cmark.3 @@ -1,12 +1,13 @@ .TH cmark 3 "December 13, 2014" "LOCAL" "Library Functions Manual" -.SH NAME - -.B cmark -\- CommonMark parsing, manipulating, and rendering - -.SH DESCRIPTION +.SH +NAME +.PP +\f[B]cmark\f[] \- CommonMark parsing, manipulating, and rendering -.SS Simple Interface +.SH +DESCRIPTION +.SS +Simple Interface .nf \f[C] @@ -16,17 +17,16 @@ \f[] .fi -.PP Current version of library. \fIchar *\fR \fBcmark_markdown_to_html\fR(\fIconst char *text\fR, \fIint len\fR) -.PP Convert \fItext\fR (assumed to be a UTF-8 encoded string with length \fIlen\fR from CommonMark Markdown to HTML, returning a null-terminated, UTF-8-encoded string. -.SS Node Structure +.SS +Node Structure .nf \f[C] @@ -67,7 +67,7 @@ typedef enum { \f[] .fi -.PP + .nf \f[C] @@ -81,7 +81,7 @@ typedef enum { \f[] .fi -.PP + .nf \f[C] @@ -94,209 +94,207 @@ typedef enum { \f[] .fi -.PP -.SS Creating and Destroying Nodes +.SS +Creating and Destroying Nodes \fIcmark_node*\fR \fBcmark_node_new\fR(\fIcmark_node_type type\fR) -.PP -\fIvoid\fR \fBcmark_node_free\fR(\fIcmark_node *node\fR) -.PP +\fIvoid\fR \fBcmark_node_free\fR(\fIcmark_node *node\fR) -\fIcmark_node*\fR \fBcmark_node_next\fR(\fIcmark_node *node\fR) -.PP -.SS Tree Traversal +.SS +Tree Traversal \fIcmark_node*\fR \fBcmark_node_previous\fR(\fIcmark_node *node\fR) -.PP + \fIcmark_node*\fR \fBcmark_node_parent\fR(\fIcmark_node *node\fR) -.PP + \fIcmark_node*\fR \fBcmark_node_first_child\fR(\fIcmark_node *node\fR) -.PP + \fIcmark_node*\fR \fBcmark_node_last_child\fR(\fIcmark_node *node\fR) -.PP -.SS Iterator +.SS +Iterator \fIcmark_iter*\fR \fBcmark_iter_new\fR(\fIcmark_node *root\fR) -.PP + \fIvoid\fR \fBcmark_iter_free\fR(\fIcmark_iter *iter\fR) -.PP + \fIcmark_event_type\fR \fBcmark_iter_next\fR(\fIcmark_iter *iter\fR) -.PP + \fIcmark_node*\fR \fBcmark_iter_get_node\fR(\fIcmark_iter *iter\fR) -.PP -.SS Accessors +.SS +Accessors \fIcmark_node_type\fR \fBcmark_node_get_type\fR(\fIcmark_node *node\fR) -.PP + \fIconst char*\fR \fBcmark_node_get_string_content\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_string_content\fR(\fIcmark_node *node\fR, \fIconst char *content\fR) -.PP + \fIint\fR \fBcmark_node_get_header_level\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_header_level\fR(\fIcmark_node *node\fR, \fIint level\fR) -.PP + \fIcmark_list_type\fR \fBcmark_node_get_list_type\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_list_type\fR(\fIcmark_node *node\fR, \fIcmark_list_type type\fR) -.PP + \fIint\fR \fBcmark_node_get_list_start\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_list_start\fR(\fIcmark_node *node\fR, \fIint start\fR) -.PP + \fIint\fR \fBcmark_node_get_list_tight\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_list_tight\fR(\fIcmark_node *node\fR, \fIint tight\fR) -.PP + \fIconst char*\fR \fBcmark_node_get_fence_info\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_fence_info\fR(\fIcmark_node *node\fR, \fIconst char *info\fR) -.PP + \fIconst char*\fR \fBcmark_node_get_url\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_url\fR(\fIcmark_node *node\fR, \fIconst char *url\fR) -.PP + \fIconst char*\fR \fBcmark_node_get_title\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_set_title\fR(\fIcmark_node *node\fR, \fIconst char *title\fR) -.PP + \fIint\fR \fBcmark_node_get_start_line\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_get_start_column\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_get_end_line\fR(\fIcmark_node *node\fR) -.PP -.SS Tree Manipulation +.SS +Tree Manipulation \fIvoid\fR \fBcmark_node_unlink\fR(\fIcmark_node *node\fR) -.PP + \fIint\fR \fBcmark_node_insert_before\fR(\fIcmark_node *node\fR, \fIcmark_node *sibling\fR) -.PP + \fIint\fR \fBcmark_node_insert_after\fR(\fIcmark_node *node\fR, \fIcmark_node *sibling\fR) -.PP + \fIint\fR \fBcmark_node_prepend_child\fR(\fIcmark_node *node\fR, \fIcmark_node *child\fR) -.PP + \fIint\fR \fBcmark_node_append_child\fR(\fIcmark_node *node\fR, \fIcmark_node *child\fR) -.PP -.SS Parsing +.SS +Parsing \fIcmark_parser *\fR \fBcmark_parser_new\fR(\fI\fR) -.PP + \fIvoid\fR \fBcmark_parser_free\fR(\fIcmark_parser *parser\fR) -.PP + \fIcmark_node *\fR \fBcmark_parser_finish\fR(\fIcmark_parser *parser\fR) -.PP + \fIvoid\fR \fBcmark_parser_feed\fR(\fIcmark_parser *parser\fR, \fIconst char *buffer\fR, \fIsize_t len\fR) -.PP + \fIcmark_node *\fR \fBcmark_parse_document\fR(\fIconst char *buffer\fR, \fIsize_t len\fR) -.PP + \fIcmark_node *\fR \fBcmark_parse_file\fR(\fIFILE *f\fR) -.PP -.SS Rendering +.SS +Rendering \fIchar *\fR \fBcmark_render_ast\fR(\fIcmark_node *root\fR) -.PP + \fIchar *\fR \fBcmark_render_html\fR(\fIcmark_node *root\fR) -.PP + \fIchar *\fR \fBcmark_render_man\fR(\fIcmark_node *root\fR) -.PP -.SH AUTHORS +.SH +AUTHORS +.PP John MacFarlane, Vicent Marti, Kārlis Gaņģis, Nick Wellnhofer. diff --git a/src/cmark.h b/src/cmark.h index d276ba9..84515fc 100644 --- a/src/cmark.h +++ b/src/cmark.h @@ -8,15 +8,14 @@ extern "C" { #endif -/** .SH NAME +/** # NAME * - * .B cmark - * \- CommonMark parsing, manipulating, and rendering + * **cmark** - CommonMark parsing, manipulating, and rendering */ -/** .SH DESCRIPTION +/** # DESCRIPTION * - * .SS Simple Interface + * ## Simple Interface */ /** Current version of library. @@ -30,7 +29,7 @@ extern "C" { CMARK_EXPORT char *cmark_markdown_to_html(const char *text, int len); -/** .SS Node Structure +/** ## Node Structure */ /** @@ -98,7 +97,7 @@ typedef int (*cmark_node_handler)(cmark_node *node, cmark_event_type ev_type, void *state); /** - * .SS Creating and Destroying Nodes + * ## Creating and Destroying Nodes */ /** @@ -112,8 +111,9 @@ CMARK_EXPORT void cmark_node_free(cmark_node *node); /** - * .SS Tree Traversal + * ## Tree Traversal */ + CMARK_EXPORT cmark_node* cmark_node_next(cmark_node *node); @@ -138,7 +138,7 @@ CMARK_EXPORT cmark_node* cmark_node_last_child(cmark_node *node); /** - * .SS Iterator + * ## Iterator */ /** @@ -166,7 +166,7 @@ cmark_node* cmark_iter_get_node(cmark_iter *iter); /** - * .SS Accessors + * ## Accessors */ /** @@ -270,7 +270,7 @@ CMARK_EXPORT int cmark_node_get_end_line(cmark_node *node); /** - * .SS Tree Manipulation + * ## Tree Manipulation */ /** @@ -299,7 +299,7 @@ CMARK_EXPORT int cmark_node_append_child(cmark_node *node, cmark_node *child); /** - * .SS Parsing + * ## Parsing */ /** @@ -333,7 +333,7 @@ CMARK_EXPORT cmark_node *cmark_parse_file(FILE *f); /** - * .SS Rendering + * ## Rendering */ /** @@ -351,7 +351,7 @@ char *cmark_render_html(cmark_node *root); CMARK_EXPORT char *cmark_render_man(cmark_node *root); -/** .SH AUTHORS +/** # AUTHORS * * John MacFarlane, Vicent Marti, Kārlis Gaņģis, Nick Wellnhofer. */ -- cgit v1.2.3