squilu/discount/markdown.3

.\"
.Dd December 20, 2007
.Dt MARKDOWN 3
.Os Mastodon
.Sh NAME
.Nm markdown
.Nd process Markdown documents
.Sh LIBRARY
Markdown 
.Pq libmarkdown , -lmarkdown
.Sh SYNOPSIS
.Fd #include <mkdio.h>
.Ft MMIOT
.Fn *mkd_in "FILE *input" "int flags"
.Ft MMIOT
.Fn *mkd_string "char *string" "int size" "int flags"
.Ft int
.Fn markdown "MMIOT *doc" "FILE *output" "int flags"
.Sh DESCRIPTION
These functions
convert
.Em Markdown
documents and strings into HTML.
.Fn markdown
processes an entire document, while
.Fn mkd_text
processes a single string.
.Pp
To process a file, you pass a FILE* to
.Fn mkd_in ,
and if it returns a nonzero value you pass that in to 
.Fn markdown ,
which then writes the converted document to the specified
.Em FILE* .
If your input has already been written into a string (generated
input or a file opened 
with 
.Xr mmap 2 )
you can feed that string to 
.Fn mkd_string
and pass its return value to
.Fn markdown.
.Pp
.Fn Markdown
accepts the following flag values (or-ed together if needed)
to restrict how it processes input:
.Bl -tag -width MKD_NOSTRIKETHROUGH -compact
.It Ar MKD_NOLINKS
Don't do link processing, block 
.Em <a>
tags.
.It Ar MKD_NOIMAGE
Don't do image processing, block
.Em <img> .
.It Ar MKD_NOPANTS
Don't run 
.Em smartypants() .
.It Ar MKD_NOHTML
Don't allow raw html through AT ALL
.It Ar MKD_STRICT
Disable 
superscript and relaxed emphasis.
.It Ar MKD_TAGTEXT
Process text inside an html tag; no 
.Em <em> ,
no 
.Em <bold> ,
no html or
.Em []
expansion.
.It Ar MKD_NO_EXT
Don't allow pseudo-protocols.
.It Ar MKD_CDATA
Generate code for xml 
.Em ![CDATA[...]] .
.It Ar MKD_NOSUPERSCRIPT
Don't generate superscripts.
Emphasis happens _everywhere_
.It Ar MKD_NOTABLES
Disallow tables.
.It Ar MKD_NOSTRIKETHROUGH
Forbid 
.Em ~~strikethrough~~ .
.It Ar MKD_TOC
Do table-of-contents processing.
.It Ar MKD_1_COMPAT
Compatibility with MarkdownTest_1.0
.It Ar MKD_AUTOLINK
Make 
.Em http://foo.com
into a link even without
.Em <> s.
.It Ar MKD_SAFELINK
Paranoid check for link protocol.
.It Ar MKD_NOHEADER
Don't process header blocks.
.It Ar MKD_TABSTOP
Expand tabs to 4 spaces.
.It Ar MKD_NODIVQUOTE
Forbid 
.Em >%class%
blocks.
.It Ar MKD_NOALPHALIST
Forbid alphabetic lists.
.It Ar MKD_NODLIST
Forbid definition lists.
.It Ar MKD_NODLDISCOUNT
Disable the discount definition list syntax style.
.It Ar MKD_DLEXTRA
Enable the extra definition list syntax style.
.It Ar MKD_EXTRA_FOOTNOTE
Enable markdown extra-style footnotes.
.It Ar MKD_NOSTYLE
Do not extract (omit) <style/> blocks from the output.
.It Ar MKD_FENCEDCODE
Allow fenced code blocks.
.It Ar MKD_IDANCHOR
Use id= anchors instead of <a name=/> for table-of-contents links.
.It Ar MKD_GITHUBTAGS
Allow underscore and dash in passed through element names.
.It Ar MKD_URLENCODEDANCHOR
Use url-encoded chars for multibyte and nonalphanumeric chars rather than dots in toc links.
.El
.Sh RETURN VALUES
.Fn markdown
returns 0 on success, 1 on failure.
The
.Fn mkd_in
and
.Fn mkd_string
functions return a MMIOT* on success, null on failure.
.Sh SEE ALSO
.Xr markdown 1 ,
.Xr mkd-callbacks 3 ,
.Xr mkd-functions 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.
.Pp
The
.Ar MMIOT
created by
.Fn mkd_string
is deleted by the
.Nm
function.