Ubuntu Manpage: lowdown-diff — view differences in markdown files

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 syntax specified by lowdown(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 -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, -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”. The -T mode form is retained for backward
compatibility.

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-callouts
Do not parse GFM/MDN callouts ("admonitions").

--parse-no-deflists
Do not parse PHP extra definition lists.

--parse-no-ext-attrs
Do not parse PHP extra extended attributes.

--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-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.

--parse-no-metadata
Do not parse metadata. 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 or sub-scripts at all.

--parse-no-tables
Do not parse GFM tables.

--parse-no-tasklists
Do not parse GFM task lists.

--parse-super-short
If super-script parsing is enabled, use the traditional non-GFM "short" syntax.

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-callout-mdn, --html-callout-gfm
Output either or both MDN or GFM callout syntaxes.

--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.

--html-titleblock
If any were parsed, format the title information (title, author, date) into a header element
appearing first in the document.

For both -tman and -tms (unless as noted), the following apply:

--nroff-code-font=fonts
Override the default constant-width fonts with a tuple of regular, bold, italic, and bold-italic
variants in that order. For example, B,B,BI,BI uses bold ("B") instead of a constant-width. Not
specifying a font will use the default, as will specifying a zero-length font name. Aliases
none, bold, and code set no special fonts, bold, and the default constant-width.

--nroff-no-groff
Deprecated alias for --nroff-traditional.

--nroff-no-numbered
Don't output numbered headings (.NH NN). 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. Only applies when --nroff-traditional is
specified.

--nroff-shortlinks
Shorten URLs for images, links, and autolinks to only the domain name and final path. Only
applies when --nroff-traditional is specified.

--nroff-traditional
Don't use hyperlink macros (.pdfhref, .UR, .MT), multi-page tables (.TS H, .TH), Unicode sequence
syntax (\[uNNNN]), example block macros (.EX), modern section headings (.NH NN, .SH NN, .pdfhref
O NN), or intra-document links (.pdfhref L). The output is compatible with traditional troff(1).

The -tterm output has the following:

--term-all-metadata
If -s is specified, output all metadata instead of just the title, author, and date.

--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.

--odt-style=file
Specify an OpenDocument style file, which must consist of at least <office:font-face-decls>,
<office:scripts>, and <office:styles> XML elements in the root of the document. This is not
syntax-checked in any way.

Output modes
The output media is specified by -t, which defaults to -thtml.

-tfodt “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.

-tgemini
Gemini protocol output. This output mode is experimental. Differences are not currently
rendered.

-thtml HTML5 output with UTF-8 encoding. Differences are rendered using the <ins> and <del> elements.

-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. Differences are rendered by colouring in blue (insert) and red (delete) (this format is
not fixed).

-tman The man macro package suitable for reading by groff(1), mandoc(1), Heirloom troff, 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. Differences are rendered by
colouring in blue (insert) and red (delete) (this format is not fixed).

-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. Differences are
rendered by colouring in blue (insert) and red (delete) (this format is not fixed).

-tterm 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).

-ttree Debugging output: not for general use.

Standalone documents
When -s is specified, additional content may be added to output:

-tfodt Envelope <office:document> and prologue <office:automatic-styles>, <office:master-styles>, and
<office:body>.

-thtml HTML5 doctype declaration followed by envelope <html> with optional language, then <head>. In
order, the <head> consists of charset and viewport <meta> elements; optional <meta> elements from
metadata affiliation (creator), author, copyright, and date; optional CSS sources from metadata;
optional JavaScript sources from metadata; the possibly-empty <title>; then optional arbitrary
content from metadata HTML header.

-tlatex
Prologue documentclass and usepackage statements, optional arbitrary content from metadata LaTeX
header, then surrounding begin{document} statements.

-tman, -tms
Prologue macros.

-tterm Prologue lines.

If parsed from the document or as given by -m or -M, the following metadata keys are used by additional
content. The metadata keys are canonicalised in lowercase and without spaces.

Metadata values should not be encoded in their output format, e.g., “css: foo&amp;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, -tms, and -tterm.

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 output in the HTML document head as a <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 -thtml.

date Document date in ISO-8601 YYYY-MM-DD format. Overridden by rcsdate. Used in -tfodt, -thtml,
-tlatex, -tman, -tms, and -tterm.

htmlheader
Arbitrary HTML content output in the HTML document head immediately prior to closing the head
element. Only used in -thtml and with -s. This metadata is not processed: it's passed unchanged
into the output.

javascript
A JavaScript file output in the HTML document head as a <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 -thtml.

lang Document language in RFC 5646 format. Only used in -thtml.

latexheader
Arbitrary LaTeX content output in the document prologue immediately prior to the begin{document}.
Only used in -tlatex and with -s. This metadata is not processed: it's passed unchanged into the
output.

manheader
Arbitrary roff content output immediately prior to the .TH macro. Only used in -tman and with
-s. This metadata is not processed: it's passed unchanged into the output.

msheader
Arbitrary roff content output immediately prior to the .TL macro. Only used in -tms and with -s.
This metadata is not processed: it's passed unchanged into the output.

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. Used in -tfodt, -thtml, -tlatex, -tman, -tms, and -tterm.

Metadata values are parsed and may be used as variables in markdown documents regardless of whether -s is
specified or not.

Default values, such “7” for the section, are not set as metadata values, and will not appear if the
metadata key is used as a variable.

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.

In formats where metadata are part of the document body, such as -tterm and -ttree, all metadata are
shown as if in the document body.

ENVIRONMENT

       NO_COLOR
               Do not emit colours when in -tterm mode.  Synonym for NO_COLOUR.  Same as --term-nocolour.

FILES

       share/odt/styles.xml
               Default styles used when  generating  standalone  -tfodt  documents.   Template  for  --odt-style
               styles.

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

AUTHORS

       lowdown-diff was written by Kristaps Dzonsons, kristaps@bsd.lv.

CAVEATS

       When  viewing -tman differences with mandoc(1), the marker colours are not rendered.  The -tgemini output
       also currently has no way of encoding differences.

Debian                                             $Mdocdate$                                    LOWDOWN-DIFF(1)