FreeBSD Manual Pages
LOWDOWN(3) BSD Library Functions Manual LOWDOWN(3) NAME lowdown -- simple markdown translator library LIBRARY library "liblowdown" SYNOPSIS #include <sys/queue.h> #include <stdio.h> #include <lowdown.h> struct lowdown_metadata struct lowdown_node struct lowdown_opts DESCRIPTION This library parses lowdown(5) into various output formats. The library consists first of a high-level interface consisting of lowdown_buf(3), lowdown_buf_diff(3), lowdown_file(3), and lowdown_file_diff(3). The high-level functions interface with low-level functions that perform parsing and formatting. These consist of lowdown_doc_new(3), lowdown_doc_parse(3), and lowdown_doc_free(3) for parsing lowdown(5) doc- uments into an abstract syntax tree, then lowdown_html_free(3), lowdown_html_new(3), and lowdown_html_rndr(3) for HTML formatting; lowdown_nroff_free(3), lowdown_nroff_new(3), and lowdown_nroff_rndr(3) for roff(7) output; lowdown_term_free(3), lowdown_term_new(3), and lowdown_term_rndr(3) for ANSI-escaped UTF-8 terminal output; and finally lowdown_tree_free(3), lowdown_tree_new(3), and lowdown_tree_rndr(3) for formatting debugging output. To compile and link, use pkg-config(1): % cc `pkg-config --cflags lowdown` -c -o sample.o sample.c % cc -o sample sample.o `pkg-config --libs lowdown` Pledge Promises The lowdown library is built to operate in security-sensitive environ- ments, such as those using pledge(2) on OpenBSD. The only promise re- quired is stdio for lowdown_file_diff(3) and lowdown_file(3): both re- quire access to the stream for reading input. Types All lowdown functions use one or more of the following structures. The struct lowdown_opts structure manage features. It has the following fields: unsigned int feat Features used during the parse. This bit-field may have the following bits OR'd: LOWDOWN_AUTOLINK Parse http, https, ftp, mailto, and relative links or link fragments. LOWDOWN_COMMONMARK Tighten input parsing to the CommonMark specifica- tion. This also uses the first ordered list value instead of starting all lists at one. This feature is experimental and incomplete. LOWDOWN_DEFLIST Parse PHP extra definition lists. This is cur- rently constrained to single-key lists. LOWDOWN_FENCED Parse GFM fenced (language-specific) code blocks. LOWDOWN_FOOTNOTES Parse MMD style footnotes. This only supports the referenced footnote style, not the "inline" style. LOWDOWN_HILITE Parse highlit sequences. This are disabled by de- fault because it may be erroneously interpreted as section headers. LOWDOWN_IMG_EXT Parse PHP image extended attributes. LOWDOWN_MATH Parse mathematics equations. LOWDOWN_METADATA Parse 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 use smart typography. LOWDOWN_NOCODEIND Do not parse indented content as code blocks. LOWDOWN_NOINTEM Do not parse emphasis within words. LOWDOWN_STRIKE Parse strikethrough sequences. LOWDOWN_SUPER Parse 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_TABLES Parse GFM tables. The default value is zero (none). unsigned int oflags Features used by the output generators. This bit-field may have the following enabled. Note that bits are by defini- tion specific to an output type. For LOWDOWN_HTML: LOWDOWN_HTML_ESCAPE If LOWDOWN_HTML_SKIP_HTML has not been set, escapes in-document HTML so that it is rendered as opaque text. 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. LOWDOWN_HTML_OWASP When escaping text, be extra paranoid in following the OWASP suggestions for which characters to es- cape. LOWDOWN_HTML_NUM_ENT Convert, when possible, HTML entities to their nu- meric form. If not set, the entities are used as given in the input. LOWDOWN_HTML_SKIP_HTML Do not render in-document HTML at all. For LOWDOWN_GEMINI, there are several flags for controlling link placement. By default, links (images, autolinks, and links) are queued when specified in-line then emitted in a block sequence after the nearest block element. LOWDOWN_GEMINI_LINK_END Emit the queue of links at the end of the document instead of after the nearest block element. LOWDOWN_GEMINI_LINK_IN Render all links within the flow of text. This will cause breakage when nested links, such as im- ages within links, links in blockquotes, etc. It should not be used unless in carefully crafted doc- uments. There may only be one of LOWDOWN_GEMINI_LINK_END or LOWDOWN_GEMINI_LINK_IN. If both are specified, the latter is unset. For LOWDOWN_LATEX: LOWDOWN_LATEX_NUMBERED Use the default numbering scheme for sections, sub- sections, etc. If not specified, these are inhib- ited. LOWDOWN_LATEX_SKIP_HTML Do not render in-document HTML at all. Text within HTML elements remains. And for LOWDOWN_MAN and LOWDOWN_NROFF: LOWDOWN_NROFF_GROFF Use GNU extensions (i.e., for groff(1)) when ren- dering output. You'll need to include -m pdfmark when invoking groff(1) for formatting links. Only applies to the LOWDOWN_NROFF output type. LOWDOWN_NROFF_HARD_WRAP Retain line-breaks within paragraphs. LOWDOWN_NROFF_NUMBERED Use numbered sections if LOWDOWON_NROFF_GROFF is not specified. Only applies to the LOWDOWN_NROFF output type. LOWDOWN_NROFF_SKIP_HTML Do not render in-document HTML at all. Text within HTML elements remains. For LOWDOWN_TERM: LOWDOWN_TERM_SHORTLINK Render link URLs in short form. For any mode, you may specify: LOWDOWN_SMARTY Don't use smart typography formatting. LOWDOWN_STANDALONE Emit a full document instead of a document frag- ment. Parts of this envelope may be populated from metadata if LOWDOWN_METADATA was provided as an op- tion. See lowdown(1) for details. size_t maxdepth The maximum parse depth before the parser exits. Most doc- uments will have a parse depth in the single digits. size_t cols For LOWDOWN_TERM, the "soft limit" for width of terminal output not including margins. This might be zero, in which case a reasonable default should be used. size_t hmargin For LOWDOWN_TERM, the left margin (space characters). size_t vmargin For LOWDOWN_TERM, the top/bottom margin (newlines). enum lowdown_type type May be set to LOWDOWN_HTML for HTML5 output, LOWDOWN_LATEX for LaTeX, LOWDOWN_MAN for -man macros, LOWDOWN_TERM for ANSI-compatible UTF-8 terminal output, LOWDOWN_GEMINI for the Gemini format, 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. This structure consists of the following fields: char *key The metadata key in its lowercase, canonical form. char *value The metadata value as rendered in the current output for- mat. The abstract syntax tree is encoded in struct lowdown_node, which con- sists of the following. enum lowdown_rndrt type The node type. (Described below.) size_t id An identifier unique within the document. This can be used as a table index since the number is assigned from a mono- tonically increasing point during the parse. struct lowdown_node *parent The parent of the node, or NULL at the root. enum lowdown_chng chng Change tracking: whether this node was inserted (LOWDOWN_CHNG_INSERT), deleted (LOWDOWN_CHNG_DELETE), or neither (LOWDOWN_CHNG_NONE). struct lowdown_nodeq children A possibly-empty list of child nodes. _anon union_ An anonymous union of type-specific structures. See below for a description of each one. The nodes may be one of the following types, with default rendering in HTML5 to illustrate functionality. LOWDOWN_ROOT The root of the document. This is always the topmost node, and the only node where the parent field is NULL. LOWDOWN_BLOCKCODE A block-level (and possibly language-specific) snippet of code. Described by the <pre><code> elements. LOWDOWN_BLOCKHTML A block-level snippet of HTML. This is simply opaque HTML content. (Only if configured during parse.) LOWDOWN_BLOCKQUOTE A block-level quotation. Described by the <blockquote> el- ement. LOWDOWN_CODESPAN A snippet of code. Described by the <code> element. LOWDOWN_DOC_FOOTER Closes out the document opened in LOWDOWN_DOC_HEADER. LOWDOWN_DOC_HEADER A header with data gathered from document metadata (if con- figured). Described by the <head> element. (Only if con- figured during parse.) LOWDOWN_DOUBLE_EMPHASIS Bold (or otherwise notable) content. Described by the <strong> element. LOWDOWN_EMPHASIS Italic (or otherwise notable) content. Described by the <em> element. LOWDOWN_ENTITY An HTML entity, which may either be named or numeric. LOWDOWN_FOOTNOTE_DEF A footnote within a LOWDOWN_FOOTNOTES_BLOCK node. De- scribed by the <li id="fnXX"> element. (Only if configured during parse.) LOWDOWN_FOOTNOTE_REF A reference to a LOWDOWN_FOOTNOTE_DEF. Described by the <sup><a> elements. (Only if configured during parse.) LOWDOWN_FOOTNOTES_BLOCK A block of footnotes. Described by the <div class="footnotes"><hr /><ol> elements. (Only if configured during parse.) LOWDOWN_HEADER A block-level header. Described (in the HTML case) by one of <h1> through <h6>. LOWDOWN_HIGHLIGHT Marked test. Described by the <mark> element. (Only if configured during parse.) LOWDOWN_HRULE A horizontal line. Described by <hr>. LOWDOWN_IMAGE An image. Described by the <img> element. LOWDOWN_LINEBREAK A hard line-break within a block context. Described by the <br> element. LOWDOWN_LINK A link to external media. Described by the <a> element. LOWDOWN_LINK_AUTO Like LOWDOWN_LINK, except inferred from text content. De- scribed by the <a> element. (Only if configured during parse.) LOWDOWN_LIST A block-level list enclosure. Described by <ul> or <ol>. LOWDOWN_LISTITEM A block-level list item, always appearing within a LOWDOWN_LIST. Described by <li>. LOWDOWN_MATH_BLOCK A block (or inline) of mathematical text in LaTeX format. Described within \[xx\] or \(xx\). This is usually (in HTML) externally handled by a JavaScript renderer. (Only if configured during parse.) LOWDOWN_META Meta-data keys and values. (Only if configured during parse.) These are described by elements in the <head> ele- ment. LOWDOWN_NORMAL_TEXT Normal text content. LOWDOWN_PARAGRAPH A block-level paragraph. Described by the <p> element. LOWDOWN_RAW_HTML An inline of raw HTML. (Only if configured during parse.) LOWDOWN_STRIKETHROUGH Content struck through. Described by the <del> element. (Only if configured during parse.) LOWDOWN_SUPERSCRIPT A superscript. Described by the <sup> element. (Only if configured during parse.) LOWDOWN_TABLE_BLOCK A table block. Described by <table>. (Only if configured during parse.) LOWDOWN_TABLE_BODY A table body section. Described by <tbody>. Parent is al- ways LOWDOWN_TABLE_BLOCK. (Only if configured during parse.) LOWDOWN_TABLE_CELL A table cell. Described by <td> or <th> if in the header. Parent is always LOWDOWN_TABLE_ROW. (Only if configured during parse.) LOWDOWN_TABLE_HEADER A table header section. Described by <thead>. Parent is always LOWDOWN_TABLE_BLOCK. (Only if configured during parse.) LOWDOWN_TABLE_ROW A table row. Described by <tr>. Parent is always LOWDOWN_TABLE_HEADER or LOWDOWN_TABLE_BODY. (Only if con- figured during parse.) LOWDOWN_TRIPLE_EMPHASIS Combination of LOWDOWN_EMPHASIS and LOWDOWN_DOUBLE_EMPHASIS. The following anonymous union structures correspond to certain nodes. Note that all buffers may be zero-length. rndr_meta Each LOWDOWN_META key-value pair is represented. The keys are lower-case without spaces or non-ASCII characters. En- closed nodes may consist only of LOWDOWN_NORMAL_TEXT and LOWDOWN_ENTITY. rndr_definition For LOWDOWN_DEFINITION, containing flags that may be HLIST_FL_BLOCK if the definition list should be interpreted as containing block elements. rndr_list For LOWDOWN_LIST, consists of a bitfield flags that may be set to HLIST_FL_ORDERED for an ordered list and HLIST_FL_UNORDERED for an unordered one. If HLIST_FL_BLOCK is set, the list should be output as if items were separate blocks. If start is a non-empty string, it is the first list item value. rndr_paragraph For LOWDOWN_PARAGRAPH, species how many lines the paragraph has in the input file and beoln, set to non-zero if the paragraph ends with an empty line instead of a breaking block element. rndr_listitem For LOWDOWN_LISTITEM, consists of a bitfield flags that may be set to HLIST_FL_ORDERED (an ordered list), HLIST_FL_UNORDERED (unordered list), HLIST_FL_DEF (definition list data), and/or HLIST_FL_BLOCK (list item output as if containing block elements). The HLIST_FL_BLOCK should not be used: use the parent list (or definition list) flags for this. The num is the index in an ordered list. rndr_header For LOWDOWN_HEADER, the level of the header starting at zero This value is relative to the metadata base header level, defaulting to one (the top-level header). rndr_normal_text The basic text content for LOWDOWN_NORMAL_TEXT. rndr_entity For LOWDOWN_ENTITY, the entity text. rndr_autolink For LOWDOWN_LINK_AUTO, the link address as link; the tex- tual component text; and the link type type, which may be one of HALINK_EMAIL for e-mail links and HALINK_NORMAL oth- erwise. Any buffer may be empty-sized. rndr_raw_html For LOWDOWN_RAW_HTML, the opaque HTML text. rndr_link Like rndr_autolink. rndr_blockcode For LOWDOWN_BLOCKCODE, the opaque text of the block and the optional lang of the code language. rndr_codespan The opaque text of the contents. rndr_table_header For LOWDOWN_TABLE_HEADER, the number of columns in each row and the per-column flags, which may be bits of HTBL_FL_ALIGN_LEFT, HTBL_FL_ALIGN_RIGHT, or HTBL_FL_ALIGN_CENTER when masked with HTBL_FL_ALIGNMASK; or HTBL_FL_HEADER. rndr_table_cell For LOWDOWN_TABLE_CELL, the current col colum number out of columns. See rndr_table_header for a description of the bits in flags. rndr_footnote_def For LOWDOWN_FOOTNOTE_DEF, the footnote number num. rndr_footnote_ref For a LOWDOWN_FOOTNOTE_REF reference to a LOWDOWN_FOOTNOTE_DEF, the footnote number num. rndr_image For LOWDOWN_IMAGE, the image address link, the image title title, dimensions NxN (width by height) in dims, and alter- nate text alt. rndr_math For LOWDOWN_MATH, the mode of display displaymode: if 1, in-line math; if 2, multi-line. rndr_blockhtml For LOWDOWN_BLOCKHTML, the opaque HTML text. SEE ALSO lowdown(1), lowdown_buf(3), lowdown_buf_diff(3), lowdown_diff(3), lowdown_doc_free(3), lowdown_doc_new(3), lowdown_doc_parse(3), lowdown_file(3), lowdown_file_diff(3), lowdown_gemini_free(3), lowdown_gemini_new(3), lowdown_gemini_rndr(3), lowdown_html_free(3), lowdown_html_new(3), lowdown_html_rndr(3), lowdown_latex_free(3), lowdown_latex_new(3), lowdown_latex_rndr(3), lowdown_metaq_free(3), lowdown_nroff_free(3), lowdown_nroff_new(3), lowdown_nroff_rndr(3), lowdown_term_free(3), lowdown_term_new(3), lowdown_term_rndr(3), lowdown_tree_free(3), lowdown_tree_new(3), lowdown_tree_rndr(3), lowdown(5) AUTHORS lowdown was forked from hoedown: https://github.com/hoedown/hoedown by Kristaps Dzonsons, kristaps@bsd.lv. It has been considerably modified since. BSD December 1, 2020 BSD
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lowdown&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>