mkd-functions.3

.\"
.Dd January 18, 2008
.Dt MKD_FUNCTIONS 3
.Os Mastodon
.Sh NAME
.Nm mkd_functions 
.Nd access and process Markdown documents.
.Sh LIBRARY
Markdown 
.Pq libmarkdown , -lmarkdown
.Sh SYNOPSIS
.Fd #include <mkdio.h>
.Ft int
.Fn mkd_compile "MMIOT *document" "int flags"
.Ft int
.Fn mkd_css "MMIOT *document" "char **doc"
.Ft int
.Fn mkd_generatecss  "MMIOT *document" "FILE *output"
.Ft int
.Fn mkd_document "MMIOT *document" "char **doc"
.Ft int
.Fn mkd_generatehtml  "MMIOT *document" "FILE *output"
.Ft int
.Fn mkd_xhtmlpage "MMIOT *document" "int flags" "FILE *output"
.Ft int
.Fn mkd_toc "MMIOT *document" "char **doc"
.Ft void
.Fn mkd_generatetoc "MMIOT *document" "FILE *output"
.Ft void
.Fn mkd_cleanup "MMIOT*"
.Ft char*
.Fn mkd_doc_title "MMIOT*"
.Ft char*
.Fn mkd_doc_author "MMIOT*"
.Ft char*
.Fn mkd_doc_date "MMIOT*"
.Sh DESCRIPTION
.Pp
The
.Nm markdown
format supported in this implementation includes
Pandoc-style header and inline 
.Ar \<style\>
blocks, and the standard
.Xr markdown 3
functions do not provide access to
the data provided by either of those extensions.
These functions give you access to that data, plus
they provide a finer-grained way of converting
.Em Markdown 
documents into HTML.
.Pp
Given a
.Ar MMIOT*
generated by
.Fn mkd_in
or
.Fn mkd_string ,
.Fn mkd_compile
compiles the document into
.Em \<style\> ,
.Em Pandoc ,
and
.Em html
sections.
.Pp
Once compiled, the document can be examined and written
by the
.Fn mkd_css ,
.Fn mkd_document ,
.Fn mkd_generatecss ,
.Fn mkd_generatehtml ,
.Fn mkd_generatetoc ,
.Fn mkd_toc ,
.Fn mkd_xhtmlpage ,
.Fn mkd_doc_title ,
.Fn mkd_doc_author ,
and
.Fn mkd_doc_date
functions.
.Pp
.Fn mkd_css
allocates a string and populates it with any \<style\> sections
provided in the document,
.Fn mkd_generatecss
writes any \<style\> sections to the output,
.Fn mkd_document
points
.Ar text
to the text of the document and returns the
size of the document,
.Fn mkd_generatehtml
writes the rest of the document to the output,
and 
.Fn mkd_doc_title ,
.Fn mkd_doc_author ,
.Fn mkd_doc_date
are used to read the contents of a Pandoc header,
if any.
.Pp
.Fn mkd_xhtmlpage
writes a xhtml page containing the document.  The regular set of
flags can be passed.
.Pp
.Fn mkd_toc
writes a document outline, in the form of a collection of nested
lists with links to each header in the document, into a string
allocated with
.Fn malloc ,
and returns the size.
.Pp
.Fn mkd_generatetoc
is like
.Fn mkd_toc ,
except that it writes the document outline to the given
.Pa FILE*
argument.
.Pp
.Fn mkd_cleanup
deletes a
.Ar MMIOT*
after processing is done.
.Pp
.Fn mkd_compile
accepts the same flags that
.Fn markdown
and
.Fn mkd_string
do; 
.Bl -tag -width MKD_NOSTRIKETHROUGH -compact
.It Ar MKD_NOIMAGE
Do not process `![]' and
remove
.Em \<img\>
tags from the output.
.It Ar MKD_NOLINKS
Do not process `[]' and remove
.Em \<a\>
tags from the output.
.It Ar MKD_NOPANTS
Do not do Smartypants-style mangling of quotes, dashes, or ellipses.
.It Ar MKD_TAGTEXT
Process the input as if you were inside a html tag.  This means that
no html tags will be generated, and 
.Fn mkd_compile
will attempt to escape anything that might terribly confuse a 
web browser.
.It Ar MKD_NO_EXT
Do not process any markdown pseudo-protocols when
handing
.Ar [][]
links.
.It Ar MKD_NOHEADER
Do not attempt to parse any Pandoc-style headers.
.It Ar MKD_TOC
Label all headers for use with the
.Fn mkd_generatetoc
function.
.It Ar MKD_1_COMPAT
MarkdownTest_1.0 compatibility flag; trim trailing spaces from the
first line of code blocks and disable implicit reference links.
.It Ar MKD_NOSTRIKETHROUGH
Disable strikethrough support.
.El
.Sh RETURN VALUES
The function
.Fn mkd_compile
returns 1 in the case of success, or 0 if the document is already compiled.
The function
.Fn mkd_generatecss
returns the number of bytes written in the case of success, or EOF if an error
occurred.  
The function
.Fn mkd_generatehtml
returns 0 on success, \-1 on failure.
.Sh SEE ALSO
.Xr markdown 1 ,
.Xr markdown 3 ,
.Xr mkd-line 3 ,
.Xr markdown 7 ,
.Xr mkd-extensions 7 ,
.Xr mmap 2 .
.Pp
http://daringfireball.net/projects/markdown/syntax
.Sh BUGS
Error handling is minimal at best.