lowdown-1.1.0004075500017500001750000000000001452256251200134555ustar00kristapskristapslowdown-1.1.0/man004075500017500001750000000000001452256251200142305ustar00kristapskristapslowdown-1.1.0/man/lowdown-diff.1010064400017500001750000000457121452256251200167760ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate$ .Dt LOWDOWN-DIFF 1 .Os .Sh NAME .Nm lowdown-diff .Nd view differences in markdown files .Sh SYNOPSIS .Nm lowdown-diff .Op input_options .Op output_options .Op Fl s .Op Fl M Ar metadata .Op Fl m Ar metadata .Op Fl o Ar file .Op Fl t Ar mode .Ar oldfile .Op Ar newfile .Sh DESCRIPTION Shows differences between .Xr lowdown 5 documents as formatted output. Results are written to standard output. .Pp The arguments are as follows: .Bl -tag -width Ds .It Fl s Standalone mode. This emits a document envelope surrounding the output by drawing from document metadata. See .Sx Metadata on providing information to the document envelope. This applies to .Fl t Ns Ar gemini , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar ms , .Fl t Ns Ar man , and .Fl t Ns Ar fodt . .It Fl M Ar metadata Provide a single metadata key-value pair. This may be in the syntax specified by .Xr lowdodwn 5 or as pairs separated by an equal sign, depending upon which character (a colon or equal sign) comes first. Exits with an error if given neither colon nor equal sign. May be invoked multiple times for each pair. This overrides .Fl m and what's parsed from the document. .It Fl m Ar metadata Like .Fl M , but is overridden by what's parsed the document, then .Fl M . .It Fl o Ar file Send output to .Ar file unless it's .Dq - , in which case fall back to the default of standard output. .It Fl t Ar mode , Fl T Ar mode The output mode. This may be .Ar html for HTML5 output, .Ar latex for LaTeX, .Ar gemini for the Gemini format, .Ar ms for roff output using the classic (i.e., no-extension) .Fl ms package and needing table support, .Ar term for ANSI-compatible UTF-8 terminal output, .Ar man for roff output using the classic .Fl man package, .Ar tree , to show the parse tree of the input document, and .Ar null to parse the document but do no rendering. See .Sx Output modes . The .Fl T Ar mode form is retained for backward compatibility. .It Ar oldfile , newfile Markdown documents used for comparison. If .Ar newfile is not given or .Dq - , it is read from standard input. .El .Pp The following are options for input parsing. These affect the parse tree passed to all outputs. .Bl -tag -width Ds .It Fl -parse-hilite Enable highlight span support. This are disabled by default because it may be erroneously interpreted as section headers. .It Fl -parse-math Recognise mathematics equations. .It Fl -parse-maxdepth=depth The maximum depth of nested elements. This defaults to 128, which is probably more than enough for any real-world document. If the maximum is hit, the system exits as if memory were exhausted. Set to zero for no maximum. .It Fl -parse-no-autolink Do not parse .Li http , .Li https , .Li ftp , .Li mailto , and relative links or link fragments. .It Fl -parse-no-cmark Do not parse with CommonMark constraints. This also disables using the first ordered list value instead of starting all lists at one. .It Fl -parse-no-codeindent Do not parse indented content as code blocks. .It Fl -parse-no-callouts Do not parse GFM/MDN callouts .Pq Qq admonitions . .It Fl -parse-no-deflists Do not parse PHP extra definition lists. .It Fl -parse-no-ext-attrs Do not parse PHP extra extended attributes. .It Fl -parse-no-fenced Do not parse GFM fenced (language-specific) code blocks. .It Fl -parse-no-footnotes Do not parse MMD footnotes. .It Fl -parse-no-img-ext Deprecated. See .Fl -parse-no-ext-attrs . .It Fl -parse-no-intraemph Do not parse emphasis within words and links. .It Fl -parse-no-mantitle Do not parse manpage title, section, source, and volume from Pandoc title metadata. Manpages titles are indicated by a title then an open parenthesis, digit followed by optional characters, then a closed parenthesis. .It Fl -parse-no-metadata Do not parse metadata. This does not affect metadata given on .Fl m or .Fl M . .It Fl -parse-no-strike Do not parse strikethroughs. .It Fl -parse-no-super Do not parse super-scripts or sub-scripts at all. .It Fl -parse-no-tables Do not parse GFM tables. .It Fl -parse-no-tasklists Do not parse GFM task lists. .It Fl -parse-super-short If super-script parsing is enabled, use the traditional non-GFM .Qq short syntax. .El .Pp There are many output options. The following are shared by all output modes: .Bl -tag -width Ds .It Fl -out-standalone Alias for .Fl s . .It Fl -out-no-smarty Do not use the smart typography filter. By default, certain character sequences are translated into output-specific glyphs. .El .Pp What follows are per-output options. For HTML with .Fl t Ns Ar html , these are as follows: .Bl -tag -width Ds .It Fl -html-callout-mdn , -html-callout-gfm Output either or both MDN or GFM callout syntaxes. .It Fl -html-hardwrap Hard-wrap paragraph content by outputting line breaks where applicable. .It Fl -html-no-escapehtml If .Fl -html-no-skiphtml has been specified, this causes embedded HTML not to be escaped, and is instead output verbatim. This has no effect if .Fl -html-no-skiphtml has not been specified. .It Fl -html-no-head-ids Do not output .Li id attributes for headers. .It Fl -html-no-num-ent Don't normalise HTML entities (when possible) as numeric ones and instead use the entities as given on input. .It Fl -html-no-owasp Don't follow the OWASP recommendations for escaping text, and do only the minimal escaping to make sure that regular content isn't interpreted as HTML. .It Fl -html-no-skiphtml Output embedded HTML. By default, embedded HTML is not output at all. See .Fl -html-no-escapehtml . .El .Pp For both .Fl t Ns Ar man and .Fl t Ns Ar ms , the following apply: .Bl -tag -width Ds .It Fl -nroff-code-font Ns = Ns Ar fonts Override the default constant-width fonts with a tuple of regular, bold, italic, and bold-italic variants in that order. For example, .Li B,B,BI,BI uses bold .Pq Qq B instead of a constant-width. Not specifying a font will use the default, as will specifying a zero-length font name. Aliases .Li none , .Li bold , and .Li code set no special fonts, bold, and the default constant-width. .It Fl -nroff-no-groff Don't use .Xr groff 1 style section headings, PDF hyperlinks and multi-page tables (these further require .Fl t Ns Ar ms mode and .Fl m Ns Ar spdf passed to .Xr groff 1 ) , or Unicode sequence syntax. The output is compatible with traditional .Xr troff 1 . .It Fl -nroff-no-numbered Don't output numbered headings. Only applies to .Fl t Ns Ar ms . .It Fl -nroff-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted. .It Fl -nroff-nolinks Don't show URLs for images and links (autolinks are still shown). .Pq Link content is still shown. Overrides .Fl -nroff-shortlinks for images and links. Applies to .Fl t Ns Ar man or when .Fl nroff-no-groff is specified. .It Fl -nroff-shortlinks Shorten URLs for images, links, and autolinks to only the domain name and final path. Applies to .Fl t Ns Ar man or when .Fl nroff-no-groff is specified. .El .Pp The .Fl t Ns Ar term output has the following: .Bl -tag -width Ds .It Fl -term-all-metadata If .Fl s is specified, output all metadata instead of just the title, author, and date. .It Fl -term-columns=columns The number of columns in the screen. Useful for when running in a pipe. Defaults to what the terminal reports or 72 if in a pipe. .It Fl -term-hmargin=margin The number of left margin spaces. Truncated to the number of columns. Defaults to zero. .It Fl -term-no-ansi Don't show ANSI styles at all. This implies .Fl -term-no-colour . .It Fl -term-no-colour Don't show ANSI colours. This will still decorate text with underlines, bolds, and italics, but not emit any colour codes. .It Fl -term-nolinks Don't show URLs for images and links (autolinks are still shown). .Pq Link content is still shown. Overrides .Fl -term-shortlinks for images and links. .It Fl -term-shortlinks Shorten URLs for images, links, and autolinks to only the domain name and final path. .It Fl -term-vmargin=margin The number of top and bottom margin newlines. Defaults to zero. .It Fl -term-width=width Set the soft limit on the number of characters per line. This may be exceeded by literal text. The default (or if zero) is the number of terminal columns or 80 at most. .El .Pp The .Fl t Ns Ar gemini output has several flags that control the placement of links. By default, links (images, autolinks, and links) are queued when specified in-line then emitted in a block sequence after the nearest block element. .Bl -tag -width Ds .It Fl -gemini-link-end Emit the queue of links at the end of the document instead of after the nearest block element. .It Fl -gemini-link-inline Render all links within the flow of text. This will cause breakage when nested links, such as images within links, links in blockquotes, etc. It should not be used unless in carefully crafted documents. .It Fl -gemini-link-noref Do not format link labels. Takes precedence over .Fl -gemini-link-roman . .It Fl -gemini-link-roman When formatting link labels, use lower-case Roman numerals instead of the default lower-case hexavigesimal (i.e., .Dq a , .Dq b , \&..., .Dq aa , .Dq ab , \&...). .It Fl -gemini-metadata Print metadata as the canonicalised key followed by a colon then the value, each on one line (newlines replaced by spaces). The metadata block is terminated by a double newline. If there is no metadata, this does nothing. .El .Pp The .Fl t Ns Ar latex output has the following options: .Bl -tag -width Ds .It Fl -latex-no-numbered Don't number sections (and subsections, etc.). .It Fl -latex-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted. .El .Pp The .Fl t Ns Ar fodt output has the following options: .Bl -tag -width Ds .It Fl -odt-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted. .It Fl -odt-style Ns = Ns Ar file Specify an OpenDocument style file, which must consist of at least .Li , .Li , and .Li XML elements in the root of the document. This is not syntax-checked in any way. .El .Ss Output modes The output media is specified by .Fl t , which defaults to .Fl t Ns Ar html . .Bl -tag -width Ds .It Fl t Ns Ar fodt .Dq Flat OpenDocument output. Automatic styles (those conditional upon document state) are generated with output. Classes specified by PHP extended attributes are not checked for existence. Differences are rendered using document tracking. .It Fl t Ns Ar gemini Gemini protocol output. This output mode is experimental. Differences are not currently rendered. .It Fl t Ns Ar html HTML5 output with UTF-8 encoding. Differences are rendered using the .Li and .Li elements. .It Fl t Ns Ar latex Simple LaTeX output. The following packages are required: .Li amsmath and .Li amssymb for maths, .Li graphicx for images, .Li inputenc Pq utf8 for UTF-8 input, .Li fontend Pq T1 and .Li textcomp for output glyphs, .Li lmodern for Latin modern font, .Li xcolor for the difference engine output, and .Li hyperref for links. Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). .It Fl t Ns Ar man The .Ar man macro package suitable for reading by .Xr groff 1 , .Xr mandoc 1 , or traditional .Xr troff 1 . Does not support equations and images. Table support is provided by .Xr tbl 1 . Since UTF-8 may be passed as input values, .Xr preconv 1 may need to be used. Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). .It Fl t Ns Ar ms The .Ar ms macro package suitable for reading by .Xr groff 1 or traditional .Xr troff 1 . Does not support equations and limited image support for encapsulated postscript (PS and EPS suffix) images. Images are always block-formatted. Image dimensions and extended attributes are ignored, though images are downsized if larger than the current text width. Table support is provided by .Xr tbl 1 . Since UTF-8 may be passed as input values, .Xr preconv 1 may need to be used. Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). .It Fl t Ns Ar term ANSI-escaped UTF-8 output suitable for reading on the terminal. Images and equations not supported. Differences are rendered by background-colouring in blue (insert) and red (delete) (this format is not fixed). .It Fl t Ns Ar tree Debugging output: not for general use. .El .Ss Standalone documents When .Fl s is specified, additional content may be added to output: .Bl -tag -width Ds .It Fl t Ns Ar fodt Envelope .Li and prologue .Li , .Li , and .Li . .It Fl t Ns Ar html Envelope .Li and prologue .Li . .It Fl t Ns Ar latex Prologue .Li documentclass and .Li usepackage statements, and surrounding .Li begin{document} statements. .It Fl t Ns Ar man , Fl t Ns Ar ms Prologue macros. .It Fl t Ns Ar term Prologue lines. .El .Pp If parsed from the document or as given by .Fl m or .Fl M , the following metadata keys are used by additional content. The metadata keys are canonicalised in lowercase and without spaces. .Pp Metadata values should not be encoded in their output format, e.g., .Dq css: foo&bar . The renderer will perform any necessary output encoding. .Bl -tag -width Ds .It Li affiliation Author affiliation (organisation or institution). Multiple affiliations may be separated by two or more spaces (including newlines). Used in .Fl t Ns Ar html , .Fl t Ns Ar latex , and .Fl t Ns Ar ms . .It Li author Document author. Multiple authors may be separated by two or more spaces (including newlines). Overridden by .Li rcsauthor . Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar ms , and .Fl t Ns Ar term . .It Li baseheaderlevel Added to each header level. Deprecated in favour of .Li shiftheadinglevelby . .It Li copyright A document copyright (without the word .Dq Copyright ) , for example, .Dq 2017, Kristaps Dzonsons . Used in .Fl t Ns Ar ms and .Fl t Ns Ar html . .It Li css A CSS file included in the HTML5 document head. Multiple CSS files (in order) may be separated by two or more spaces (including newlines). Only used in .Fl t Ns Ar html . .It Li date Document date in ISO-8601 YYYY-MM-DD format. Overridden by .Li rcsdate . Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar ms , and .Fl t Ns Ar term . .It Li javascript A JavaScript file included in the HTML5 document head. Multiple script files (in order) may be separated by two or more spaces (including newlines). Only used in .Fl t Ns Ar html . .It Li lang Document language in RFC 5646 format. Only used in .Fl t Ns Ar html . .It Li rcsauthor Like .Li author , but in RCS author format. Overrides .Li author . .It Li rcsdate Like .Li date , but in RCS date format. Overrides .Li date . .It Li section Man page section, defaulting to .Dq 7 . Only used in .Fl t Ns Ar man . .It Li shiftheadinglevelby Shift all headers by the given number. For example, a value of 1 causes headers originally at level 1 .Pq Dq

to be level 2 .Pq Dq

