Provided by: lowdown_0.10.0-1_amd64 
NAME
lowdown-diff — view differences in markdown files
SYNOPSIS
lowdown-diff [input_options] [output_options] [-s] [-M metadata] [-m metadata] [-o file]
[-T mode] oldfile [newfile]
DESCRIPTION
Shows differences between lowdown(5) documents as formatted output. Results are written to
standard output.
The arguments are as follows:
-s Standalone mode. This emits a document envelope surrounding the output by drawing
from document metadata. See Metadata on providing information to the document
envelope. This applies to -Tgemini, -Thtml, -Tlatex, -Tms, -Tman, and -Tfodt.
-M metadata
Provide a single metadata key-value pair. This may be in the usual lowdown(5)
colon-separated metadata format or instead separated by an equal sign, depending
upon which character comes first. Exits with an error if given neither colon nor
equal sign. May be invoked multiple times for each pair. This overrides -m and
what's parsed from the document.
-m metadata
Like -M, but is overridden by what's parsed the document, then -M.
-o file
Send output to file unless it's “-”, in which case fall back to the default of
standard output.
-T mode
The output mode. This may be html for HTML5 output, latex for LaTeX, gemini for the
Gemini format, ms for roff output using the classic (i.e., no-extension) -ms package
and needing table support, term for ANSI-compatible UTF-8 terminal output, man for
roff output using the classic -man package, tree, to show the parse tree of the
input document, and null to parse the document but do no rendering. See Output
modes.
oldfile, newfile
Markdown documents used for comparison. If newfile is not given or “-”, it is read
from standard input.
The following are options for input parsing. These affect the parse tree passed to all
outputs.
--parse-hilite
Enable highlight span support. This are disabled by default because it may be
erroneously interpreted as section headers.
--parse-math
Recognise mathematics equations.
--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.
--parse-no-autolink
Do not parse http, https, ftp, mailto, and relative links or link fragments.
--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.
--parse-no-codeindent
Do not parse indented content as code blocks.
--parse-no-deflists
Do not parse PHP extra definition lists.
--parse-no-fenced
Do not parse GFM fenced (language-specific) code blocks.
--parse-no-footnotes
Do not parse MMD footnotes.
--parse-no-img-ext
Deprecated. See --parse-no-ext-attrs.
--parse-no-intraemph
Do not parse emphasis within words and links.
--parse-no-metadata
Do not parse MMD metadata. For the first paragraph to count as metadata, the first
line must have a colon in it. This does not affect metadata given on -m or -M.
--parse-no-strike
Do not parse strikethroughs.
--parse-no-super
Do not parse super-scripts.
--parse-no-tables
Do not parse GFM tables.
--parse-no-tasklists
Do not parse GFM task lists.
There are many output options. The following are shared by all output modes:
--out-standalone
Alias for -s.
--out-no-smarty
Do not use the smart typography filter. By default, certain character sequences are
translated into output-specific glyphs.
What follows are per-output options. For HTML with -Thtml, these are as follows:
--html-hardwrap
Hard-wrap paragraph content by outputting line breaks where applicable.
--html-no-escapehtml
If --html-no-skiphtml has been specified, this causes embedded HTML not to be
escaped, and is instead output verbatim. This has no effect if --html-no-skiphtml
has not been specified.
--html-no-head-ids
Do not output id attributes for headers.
--html-no-num-ent
Don't normalise HTML entities (when possible) as numeric ones and instead use the
entities as given on input.
--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.
--html-no-skiphtml
Output embedded HTML. By default, embedded HTML is not output at all. See
--html-no-escapehtml.
For both -Tman and -Tms, the following apply:
--nroff-no-groff
Don't use groff(1) style section headings, PDF hyperlinks and multi-page tables
(these further require -Tms mode and -mspdf passed to groff(1)), or Unicode sequence
syntax. The output is compatible with traditional troff(1). Applies to -Tman and
-Tms.
--nroff-no-numbered
Don't output numbered headings. Only applies to -Tms.
--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.
--nroff-nolinks
Don't show URLs for images and links (autolinks are still shown). (Link content is
still shown.) Overrides --nroff-shortlinks for images and links. Applies to -Tman
or when -nroff-no-groff is specified.
--nroff-shortlinks
Shorten URLs for images, links, and autolinks to only the domain name and final
path. Applies to -Tman or when -nroff-no-groff is specified.
The -Tterm output has the following:
--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.
--term-hmargin=margin
The number of left margin spaces. Truncated to the number of columns. Defaults to
zero.
--term-no-ansi
Don't show ANSI styles at all. This implies --term-no-colour.
--term-no-colour
Don't show ANSI colours. This will still decorate text with underlines, bolds, and
italics, but not emit any colour codes.
--term-nolinks
Don't show URLs for images and links (autolinks are still shown). (Link content is
still shown.) Overrides --term-shortlinks for images and links.
--term-shortlinks
Shorten URLs for images, links, and autolinks to only the domain name and final
path.
--term-vmargin=margin
The number of top and bottom margin newlines. Defaults to zero.
--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.
The -Tgemini 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.
--gemini-link-end
Emit the queue of links at the end of the document instead of after the nearest
block element.
--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.
--gemini-link-noref
Do not format link labels. Takes precedence over --gemini-link-roman.
--gemini-link-roman
When formatting link labels, use lower-case Roman numerals instead of the default
lower-case hexavigesimal (i.e., “a”, “b”, ..., “aa”, “ab”, ...).
--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.
The -Tlatex output has the following options:
--latex-no-numbered
Don't number sections (and subsections, etc.).
--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.
The -Tfodt output has the following options:
--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.
Metadata
If parsed from the document or as given by -m or -M, the following metadata keys are
recognised by output front-ends. The metadata keys are canonicalised in lowercase and
without spaces.
Metadata values should not be encoded in their output format, e.g., “css: foo&bar”. The
renderer will perform any necessary output encoding.
affiliation
Author affiliation (organisation or institution). Multiple affiliations may be
separated by two or more spaces (including newlines). Used in -Thtml, -Tlatex, and
-Tms.
author Document author. Multiple authors may be separated by two or more spaces (including
newlines). Overridden by rcsauthor. Used in -Tfodt, -Thtml, -Tlatex, and -Tms.
baseheaderlevel
Added to each header level. Deprecated in favour of shiftheadinglevelby.
copyright
A document copyright (without the word “Copyright”), for example, “2017, Kristaps
Dzonsons”. Used in -Tms and -Thtml.
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 -Thtml.
date Document date in ISO-8601 YYYY-MM-DD format. Overridden by rcsdate. Used in
-Tfodt, -Thtml, -Tlatex, -Tman, and -Tms.
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
-Thtml.
rcsauthor
Like author, but in RCS author format. Overrides author.
rcsdate
Like date, but in RCS date format. Overrides date.
section
Man page section, defaulting to “7”. Only used in -Tman.
shiftheadinglevelby
Shift all headers by the given number. For example, a value of 1 causes headers
originally at level 1 (“<h1>”) to be level 2 (“<h2>”), while a value of -1 moves
level 2 to 1. Levels will not move to less than 1. Takes precedence over
baseheaderlevel. If unset or not a valid number, defaults to zero. Used in -Tfodt,
-Thtml, -Tlatex, -Tman, and -Tms.
source Man page source (organisation providing the manual). Only used in -Tman.
volume Man page volume (describes the manual page section). Only used in -Tman.
title Document title, defaulting to “Untitled article”. Used in -Tfodt, -Thtml, -Tlatex,
-Tman, and -Tms.
Metadata values are parsed and may be used as variables in markdown documents regardless of
whether -s is specified or not.
Default values, such “Untitled article” for the title, are not set as metadata values, and
will not appear if the metadata key is used as a variable.
Output modes
A detailed description of the output modes follows.
-Tlatex
“Flat” OpenDocument output. This output mode is still in development.
-Tgemini
Gemini protocol output. This output mode (and the protocol) are experimental.
-Thtml HTML5 output with UTF-8 encoding. All features of lowdown(5) are supported.
-Tlatex
Simple LaTeX output. The following packages are required: amsmath and amssymb for
maths, graphicx for images, inputenc (utf8) for UTF-8 input, fontend (T1) and
textcomp for output glyphs, lmodern for Latin modern font, xcolor for the difference
engine output, and hyperref for links.
-Tman The man macro package suitable for reading by groff(1), mandoc(1), or traditional
troff(1). Does not support equations and images. Table support is provided by
tbl(1). Since UTF-8 may be passed as input values, preconv(1) may need to be used.
-Tms The ms macro package suitable for reading by groff(1) or traditional 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 tbl(1). Since UTF-8 may be passed
as input values, preconv(1) may need to be used.
-Tterm ANSI-escaped UTF-8 output suitable for reading on the terminal. Images and
equations not supported.
-Ttree Debugging output: not for general use.
Without -s specified, several of these modes will omit parts of the output:
-Tfodt Omit all but the <office:automatic-styles>, <office:master-styles>, and
<office:body> elements and their children.
-Thtml Omit all but the <body> element and its children.
-Tlatex
Omit the documentclass, usepackage, and surrounding begin{document} statements.
-Tman, -Tms
Omit the document prologue.
Output is augmented with features for viewing file differences. These depend upon the
output mode.
-Tfodt Uses the change-tracking feature to display insertions and deletions.
-Tman, -Tms
When data has been removed, it is coloured red. When data has been inserted, it is
coloured in green. In either case, your formatter must support colours or the texts
will be freely intermingled.
-Thtml When data has been removed from the old document, it is marked up with the <del>
element. When data has been inserted into the new document, <ins> is used instead.
-Tlatex
When data has been removed, it is coloured red. When data has been inserted, it is
coloured in green.
-Tterm Removed and inserted data have different background colours.
ENVIRONMENT
The following environment variables affect the execution of lowdown-diff:
NO_COLOR
Do not emit colours when in -Tterm mode. Synonym for NO_COLOUR. Same as
--term-nocolour.
EXIT STATUS
The lowdown-diff utility exits 0 on success, and >0 if an error occurs.
EXAMPLES
To view Markdown differences on an ANSI-compatible, UTF-8 terminal:
lowdown-diff -Tterm old.md new.md | less -R
The terminal may also be used with groff(1) rendering:
lowdown-diff -sTms old.md new.md | \
groff -itk -mspdf -Tutf8 | less -R
lowdown-diff -sTman old.md new.md | \
groff -itk -man -Tutf8 | less -R
To emit a standalone HTML5 document:
lowdown-diff -s old.md new.md > foo.html
To use groff(1) to format as a PS file:
lowdown-diff -sTms old.md new.md | \
groff -itk -mspdf > foo.ps
Or with LaTeX:
lowdown-diff -sTlatex old.md new.md > foo.latex
pslatex foo.latex
PDF generation follows similar logic:
lowdown-diff -sTms old.md new.md | \
pdfroff -itk -mspdf > foo.pdf
lowdown-diff -sTlatex old.md new.md > foo.latex
pdflatex foo.latex
UTF-8 support for 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 devpdf set of the groff(1) font directory and are prefixed
with ‘U’.
lowdown-diff -sTms old.md new.md | \
pdfroff -itk -mspdf -FU-T > foo.pdf
SEE ALSO
lowdown(1), lowdown(3), lowdown(5)
AUTHORS
lowdown-diff was written by Kristaps Dzonsons, kristaps@bsd.lv.
CAVEATS
When viewing -Tman differences with mandoc, the marker colours are not rendered. The
-Tgemini output also currently has no way of encoding differences.