Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LOWDOWN(3)		 BSD Library Functions Manual		    LOWDOWN(3)

NAME
     lowdown, lowdown_buf, lowdown_errstr, lowdown_file,
     lowdown_standalone_close, lowdown_standalone_open -- simple markdown
     translator	library

LIBRARY
     library "liblowdown"

SYNOPSIS
     #include <stdio.h>
     #include <lowdown.h>

     void
     lowdown_buf(const struct lowdown_opts *opts, const	unsigned char *buf,
	 size_t	bufsz, unsigned	char **ret, size_t *retsz,
	 struct	lowdown_meta **meta, size_t *metasz);

     const char	*
     lowdown_errstr(enum lowdown_err);

     int
     lowdown_file(const	struct lowdown_opts *opts, FILE	*f,
	 unsigned char **ret, size_t *retsz, struct lowdown_meta **meta,
	 size_t	*metasz);

     void
     lowdown_standalone_close(const struct lowdown_opts	*opts,
	 unsigned char **ret, size_t *retsz);

     void
     lowdown_standalone_open(const struct lowdown_opts *opts,
	 const struct lowdown_meta *meta, size_t metasz, unsigned char **ret,
	 size_t	*retsz);

DESCRIPTION
     The lowdown library parses	Markdown into HTML or roff (-ms	or -man	macro
     sets).  There are two forms of invocation.

     The first,	lowdown_file, operates from an already-opened FILE stream.
     The second, lowdown_buf, operates directly	on an input buffer buf of size
     bufsz.

     Both accept a configuration structure, opts, which	has the	following
     fields:

     arg     Pointer passed to msg, if not NULL.

     feat    Features used during the parse.  This bit-field may have the fol-
	     lowing bits OR'd:

	     LOWDOWN_TABLES
		     Allow for GFM tables.
	     LOWDOWN_FENCED
		     Allow for GFM fenced (language-specific) code blocks.
	     LOWDOWN_FOOTNOTES
		     MMD style footnotes.  This	only supports one-liner	foot-
		     notes on the same line as the footnote definition (not
		     the in-line referent).
	     LOWDOWN_AUTOLINK
		     Autolink http, https, ftp,	mailto,	and relative links or
		     link fragments.
	     LOWDOWN_STRIKE
		     Strikethrough support.
	     LOWDOWN_HILITE
		     Highlight.	 Do not	use this option.
	     LOWDOWN_SUPER
		     Allow for super-scripts.  This accepts foo^bar, which
		     puts the parts following the caret	until whitespace in
		     superscripts; or foo^(bar), which puts only the parts in
		     parenthesis.
	     LOWDOWN_MATH
		     Recognise single-dollar math mode.
	     LOWDOWN_NOINTEM
		     Disable emphasis with links.
	     LOWDOWN_SPHD
		     Require a space between hash marks	and header.
	     LOWDOWN_MATHEXP
		     Recognise double-dollar math mode.	 This only works if
		     LOWDOWN_MATH has also been	set.
	     LOWDOWN_NOCODEIND
		     Do	not indent code	blocks.
	     LOWDOWN_METADATA
		     Accept MMD	metadata.  For the first paragraph to count as
		     meta-data,	the first line must have a colon in it.	 Oth-
		     erwise it's considered a regular paragraph.  Meta-data is
		     escaped according to the output mode; and if the
		     LOWDOWN_SMARTY flag is set, also smartypantsed.

	     The default value is zero (none).

     msg     Message function for logging messages.  If	NULL, messages are not
	     logged.

     ofeat   Features used by the output generators.  This bit-field may have
	     the following enabled.  Note that bits are	by definition specific
	     to	an output type.

	     For LOWDOWN_HTML:

	     LOWDOWN_HTML_SKIP_HTML
		     Do	not render in-document HTML at all.  Note that
		     LOWDOWN_HTML_ESCAPE takes priority	if both	are specified.
		     Text within HTML elements remains.
	     LOWDOWN_HTML_ESCAPE
		     Leaves in-line HTML in its	source form as if it were
		     opaque text.  Takes precedence over LOWDOWN_HTML_ESCAPE.
	     LOWDOWN_HTML_HARD_WRAP
		     Retain line-breaks	within paragraphs.

	     And for LOWDOWN_MAN and LOWDOWN_NROFF:

	     LOWDOWN_NROFF_SKIP_HTML
		     Do	not render in-document HTML at all.  Text within HTML
		     elements remains.
	     LOWDOWN_NROFF_HARD_WRAP
		     Retain line-breaks	within paragraphs.
	     LOWDOWN_NROFF_NUMBERED
		     Use numbered sections.  Only applies to the LOWDOWN_NROFF
		     output type.
	     LOWDOWN_NROFF_GROFF
		     Use GNU extensions	(i.e., for groff(1)) when rendering
		     output.  You'll need to include -m	pdfmark	when invoking
		     groff(1) for formatting links.

	     For any mode, you may specify:

	     LOWDOWN_SMARTY
		     Don't use "smartypants" formatting.

     type    May be set	to LOWDOWN_HTML	for HTML5 output, LOWDOWN_MAN for -man
	     macros, or	LOWDOWN_NROFF for -ms macros.  Both LOWDOWN_MAN	and
	     LOWDOWN_MS	will use troff tables, which usually require the
	     tbl(1) preprocessor.

     The results for both functions are	stored in ret, which must later	be
     passed to free(3),	of size	retsz.	Both functions also accept the meta
     and metasz	pointers.  If both of these are	not NULL, they are set to any
     meta tags that have been parsed.  It is the caller's job to free the meta
     structure resources.  Obviously, the meta tags are	parsed only if
     LOWDOWN_METADATA has been provided.

     The lowdown_errstr	is provided to return a	human-readable version of enum
     lowdown_err.  It returns a	generic	(en_GB)	description.

     The lowdown_standalone_open and lowdown_standalone_close are utility
     functions for outputting a	document header	and footer (in the given out-
     put format) given document	meta-data.  The	recognised meta-data keys are
     "title" (free-form	text of	the title), "author" (free-form	text of	one or
     more names), and "date" (ISO-8601 yy/mm/dd).

     The "rcsdate" may be specified instead of "date", and should consists of
     the rcs(1)	$Date$ keyword.	 The "rcsauthor" may be	similarly used and
     consists of the rcs(1) $Author$ keyword.

     Two or more consecutive white-space (newlines, tabs, spaces) in the
     "author" value indicates multiple authors.

RETURN VALUES
     The lowdown_file returns zero if the file-reading sequenced failed, non-
     zero otherwise.

SEE ALSO
     groff(1), lowdown(1)

AUTHORS
     The lowdown library was forked by Kristaps	Dzonsons <kristaps@bsd.lv>
     from hoedown: https://github.com/hoedown/hoedown

CAVEATS
     The lowdown library functions will	invoke exit(3) if internal memory al-
     location fails.  There is no way to catch these conditions.

BSD				March 27, 2017				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lowdown&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help