summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2014-12-13 20:46:16 -0800
committerJohn MacFarlane <jgm@berkeley.edu>2014-12-13 20:56:30 -0800
commitcc2843b8cb769f0fa60c45a2e0f8f781dff9e845 (patch)
tree167224e0ed1508d24f01eaee3eed755665b67334
parent59cc3c9323dc0b7aa1fd5817e12884ef925461d4 (diff)
Write API docs in cmark.h using markdown.
`man/make_man_page.py` now converts using cmark.
-rw-r--r--man/make_man_page.py26
-rw-r--r--man/man3/cmark.3134
-rw-r--r--src/cmark.h28
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.
*/