home | help 
SOLDOUT_MARKDOWN(3)	     Library Functions Manual	     SOLDOUT_MARKDOWN(3)

NAME
     soldout_markdown, markdown -- parse markdown document

SYNOPSIS
     #include <markdown.h>

     #define MKD_CELL_ALIGN_DEFAULT
     #define MKD_CELL_ALIGN_LEFT
     #define MKD_CELL_ALIGN_RIGHT
     #define MKD_CELL_ALIGN_CENTER
     #define MKD_CELL_ALIGN_MASK
     #define MKD_CELL_HEAD
     #define MKD_LIST_ORDERED
     #define MKD_LI_BLOCK

     void
     markdown(struct buf *ob, struct buf *ib, const struct mkd_renderer *rndr);

DESCRIPTION
     The  markdown() function parses the input buffer ib and renders it into the
     output buffer ob; rndr is a pointer to the renderer structure.

     Function pointers in struct mkd_renderer can be NULL.  A  null  block-level
     callback will make the corresponding block disappear from the output, as if
     the  callback was an empty function.  A null span-level callback will cause
     the corresponding element to be treated as normal characters, copied verba-
     tim to the output.  Moreover, span-level callbacks return an integer, which
     tells whether the renderer accepts to  render  the  item  (non-zero  return
     value) or whether it should be copied verbatim (zero return value).

     The  first  argument  of  a  renderer function is always the output buffer,
     where the function is supposed to write its output.  The last argument of a
     renderer function is always a private pointer, which is  opaque  member  of
     struct mkd_renderer.  libsoldout itself never does nothing with this data.

     emph_chars is a zero-terminated string which contains the set of characters
     that  trigger emphasis.  In regular markdown, emphasis is only triggered by
     `_' and `*', but in some extensions it might be useful to add other charac-
     ters to this list.  The character	that  triggered  the  emphasis	is  then
     passed  to emphasis, double_emphasis and triple_emphasis function callbacks
     through the parameter c.

     The normal_text callback should perform whatever escape is needed	to  have
     the output looking like the input data.

     libsoldout supports PHP-Markdown-like tables.  It uses the following flags:
     MKD_CELL_ALIGN_DEFAULT,	  MKD_CELL_ALIGN_LEFT,	   MKD_CELL_ALIGN_RIGHT,
     MKD_CELL_ALIGN_CENTER, MKD_CELL_ALIGN_MASK, MKD_CELL_HEAD in these function
     callbacks: table_cell and table_row.

     MKD_LIST_ORDERED, MKD_LI_BLOCK are used as flags in  these  function  call-
     backs: list and listitem.

   Types
     enum mkd_autolink
     type of autolink:

     MKDA_NOT_AUTOLINK
	     used internally when it is not an autolink.

     MKDA_NORMAL
	     normal http/https/ftp link.

     MKDA_EXPLICIT_EMAIL
	     e-mail link with explicit mailto.

     MKDA_IMPLICIT_EMAIL
	     e-mail link without mailto.

     struct mkd_renderer
     consists of the following fields:

     Document level callbacks

	     prolog  a pointer to a void function(struct buf *ob, void *opaque)

	     epilog  a pointer to a void function(struct buf *ob, void *opaque)

     Block level callbacks (NULL skips the block)

	     blockcode
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, void *opaque)

	     blockquote
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, void *opaque)

	     blockhtml
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, void *opaque)

	     header  a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, int level, void *opaque)

	     hrule   a pointer to a void function(struct buf *ob, void *opaque)

	     list    a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, int flags, void *opaque)

	     listitem
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, int flags, void *opaque)

	     paragraph
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, void *opaque)

	     table   a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *head_row, struct buf *rows, void *opaque)

	     table_cell
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, int flags, void *opaque)

	     table_row
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *cells, int flags, void *opaque)

     Span level callbacks (NULL or return 0 prints the span verbatim)

	     autolink
		     a	   pointer    to    a	 int	function(struct buf *ob,
		     struct buf *link, enum mkd_autolink type, void *opaque)

	     codespan
		     a	  pointer    to    a	int	function(struct buf *ob,
		     struct buf *text, void *opaque)

	     emphasis
		     a	   pointer    to    a	 int	function(struct buf *ob,
		     struct buf *text, char c, void *opaque)

	     double_emphasis
		     a	  pointer    to    a	int	function(struct buf *ob,
		     struct buf *text, char c, void *opaque)

	     triple_emphasis
		     a	   pointer    to    a	 int	function(struct buf *ob,
		     struct buf *text, char c, void *opaque)

	     image   a	  pointer    to    a	int	function(struct buf *ob,
		     struct buf *link,	  struct buf *title,	struct buf *alt,
		     void *opaque)

	     linebreak
		     a pointer to a int function(struct buf *ob, void *opaque)

	     link    a	  pointer    to    a	int	function(struct buf *ob,
		     struct buf *link,	struct buf *title,  struct buf *content,
		     void *opaque)

	     raw_html_tag
		     a	  pointer    to    a	int	function(struct buf *ob,
		     struct buf *tag, void *opaque)

     Low level callbacks (NULL copies input directly into the output)

	     entity  a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *entity, void *opaque)

	     normal_text
		     a	  pointer    to    a	void	function(struct buf *ob,
		     struct buf *text, void *opaque)

     Renderer data

	     int max_work_stack
		     prevent arbitrary deep recursion.

	     const char * emph_chars
		     chars that trigger emphasis rendering.

	     void * opaque
		     opaque data send to every rendering callback.

RETURN VALUES
     The markdown() function does not return a value.

SEE ALSO
     soldout(3), soldout_buffer(3), soldout_renderers(3)

AUTHORS
     The soldout library was written by Natasha "Kerensikova" Porte <natacha@in-
     stinctive.eu>.   Manual  page was originally written by Massimo Manghi <mx-
     manghi@apache.org>, and rewritten	to  mdoc  format  by  Svyatoslav  Mishyn
     <juef@openmailbox.org>.

FreeBSD ports 15.quarterly	  May 30, 2016		     SOLDOUT_MARKDOWN(3)
home | help