, while a value of -1 moves level 2 to 1. Levels will not move to less than 1. Takes precedence over .Li baseheaderlevel . If unset or not a valid number, defaults to zero. Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , and .Fl t Ns Ar ms . .It Li source Man page source (organisation providing the manual). Only used in .Fl t Ns Ar man . .It Li volume Man page volume (describes the manual page section). Only used in .Fl t Ns Ar man . .It Li title Document title. Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar ms , and .Fl t Ns Ar term . .El .Pp Metadata values are parsed and may be used as variables in markdown documents regardless of whether .Fl s is specified or not. .Pp Default values, such .Dq 7 for the .Li section , are not set as metadata values, and will not appear if the metadata key is used as a variable. .Pp Differences in additional content metadata are rendered differently than in the document body: deleted metadata key-value pairs are not processed in the output, so only inserted or retained metadata are processed. .Pp In formats where metadata are part of the document body, such as .Fl t Ns Ar term and .Fl t Ns Ar tree , all metadata are shown as if in the document body. .Sh ENVIRONMENT .Bl -tag -width Ds .It Ev NO_COLOR Do not emit colours when in .Fl t Ns Ar term mode. Synonym for .Ev NO_COLOUR . Same as .Fl -term-nocolour . .El .Sh FILES .Bl -tag -width Ds .It Pa share/odt/styles.xml Default styles used when generating standalone .Fl t Ns Ar fodt documents. Template for .Fl -odt-style styles. .El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES To view Markdown differences on an ANSI-compatible, UTF-8 terminal: .Pp .Dl lowdown-diff -tterm old.md new.md | less -R .Pp The terminal may also be used with .Xr groff 1 rendering: .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e groff -itk -mspdf -Tutf8 | less -R lowdown-diff -stman old.md new.md | \e groff -itk -man -Tutf8 | less -R .Ed .Pp To emit a standalone HTML5 document: .Pp .Dl lowdown-diff -s old.md new.md > foo.html .Pp To use .Xr groff 1 to format as a PS file: .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e groff -itk -mspdf > foo.ps .Ed .Pp Or with LaTeX: .Bd -literal -offset indent lowdown-diff -stlatex old.md new.md > foo.latex pslatex foo.latex .Ed .Pp PDF generation follows similar logic: .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e pdfroff -itk -mspdf > foo.pdf lowdown-diff -stlatex old.md new.md > foo.latex pdflatex foo.latex .Ed .Pp UTF-8 support for .Xr groff 1 PDF or PS output requires appropriate fonts, such as the Unicode Times font. This and other Unicode fonts are not always installed by default. They may be found, for PDF output, in the .Pa devpdf set of the .Xr groff 1 font directory and are prefixed with .Sq U . .Bd -literal -offset indent lowdown-diff -stms old.md new.md | \e pdfroff -itk -mspdf -FU-T > foo.pdf .Ed .Sh SEE ALSO .Xr lowdown 1 , .Xr lowdown 3 , .Xr lowdown 5 .Sh AUTHORS .Nm was written by .An Kristaps Dzonsons , .Mt kristaps@bsd.lv . .Sh CAVEATS When viewing .Fl t Ns Ar man differences with .Xr mandoc 1 , the marker colours are not rendered. The .Fl t Ns Ar gemini output also currently has no way of encoding differences. lowdown-1.1.0/man/lowdown.1010064400017500001750000000446741452256251200160760ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate$ .Dt LOWDOWN 1 .Os .Sh NAME .Nm lowdown .Nd simple markdown translator .Sh SYNOPSIS .Nm lowdown .Op input_options .Op output_options .Op Fl Ls .Op Fl M Ar metadata .Op Fl m Ar metadata .Op Fl o Ar file .Op Fl t Ar mode .Op Fl X Ar keyword .Op Ar file .Sh DESCRIPTION Translate from .Xr lowdown 5 into diverse output formats. Results are written to standard output. .Pp The arguments are as follows: .Bl -tag -width Ds .It Fl L Lists metadata keys, one key per line. The .Fl t mode is ignored. Metadata is automatically enabled. Unsets .Fl X . .It Fl s Standalone mode. This emits a document envelope surrounding the output by drawing from document metadata. See .Sx Metadata on providing information to the document envelope. This applies to .Fl t Ns Ar gemini , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar ms , .Fl t Ns Ar man , and .Fl t Ns Ar fodt . .It Fl M Ar metadata Provide a single metadata key-value pair. This may be in the syntax specified by .Xr lowdodwn 5 or as pairs separated by an equal sign, depending upon which character (a colon or equal sign) comes first. Exits with an error if given neither colon nor equal sign. May be invoked multiple times for each pair. This overrides .Fl m and what's parsed from the document. .It Fl m Ar metadata Like .Fl M , but is overridden by what's parsed the document, then .Fl M . .It Fl o Ar file Send output to .Ar file unless it's .Dq - , in which case fall back to the default of standard output. .It Fl t Ar mode , Fl T Ar mode The output mode. This may be .Ar html for HTML5 output, .Ar latex for LaTeX, .Ar gemini for the Gemini format, .Ar ms for roff output using the classic (i.e., no-extension) .Fl ms package and needing table support, .Ar term for ANSI-compatible UTF-8 terminal output, .Ar man for roff output using the classic .Fl man package, .Ar tree , to show the parse tree of the input document, and .Ar null to parse the document but do no rendering. See .Sx Output modes . The .Fl T Ar mode form is retained for backward compatibility. .It Fl X Ar keyword Output the metadata value of .Ar keyword or an empty string if not found. The .Fl t mode is ignored. Metadata is automatically enabled. Unsets .Fl L . .It Ar file Input Markdown document. If not given or if .Ar file is .Dq - , it is read from standard input. .El .Pp The following are options for input parsing. These affect the parse tree passed to all outputs. .Bl -tag -width Ds .It Fl -parse-hilite Enable highlight span support. This are disabled by default because it may be erroneously interpreted as section headers. .It Fl -parse-math Recognise mathematics equations. .It Fl -parse-maxdepth=depth The maximum depth of nested elements. This defaults to 128, which is probably more than enough for any real-world document. If the maximum is hit, the system exits as if memory were exhausted. Set to zero for no maximum. .It Fl -parse-no-autolink Do not parse .Li http , .Li https , .Li ftp , .Li mailto , and relative links or link fragments. .It Fl -parse-no-cmark Do not parse with CommonMark constraints. This also disables using the first ordered list value instead of starting all lists at one. .It Fl -parse-no-codeindent Do not parse indented content as code blocks. .It Fl -parse-no-callouts Do not parse GFM/MDN callouts .Pq Qq admonitions . .It Fl -parse-no-deflists Do not parse PHP extra definition lists. .It Fl -parse-no-ext-attrs Do not parse PHP extra extended attributes. .It Fl -parse-no-fenced Do not parse GFM fenced (language-specific) code blocks. .It Fl -parse-no-footnotes Do not parse MMD footnotes. .It Fl -parse-no-img-ext Deprecated. See .Fl -parse-no-ext-attrs . .It Fl -parse-no-intraemph Do not parse emphasis within words and links. .It Fl -parse-no-mantitle Do not parse manpage title, section, source, and volume from Pandoc title metadata. Manpages titles are indicated by a title then an open parenthesis, digit followed by optional characters, then a closed parenthesis. .It Fl -parse-no-metadata Do not parse metadata. This does not affect metadata given on .Fl m or .Fl M . .It Fl -parse-no-strike Do not parse strikethroughs. .It Fl -parse-no-super Do not parse super-scripts or sub-scripts at all. .It Fl -parse-no-tables Do not parse GFM tables. .It Fl -parse-no-tasklists Do not parse GFM task lists. .It Fl -parse-super-short If super-script parsing is enabled, use the traditional non-GFM .Qq short syntax. .El .Pp There are many output options. The following are shared by all output modes: .Bl -tag -width Ds .It Fl -out-standalone Alias for .Fl s . .It Fl -out-no-smarty Do not use the smart typography filter. By default, certain character sequences are translated into output-specific glyphs. .El .Pp What follows are per-output options. For HTML with .Fl t Ns Ar html , these are as follows: .Bl -tag -width Ds .It Fl -html-callout-mdn , -html-callout-gfm Output either or both MDN or GFM callout syntaxes. .It Fl -html-hardwrap Hard-wrap paragraph content by outputting line breaks where applicable. .It Fl -html-no-escapehtml If .Fl -html-no-skiphtml has been specified, this causes embedded HTML not to be escaped, and is instead output verbatim. This has no effect if .Fl -html-no-skiphtml has not been specified. .It Fl -html-no-head-ids Do not output .Li id attributes for headers. .It Fl -html-no-num-ent Don't normalise HTML entities (when possible) as numeric ones and instead use the entities as given on input. .It Fl -html-no-owasp Don't follow the OWASP recommendations for escaping text, and do only the minimal escaping to make sure that regular content isn't interpreted as HTML. .It Fl -html-no-skiphtml Output embedded HTML. By default, embedded HTML is not output at all. See .Fl -html-no-escapehtml . .El .Pp For both .Fl t Ns Ar man and .Fl t Ns Ar ms , the following apply: .Bl -tag -width Ds .It Fl -nroff-code-font Ns = Ns Ar fonts Override the default constant-width fonts with a tuple of regular, bold, italic, and bold-italic variants in that order. For example, .Li B,B,BI,BI uses bold .Pq Qq B instead of a constant-width. Not specifying a font will use the default, as will specifying a zero-length font name. Aliases .Li none , .Li bold , and .Li code set no special fonts, bold, and the default constant-width. .It Fl -nroff-no-groff Don't use .Xr groff 1 style section headings, PDF hyperlinks and multi-page tables (these further require .Fl t Ns Ar ms mode and .Fl m Ns Ar spdf passed to .Xr groff 1 ) , or Unicode sequence syntax. The output is compatible with traditional .Xr troff 1 . .It Fl -nroff-no-numbered Don't output numbered headings. Only applies to .Fl t Ns Ar ms . .It Fl -nroff-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted. .It Fl -nroff-nolinks Don't show URLs for images and links (autolinks are still shown). .Pq Link content is still shown. Overrides .Fl -nroff-shortlinks for images and links. Applies to .Fl t Ns Ar man or when .Fl nroff-no-groff is specified. .It Fl -nroff-shortlinks Shorten URLs for images, links, and autolinks to only the domain name and final path. Applies to .Fl t Ns Ar man or when .Fl nroff-no-groff is specified. .El .Pp The .Fl t Ns Ar term output has the following: .Bl -tag -width Ds .It Fl -term-all-metadata If .Fl s is specified, output all metadata instead of just the title, author, and date. .It Fl -term-columns=columns The number of columns in the screen. Useful for when running in a pipe. Defaults to what the terminal reports or 72 if in a pipe. .It Fl -term-hmargin=margin The number of left margin spaces. Truncated to the number of columns. Defaults to zero. .It Fl -term-no-ansi Don't show ANSI styles at all. This implies .Fl -term-no-colour . .It Fl -term-no-colour Don't show ANSI colours. This will still decorate text with underlines, bolds, and italics, but not emit any colour codes. .It Fl -term-nolinks Don't show URLs for images and links (autolinks are still shown). .Pq Link content is still shown. Overrides .Fl -term-shortlinks for images and links. .It Fl -term-shortlinks Shorten URLs for images, links, and autolinks to only the domain name and final path. .It Fl -term-vmargin=margin The number of top and bottom margin newlines. Defaults to zero. .It Fl -term-width=width Set the soft limit on the number of characters per line. This may be exceeded by literal text. The default (or if zero) is the number of terminal columns or 80 at most. .El .Pp The .Fl t Ns Ar gemini output has several flags that control the placement of links. By default, links (images, autolinks, and links) are queued when specified in-line then emitted in a block sequence after the nearest block element. .Bl -tag -width Ds .It Fl -gemini-link-end Emit the queue of links at the end of the document instead of after the nearest block element. .It Fl -gemini-link-inline Render all links within the flow of text. This will cause breakage when nested links, such as images within links, links in blockquotes, etc. It should not be used unless in carefully crafted documents. .It Fl -gemini-link-noref Do not format link labels. Takes precedence over .Fl -gemini-link-roman . .It Fl -gemini-link-roman When formatting link labels, use lower-case Roman numerals instead of the default lower-case hexavigesimal (i.e., .Dq a , .Dq b , \&..., .Dq aa , .Dq ab , \&...). .It Fl -gemini-metadata Print metadata as the canonicalised key followed by a colon then the value, each on one line (newlines replaced by spaces). The metadata block is terminated by a double newline. If there is no metadata, this does nothing. .El .Pp The .Fl t Ns Ar latex output has the following options: .Bl -tag -width Ds .It Fl -latex-no-numbered Don't number sections (and subsections, etc.). .It Fl -latex-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted. .El .Pp The .Fl t Ns Ar fodt output has the following options: .Bl -tag -width Ds .It Fl -odt-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted. .It Fl -odt-style Ns = Ns Ar file Specify an OpenDocument style file, which must consist of at least .Li , .Li , and .Li XML elements in the root of the document. This is not syntax-checked in any way. .El .Ss Output modes The output media is specified by .Fl t , which defaults to .Fl t Ns Ar html . .Bl -tag -width Ds .It Fl t Ns Ar fodt .Dq Flat OpenDocument output. Automatic styles (those conditional upon document state) are generated with output. Classes specified by PHP extended attributes are not checked for existence. .It Fl t Ns Ar gemini Gemini protocol output. This output mode is experimental. .It Fl t Ns Ar html HTML5 output with UTF-8 encoding. .It Fl t Ns Ar latex Simple LaTeX output. The following packages are required: .Li amsmath and .Li amssymb for maths, .Li graphicx for images, .Li inputenc Pq utf8 for UTF-8 input, .Li fontend Pq T1 and .Li textcomp for output glyphs, .Li lmodern for Latin modern font, .Li xcolor for the difference engine output, and .Li hyperref for links. .It Fl t Ns Ar man The .Ar man macro package suitable for reading by .Xr groff 1 , .Xr mandoc 1 , or traditional .Xr troff 1 . Does not support equations and images. Table support is provided by .Xr tbl 1 . Since UTF-8 may be passed as input values, .Xr preconv 1 may need to be used. .It Fl t Ns Ar ms The .Ar ms macro package suitable for reading by .Xr groff 1 or traditional .Xr troff 1 . Does not support equations and limited image support for encapsulated postscript (PS and EPS suffix) images. Images are always block-formatted. Image dimensions and extended attributes are ignored, though images are downsized if larger than the current text width. Table support is provided by .Xr tbl 1 . Since UTF-8 may be passed as input values, .Xr preconv 1 may need to be used. .It Fl t Ns Ar term ANSI-escaped UTF-8 output suitable for reading on the terminal. Images and equations not supported. .It Fl t Ns Ar tree Debugging output: not for general use. .El .Ss Standalone documents When .Fl s is specified, additional content may be added to output: .Bl -tag -width Ds .It Fl t Ns Ar fodt Envelope .Li and prologue .Li , .Li , and .Li . .It Fl t Ns Ar html Envelope .Li and prologue .Li . .It Fl t Ns Ar latex Prologue .Li documentclass and .Li usepackage statements, and surrounding .Li begin{document} statements. .It Fl t Ns Ar man , Fl t Ns Ar ms Prologue macros. .It Fl t Ns Ar term Prologue lines. .El .Pp If parsed from the document or as given by .Fl m or .Fl M , the following metadata keys are used by additional content. The metadata keys are canonicalised in lowercase and without spaces. .Pp Metadata values should not be encoded in their output format, e.g., .Dq css: foo&bar . The renderer will perform any necessary output encoding. .Bl -tag -width Ds .It Li affiliation Author affiliation (organisation or institution). Multiple affiliations may be separated by two or more spaces (including newlines). Used in .Fl t Ns Ar html , .Fl t Ns Ar latex , and .Fl t Ns Ar ms . .It Li author Document author. Multiple authors may be separated by two or more spaces (including newlines). Overridden by .Li rcsauthor . Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar ms , and .Fl t Ns Ar term . .It Li baseheaderlevel Added to each header level. Deprecated in favour of .Li shiftheadinglevelby . .It Li copyright A document copyright (without the word .Dq Copyright ) , for example, .Dq 2017, Kristaps Dzonsons . Used in .Fl t Ns Ar ms and .Fl t Ns Ar html . .It Li css A CSS file included in the HTML5 document head. Multiple CSS files (in order) may be separated by two or more spaces (including newlines). Only used in .Fl t Ns Ar html . .It Li date Document date in ISO-8601 YYYY-MM-DD format. Overridden by .Li rcsdate . Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar ms , and .Fl t Ns Ar term . .It Li javascript A JavaScript file included in the HTML5 document head. Multiple script files (in order) may be separated by two or more spaces (including newlines). Only used in .Fl t Ns Ar html . .It Li lang Document language in RFC 5646 format. Only used in .Fl t Ns Ar html . .It Li rcsauthor Like .Li author , but in RCS author format. Overrides .Li author . .It Li rcsdate Like .Li date , but in RCS date format. Overrides .Li date . .It Li section Man page section, defaulting to .Dq 7 . Only used in .Fl t Ns Ar man . .It Li shiftheadinglevelby Shift all headers by the given number. For example, a value of 1 causes headers originally at level 1 .Pq Dq

