.\" Copyright (c) Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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 short arguments are as follows:
.Bl -tag -width Ds
.It Fl s
Produce a standalone document (e.g., a valid HTML document including
document type, head, etc.) around the formatted content.
See
.Sx Standalone documents
for details.
.It Fl M Ar metadata
Provide a single metadata key-value pair.
This may be in the normal syntax 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.
This overrides
.Fl m
and what's parsed from the document.
See
.Sx Metadata .
.It Fl m Ar metadata
Like
.Fl M ,
but 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
.Dq gemtext
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 media .
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 long 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 Dq 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
.Dq short
syntax.
.El
.Pp
There are many output long options.
The following are shared by all output media:
.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.
.It Fl -template Ar template
When producing standalone
.Fl s
output, use a template file.
See
.Sx Templates .
Currently only for
.Fl t Ns Ar gemini ,
.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 tree .
.El
.Pp
What follows are per-output long 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 .
.It Fl -html-titleblock
If any were parsed, format the title information (title, author, date)
into a header element appearing first in the document.
.El
.Pp
For both roff formats
.Fl t Ns Ar man
and
.Fl t Ns Ar ms
.Pq unless as noted ,
the following apply:
.Bl -tag -width Ds
.It Fl -roff-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 Dq 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 -roff-endnotes
Delay printing of footnotes until the end of the document.
Only applies to
.Fl t Ns Ar ms ,
as
.Fl t Ns Ar man
only supports endnotes.
.It Fl -roff-no-numbered
Don't output numbered headings
.Po
.Li .NH NN
.Pc .
Only applies to
.Fl t Ns Ar ms .
.It Fl -roff-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 -roff-no-links
Don't show URLs for images and links (autolinks are still shown).
.Pq Link content is still shown.
Overrides
.Fl -roff-short-links
for images and links.
Only applies when
.Fl -roff-traditional
is specified.
.It Fl -roff-short-links
Shorten URLs for images, links, and autolinks to only the domain name
and final path.
Only applies when
.Fl -roff-traditional
is specified.
.It Fl -roff-traditional
Don't use hyperlink macros
.Po
.Li .pdfhref ,
.Li .UR ,
.Li .MT
.Pc ,
multi-page tables
.Po
.Li .TS H ,
.Li .TH
.Pc ,
Unicode sequence syntax
.Po
.Li \e[uNNNN]
.Pc ,
example block macros
.Po
.Li .EX
.Pc ,
modern section headings
.Po
.Li .NH NN ,
.Li .SH NN ,
.Li .pdfhref O NN
.Pc ,
or intra-document links
.Po
.Li .pdfhref L
.Pc .
The output is compatible with traditional
.Xr troff 1 .
.El
.Pp
The argument prefix
.Fl -nroff ,
such as in
.Fl -nroff-traditional ,
is deprecated in favour of
.Fl -roff .
.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 terminal.
Useful for when running in a pipe.
Defaults to what the terminal reports or 72 if not in a terminal.
.It Fl -term-hmargin=margin
The number of left margin characters.
Defaults to zero.
Can also be
.Ar auto
to set the left margin to half the remaining
.Fl -term-columns
after subtracting
.Fl -term-width .
.It Fl -term-hpadding=padding
The number of left padding characters.
Defaults to four.
Padding eats into
.Fl -term-width .
.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-no-links
Don't show URLs for images and links (autolinks are still shown).
.Pq Link content is still shown.
Overrides
.Fl -term-short-links
and
.Fl -term-no-rellinks .
.It Fl -term-no-rellinks
Don't show URLs for relative links.
.Pq Link content is still shown.
Overrides
.Fl -term-short-links .
.It Fl -term-short-links
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
Soft limit on the number of characters per line including
.Pq Fl -term-hpadding .
This may be exceeded by literal text.
If zero or unset, defaults to
.Fl -term-columns
or 80 at most.
Truncates to
.Fl -term-columns .
.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 <office:font-face-decls> ,
.Li <office:scripts> ,
and
.Li <office:styles>
XML elements in the root of the document.
This is not syntax-checked in any way.
.El
.Ss Output media
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
.Dq gemtext
format.
.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 frontend 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 ,
Heirloom
.Xr troff ,
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 programmatic use, as the format may change between versions.
.El
.Ss Differences
The differences between old and new document are illustrated in the following
ways:
.Bl -tag -width Ds
.It Fl t Ns Ar fodt
.Dq Flat
Differences are rendered using document tracking.
.It Fl t Ns Ar gemini
Differences are not rendered.
.It Fl t Ns Ar latex
Differences are rendered by colouring in blue (insert) and red (delete)
(this format is not fixed).
.It Fl t Ns Ar man
Differences are rendered by colouring in blue (insert) and red (delete)
(this format is not fixed).
.It Fl t Ns Ar ms
Differences are rendered by colouring in blue (insert) and red (delete)
(this format is not fixed).
.It Fl t Ns Ar term
Differences are rendered by background-colouring in blue (insert) and
red (delete) (this format is not fixed).
.It Fl t Ns Ar tree
Differences are manually in the tree output.
.El
.Pp
Differences in content metadata use the following rule: deleted metadata
key-value pairs are not processed in the output, so only inserted or
retained metadata are processed.
.Ss Standalone documents
When
.Fl s
is specified, the formatted content is serialised into a self-contained
document template as defined by the output type.
.Pp
If not explicitly set with
.Fl -template ,
a default template is produced as follows:
.Bl -tag -width Ds
.It Fl t Ns Ar fodt
Envelope
.Li <office:document>
and prologue
.Li <office:automatic-styles> ,
.Li <office:master-styles> ,
and
.Li <office:body> .
.It Fl t Ns Ar html
HTML5 doctype declaration followed by envelope
.Li <html>
with optional language, then
.Li <head> .
In order, the
.Li <head>
consists of charset and viewport
.Li <meta>
elements; optional
.Li <meta>
elements from metadata affiliation (creator), author, copyright, and
date;
optional CSS sources from metadata;
optional JavaScript sources from metadata;
the possibly-empty
.Li <title> ;
then optional arbitrary content from metadata HTML header.
.It Fl t Ns Ar latex
Prologue
.Li documentclass
and
.Li usepackage
statements, optional arbitrary content from metadata LaTeX header, then
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.
.It Fl t Ns Ar tree
Metadata and parsed template.
.El
.Pp
See
.Sx Metadata
for metadata values used by the default template.
.Ss Metadata
Metadata keys are canonicalised and de-deduplicated in the following
order:
.Fl m
.Pq overridden by document content and Fl M ,
the prologue of the document itself, then
.Fl M
.Pq overriding document content and Fl m .
.Pp
After de-duplication, metadata is serialised into document variables
and/or standalone
.Fl s
output.
.Pp
When not using
.Fl -template ,
the following metadata keys are used in the default
.Fl s
template:
.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 output in the HTML document head as a
.Li <link rel="stylesheet" href="..." />
statement.
Multiple CSS files (in order) may be separated by two or more spaces
(including newlines) and are output in the given order.
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 htmlheader
Arbitrary HTML content output in the HTML document head immediately
prior to closing the head element.
Only used in
.Fl t Ns Ar html
and with
.Fl s .
This metadata is not processed: it's passed unchanged into the output.
.It Li javascript
A JavaScript file output in the HTML document head as a
.Li <script src="..."></script>
statement.
Multiple script files (in order) may be separated by two or more spaces
(including newlines) and are output in the given order.
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 latexheader
Arbitrary LaTeX content output in the document prologue immediately
prior to the
.Li begin{document} .
Only used in
.Fl t Ns Ar latex
and with
.Fl s .
This metadata is not processed: it's passed unchanged into the output.
.It Li manheader
Arbitrary roff content output immediately prior to the
.Li .TH
macro.
Only used in
.Fl t Ns Ar man
and with
.Fl s .
This metadata is not processed: it's passed unchanged into the output.
.It Li msheader
Arbitrary roff content output immediately prior to the
.Li .TL
macro.
Only used in
.Fl t Ns Ar ms
and with
.Fl s .
This metadata is not processed: it's passed unchanged into the output.
.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 <h1>
to be level 2
.Pq Dq <h2> ,
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
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.
.Ss Templates
Some output media accept a template
.Pq Fl -template
to customise standalone
.Pq Fl s
output.
Parsed input content is filled into templates through control statements
that support conditionals, loops, and variable transformation sequences.
.Pp
Control statements are delimited as
.Cm $statement$
or
.Cm ${statement} .
Arbitrary white-space may surround the case-insensitive statement
between matching delimiters.
Statements without a closing delimiter are considered opaque text.
.Pp
The following statements are available:
.Bl -tag -width Ds
.It Cm $$ , ${}
Output a literal
.Cm $ .
This may contain arbitrary white-space.
.It Cm $ifdef(expression)$
Conditional statement.
There may not be any white-space between the
.Cm ifdef
and the opening parenthesis.
Begins a block that is ended by a
.Cm else ,
.Cm endif ,
or the end of file.
Its contents are output only if
.Cm expression
evaluates to a non-empty string.
.It Cm $else$
Begins a block that is ended by a
.Cm endif
or end of file.
Its contents are output only if the condition of a 
preceding
.Cm ifdef
evaluates to an empty string.
An
.Cm else
without a preceding
.Cm ifdef
is not output.
.It Cm $endif$
Closes a block begin with
.Cm ifdef
or
.Cm else .
If not preceded by one of those statements, is silently ignored.
.It Cm $for(expression)$
Looping statement.
There may not be any white-space between the
.Cm for
and the opening parenthesis.
Begins a block that is ended by an
.Cm endfor
or the end of file.
Block contents contents are repeatedly output for each list item
evaluated from
.Cm expression .
The anaphoric keyword
.Cm this
may be used to access the current loop expression within the block.
.It Cm $expression$
Replaced by the result of evaluating a template expression.
.El
.Pp
If a control statement ends with two consecutive hyphens before the
closing delimiter, input is consumed up to and including the next
newline or until end of file.
This allows for line-sensitive output media to use control statements
without superfluous blank lines.
.Pp
Expressions consist of
.Pp
.Dl initial[([arg]*)]?[.transform[([arg]*)]?]* ,
.Pp
or an initial value accepting optional arguments followed by an optional
series of transforms accepting optional arguments.
If an argument list is empty or not provided, it evaluates to an empty
list.
.Pp
The
.Li initial
value is one of the following:
.Bl -tag -width Ds
.It Cm and(expression[,expression]*)
A non-empty list containing the value
.Li true
if all expressions evaluate to non-empty lists, otherwise an empty list.
An empty expression evaluates to an empty list.
.It Li \(dqliteral string\(dq
Evaluates to a singleton list containing the string.
An empty string evaluates to an empty list.
The double quote character may be escaped, such as
.Li \(dqfoo\e\(dqbar\(dq .
.It Cm body
The parsed input document body.
.It canonicalised metadata key
The value for the given metadata key, if found, otherwise an empty list.
.It Cm body
The parsed input document body.
.It Cm meta(key)
Produce the metadata value for the canonicalised metadata
.Cm key .
Allows for keys that are also keywords like
.Li body
or
.Li endif .
.It Cm not(expression)
A non-empty list
containing the value
.Li true
if the expression evaluates as an empty list, otherwise an empty list.
.It Cm or(expression[,expression]*)
A non-empty list containing the value
.Li true
if one expression evaluates to non-empty lists, otherwise an empty list.
An empty expression evaluates to an empty list.
.It Cm this
The value of a current loop context or an empty list.
.El
.Pp
If a metadata key is not specified in the input, or if the anaphoric
.Cm this
has not initialised by a looping context, the initial value evaluates to an
empty list.
Otherwise, the value is a singleton list.
.Pp
If transforms are invalid, they will transform into an empty list.
.Pp
The following transformations are available:
.Bl -tag -width Ds
.It Cm escapegemini , escapegeminiline
Escape list items for gemini
.Pq Fl t Ns Ar gemini ,
either for multiple lines or compressed to a single line.
.It Cm escapehtml , escapehtmlattr , escapehtmlurl
Escape list items for HTML
.Pq Fl t Ns Ar html
body content, attributes, and URL attributes,
respectively.
.It Cm escapelatex
Escape list items for LaTeX
.Pq Fl t Ns Ar latex
body content.
.It Cm escaperoff , escaperoffline
Escape list items for roff
.Pq Fl t Ns Ar ms , Fl t Ns Ar man ,
either for multiple lines or compressed to a single line.
.Cm escaperoff
also escapes initial roff delimiters and those after newlines.
.It Cm join
Join a list into a singleton list using two spaces as a join delimiter.
.It Cm lowercase
Lowercase all list items.
.It Cm split
Split list items on sequences of two or more white-space tokens (space,
newline, tab).
This is usually invoked on a singleton, but may be repeatedly invoked on
a pre-split list.
Invokes
.Cm trim
prior to the first split.
The resulting list has no items that are only white-space.
.It Cm trim
Trim white-space from the beginning and end of all list items.
If an item has no non-white-space, it is discarded.
.It Cm uppercase
Uppercase all list items.
.El
.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/html/default.html
The default template used if
.Fl -template
is not provided to
.Fl t Ns Ar html .
.It Pa share/latex/default.latex
The default template used if
.Fl -template
is not provided to
.Fl t Ns Ar latex .
.It Pa share/man/default.man
The default template used if
.Fl -template
is not provided to
.Fl t Ns Ar man .
.It Pa share/man/default.ms
The default template used if
.Fl -template
is not provided to
.Fl t Ns Ar ms .
.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.