LOWDOWN(3) Library Functions Manual LOWDOWN(3)

NAME

lowdownsimple markdown translator library

LIBRARY

library “liblowdown”

SYNOPSIS

#include <sys/queue.h>
#include <stdio.h>
#include <lowdown.h>
struct lowdown_opts
struct lowdown_metadata
enum lowdown_err
typedef void
(*lowdown_msg)(enum lowdown_err err, void *arg, const char *msg);

DESCRIPTION

The lowdown library parses Markdown as defined in lowdown(5) into HTML or roff (-ms or -man macro sets). It consists of both a high-level interface consisting of lowdown_buf(3), lowdown_buf_diff(3), lowdown_file(3), and lowdown_file_diff(3); then a series of low-level interfaces directly to the parsers and renderers.
Most functions use the struct lowdown_opts structure to manage features.
struct lowdown_opts { 
  lowdown_msg msg; 
  enum lowdown_type type; 
  void *arg; 
  unsigned int feat; 
  unsigned int oflags; 
};
It has the following fields:
 
 
arg
Pointer passed to msg, if not NULL.
 
 
feat
Features used during the parse. This bit-field may have the following 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 footnotes 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_COMMONMARK
Recognise CommonMark input. Experimental.
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. Otherwise 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 (lowdown_msg) 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.
LOWDOWN_HTML_HEAD_IDS
Have an identifier written with each header element consisting of an HTML-escaped version of the header contents.
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.
LOWDOWN_STANDALONE
Emit a full document instead of a document fragment. Parts of this envelope may be populated from metadata if LOWDOWN_METADATA was provided as an option. See lowdown(1) for details.
 
 
type
May be set to LOWDOWN_HTML for HTML5 output, LOWDOWN_MAN for -man macros, or LOWDOWN_NROFF for -ms macros. The LOWDOWN_TREE type causes a debug tree to be written.
Both LOWDOWN_MAN and LOWDOWN_MS will use troff tables, which usually require the tbl(1) preprocessor.
Another common structure is struct lowdown_metadata, which is used to hold parsed (and output-formatted) metadata keys and values if LOWDOWN_METADATA was provided as an input bit.
struct lowdown_meta { 
  char *key; 
  char *value; 
};
This structure consists of the following fields:
 
 
key
The metadata key in its lowercase, canonical form.
 
 
value
The metadata value as rendered in the current output format.
An error message function of type lowdown_msg is given in struct lowdown_opts.
typedef	void (*lowdown_msg) 
  (enum lowdown_err, void *, const char *);
It accepts the following arguments:
 
 
err
An error code programmatically describing the error.
 
 
arg
An opaque pointer provided in struct lowdown_opts.
 
 
msg
Additional information about the error.
The error code may be one of:
 
 
LOWDOWN_ERR_SPACE_BEFORE_LINK
Spaces before the URL portion of a link. This is not portable.
 
 
LOWDOWN_ERR_METADATA_BAD_CHAR
A bad character in a metadata key (it is converted into “”?).
 
 
LOWDOWN_ERR_UNKNOWN_FOOTNOTE
A footnote reference to an unknown footnote, and is thus being ignored.
 
 
LOWDOWN_ERR_DUPE_FOOTNOTE
A duplicate footnote reference was encountered, and is thus being ignored.

Pledge Promises

The lowdown library is built to operate in security-sensitive environments, such as those using pledge(2) on OpenBSD. The only promise required is stdio for lowdown_file_diff(3) and lowdown_file(3): both require access to the stream for reading input.

SEE ALSO

lowdown(1), lowdown_buf(3), lowdown_buf_diff(3), lowdown_doc_free(3), lowdown_doc_new(3), lowdown_doc_parse(3), lowdown_errstr(3), lowdown_file(3), lowdown_file_diff(3), lowdown_html_free(3), lowdown_html_new(3), lowdown_html_rndr(3), lowdown_nroff_free(3), lowdown_nroff_new(3), lowdown_nroff_rndr(3), lowdown_tree_free(3), lowdown_tree_new(3), lowdown_tree_rndr(3), lowdown(5)

AUTHORS

The lowdown library was forked by Kristaps Dzonsons <kristaps@bsd.lv> from hoedown. It has been considerably changed since then.
June 18, 2018 OpenBSD 6.3