to be level 2 .Pq Dq

, while a value of -1 moves level 2 to 1. Levels will not move to less than 1. Takes precedence over .Li baseheaderlevel . If unset or not a valid number, defaults to zero. Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , and .Fl t Ns Ar ms . .It Li source Man page source (organisation providing the manual). Only used in .Fl t Ns Ar man . .It Li volume Man page volume (describes the manual page section). Only used in .Fl t Ns Ar man . .It Li title Document title. Used in .Fl t Ns Ar fodt , .Fl t Ns Ar html , .Fl t Ns Ar latex , .Fl t Ns Ar man , .Fl t Ns Ar ms , and .Fl t Ns Ar term . .El .Pp Metadata values are parsed and may be used as variables in markdown documents regardless of whether .Fl s is specified or not. .Pp Default values, such .Dq 7 for the .Li section , are not set as metadata values, and will not appear if the metadata key is used as a variable. .Sh ENVIRONMENT .Bl -tag -width Ds .It Ev NO_COLOR Do not emit colours when in .Fl t Ns Ar term mode. Synonym for .Ev NO_COLOUR . Same as .Fl -term-nocolour . .El .Sh FILES .Bl -tag -width Ds .It Pa share/odt/styles.xml Default styles used when generating standalone .Fl t Ns Ar fodt documents. Template for .Fl -odt-style styles. .El .Sh EXIT STATUS .Ex -std .Pp If the .Fl X flag is used, .Nm lowdown exits with an error if the given keyword is not found. .Sh EXAMPLES To view a Markdown file on an ANSI-compatible, UTF-8 terminal: .Pp .Dl lowdown -tterm foo.md | less -R .Pp The terminal may also be used with .Xr groff 1 or .Xr mandoc 1 rendering: .Bd -literal -offset indent lowdown -stms foo.md | groff -itk -mspdf -Tutf8 | less -R lowdown -stman foo.md | groff -itk -man -Tutf8 | less -R lowdown -stman foo.md | mandoc | less .Ed .Pp To emit a standalone HTML5 document: .Pp .Dl lowdown -s foo.md > foo.html .Pp To use .Xr groff 1 or .Xr mandoc 1 to format as a PS file: .Bd -literal -offset indent lowdown -stms foo.md | groff -itk -mspdf > foo.ps lowdown -stman foo.md | mandoc -Tps > foo.ps .Ed .Pp Or with LaTeX: .Bd -literal -offset indent lowdown -stlatex foo.md > foo.latex pslatex foo.latex .Ed .Pp PDF generation follows similar logic: .Bd -literal -offset indent lowdown -stms foo.md | pdfroff -itk -mspdf > foo.pdf lowdown -stman foo.md | mandoc -Tpdf > foo.pdf lowdown -stlatex foo.md > foo.latex pdflatex foo.latex .Ed .Pp UTF-8 support for .Xr groff 1 PDF or PS output requires appropriate fonts, such as the Unicode Times font. This and other Unicode fonts are not always installed by default. They may be found, for PDF output, in the .Pa devpdf set of the .Xr groff 1 font directory and are prefixed with .Sq U . .Bd -literal -offset indent lowdown -stms foo.md | pdfroff -itk -mspdf -FU-T > foo.pdf .Ed .Pp To list all metadata keys, then to extract the .Qq title metadata value from .Pa foo.md : .Pp .Dl lowdown -L foo.md .Dl lowdown -X title foo.md .Sh SEE ALSO .Xr lowdown-diff 1 , .Xr lowdown 3 , .Xr lowdown 5 .Sh AUTHORS .Nm lowdown was forked from .Lk https://github.com/hoedown/hoedown hoedown by .An Kristaps Dzonsons , .Mt kristaps@bsd.lv . It has been considerably modified since. lowdown-1.1.0/man/lowdown.3010064400017500001750000000632011452256251200160630ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate$ .Dt LOWDOWN 3 .Os .Sh NAME .Nm lowdown .Nd simple markdown translator library .Sh LIBRARY .Lb liblowdown .Sh SYNOPSIS .In sys/queue.h .In stdio.h .In lowdown.h .Vt "struct lowdown_meta" .Vt "struct lowdown_node" .Vt "struct lowdown_opts" .Sh DESCRIPTION This library parses .Xr lowdown 5 into various output formats. .Pp The library consists first of a high-level interface consisting of .Xr lowdown_buf 3 , .Xr lowdown_buf_diff 3 , .Xr lowdown_file 3 , and .Xr lowdown_file_diff 3 . .Pp The high-level functions interface with low-level functions that perform parsing and formatting. These consist of .Xr lowdown_doc_new 3 , .Xr lowdown_doc_parse 3 , and .Xr lowdown_doc_free 3 for parsing .Xr lowdown 5 documents into an abstract syntax tree. .Pp The front-end functions for freeing, allocation, and rendering are as follows. .Bl -bullet .It HTML5: .Bl -item -compact .It .Xr lowdown_html_free 3 .It .Xr lowdown_html_new 3 .It .Xr lowdown_html_rndr 3 .El .It gemini: .Bl -item -compact .It .Xr lowdown_gemini_free 3 .It .Xr lowdown_gemini_new 3 .It .Xr lowdown_gemini_rndr 3 .El .It LaTeX: .Bl -item -compact .It .Xr lowdown_latex_free 3 .It .Xr lowdown_latex_new 3 .It .Xr lowdown_latex_rndr 3 .El .It OpenDocument: .Bl -item -compact .It .Xr lowdown_odt_free 3 .It .Xr lowdown_odt_new 3 .It .Xr lowdown_odt_rndr 3 .El .It roff: .Bl -item -compact .It .Xr lowdown_nroff_free 3 .It .Xr lowdown_nroff_new 3 .It .Xr lowdown_nroff_rndr 3 .El .It UTF-8 ANSI terminal: .Bl -item -compact .It .Xr lowdown_term_free 3 .It .Xr lowdown_term_new 3 .It .Xr lowdown_term_rndr 3 .El .It debugging: .Bl -item -compact .It .Xr lowdown_tree_rndr 3 .El .El .Pp To compile and link, use .Xr pkg-config 1 : .Bd -literal % cc `pkg-config --cflags lowdown` -c -o sample.o sample.c % cc -o sample sample.o `pkg-config --libs lowdown` .Ed .Ss Pledge Promises The .Nm lowdown library is built to operate in security-sensitive environments, such as those using .Xr pledge 2 on .Ox . The only promise required is .Va stdio for .Xr lowdown_file_diff 3 and .Xr lowdown_file 3 : both require access to the stream for reading input. .Sh TYPES All .Nm lowdown functions use one or more of the following structures. .Pp The main structure for configuring parsing and output is .Vt struct lowdown_opts . It has the following fields: .Bl -tag -width Ds .It Va enum lowdown_type type The output medium: .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_HTML HTML5 .It Dv LOWDOWN_LATEX LaTeX .It Dv LOWDOWN_MAN roff .Fl m Ns Ar an macros .It Dv LOWDOWN_FODT .Dq flat OpenDocument .It Dv LOWDOWN_TERM ANSI-compatible UTF-8 terminal output .It Dv LOWDOWN_GEMINI Gemini format .It Dv LOWDOWN_NROFF roff .Fl m Ns Ar s macros .It Dv LOWDOWN_TREE syntax tree (debugging) .El .It Va unsigned int feat Parse-time features. This bit-field may have the following bits OR'd: .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_ATTRS Parse PHP extra link, header, and image attributes. .It Dv LOWDOWN_AUTOLINK Parse .Li http , .Li https , .Li ftp , .Li mailto , and relative links or link fragments. .It Dv LOWDOWN_CALLOUTS Parse MDN/GFM callouts .Pq Dq admonitions . .It Dv LOWDOWN_COMMONMARK Tighten input parsing to the CommonMark specification. This also uses the first ordered list value instead of starting all lists at one. This feature is .Em experimental and .Em incomplete . .It Dv LOWDOWN_DEFLIST Parse PHP extra definition lists. This is currently constrained to single-key lists. .It Dv LOWDOWN_FENCED Parse GFM fenced (language-specific) code blocks. .It Dv LOWDOWN_FOOTNOTES Parse MMD style footnotes. This only supports the referenced footnote style, not the .Dq inline style. .It Dv LOWDOWN_HILITE Parse highlit sequences. This are disabled by default because it may be erroneously interpreted as section headers. .It Dv LOWDOWN_IMG_EXT Deprecated. Use .Dv LOWDOWN_ATTRS instead. .It Dv LOWDOWN_MANTITLE Recognise manpage titles in Pandoc metadata title lines. Only applicable if .Dv LOWDOWN_METADATA is also provided. Manpages titles must begin with a non-empty title followed by an open parenthesis, digit or .Dq n , optional letters after, then a closing parenthesis. This may be optionally followed by a source and, if a vertical bar is detected, the content after as the volume. These are passed to the renderers as the .Li title , .Li volume , and optionally .Li source and .Li volume metadata key-value pairs. The original title is not recoverable. .It Dv LOWDOWN_MATH Parse mathematics equations. .It Dv LOWDOWN_METADATA Parse in-document metadata. .It Dv LOWDOWN_NOCODEIND Do not parse indented content as code blocks. .It Dv LOWDOWN_NOINTEM Do not parse emphasis within words. .It Dv LOWDOWN_STRIKE Parse strikethrough sequences. .It Dv LOWDOWN_SUPER Parse super-scripts. This accepts foo^bar^ GFM super-scripts. .It Dv LOWDOWN_SUPER_SHORT If .Dv LOWDOWN_SUPER is enabled, instead of the GFM style, accept the .Dq short form of superscript. 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. .It Dv LOWDOWN_TABLES Parse GFM tables. .It Dv LOWDOWN_TASKLIST Parse GFM task list items. .El .It Va unsigned int oflags Output-time features. Bit values are specific to the .Va type and are not guaranteed to be globally unique. .Pp For all types: .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_SMARTY Don't use smart typography formatting. .It Dv LOWDOWN_STANDALONE Emit a full document instead of a document fragment. This envelope is largely populated from metadata if .Dv LOWDOWN_METADATA was provided as an option or as given in .Va meta or .Va metaovr . .El .Pp For .Dv LOWDOWN_HTML : .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_HTML_CALLOUT_MDN , LOWDOWN_HTML_CALLOUT_GFM Output MDN and/or GFM-style callout syntax. .It Dv LOWDOWN_HTML_ESCAPE If .Dv LOWDOWN_HTML_SKIP_HTML has not been set, escapes in-document HTML so that it is rendered as opaque text. .It Dv LOWDOWN_HTML_HARD_WRAP Retain line-breaks within paragraphs. .It Dv LOWDOWN_HTML_HEAD_IDS Have an identifier written with each header element consisting of an HTML-escaped version of the header contents. .It Dv LOWDOWN_HTML_NUM_ENT Convert, when possible, HTML entities to their numeric form. If not set, the entities are used as given in the input. .It Dv LOWDOWN_HTML_OWASP When escaping text, be extra paranoid in following the OWASP suggestions for which characters to escape. .It Dv LOWDOWN_HTML_SKIP_HTML Do not render in-document HTML at all. .It Dv LOWDOWN_HTML_TITLEBLOCK If used with .Dv LOWDOWN_STANDALONE , output a Pandoc-style title block. This is a .Li
element right after the opening .Li containing elements for specified title, author(s), and date. These are .Li

and .Li

