brennen
/
text-markdown-discount


								.\"

								.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_style  "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_style ,

								.Fn mkd_document ,

								.Fn mkd_generatehtml ,

								.Fn mkd_toc ,

								.Fn mkd_generatetoc ,

								.Fn mkd_xhtmlpage ,

								.Fn mkd_doc_title ,

								.Fn mkd_doc_author ,

								and

								.Fn mkd_doc_date

								functions.

								The

								.Fn mkd_style

								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_NOIMAGE -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 compatability flag; trim trailing spaces from the

								first line of code blocks and disable implicit reference links.

								.El

								.Sh RETURN VALUES

								The functions

								.Fn mkd_compile ,

								.Fn mkd_style ,

								and

								.Fn mkd_generatehtml

								return 0 on success, -1 on failure.

								.Sh SEE ALSO

								.Xr markdown 1 ,

								.Xr markdown 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.