elements, respectively, with classes set to what's being output (title, etc.). At least one of these must be specified for the title block to be output. .El .Pp For .Dv 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 node. (See .Sx ABSTRACT SYNTAX TREE . ) .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_GEMINI_LINK_END Emit the queue of links at the end of the document instead of after the nearest block node. .It Dv LOWDOWN_GEMINI_LINK_IN Render all links within the flow of text. This will cause breakage when nested links, such as images within links, links in blockquotes, etc. It should not be used unless in carefully crafted documents. .It Dv LOWDOWN_GEMINI_LINK_NOREF Do not format link labels. Takes precedence over .Dv LOWDOWN_GEMINI_LINK_ROMAN . .It Dv LOWDOWN_GEMINI_LINK_ROMAN When formatting link labels, use lower-case Roman numerals instead of the default lowercase hexavigesimal (i.e., .Dq a , .Dq b , \&..., .Dq aa , .Dq ab , \&...). .It Dv LOWDOWN_GEMINI_METADATA Print metadata as the canonicalised key followed by a colon then the value, each on one line (newlines replaced by spaces). The metadata block is terminated by a double newline. If there is no metadata, this does nothing. .El .Pp There may only be one of .Dv LOWDOWN_GEMINI_LINK_END or .Dv LOWDOWN_GEMINI_LINK_IN . If both are specified, the latter is unset. .Pp For .Dv LOWDOWN_FODT : .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_ODT_SKIP_HTML Do not render in-document HTML at all. Text within HTML elements remains. .El .Pp For .Dv LOWDOWN_LATEX : .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_LATEX_NUMBERED Use the default numbering scheme for sections, subsections, etc. If not specified, these are inhibited. .It Dv LOWDOWN_LATEX_SKIP_HTML Do not render in-document HTML at all. Text within HTML elements remains. .El .Pp For .Dv LOWDOWN_MAN and .Dv LOWDOWN_NROFF : .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_NROFF_GROFF Use GNU extensions (i.e., for .Xr groff 1 ) when rendering output. The groff arguments must include .Fl m Ns Ar pdfmark for formatting links with .Dv LOWDOWN_MAN or .Fl m Ns Ar spdf instead of .Fl m Ns Ar s for .Dv LOWDOWN_NROFF . Applies to the .Dv LOWDOWN_MAN and .Dv LOWDOWN_NROFF output types. .It Dv LOWDOWN_NROFF_NOLINK Don't show links at all if they have embedded text. Applies to images and regular links. Only in .Dv LOWDOWN_MAN or when .Dv LOWDOWN_NROFF_GROFF is not specified. .It Dv LOWDOWN_NROFF_NUMBERED Use numbered sections if .Dv LOWDOWON_NROFF_GROFF is not specified. Only applies to the .Dv LOWDOWN_NROFF output type. .It Dv LOWDOWN_NROFF_SHORTLINK Render link URLs in short form. Applies to images, autolinks, and regular links. Only in .Dv LOWDOWN_MAN or when .Dv LOWDOWN_NROFF_GROFF is not specified. .It Dv LOWDOWN_NROFF_SKIP_HTML Do not render in-document HTML at all. Text within HTML elements remains. .El .Pp For .Dv LOWDOWN_TERM : .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_TERM_ALL_META If .Dv LOWDOWN_STANDALONE is specified, output all metadata instead of just the title, author, and date. .It Dv LOWDOWN_TERM_NOANSI Don't apply ANSI style codes at all. This implies .Dv LOWDOWN_TERM_NOCOLOUR . .It Dv LOWDOWN_TERM_NOCOLOUR Don't apply ANSI colour codes. This will still show underline, bold, etc. This should not be used in difference mode, as the output will make no sense. .It Dv LOWDOWN_TERM_NOLINK Don't show links at all. Applies to images and regular links: autolinks are still shown. This may be combined with .Dv LOWDOWN_TERM_SHORTLINK to also shorten autolinks. .It Dv LOWDOWN_TERM_SHORTLINK Render link URLs in short form. Applies to images, autolinks, and regular links. This may be combined with .Dv LOWDOWN_TERM_NOLINK to only show shortened autolinks. .El .It Va size_t maxdepth The maximum parse depth before the parser exits. Most documents will have a parse depth in the single digits. .It Va size_t cols For .Dv LOWDOWN_TERM , the .Dq soft limit for width of terminal output not including margins. If zero, 80 shall be used. .It Va size_t hmargin For .Dv LOWDOWN_TERM , the left margin (space characters). .It Va size_t vmargin For .Dv LOWDOWN_TERM , the top/bottom margin (newlines). .It Va struct lowdown_opts_nroff nroff If .Va type is .Dv LOWDOWN_MAN or .Dv LOWDOWN_NROFF , this contains constant-width font variants: .Vt "const char *cr" for roman constant-width, .Vt "const char *cb" for bold, .Vt "const char *ci" for italic, and .Vt "const char *cbi" for bold-italic. If any of these are .Dv NULL , they default to their constant-width variants. .It Va struct lowdown_opts_odt odt If .Va type is .Dv LOWDOWN_FODT , this contains .Vt "const char *sty" , which is either .Dv NULL or the OpenDocument styles used when creating standalone documents. If .Dv NULL , the default styles are used. .It Va char **meta An array of metadata key-value pairs or .Dv NULL . Each pair must appear as if provided on one line (or multiple lines) of the input, including the terminating newline character. If not consisting of a valid pair (e.g., no newline, no colon), then it is ignored. When processed, these values are overridden by those in the document (if .Dv LOWDOWN_METADATA is specified) or by those in .Va metaovr . .It Va size_t metasz Number of pairs in .Va metaovr . .It Va char **metaovr See .Va meta . The difference is that .Va metaovr is applied after .Va meta and in-document metadata, so it overrides prior values. .It Va size_t metaovrsz Number of pairs in .Va metaovr . .El .Pp Parsed metadata is held in key-value .Vt "struct lowdown_meta" pairs, or collectively as .Va "struct lowdown_metaq" , if .Dv LOWDOWN_METADATA is set in .Va feat . The former structure consists of the following fields: .Bl -tag -width Ds .It Va char *key The metadata key in its canonical form: lowercase alphanumerics, hyphen, and underscore. Whitespace is removed and other characters replaced by a question mark. .It Va char *value The metadata value. This may be an empty string. .El .Pp The abstract syntax tree is encoded in .Vt struct lowdown_node , which consists of the following. .Bl -tag -width Ds .It Va enum lowdown_rndrt type The node type, using HTML5 output as an illustration: .Pp .Bl -tag -width Ds -compact .It Dv LOWDOWN_BLOCKCODE A block-level snippet of code described by .Li 

 .
.It Dv LOWDOWN_BLOCKHTML
A block-level snippet of HTML.
This is simply opaque HTML content.
.It Dv LOWDOWN_BLOCKQUOTE
A block-level quotation described by
.Li 
 .
.It Dv LOWDOWN_CODESPAN
An inline-level snippet of code described by
.Li  .
.It Dv LOWDOWN_DEFINITION
A definition list described by
.Li 
 .
.It Dv LOWDOWN_DEFINITION_DATA
Definition data described by
.Li 
 .
.It Dv LOWDOWN_DEFINITION_TITLE
Definition title described by
.Li 
 .
.It Dv LOWDOWN_DOC_HEADER
Container for metadata described by
.Li  .
.It Dv LOWDOWN_DOUBLE_EMPHASIS
Bold (or otherwise notable) content described by
.Li  .
.It Dv LOWDOWN_EMPHASIS
Italic (or otherwise notable) content described by
.Li  .
.It Dv LOWDOWN_ENTITY
Named or numeric HTML entity.
.It Dv LOWDOWN_FOOTNOTE
Footnote content.
.It Dv LOWDOWN_HEADER
A block-level header described by one of
.Li 

through
.Li 
 .
.It Dv LOWDOWN_HIGHLIGHT
Marked test described by
.Li  .
.It Dv LOWDOWN_HRULE
A horizontal line described by
.Li 
 .
.It Dv LOWDOWN_IMAGE
An image described by
.Li  .
.It Dv LOWDOWN_LINEBREAK
A hard line-break within a block context described by
.Li 
 .
.It Dv LOWDOWN_LINK
A link to external media described by
.Li  .
.It Dv LOWDOWN_LINK_AUTO
Like
.Dv LOWDOWN_LINK ,
except inferred from text content.
.It Dv LOWDOWN_LIST
A list enclosure described by
.Li 
    
or
.Li 
       .
.It Dv LOWDOWN_LISTITEM
A list item described by
.Li 
    1.  .
.It Dv LOWDOWN_MATH_BLOCK
A snippet of mathematical text in LaTeX format described within
.Li \e[xx\e]
or
.Li \e(xx\e) .
This is usually (in HTML) externally handled by a JavaScript renderer.
.It Dv LOWDOWN_META
Meta-data keys and values.
These are described by elements in
.Li  .
.It Dv LOWDOWN_NORMAL_TEXT
Normal text content.
.It Dv LOWDOWN_PARAGRAPH
A block-level paragraph described by
.Li 
       .
.It Dv LOWDOWN_RAW_HTML
An inline of raw HTML.
(Only if configured during parse.)
.It Dv LOWDOWN_ROOT
The root of the document.
This is always the topmost node, and the only node where the
.Va parent
field is
.Dv NULL .
.It Dv LOWDOWN_STRIKETHROUGH
Content struck through.
Described by
.Li  .
.It Dv LOWDOWN_SUBSCRIPT , Dv LOWDOWN_SUPERSCRIPT
A subscript or superscript described by
.Li 
or
.Li  ,
respectively.
.It Dv LOWDOWN_TABLE_BLOCK
A table block described by
.Li  .
.It Dv LOWDOWN_TABLE_BODY
A table body section described by
.Li  .
.It Dv LOWDOWN_TABLE_CELL
A table cell described by
.Li  .
.It Dv LOWDOWN_TABLE_ROW
A table row described by
.Li  .
.It Dv LOWDOWN_TRIPLE_EMPHASIS
Combination of
.Dv LOWDOWN_EMPHASIS
and
.Dv LOWDOWN_DOUBLE_EMPHASIS .
.El
.It Va size_t id
An identifier unique within the document.
This can be used as a table index since the number is assigned from a
monotonically increasing point during the parse.
.It Va struct lowdown_node *parent
The parent of the node, or
.Dv NULL
at the root.
.It Va enum lowdown_chng chng
Change tracking: whether this node was inserted
.Pq Dv LOWDOWN_CHNG_INSERT ,
deleted
.Pq Dv LOWDOWN_CHNG_DELETE ,
or neither
.Pq Dv LOWDOWN_CHNG_NONE .
.It Va struct lowdown_nodeq children
A possibly-empty list of child nodes.
.It Va 
An anonymous union of type-specific structures.
.Pp
.Bl -tag -width Ds -compact
.It Va rndr_autolink
For
.Dv LOWDOWN_LINK_AUTO ,
the link address as
.Va link
and the link type
.Va type ,
which may be one of
.Dv HALINK_EMAIL
for e-mail links and
.Dv HALINK_NORMAL
otherwise.
Any buffer may be empty-sized.
.It Va rndr_blockcode
For
.Dv LOWDOWN_BLOCKCODE ,
the opaque
.Va text
of the block and the optional
.Va lang
of the code language.
.It Va rndr_blockhtml
For
.Dv LOWDOWN_BLOCKHTML ,
the opaque HTML
.Va text .
.It Va rndr_codespan
The opaque
.Va text
of the contents.
.It Va rndr_definition
For
.Dv LOWDOWN_DEFINITION ,
containing
.Va flags
that may be
.Dv HLIST_FL_BLOCK
if the definition list should be interpreted as containing block
nodes.
.It Va rndr_entity
For
.Dv LOWDOWN_ENTITY ,
the entity
.Va text .
.It Va rndr_header
For
.Dv LOWDOWN_HEADER ,
the
.Va level
of the header starting at zero (this value is relative to the metadata
base header level, defaulting to one), optional space-separated class
list
.Va attr_cls ,
and optional single identifier
.Va attr_id .
.It Va rndr_image
For
.Dv LOWDOWN_IMAGE ,
the image address
.Va link ,
the image title
.Va title ,
dimensions NxN (width by height) in
.Va dims ,
and alternate text
.Va alt .
CSS in-line style for width and height may be given in
.Va attr_width
and/or
.Va attr_height ,
and a space-separated list of classes may be in
.Va attr_cls
and a single identifier may be in
.Va attr_id .
.It Va rndr_link
Like
.Va rndr_autolink ,
but without a type and further defining an optional link title
.Va title ,
optional space-separated class list
.Va attr_cls ,
and optional single identifier
.Va attr_id .
.It Va rndr_list
For
.Dv LOWDOWN_LIST ,
consists of a bitfield
.Va flags
that may be set to
.Dv HLIST_FL_ORDERED
for an ordered list and
.Dv HLIST_FL_UNORDERED
for an unordered one.
If
.Dv HLIST_FL_BLOCK
is set, the list should be output as if items were separate blocks.
The
.Va start
value for
.Dv HLIST_FL_ORDERED
is the starting list item position, which is one by default and never
zero.
The
.Va items
is the number of list items.
.It Va rndr_listitem
For
.Dv LOWDOWN_LISTITEM ,
consists of a bitfield
.Va flags
that may be set to
.Dv HLIST_FL_ORDERED
for an ordered list,
.Dv HLIST_FL_UNORDERED
for an unordered list,
.Dv HLIST_FL_DEF
for definition list data,
.Dv HLIST_FL_CHECKED
or
.Dv HLIST_FL_UNCHECKED
for an unordered
.Dq task
list, and/or
.Dv HLIST_FL_BLOCK
for list item output as if containing block nodes.
The
.Dv HLIST_FL_BLOCK
should not be used: use the parent list (or definition list) flags for
this.
The
.Va num
is the index in a
.Dv HLIST_FL_ORDERED
list.
It is monotonically increasing with each item in the list, starting at
the
.Va start
variable given in
.Vt struct rndr_list .
.It Va rndr_math
For
.Dv LOWDOWN_MATH ,
the mode of display in
.Va blockmode :
if 1, in-line math; if 2, multi-line.
The opaque equation, which is assumed to be in LaTeX format, is in the
opaque
.Va text .
.It Va rndr_meta
Each
.Dv LOWDOWN_META
key-value pair is represented.
The keys are lower-case without spaces or non-ASCII characters.
If provided, enclosed nodes may consist only of
.Dv LOWDOWN_NORMAL_TEXT
and
.Dv LOWDOWN_ENTITY .
.It Va rndr_normal_text
The basic
.Va text
content for
.Dv LOWDOWN_NORMAL_TEXT .
If
.Va flags
is set to
.Dv HTEXT_ESCAPED ,
the text may be escaped for output, but may not be altered by any smart
typography or similar (it should be passed as-is).
.It Va rndr_paragraph
For
.Dv LOWDOWN_PARAGRAPH ,
species how many
.Va lines
the paragraph has in the input file and
.Va beoln ,
set to non-zero if the paragraph ends with an empty line instead of a
breaking block node.
.It Va rndr_raw_html
For
.Dv LOWDOWN_RAW_HTML ,
the opaque HTML
.Va text .
.It Va rndr_table
For
.Dv LOWDOWN_TABLE_BLOCK ,
the number of
.Va columns
in each row or header row.
The number of columns in
.Va rndr_table ,
.Va rndr_table_header ,
and
.Va rndr_table_cell
are the same.
.It Va rndr_table_cell
For
.Dv LOWDOWN_TABLE_CELL ,
the current
.Va col
column number out of
.Va columns .
See
.Va rndr_table_header
for a description of the bits in
.Va flags .
The number of columns in
.Va rndr_table ,
.Va rndr_table_header ,
and
.Va rndr_table_cell
are the same.
.It Va rndr_table_header
For
.Dv LOWDOWN_TABLE_HEADER ,
the number of
.Va columns
in each row and the per-column
.Va flags ,
which may tested for equality against
.Dv HTBL_FL_ALIGN_LEFT ,
.Dv HTBL_FL_ALIGN_RIGHT ,
or
.Dv HTBL_FL_ALIGN_CENTER
after being masked with
.Dv HTBL_FL_ALIGNMASK ;
or
.Dv HTBL_FL_HEADER .
If no alignment is specified after the mask, the default should be
left-aligned.
The number of columns in
.Va rndr_table ,
.Va rndr_table_header ,
and
.Va rndr_table_cell
are the same.
.El
.El
.Sh ABSTRACT SYNTAX TREE
A parsed document is a tree of
.Vt struct lowdown_node
nodes.
If a node is
.Dq block ,
it may contain other block or inline nodes.
If
.Dq inline,
it may only contain other inline nodes.
.Dq Special
nodes are documented below.
An additional mark of
.Dq void
means that the node will never contain children.
.Pp
.Bl -column "LOWDOWN_DEFINITION_TITLE" "special, void" -offset indent -compact
.It Node Ta Scope
.It Dv LOWDOWN_BLOCKCODE Ta block, void
.It Dv LOWDOWN_BLOCKHTML Ta block, void
.It Dv LOWDOWN_BLOCKQUOTE Ta block
.It Dv LOWDOWN_CODESPAN Ta inline, void
.It Dv LOWDOWN_DEFINITION Ta block
.It Dv LOWDOWN_DEFINITION_DATA Ta special
.It Dv LOWDOWN_DEFINITION_TITLE Ta special
.It Dv LOWDOWN_DOC_HEADER Ta special
.It Dv LOWDOWN_DOUBLE_EMPHASIS Ta inline
.It Dv LOWDOWN_EMPHASIS Ta inline
.It Dv LOWDOWN_ENTITY Ta inline, void
.It Dv LOWDOWN_FOOTNOTE Ta block, special
.It Dv LOWDOWN_HEADER Ta block
.It Dv LOWDOWN_HRULE Ta inline, void
.It Dv LOWDOWN_IMAGE Ta inline, void
.It Dv LOWDOWN_LINEBREAK Ta inline, void
.It Dv LOWDOWN_LINK Ta inline
.It Dv LOWDOWN_LINK_AUTO Ta inline, void
.It Dv LOWDOWN_LIST Ta block
.It Dv LOWDOWN_LISTITEM Ta special
.It Dv LOWDOWN_MATH_BLOCK Ta inline, void
.It Dv LOWDOWN_META Ta special
.It Dv LOWDOWN_NORMAL_TEXT Ta inline, void
.It Dv LOWDOWN_PARAGRAPH Ta block
.It Dv LOWDOWN_RAW_HTML Ta inline, void
.It Dv LOWDOWN_ROOT Ta special
.It Dv LOWDOWN_STRIKETHROUGH Ta inline
.It Dv LOWDOWN_SUBSCRIPT Ta inline
.It Dv LOWDOWN_SUPERSCRIPT Ta inline
.It Dv LOWDOWN_TABLE_BLOCK Ta block
.It Dv LOWDOWN_TABLE_BODY Ta special
.It Dv LOWDOWN_TABLE_CELL Ta special
.It Dv LOWDOWN_TABLE_HEADER Ta special
.It Dv LOWDOWN_TABLE_ROW Ta special
.It Dv LOWDOWN_TRIPLE_EMPHASIS Ta inline
.El
.Pp
The general structure of the AST is as follows.
Nodes have no order imposed on them unless as noted:
.Pp
.Bl -dash -compact
.It
.Dv LOWDOWN_ROOT
.Pq ordered
.Bl -dash -compact
.It
.Dv LOWDOWN_DOC_HEADER
.Bl -dash -compact
.It
.Dv LOWDOWN_META
.Bl -dash -compact
.It
.Dv LOWDOWN_ENTITY
.It
.Dv LOWDOWN_NORMAL_TEXT
.El
.El
.It
.Pq zero or more block nodes
.El
.El
.Pp
Special nodes have specific placement within their parents as follows:
.Bl -dash
.It
.Dv LOWDOWN_DEFINITION
.Pq one or more ordered pairs of...
.Bl -dash -compact
.It
.Dv LOWDOWN_DEFINITION_TITLE
.Bl -dash -compact
.It
.Pq inline nodes
.El
.It
.Dv LOWDOWN_DEFINITION_DATA
.Bl -dash -compact
.It
.Pq block nodes
.El
.El
.It
.Dv LOWDOWN_HEADER
.Bl -dash -compact
.It
.Pq inline nodes
.El
.It
.Dv LOWDOWN_LIST
.Bl -dash -compact
.It
.Dv LOWDOWN_LISTITEM
.Bl -dash -compact
.It
.Pq inline or block nodes, depending
.El
.El
.It
.Dv LOWDOWN_TABLE_BLOCK
.Pq ordered
.Bl -dash -compact
.It
.Dv LOWDOWN_TABLE_HEADER
.Pq zero or more...
.Bl -dash -compact
.It
.Dv LOWDOWN_TABLE_ROW
.Pq one or more...
.Bl -dash -compact
.It
.Dv LOWDOWN_TABLE_CELL
.Bl -dash -compact
.It
.Pq inline nodes
.El
.El
.El
.It
.Dv LOWDOWN_TABLE_BODY
.Pq zero or more...
.Bl -dash -compact
.It
.Dv LOWDOWN_TABLE_ROW
.Pq one or more...
.Bl -dash -compact
.It
.Dv LOWDOWN_TABLE_CELL
.Bl -dash -compact
.It
.Pq inline nodes
.El
.El
.El
.El
.El
.Pp
Lastly,
.Dv LOWDOWN_FOOTNOTE
may appear anywhere in the document and contains block nodes.
.Sh SEE ALSO
.Xr lowdown 1 ,
.Xr lowdown_buf 3 ,
.Xr lowdown_buf_diff 3 ,
.Xr lowdown_diff 3 ,
.Xr lowdown_doc_free 3 ,
.Xr lowdown_doc_new 3 ,
.Xr lowdown_doc_parse 3 ,
.Xr lowdown_file 3 ,
.Xr lowdown_file_diff 3 ,
.Xr lowdown_gemini_free 3 ,
.Xr lowdown_gemini_new 3 ,
.Xr lowdown_gemini_rndr 3 ,
.Xr lowdown_html_free 3 ,
.Xr lowdown_html_new 3 ,
.Xr lowdown_html_rndr 3 ,
.Xr lowdown_latex_free 3 ,
.Xr lowdown_latex_new 3 ,
.Xr lowdown_latex_rndr 3 ,
.Xr lowdown_metaq_free 3 ,
.Xr lowdown_nroff_free 3 ,
.Xr lowdown_nroff_new 3 ,
.Xr lowdown_nroff_rndr 3 ,
.Xr lowdown_odt_free 3 ,
.Xr lowdown_odt_new 3 ,
.Xr lowdown_odt_rndr 3 ,
.Xr lowdown_term_free 3 ,
.Xr lowdown_term_new 3 ,
.Xr lowdown_term_rndr 3 ,
.Xr lowdown_tree_rndr 3 ,
.Xr lowdown 5
.Sh AUTHORS
.Nm lowdown
was forked from
.Lk https://github.com/hoedown/hoedown hoedown
by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .
It has been considerably modified since.
lowdown-1.1.0/man/lowdown_buf.3010064400017500001750000000057431452256251200167260ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_BUF 3
.Os
.Sh NAME
.Nm lowdown_buf
.Nd parse a Markdown buffer into formatted output
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_buf
.Fa "const struct lowdown_opts *opts"
.Fa "const char *buf"
.Fa "size_t bufsz"
.Fa "char **ret"
.Fa "size_t *retsz"
.Fa "struct lowdown_metaq *metaq"
.Fc
.Sh DESCRIPTION
Parses a
.Xr lowdown 5
buffer
.Fa buf
of size
.Fa bufsz
into an output buffer
.Fa ret
of size
.Fa retsz
according to a configuration
.Fa opts .
The output format is specified by
.Fa opts->type .
If
.Dv LOWDOWN_METADATA
is set in
.Fa opts->feat
and
.Fa metaq
is not
.Dv NULL ,
.Fa metaq
is filled with metadata rendered in the given output format.
.Pp
The caller is responsible for freeing
.Fa ret
and
.Fa metaq .
.Sh RETURN VALUES
Returns zero on failure, non-zero on success.
On failure, the values pointed to by
.Fa res
and
.Fa rsz
are undefined.
.Sh EXAMPLES
The following parses standard input into a standalone HTML5 document.
It enables footnotes, autolinks, tables, superscript, strikethrough,
fenced codeblocks, commonmark, definition lists, extended image
attributes, and metadata processing.
The output passes through raw HTML and has smart typography.
.Bd -literal -offset indent
struct lowdown_opts opts;
char *buf = NULL, *obuf;
char rbuf[1024];
size_t sz, bufsz = 0, obufsz;

while (!(feof(stdin) || ferror(stdin))) {
	sz = fread(rbuf, 1, sizeof(rbuf), stdin);
	if (sz == 0)
		err(1, "fread");
	buf = realloc(buf, bufsz + sz);
	if (buf == NULL)
		err(1, NULL);
	memcpy(buf + bufsz, rbuf, sz);
	bufsz += sz;
}

if (ferror(stdin))
	err(1, "fread");

memset(&opts, 0, sizeof(struct lowdown_opts));
opts.type = LOWDOWN_HTML;
opts.feat = LOWDOWN_FOOTNOTES |
	LOWDOWN_AUTOLINK |
	LOWDOWN_TABLES |
	LOWDOWN_SUPER |
	LOWDOWN_STRIKE |
	LOWDOWN_FENCED |
	LOWDOWN_COMMONMARK |
	LOWDOWN_DEFLIST |
	LOWDOWN_IMG_EXT |
	LOWDOWN_METADATA;
opts.oflags = LOWDOWN_HTML_HEAD_IDS |
	LOWDOWN_HTML_NUM_ENT |
	LOWDOWN_HTML_OWASP |
	LOWDOWN_SMARTY |
	LOWDOWN_STANDALONE;
if (!lowdown_buf(&opts, buf, bufsz, &obuf, &obufsz, NULL))
	errx(1, "lowdown_buf");
fwrite(buf, 1, bufsz, stdout);
free(buf);
free(obuf);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_metaq_free 3
lowdown-1.1.0/man/lowdown_buf_diff.3010064400017500001750000000032231452256251200177050ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_BUF_DIFF 3
.Os
.Sh NAME
.Nm lowdown_buf
.Nd parse and diff Markdown buffers into formatted output
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_buf_diff
.Fa "const struct lowdown_opts *opts"
.Fa "const char *new"
.Fa "size_t newsz"
.Fa "const char *old"
.Fa "size_t oldsz"
.Fa "char **ret"
.Fa "size_t *retsz"
.Fc
.Sh DESCRIPTION
Parses
.Xr lowdown 5
buffers
.Fa new
of size
.Fa newsz
and
.Fa old
of size
.Fa oldsz
and produces an edit script in
.Fa ret
of size
.Fa retsz
according to configurations
.Fa opts .
The script defines differences from
.Fa old
to
.Fa new .
The output format is specified by
.Fa opts->type .
.Pp
The caller is responsible for freeing
.Fa ret .
.Sh RETURN VALUES
Returns zero on failure, non-zero on success.
Failure occurs from memory exhaustion.
.Sh SEE ALSO
.Xr lowdown 3
lowdown-1.1.0/man/lowdown_buf_free.3010064400017500001750000000023061452256251200177170ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_BUF_FREE 3
.Os
.Sh NAME
.Nm lowdown_buf_free
.Nd free a dynamic buffer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_buf_free
.Fa "struct lowdown_buf *buf"
.Fc
.Sh DESCRIPTION
Frees a dynamic buffer created with
.Xr lowdown_buf_new 3 .
If
.Va buf
is
.Dv NULL ,
the function does nothing.
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_buf_new 3
lowdown-1.1.0/man/lowdown_buf_new.3010064400017500001750000000024541452256251200175730ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_BUF_NEW 3
.Os
.Sh NAME
.Nm lowdown_buf_new
.Nd allocate a dynamic buffer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft struct lowdown_buf *
.Fo lowdown_buf_new
.Fa "size_t growsz"
.Fc
.Sh DESCRIPTION
Allocates a dynamic buffer that grows in increments of size
.Fa growsz ,
which may not be zero.
.Sh RETURN VALUES
Returns a pointer to a buffer or
.Dv NULL
on memory failure.
The pointer must be freed with
.Xr lowdown_buf_free 3 .
.Sh SEE ALSO
.Xr lowdown 3
lowdown-1.1.0/man/lowdown_diff.3010064400017500001750000000061121452256251200170510ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_DIFF 3
.Os
.Sh NAME
.Nm lowdown_diff
.Nd compute difference between parsed Markdown trees
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft "struct lowdown_node *"
.Fo lowdown_diff
.Fa "const struct lowdown_node *nold"
.Fa "const struct lowdown_node *nnew"
.Fa "size_t *maxn"
.Fc
.Sh DESCRIPTION
Computes the difference between two Markdown trees, the source
.Fa nold
and destination
.Fa nnew ,
parsed by
.Xr lowdown_doc_parse 3 .
It uses the
.Vt enum lowdown_chng
type in the return tree's nodes to dictate insertions into and deletions
from
.Fa nold .
The
.Fa maxn
argument, if not
.Dv NULL ,
is set to one greater than the highest node identifier of the returned
tree.
.Sh RETURN VALUES
Returns a pointer to the difference tree or
.Dv NULL
on memory exhaution.
The pointer must be freed with
.Xr lowdown_node_free 3 .
.Sh EXAMPLES
The following parses and compares
.Va old
of length
.Va osz
and
.Va new
of length
.Va nsz .
It first allocates the parser, then the document, then the renderer
(HTML is used in this case).
Then it passes output to the renderer, prints it, and cleans up
resources.
On any memory errors, it exits with
.Xr err 3 .
.Bd -literal -offset indent
struct lowdown_doc *doc;
struct lowdown_node *no, *nn, *diff;
struct lowdown_buf *ob;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((no = lowdown_doc_parse(doc, NULL, old, osz, NULL)) == NULL)
	err(1, NULL);
if ((nn = lowdown_doc_parse(doc, NULL, new, nsz, NULL)) == NULL)
	err(1, NULL);
if ((diff = lowdown_diff(no, nn, NULL)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_html_new(NULL)) == NULL)
	err(1, NULL);
if ((ob = lowdown_buf_new(1024)) == NULL)
	err(1, NULL);
if (!lowdown_html_rndr(ob, rndr, diff))
	err(1, NULL);

fwrite(stdout, 1, ob->size, ob->data);

lowdown_buf_free(ob);
lowdown_html_rndr_free(rndr);
lowdown_node_free(no);
lowdown_node_free(nn);
lowdown_node_free(diff);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3
.Rs
.%A Gregory Cobena
.%A Serge Abiteboul
.%A Amelie Marian
.%D 2002
.%T "Detecting Changes in XML Documents"
.%U https://www.cs.rutgers.edu/~amelie/papers/2002/diff.pdf
.Re
.Rs
.%A Wu Sun
.%A Manber Udi
.%A Myers Gene
.%T "An O(NP) sequence comparison algorithm"
.%J Information Processing Letters
.%V Volume 35
.%I Issue 6
.%D 1990
.Re
lowdown-1.1.0/man/lowdown_doc_free.3010064400017500001750000000023101452256251200177030ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_DOC_FREE 3
.Os
.Sh NAME
.Nm lowdown_doc_free
.Nd free a Markdown parser instance
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_doc_free
.Fa "struct lowdown_doc *doc"
.Fc
.Sh DESCRIPTION
Frees a parser created with
.Xr lowdown_doc_new 3 .
If
.Va doc
is
.Dv NULL ,
the function does nothing.
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_doc_new 3
lowdown-1.1.0/man/lowdown_doc_new.3010064400017500001750000000041151452256251200175600ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_DOC_NEW 3
.Os
.Sh NAME
.Nm lowdown_doc_new
.Nd allocate a Markdown parser
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft struct lowdown_doc *
.Fo lowdown_doc_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates a Markdown parser instance with configuration
.Fa opts .
If
.Fa opts
is
.Dv NULL ,
all values are assumed to be zero except for the maximum parse depth,
which is fixed at 128.
.Pp
The returned instance may be used with multiple invocations of
.Xr lowdown_doc_parse 3 .
.Sh RETURN VALUES
Returns a pointer to the parser or
.Dv NULL
on memory allocation failure.
The returned pointer must be freed with a call to
.Xr lowdown_doc_free 3 .
.Pp
Any pointer values in
.Fa opts ,
such as those in
.Va meta
and
.Va metaovr ,
are copied over, so they need not persist after being passed to
.Fn lowdown_doc_new .
.Sh EXAMPLES
The following parses
.Va b
if length
.Va bsz
and throws away the result.
.Bd -literal -offset indent
struct lowdown_doc *doc;
struct lowdown_node *n;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);

lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_doc_free 3 ,
.Xr lowdown_doc_parse 3
lowdown-1.1.0/man/lowdown_doc_parse.3010064400017500001750000000053471452256251200201110ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_DOC_PARSE 3
.Os
.Sh NAME
.Nm lowdown_doc_parse
.Nd parse a Markdown document into an AST
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft "struct lowdown_node *"
.Fo lowdown_doc_parse
.Fa "struct lowdown_doc *doc"
.Fa "size_t *maxn"
.Fa "const char *input"
.Fa "size_t inputsz"
.Fa "struct lowdown_metaq *metaq"
.Fc
.Sh DESCRIPTION
Parse a
.Xr lowdown 5
document
.Fa input
of length
.Fa inputsz
into an AST with the parser
.Fa doc .
The
.Fa maxn
argument, if not
.Dv NULL ,
is set to one greater than the highest node identifier.
Its value is undefined if the function returns
.Dv NULL .
.Pp
If
.Fa metaq
is not
.Dv NULL ,
it is filled in with document metadata (if any).
Metadata key names are canonicalised and duplicate names are ignored.
The results should be freed with
.Xr lowdown_metaq_free 3 .
.Pp
This function may be invoked multiple times with a single
.Fa doc
and different input.
.Sh RETURN VALUES
Returns the root of the parse tree or
.Dv NULL
on memory allocation failure.
If not
.Dv NULL ,
the returned node is always of type
.Dv LOWDOWN_ROOT .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz .
It first allocates the parser, then the document, then the renderer
(HTML is used in this case).
Then it passes output to the renderer, prints it, and cleans up
resources.
On any memory errors, it exits with
.Xr err 3 .
.Bd -literal -offset indent
struct lowdown_doc *doc;
struct lowdown_node *n;
struct lowdown_buf *ob;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_html_new(NULL)) == NULL)
	err(1, NULL);
if ((ob = lowdown_buf_new(1024)) == NULL)
	err(1, NULL);
if (!lowdown_html_rndr(ob, rndr, n))
	err(1, NULL);

fwrite(stdout, 1, ob->size, ob->data);

lowdown_buf_free(ob);
lowdown_html_rndr_free(rndr);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3
lowdown-1.1.0/man/lowdown_file.3010064400017500001750000000051661452256251200170700ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_FILE 3
.Os
.Sh NAME
.Nm lowdown_file
.Nd parse a Markdown file into formatted output
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_file
.Fa "const struct lowdown_opts *opts"
.Fa "FILE *in"
.Fa "char **ret"
.Fa "size_t *retsz"
.Fa "struct lowdown_metaq *metaq"
.Fc
.Sh DESCRIPTION
Parses a
.Xr lowdown 5
file stream
.Fa in
into an output buffer
.Fa ret
of size
.Fa retsz
according to configuration
.Fa opts .
The output format is specified by
.Fa opts->type .
If
.Dv LOWDOWN_METADATA
is set in
.Fa opts->feat
and
.Fa metaq
is not
.Dv NULL ,
.Fa metaq
is filled with metadata rendered in the given output format.
.Pp
On success, the caller is responsible for freeing
.Fa ret
and
.Fa metaq .
.Sh RETURN VALUES
Returns zero on failure, non-zero on success.
On failure, the values pointed to by
.Fa res
and
.Fa rsz
are undefined.
.Sh EXAMPLES
The following parses standard input into a standalone HTML5 document.
It enables footnotes, autolinks, tables, superscript, strikethrough,
fenced codeblocks, commonmark, definition lists, extended image
attributes, and metadata processing.
The output passes through raw HTML and has smart typography.
.Bd -literal -offset indent
struct lowdown_opts opts;
char *buf;
size_t bufsz;

memset(&opts, 0, sizeof(struct lowdown_opts));
opts.type = LOWDOWN_HTML;
opts.feat = LOWDOWN_FOOTNOTES |
	LOWDOWN_AUTOLINK |
	LOWDOWN_TABLES |
	LOWDOWN_SUPER |
	LOWDOWN_STRIKE |
	LOWDOWN_FENCED |
	LOWDOWN_COMMONMARK |
	LOWDOWN_DEFLIST |
	LOWDOWN_IMG_EXT |
	LOWDOWN_METADATA;
opts.oflags = LOWDOWN_HTML_HEAD_IDS |
	LOWDOWN_HTML_NUM_ENT |
	LOWDOWN_HTML_OWASP |
	LOWDOWN_SMARTY |
	LOWDOWN_STANDALONE;
if (!lowdown_file(&opts, stdin, &buf, &bufsz, NULL))
	errx(1, "lowdown_file");
fwrite(buf, 1, bufsz, stdout);
free(buf);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_metaq_free 3
lowdown-1.1.0/man/lowdown_file_diff.3010064400017500001750000000031731452256251200200540ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_FILE_DIFF 3
.Os
.Sh NAME
.Nm lowdown_file_diff
.Nd parse and diff Markdown files into formatted output
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_file_diff
.Fa "const struct lowdown_opts *opts"
.Fa "FILE *fnew"
.Fa "FILE *fold"
.Fa "char **ret"
.Fa "size_t *retsz"
.Fc
.Sh DESCRIPTION
Parses
.Xr lowdown 5
file streams
.Fa fnew
and
.Fa fold
and produces an edit script in
.Fa ret
of size
.Fa retsz
according to configurations
.Fa opts .
The output format is specified by
.Fa opts->type .
.Pp
On success, the caller is responsible for freeing
.Fa ret .
.Sh RETURN VALUES
Returns zero on failure, non-zero on success.
Failure occurs when the file read failed or on memory exhaustion.
On failure, the contents of
.Fa ret
and
.Fa retsz
are undefined.
.Sh SEE ALSO
.Xr lowdown 3
lowdown-1.1.0/man/lowdown_gemini_free.3010064400017500001750000000041161452256251200204140ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_GEMINI_FREE 3
.Os
.Sh NAME
.Nm lowdown_gemini_free
.Nd free a Markdown gemini renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_gemini_free
.Fa "void *arg"
.Fc
.Sh DESCRIPTION
Frees the gemini renderer created with
.Xr lowdown_gemini_new 3 .
If
.Va arg
is
.Dv NULL ,
the function does nothing.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in Gemini format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if (setlocale(LC_CTYPE, "en_US.UTF-8") == NULL)
	err(1, NULL);
if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_gemini_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_gemini_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_gemini_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_gemini_new 3
.Sh STANDARDS
The gemini format is documented in
.Lk https://gemini.circumlunar.space/docs/specification.html Project Gemini .
The version at the time of writing is 0.14.3.
lowdown-1.1.0/man/lowdown_gemini_new.3010064400017500001750000000052251452256251200202660ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_GEMINI_NEW 3
.Os
.Sh NAME
.Nm lowdown_gemini_new
.Nd allocate a Markdown gemini renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void *
.Fo lowdown_gemini_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates a Gemini renderer using
.Fa opts->oflags ,
or zero if
.Fa opts
is
.Dv NULL .
The returned pointer may be used with multiple invocations of
.Xr lowdown_gemini_rndr 3
and must be freed with
.Xr lowdown_gemini_free 3 .
.Pp
The bits recognised in
.Fa opts->oflags
are
.Dv LOWDOWN_GEMINI_LINK_IN ,
.Dv LOWDOWN_GEMINI_LINK_END ,
.Dv LOWDOWN_GEMINI_LINK_NOREF ,
.Dv LOWDOWN_GEMINI_LINK_ROMAN ,
.Dv LOWDOWN_GEMINI_METADATA ,
and
.Dv LOWDOWN_STANDALONE .
These are documented in
.Xr lowdown 3 .
.Sh RETURN VALUES
Returns a pointer to the renderer or
.Dv NULL
on memory failure.
The returned pointer must be freed with
.Xr lowdown_gemini_free 3 .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in Gemini format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if (setlocale(LC_CTYPE, "en_US.UTF-8") == NULL)
	err(1, NULL);
if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_gemini_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_gemini_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_gemini_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_gemini_free 3 ,
.Xr lowdown_gemini_rndr 3
.Sh STANDARDS
The gemini format is documented in
.Lk https://gemini.circumlunar.space/docs/specification.html Project Gemini .
The version at the time of writing is 0.14.3.
lowdown-1.1.0/man/lowdown_gemini_rndr.3010064400017500001750000000051421452256251200204400ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_GEMINI_RNDR 3
.Os
.Sh NAME
.Nm lowdown_gemini_rndr
.Nd render Markdown into gemini
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_gemini_rndr
.Fa "struct lowdown_buf *out"
.Fa "void *arg"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3
using the gemini renderer
.Fa arg
as returned by
.Xr lowdown_gemini_new 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Pp
The caller is expected to have invoked
.Xr setlocale 3
to a
.Qq UTF-8
character encoding prior to using this function, otherwise UTF-8
sequences will not be properly recognised.
This is used when formatting table column widths.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in Gemini format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if (setlocale(LC_CTYPE, "en_US.UTF-8") == NULL)
	err(1, NULL);
if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_gemini_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_gemini_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_gemini_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_gemini_free 3 ,
.Xr lowdown_gemini_new 3
.Sh STANDARDS
The gemini format is documented in
.Lk https://gemini.circumlunar.space/docs/specification.html Project Gemini .
The version at the time of writing is 0.14.3.
lowdown-1.1.0/man/lowdown_html_free.3010064400017500001750000000037271452256251200201170ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_HTML_FREE 3
.Os
.Sh NAME
.Nm lowdown_html_free
.Nd free a Markdown HTML renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_html_free
.Fa "void *arg"
.Fc
.Sh DESCRIPTION
Frees the HTML renderer created with
.Xr lowdown_html_new 3 .
If
.Va arg
is
.Dv NULL ,
the function does nothing.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in HTML format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_html_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_html_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_html_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_html_new 3
.Sh STANDARDS
The referenced HTML5 standard is
.Lk https://www.w3.org/TR/html52 HTML5.2 .
Output is compatible with prior HTML5 standards.
lowdown-1.1.0/man/lowdown_html_new.3010064400017500001750000000051461452256251200177640ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_HTML_NEW 3
.Os
.Sh NAME
.Nm lowdown_html_new
.Nd allocate a Markdown HTML renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void *
.Fo lowdown_html_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates an HTML5 renderer using
.Fa opts->flags ,
or zero if
.Fa opts
is
.Dv NULL .
This field is documented in
.Xr lowdown 3 .
The returned pointer may be used with multiple invocations of
.Xr lowdown_html_rndr 3
and must be freed with
.Xr lowdown_html_free 3 .
.Pp
The bits recognised in
.Fa opts->oflags
are
.Dv LOWDOWN_HTML_OWASP ,
.Dv LOWDOWN_HTML_NUM_ENT ,
.Dv LOWDOWN_HTML_HEAD_IDS ,
.Dv LOWDOWN_HTML_HARD_WRAP ,
.Dv LOWDOWN_HTML_SKIP_HTML ,
.Dv LOWDOWN_HTML_ESCAPE ,
.Dv LOWDOWN_HTML_CALLOUT_MDN ,
.Dv LOWDOWN_HTML_CALLOUT_GFM ,
and
.Dv LOWDOWN_STANDALONE .
.Sh RETURN VALUES
Returns a pointer to the renderer or
.Dv NULL
on memory failure.
The returned pointer must be freed with
.Xr lowdown_html_free 3 .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in HTML format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_html_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_html_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_html_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_html_free 3 ,
.Xr lowdown_html_rndr 3
.Sh STANDARDS
The referenced HTML5 standard is
.Lk https://www.w3.org/TR/html52 HTML5.2 .
Output is compatible with prior HTML5 standards.
lowdown-1.1.0/man/lowdown_html_rndr.3010064400017500001750000000044641452256251200201420ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_HTML_RNDR 3
.Os
.Sh NAME
.Nm lowdown_html_rndr
.Nd render Markdown into HTML
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_html_rndr
.Fa "struct lowdown_buf *out"
.Fa "void *arg"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3
using the HTML renderer
.Fa arg
as returned by
.Xr lowdown_html_new 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Pp
The output consists of a UTF-8 HTML5 document.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in HTML format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_html_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_html_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_html_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_html_free 3 ,
.Xr lowdown_html_new 3
.Sh STANDARDS
The referenced HTML5 standard is
.Lk https://www.w3.org/TR/html52 HTML5.2 .
Output is compatible with prior HTML5 standards.
lowdown-1.1.0/man/lowdown_latex_free.3010064400017500001750000000035271452256251200202660ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_LATEX_FREE 3
.Os
.Sh NAME
.Nm lowdown_latex_free
.Nd free a Markdown LaTeX renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_latex_free
.Fa "void *arg"
.Fc
.Sh DESCRIPTION
Frees the LaTeX renderer created with
.Xr lowdown_latex_new 3 .
If
.Va arg
is
.Dv NULL ,
the function does nothing.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in LaTeX format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_latex_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_latex_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_latex_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_latex_new 3
lowdown-1.1.0/man/lowdown_latex_new.3010064400017500001750000000045011452256251200201270ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_LATEX_NEW 3
.Os
.Sh NAME
.Nm lowdown_latex_new
.Nd allocate a Markdown LaTeX renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void *
.Fo lowdown_latex_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates an LaTeX renderer using
.Fa opts->flags ,
or zero if
.Fa opts
is
.Dv NULL .
This field is documented in
.Xr lowdown 3 .
The returned pointer may be used with multiple invocations of
.Xr lowdown_latex_rndr 3
and must be freed with
.Xr lowdown_latex_free 3 .
.Pp
The bits recognised in
.Fa opts->oflags
are
.Dv LOWDOWN_LATEX_NUMBERED ,
.Dv LOWDOWN_LATEX_SKIP_HTML ,
and
.Dv LOWDOWN_STANDALONE .
.Sh RETURN VALUES
Returns a pointer to the renderer or
.Dv NULL
on memory failure.
The returned pointer must be freed with
.Xr lowdown_latex_free 3 .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in LaTeX format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_latex_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_latex_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_latex_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_latex_free 3 ,
.Xr lowdown_latex_rndr 3
lowdown-1.1.0/man/lowdown_latex_rndr.3010064400017500001750000000042021452256251200203010ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_LATEX_RNDR 3
.Os
.Sh NAME
.Nm lowdown_latex_rndr
.Nd render Markdown into LaTeX
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_latex_rndr
.Fa "struct lowdown_buf *out"
.Fa "void *arg"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3
using the LaTeX renderer
.Fa arg
as returned by
.Xr lowdown_latex_new 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in LaTeX format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_latex_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_latex_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_latex_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_latex_free 3 ,
.Xr lowdown_latex_new 3
lowdown-1.1.0/man/lowdown_metaq_free.3010064400017500001750000000025211452256251200202510ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_METAQ_FREE 3
.Os
.Sh NAME
.Nm lowdown_metaq_free
.Nd free rendered metadata key-value pairs
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_metaq_free
.Fa "struct lowdown_metaq *q"
.Fc
.Sh DESCRIPTION
Frees rendered metadata
.Fa q
as created by
.Xr lowdown_buf 3 ,
.Xr lowdown_buf_diff 3 ,
.Xr lowdown_file 3 ,
.Xr lowdown_file_diff 3 ,
or the low-level rendering functions.
.Pp
If
.Fa q
is
.Dv NULL ,
the function does nothing.
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_doc_new 3
lowdown-1.1.0/man/lowdown_node_free.3010064400017500001750000000024411452256251200200700ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_NODE_FREE 3
.Os
.Sh NAME
.Nm lowdown_node_free
.Nd free a parsed Markdown tree
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_node_free
.Fa "struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Frees a parsed tree
.Fa n
as created with
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3 ,
including all of its descendents.
If
.Fa n
is
.Dv NULL ,
the function does nothing.
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_diff 3 ,
.Xr lowdown_doc_new 3
lowdown-1.1.0/man/lowdown_nroff_free.3010064400017500001750000000043271452256251200202620ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_NROFF_FREE 3
.Os
.Sh NAME
.Nm lowdown_nroff_free
.Nd free a Markdown roff renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_nroff_free
.Fa "void *arg"
.Fc
.Sh DESCRIPTION
Frees the roff renderer created with
.Xr lowdown_nroff_new 3 .
If
.Va arg
is
.Dv NULL ,
the function does nothing.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in
.Xr groff_ms 7
format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_nroff_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_nroff_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_nroff_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_nroff_new 3
.Pp
This uses both the original troff
.Ar man
macros for
.At v7 ,
defined in
.Xr man 7 ,
and the
.Ar man-ext
groff extensions.
Both are implemented in mandoc.
.Pp
The troff
.Ar ms
macros are defined in
.Xr groff_ms 7 ,
with the
.Ar mspdf
groff extensions described in
.Qq Portable Document Format Publishing with GNU Troff
by Keith Marshall.
Neither are implemented in mandoc.
lowdown-1.1.0/man/lowdown_nroff_new.3010064400017500001750000000073061452256251200201320ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_NROFF_NEW 3
.Os
.Sh NAME
.Nm lowdown_nroff_new
.Nd allocate a roff renderer for lowdown documents
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void *
.Fo lowdown_nroff_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates a roff renderer using
.Fa opts->oflags
and
.Fa opts->type ,
or zero and
.Dv LOWDODN_NROFF ,
respectively, if
.Fa opts
is
.Dv NULL .
These are documented in
.Xr lowdown 3 .
The returned pointer may be used with multiple invocations of
.Xr lowdown_nroff_rndr 3
and must be freed with
.Xr lowdown_nroff_free 3 .
.Pp
The bits recognised in
.Fa opts->oflags
are
.Dv LOWDOWN_NROFF_GROFF ,
.Dv LOWDOWN_NROFF_NOLINK ,
.Dv LOWDOWN_NROFF_NUMBERED ,
.Dv LOWDOWN_NROFF_SHORTLINK ,
.Dv LOWDOWN_NROFF_SKIP_HTML ,
and
.Dv LOWDOWN_STANDALONE .
.Pp
The values recognised in
.Fa opts->type
are
.Dv LOWDOWN_MAN
and
.Dv LOWDODN_NROFF :
anything else triggers
.Dv LOWDODN_NROFF .
.Pp
If
.Dv LOWDOWN_NROFF_GROFF
is set in
.Dv LOWDOWN_MAN
mode, macros from the
.Ar man-ext
package as well as the original
.Ar man
are used in output.
These are supported by both groff and mandoc.
If in
.Dv LOWDODN_NROFF
mode, GNU extensions to
.Ar ms
are used along with
.Ar mspdf .
These are only supported by groff.
.Pp
The allocated rendered will use constant-width fonts
.Qq CR
.Pq regular ,
.Qq CB
.Pq bold ,
.Qq CI
.Pq italic ,
and
.Qq CBI
.Pq bold-italic .
Override the defaults with variables in the
.Vt "struct lowdown_opts_nroff"
structure.
.Sh RETURN VALUES
Returns a pointer to the renderer or
.Dv NULL
on memory failure.
The returned pointer must be freed with
.Xr lowdown_nroff_free 3 .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in
.Xr groff_ms 7
format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_nroff_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_nroff_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_nroff_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_nroff_free 3 ,
.Xr lowdown_nroff_rndr 3 ,
.Pp
This uses both the original troff
.Ar man
macros for
.At v7 ,
defined in
.Xr man 7 ,
and the
.Ar man-ext
groff extensions.
Both are implemented in mandoc.
.Pp
The troff
.Ar ms
macros are defined in
.Xr groff_ms 7 ,
with the
.Ar mspdf
groff extensions described in
.Qq Portable Document Format Publishing with GNU Troff
by Keith Marshall.
Neither are implemented in mandoc.
.Sh CAVEATS
The default constant-width fonts may not available for the formatter's
output device (for example, the terminal).
In this case, the formatter may raise a warning and ignore the font.
lowdown-1.1.0/man/lowdown_nroff_rndr.3010064400017500001750000000051251452256251200203030ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_NROFF_RNDR 3
.Os
.Sh NAME
.Nm lowdown_nroff_rndr
.Nd render Markdown into roff
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_nroff_rndr
.Fa "struct lowdown_buf *out"
.Fa "void *arg"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3
using the roff renderer
.Fa arg
as returned by
.Xr lowdown_nroff_new 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Pp
The output consists of roff output using the
.Ar ms
or
.Ar man
macro packages.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in
.Xr groff_ms 7
format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_nroff_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_nroff_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_nroff_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_nroff_free 3 ,
.Xr lowdown_nroff_new 3
.Pp
This uses both the original troff
.Ar man
macros for
.At v7 ,
defined in
.Xr man 7 ,
and the
.Ar man-ext
groff extensions.
Both are implemented in mandoc.
.Pp
The troff
.Ar ms
macros are defined in
.Xr groff_ms 7 ,
with the
.Ar mspdf
groff extensions described in
.Qq Portable Document Format Publishing with GNU Troff
by Keith Marshall.
Neither are implemented in mandoc.
lowdown-1.1.0/man/lowdown_odt_free.3010064400017500001750000000037331452256251200177360ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_ODT_FREE 3
.Os
.Sh NAME
.Nm lowdown_odt_free
.Nd free a Markdown OpenDocument renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_odt_free
.Fa "void *arg"
.Fc
.Sh DESCRIPTION
Frees the OpenDocument renderer created with
.Xr lowdown_odt_new 3 .
If
.Va arg
is
.Dv NULL ,
the function does nothing.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in
.Dq flat
OpenDocument format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_odt_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_odt_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_odt_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_odt_new 3
.Sh STANDARDS
The referenced OpenDocument standard is
.Lk https://docs.oasis-open.org/office/OpenDocument/v1.3/ 1.3 .
lowdown-1.1.0/man/lowdown_odt_new.3010064400017500001750000000051261452256251200176040ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_ODT_NEW 3
.Os
.Sh NAME
.Nm lowdown_odt_new
.Nd allocate a Markdown OpenDocument renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void *
.Fo lowdown_odt_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates an OpenDocument renderer using
.Fa opts->flags ,
or zero if
.Fa opts
is
.Dv NULL .
This field is documented in
.Xr lowdown 3 .
The returned pointer may be used with multiple invocations of
.Xr lowdown_odt_rndr 3
and must be freed with
.Xr lowdown_odt_free 3 .
.Pp
The bits recognised in
.Fa opts->oflags
are
.Dv LOWDOWN_ODT_SKIP_HTML
and
.Dv LOWDOWN_STANDALONE .
.Pp
The
.Fa opts->odt.sty
field, if not
.Dv NULL ,
overrides the default
.Li  ,
.Li  ,
and
.Li 
elements of the document styles.
.Sh RETURN VALUES
Returns a pointer to the renderer or
.Dv NULL
on memory failure.
The returned pointer must be freed with
.Xr lowdown_odt_free 3 .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in
.Dq flat
OpenDocument format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_odt_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_odt_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_odt_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_odt_free 3 ,
.Xr lowdown_odt_rndr 3
.Sh STANDARDS
The referenced OpenDocument standard is
.Lk https://docs.oasis-open.org/office/OpenDocument/v1.3/ 1.3 .
lowdown-1.1.0/man/lowdown_odt_rndr.3010064400017500001750000000044711452256251200177620ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_ODT_RNDR 3
.Os
.Sh NAME
.Nm lowdown_odt_rndr
.Nd render Markdown into OpenDocument
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_odt_rndr
.Fa "struct lowdown_buf *out"
.Fa "void *arg"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3
using the OpenDocument renderer
.Fa arg
as returned by
.Xr lowdown_odt_new 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Pp
The output consists of an OpenDocument document.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in
.Dq flat
OpenDocument format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_odt_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_odt_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_odt_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_odt_free 3 ,
.Xr lowdown_odt_new 3
.Sh STANDARDS
The referenced OpenDocument standard is
.Lk https://docs.oasis-open.org/office/OpenDocument/v1.3/ 1.3 .
lowdown-1.1.0/man/lowdown_term_free.3010064400017500001750000000037611452256251200201200ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_TERM_FREE 3
.Os
.Sh NAME
.Nm lowdown_term_free
.Nd free an Markdown terminal renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void
.Fo lowdown_term_free
.Fa "void *arg"
.Fc
.Sh DESCRIPTION
Frees the terminal renderer created with
.Xr lowdown_term_new 3 .
If
.Va arg
is
.Dv NULL ,
the function does nothing.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in ANSI terminal format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if (setlocale(LC_CTYPE, "en_US.UTF-8") == NULL)
	err(1, NULL);

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_term_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_term_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_term_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_term_new 3
.Sh STANDARDS
ANSI escape codes are described in ISO/IEC 6429, previously ECMA-48.
lowdown-1.1.0/man/lowdown_term_new.3010064400017500001750000000050671452256251200177710ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_TERM_NEW 3
.Os
.Sh NAME
.Nm lowdown_term_new
.Nd allocate a Markdown terminal renderer
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft void *
.Fo lowdown_term_new
.Fa "const struct lowdown_opts *opts"
.Fc
.Sh DESCRIPTION
Allocates a terminal renderer using
.Fa opts->cols ,
.Fa opts->hmargin ,
.Fa opts->vmargin ,
and
.Fa opts->oflags ,
or 80 and all others zero, respectively, if
.Fa opts
is
.Dv NULL .
These fields are documented in
.Xr lowdown 3 .
The returned pointer may be used with multiple invocations of
.Xr lowdown_term_rndr 3
and must be freed with
.Xr lowdown_term_free 3 .
.Pp
The bits recognised in
.Fa opts->oflags
are
.Dv LOWDOWN_TERM_SHORTLINK ,
.Dv LOWDOWN_TERM_NOCOLOUR ,
and
.Dv LOWDOWN_TERM_NOLINK .
.Sh RETURN VALUES
Returns a pointer to the renderer or
.Dv NULL
on memory failure.
The returned pointer must be freed with
.Xr lowdown_term_free 3 .
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs in ANSI terminal format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if (setlocale(LC_CTYPE, "en_US.UTF-8") == NULL)
	err(1, NULL);

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_term_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_term_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_term_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_term_free 3 ,
.Xr lowdown_term_rndr 3
.Sh STANDARDS
ANSI escape codes are described in ISO/IEC 6429, previously ECMA-48.
lowdown-1.1.0/man/lowdown_term_rndr.3010064400017500001750000000050751452256251200201440ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_TERM_RNDR 3
.Os
.Sh NAME
.Nm lowdown_term_rndr
.Nd render Markdown into terminal output
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_term_rndr
.Fa "struct lowdown_buf *out"
.Fa "void *arg"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3
using the terminal renderer
.Fa arg
as returned by
.Xr lowdown_term_new 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Pp
The output consists of UTF-8 encoded characters and ANSI (really ISO/IEC
6429) escape sequences.
.Pp
The caller is expected to have invoked
.Xr setlocale 3
to a
.Qq UTF-8
character encoding prior to using this function, otherwise UTF-8
sequences will not be properly recognised.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va bi
of length
.Va bsz
and outputs in ANSI terminal format.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if (setlocale(LC_CTYPE, "en_US.UTF-8") == NULL)
	err(1, NULL);

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if ((rndr = lowdown_term_new(NULL)) == NULL)
	err(1, NULL);
if (!lowdown_term_rndr(out, rndr, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_term_free(rndr);
lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3 ,
.Xr lowdown_term_free 3 ,
.Xr lowdown_term_new 3
.Sh STANDARDS
ANSI escape codes are described in ISO/IEC 6429, previously ECMA-48.
lowdown-1.1.0/man/lowdown_tree_rndr.3010064400017500001750000000041341452256251200201270ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN_TREE_RNDR 3
.Os
.Sh NAME
.Nm lowdown_tree_rndr
.Nd render Markdown into debugging output
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft int
.Fo lowdown_tree_rndr
.Fa "struct lowdown_buf *out"
.Fa "const struct lowdown_node *n"
.Fc
.Sh DESCRIPTION
Renders a node tree
.Fa n
created by
.Xr lowdown_doc_parse 3
or
.Xr lowdown_diff 3 .
The output is written into
.Fa out ,
which must be initialised and freed by the caller.
.Pp
The output consists of an UTF-8 tree.
The format is not standardised and subject to change.
.Pp
Unlike other renderers,
.Fn lowdown_tree_rndr
accepts no options and thus has no context.
.Sh RETURN VALUES
Returns zero on failure to allocate memory, non-zero on success.
.Sh EXAMPLES
The following parses
.Va b
of length
.Va bsz
and outputs the parse tree.
.Bd -literal -offset indent
struct lowdown_buf *out;
struct lowdown_doc *doc;
struct lowdown_node *n;
void *rndr;

if ((doc = lowdown_doc_new(NULL)) == NULL)
	err(1, NULL);
if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
	err(1, NULL);
if ((out = lowdown_buf_new(256)) == NULL)
	err(1, NULL);
if (!lowdown_tree_rndr(out, n))
	err(1, NULL);

fwrite(out->data, 1, out->size, stdout);

lowdown_buf_free(out);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3
lowdown-1.1.0/man/lowdown.5010064400017500001750000000733651452256251200161010ustar00kristapskristaps.\" Copyright (c) Kristaps Dzonsons 
.\" Copyright (c) 2017 Christina Sophonpanich
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN 5
.Os
.
.
.Sh NAME
.Nm lowdown
.Nd Markdown reference for lowdown
.
.
.Sh DESCRIPTION
Markdown is a simple, plain-text formatting language.
.Dq Plain-text
in this case means the document input looks similar to the output, less
the formatting niceties (boxed tables, italics, clickable links, etc.)
provided by the output medium.
For example:
.Bd -literal -offset indent
# How to be a Picard fan

## Introduction

In order to develop fandom skills one must first and foremost
know *whom* one idolises. Therefore: **who is Captain Picard**?

1. Picard was named the \e*Best Star Trek Captain\e*, according
to a [5-week poll](poll.html).

    > Picard continued his winning ways in the final week,
    > with fans naming him the most inspiring captain.

2. Picard is handsome. ![Picard](image.jpg)
3. Picard knows how to code: `make engage`

---------------------------------

## Picard Fandom

Here's why everyone wants to be a fan...
.Ed
.Pp
This example consists of a series of block elements: section header,
sub-section header, paragraph, set of list elements, horizontal rule,
then another sub-section header.
Each block element contains inline elements: normal text, emphasised text
(bold and italised), an image, a link, and a span of code.
.Pp
This document describes the Markdown syntax accepted by
.Xr lowdown 1 .
.
.
.Sh TEXT
Text within Markdown documents must be UTF-8.
The document may have the byte-order mark (BOM), although this practice
is discouraged by the Unicode standard.
Lines of text may be UNIX terminated
.Pq Sq \en
or DOS
.Pq Sq \er\en .
In the latter case, carriage returns are stripped from input if detected
at the first line.
.
.
.Sh BLOCK ELEMENTS
A block element starts on a new line and extends to the next blank line
or block element.
A block element contains inline elements.
.
.Ss Paragraphs and Line Breaks
A paragraph is made up of one or more lines of text possibly containing
inline elements.
Paragraphs are separated by blank lines.
.Pp
To insert a hard line break (i.e., a line-break in the input that is
reproduced in the output), insert two spaces at the end of the line.
If commonmark input parsing is enabled, this may also be effected by
escaping the newline:
.Bd -literal -offset indent
Darmok and Jalad...\e
at Tanagra.
.Ed
.
.Ss Headers
There are two styles of headers: underlined
.Pq Dq setext
and hash-marked
.Pq Dq atx .
For underlined headers, underline the given word using equal signs
.Pq Dq =
for first-level headers and dashes
.Pq Dq \&-
for second-level headers.
.Bd -literal -offset indent
This is an underlined header 1
==============================
.Ed
.Pp
For hash-marked headers, use the corresponding number of hash characters
to the corresponding level of header, up to 6 levels, at the start of
the line separated by one space followed by the header.
.Bd -literal -offset indent
## This is a hash-marked header 2
.Ed
.Pp
If commonmark input parsing is enabled, the space is required after the
hash-marks in any hash-marked header.
.Pp
Both types support PHP Extra attributes enclosed in curly braces.
These may begin at any point and must end at the end of the line.
.Bd -literal -offset indent
## Star Trek: Enterprise { #stent }

Star Trek: Enterprise { .reboots }
---------------------
.Ed
.Pp
Non-empty values with a leading period are interpreted as HTML (CSS) or
OpenDocument classes, and values with a leading pound symbol are
interpreted as in-document link identifiers.
.Pp
Extra attribute identifiers override the default mechanism for creating
header identifiers.
They should contain only ASCII alphanumeric characters.
.Ss Block Quotes
Block quoted sections are invoked with a single right-angle bracket
.Pq Dq >
followed by a space at the start of each line and between paragraphs.
.Bd -literal -offset indent
> The Prime Directive is not just a set of rules;
> it is a philosophy... and a very correct one.
>
> (It goes on for a few paragraphs).
.Ed
.Pp
Block quotes may also have a non-multiline invocation: you need only
invoke the right-angle bracket at the start of a paragraph and omit it
entirely between paragraphs.
.Bd -literal -offset indent
> You cannot explain away a wantonly immoral act because
you think it is connected to some higher purpose.

> Here is another paragraph about Picard wisdom.
.Ed
.Pp
Consecutive blockquotes as above will be merged as paragraphs within a
single block quote on output, even if styles
.Pq non-multiline and otherwise
are mixed.
.Pp
Block quotes may be nested within other block quotes, as may any other
block elements such as headers, ordered/unordered lists, and code
blocks.
.Bd -literal -offset indent
> ### hash-marked header 3
>
> > I'd be delighted to offer any advice
> > I have on understanding women.
> > When I have some, I'll let you know.
>
> 1.  advice list item 1
> 2.  advice list item 2
>
> Here's the code to implement JLP's advice:

>     yes | read engage
.Ed
.
.Ss Admonitions
Also called
.Qq callouts ,
these special block quotes call attention to contents.
These are generally rendered as-is, but some output modes will specially
render admonitions to highlight the content.
.Bd -literal -offset indent
> **Note**
>
> The computer is voiced by Majel Barrett.
.Ed
.Pp
Callouts begin with a double-emphasis
.Qq Note
or
.Qq Warning ,
and omitting the initial newline suppresses white-space after the
callout type.
This is GFM syntax.
The MDN syntax includes an initial phrase following the callout type and
colon, and also supports the
.Qq Callout
type:
.Bd -literal -offset indent
> **Warning:** red alert.
>
> Romulan warbird decloaking!
.Ed
.Ss Lists
Lists may be specified as ordered (numbered) or unordered.
Ordered lists are invoked as numbers followed by periods
.Pq e.g., Dq 1.
and rendered in a similar format.
.Em Note :
it does not matter which order or which numbers you use in your ordered
lists, as all ordered lists start at one.
.Bd -literal -offset indent
1. Make.
2. It.
1. So. (Not 1. again!)
.Ed
.Pp
If commonmark input parsing is enabled, list items may alternatively
terminate with the right parenthesis:
.Bd -literal -offset indent
1) Live long
2) Prosper
.Ed
.Pp
To prevent lists erroneously started by a paragraph beginning with a
number and period, use a backslash before the period.
.Bd -literal -offset indent
1987. The year TNG premiered.

1987\e. The year TNG premiered.
.Ed
.Pp
Unordered lists, on the other hand, can be invoked using either
asterisk
.Pq Dq * ,
pluses
.Pq Dq + ,
or hyphens
.Pq Dq \- ,
and can be a mix of all three styles.
Regardless the style, list items are rendered the same way.
.Bd -literal -offset indent
- Earl Grey tea.
* Shakespeare.
+ Exotic fish.
.Ed
.Pp
All nested block elements need a new line break, otherwise they will be
rendered on the same line as the list item on output.
To insert paragraphs into a list item, indent each paragraph with either
four spaces or one tab.
.Bd -literal -offset indent
- First list item

    Courage can be an emotion too.

    Things are only impossible until they're not.
+ Second list item
+ Third list item
.Ed
.Pp
To insert block quotes into a list item, indent the block quote with
four spaces or one tab prior to the right-angle bracket
.Pq Dq > .
.Bd -literal -offset indent
* List item 1
* List item 2

     > I am Locutus of Borg.

     > That is the cutest of Borg.
.Ed
.Pp
Code blocks need to be indented twice (two tabs or eight leading spaces): once
for being recognised within the list item, another for the code block itself.
.Bd -literal -offset indent
* Here is a list item for an indented code block:

        alias path='echo -e ${PATH//:/\\n}'
.Ed
.Pp
To make list elements occur in tight sequence \(em like a grocery list
\(em don't have an empty line between the items.
.Bd -literal -offset indent
- Phaser
- Communicator
.Ed
.Pp
On the other hand, if you want to render lists separated by white-space,
use the following syntax:
.Bd -literal -offset indent
- A phaser is a type of weapon.

- A communicator keeps Riker in contact with Troi.
.Ed
.Pp
This applies to ordered and unordered list types.
.
.Ss Task lists
One form of an unordered list is task lists, a GFM extension.
These begin with checkboxes (checked or not), rendered similarly in the output.
.Bd -literal -offset indent
Star Trek series with episodes in the Delta quadrant:

- [ ] Original series
- [x] TNG
- [ ] DS9
- [x] Voyager
- [ ] Enterprise
- [ ] Discovery
.Ed
.Pp
The check may be upper or lower case.
A space must follow the right square bracket.
.
.Ss Definition Lists
Definition lists are a PHP Extra extension.
They're similar to lists except in having key and value pairs, with keys
being preceded by a blank line:
.Bd -literal -offset indent
Best understated characters:

*Quark*
: Armin Shimerman

*Weyoun*
: Jeffrey Combs
.Ed
.Pp
Keys consist of a single line and may contain inline elements.
Like other lists, values may consist of arbitrary nested blocks.
There may be multiple consecutive values per key.
If the key and value are separated by a blank line, the list is emitted
as if it contained block elements (usually output as spacing between
key-value pairs).
.
.Ss Code Blocks
Code blocks consist of pre-formatted text, such as source code.
Each code block contains opaque/literal text.
This means that new lines and white spaces are retained \(em they're not
formatted in any way, and any text inside the code block is not
interpreted.
To invoke a code block, create a line break then indent each line with four
spaces or one tab.
.Bd -literal -offset indent
Here is a paragraph about Bridge protocol

    Here is a code block for the command "Engage"
.Ed
.Pp
Within a code block, text is escaped given the output format.
Therefore, characters that would normally need to be escaped in other
text processing languages such as ampersands
.Pq Dq &
do not need to be escaped.
.Bd -literal -offset indent
Here is how you start the program xterm:

    xterm &
.Ed
.
.Ss Horizontal Rules
A horizontal rule is a line that goes across an output page.
These are invoked with three or more asterisks
.Pq Dq * ,
hyphens
.Pq Dq \- ,
or underscores
.Pq Dq _
on their own line.
Spaces between these characters are disregarded.
.Bd -literal -offset indent
***
* * *
---
- - -
___
_ _ _
___________________________
.Ed
.
.
.Ss Metadata
Documents can include metadata that is not part of the main text.
The syntax follows the MMD and Pandoc specifications.
.Pp
In the MMD syntax, the block begins on the document's first line and
continues until the first blank line.
Keys and values are separated by a colon, and pairs separated by a
newline.
A key (and following value) must exist on the line beginning the
metadata pair, but the value may span multiple lines.
.Bd -literal -offset indent
Title: Captain's log
Author: Captain J-L Picard
Summary: As part of an exchange program, we're taking
 aboard a Klingon officer to return the recent visit
 of Commander Riker to the cruiser Pagh.
Stardate: 43917.4
.Ed
.Pp
Alternatively, a block of MMD metadata may begin with a line of
.Qq ---
and end with
.Qq ---
or
.Qq \&... .
.Pp
If there are multiple lines of text in a metadata value, subsequent
lines should (but need not) be offset with whitespace.
Otherwise, they must not have a colon in the value, else they will be
construed as a subsequent pair's key.
.Pp
End each line with two spaces to ensure linebreaks are rendered on
output for non-conforming Markdown renderers.
Moreover, beginning a document with a regular sentence containing a
colon might invoke metadata.
To escape this, add one blank line to the beginning of the document.
.Pp
Metadata keys must consist of alphanumeric ASCII characters, the hyphen
.Pq Qq \&- ,
or the underscore
.Pq Qq \&_ .
They must have at least one character and are stripped of white-space
and converted to lower case.
.Pp
Metadata values are opaque text: Markdown statements (e.g., italics,
entities, etc.) are copied as-is.
The values will have leading white-space stripped, i.e., space following
the colon.
.Pp
If multiple metadata keys resolve to the same name, the last invocation
is retained.
This check happens after canonicalising the name by stripping spaces,
converting to lower-case, and substituting unknown characters.
.Pp
In the Pandoc syntax, the block stops at the first line not starting
with a percent sign or space.
Metadata is limited to at most three keys: title, author(s), and date.
The first line is for title, the second (if provided) for author(s), and
the third (also if provided) for date.
Lines may continue by having a subsequent line begin with a space.
If only one leading-percent line is included, the metadata is only for
the title; if two, for a title and author(s); and so on.
If a leading-percent line is blank, the corresponding metadata is left
empty (unspecified).
.Bd -literal -offset indent
% A Skin of Evil
% Tasha Yar
  Armus
% 1988-04-2525

Wow what a day...
.Ed
.Pp
Multiple authors may be separated by multiple white-space (including
newlines), a semicolon, or both.
.Pp
The Pandoc title line is automatically scanned for whether it's a
manpage-style title:
.Bd -literal -offset indent
% TREK(6)
.Ed
.Pp
.Nm lowdown
recognises a manpage title from the open parenthesis followed by a
number (or
.Qq n ) ,
optional following characters, then a closing parenthesis.
If found, the title is broken down into title and section.
Any text following the title is further recognised as the source and, if
a vertical bar is detected, what comes after as the volume.
.Bd -literal -offset indent
% TREK(6) OpenBSD | Games Manual
.Ed
.Pp
These may be accessed with the
.Li title
and
.Li section
metadata keys, and optionally
.Li volume
and
.Li source .
.Pp
Using either syntax, dates should be in the YYYY-MM-DD format, but can
be in any format.
Metadata values may be pasted into a document by
referencing the
.Li \&[%key] ,
such as using the above example, again with the caveat that Markdown
annotations (italics, etc.) are copied verbatim:
.Bd -literal -offset indent
date: 43917.4

It's currently stardate [%date].
.Ed
.Pp
Or using Pandoc:
.Bd -literal -offset indent
%
%
% 43917.4
It's currently stardate [%date].
.Ed
.
.
.Ss Mathematics
Mathematics support is an extension of Markdown.
The extension only describes how the math blocks begin and end: the
contained equations are usually in LaTeX and implemented in the
front-end (e.g., HTML).
There are two types: inline and block.
Both may occur anywhere in a text stream.
Inline equations are rendered as part of the text; block equations are
rendered on their own.
.Bd -literal -offset indent
This is an inline $f(x)$ function.
This is a block $$f(x)$$ function.
This is also an inline \e\e(f(x)\e\e) function.
This is also a block \e\e[f(x)\e\e] function.
.Ed
.
.Ss Tables
Tables are a GFM (GitHub-flavoured Markdown) extension of the basic
syntax.
They consist of a table header and body, and columns may be left, right,
or centre justified.
.Bd -literal -offset indent
| Officer         | Rank                 |
| --------------: | -------------------- |
| Jean-Luc Picard | Captain              |
| Worf            | Lieutenant Commander |
| Data            | Lieutenant Commander |
| William Riker   | Commander            |
.Ed
.Pp
The table header must be followed by a line of hyphens with at least
three hyphen/colons per column.
Columns are separated by vertical bars.
The colon indicates alignment: a colon at the beginning means left
justified; at the right for right justified, and both for centred.
.Pp
The leading and trailing column separator is superfluous.
Table data is not necessary, but the table header is.
The minimum table structure for the above is:
.Bd -literal -offset indent
Officer | Rank
--:|---
Jean-Luc Picard | Captain
.Ed
.Pp
Table columns may contain arbitrary inline elements.
.
.Ss Footnote Definition
Footnotes are a MMD extension of the basic syntax.
Footnote definitions may occur anywhere in the text (except within
blocks) and are
.Dq pointed to
by a
.Sx Footnote Reference .
They consist of the footnote name (in square brackets, preceded by the
caret), a colon, then everything remaining in the block is the footnote
content.
.Bd -literal -offset indent
[^pt]:
    Klingon insult, meaning something like "weirdo," deriving from
    the verb "to be weird" (**taQ**), with and [sic] you (plural)
    imperative prefix (**pe-**).
.Ed
.Pp
Footnote contents may be on the same line as the colon.
The footnote name is rendered as a number.
If a footnote definition is not referred to, it is not printed.
.
.Ss HTML Blocks
Embedded HTML is discouraged, as it inhibits formatting into non-HTML
output, but is still accepted.
Blocks of HTML must begin with a recognised HTML block-level element.
.Pp
In the original Markdown, block-level elements were well-defined by
HTML4.
HTML5 elements are also accepted, but as there is no concept of
block-level in HTML5, these are non-canonical.
Accepted elements are
.Li 
       ,
.Li 
       ,
.Li 
       ,
or
.Li 
if in the header.
.It Dv LOWDOWN_TABLE_HEADER
A table header section described by
.Li