lowdown-diff - Man Page

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 short 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 long 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 long 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.
--template template: When producing standalone -s output, use a template file. See Templates. This is experimental functionality. Currently only for -thtml.

What follows are per-output long 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-endnotes: Delay printing of footnotes until the end of the document. Only applies to -tms, as -tman only supports endnotes.
--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&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.

Templates

Some output modes accept a template (--template) to customise standalone (-s) output. Parsed input content is filled into templates through control statements that support conditionals, loops, and transformation sequences.

Templates control statements are delimited as $statement$ or ${statement}. Arbitrary white-space may surround the case-insensitive statement between matching delimiters. Empty statements are stripped, with the exception of $$, which outputs a literal $. Statements without a closing delimiter are considered opaque text.

The following statements are available:

$ifdef(expression)$: Conditional statement. There may not be any white-space between the ifdef and the opening parenthesis. Begins a block that is ended by a else, endif, or the end of file. Its contents are output only if expression evaluates to a non-empty string.
$else$: Begins a block that is ended by a endif or end of file. Its contents are output only if the condition of a preceding ifdef evaluates to an empty string. An else without a preceding ifdef is not output.
$endif$: Closes a block begin with ifdef or else. If not preceded by one of those statements, is silently ignored.
$for(expression)$: Looping statement. There may not be any white-space between the for and the opening parenthesis. Begins a block that is ended by an endfor or the end of file. Block contents contents are repeatedly output for each list item evaluated from expression. The anaphoric keyword this may be used to access the current loop expression within the block.
$expression$: Replaced by the result of evaluating a template expression.

Expressions consist of initial[([arg]*)]?[.transform[([arg]*)]?]*, or an initial value followed by an optional series of transforms that accept optional arguments.

The initial value is one of the following:

a canonicalised metadata key
this (value of a current loop context)
body (parsed input document body)
meta(val) to force accepting val as a metadata key, even if it's a special variable like body

If a metadata key is not specified in the input, or if the anaphoric this has not initialised by a looping context, the initial value evaluates to an empty list. Otherwise, the value is a singleton list.

If transforms are invalid, they will transform into an empty list.

The following transformations are available:

escapehtml, escapehtmlattr, escapehtmlurl: Escape list items for HTML body content, attributes, and URL attributes, respectively.
join: Join a list into a singleton list using two spaces as a join delimiter.
lowercase: Lowercase all list items.
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 trim prior to the first split. The resulting list has no items that are only white-space.
trim: Trim white-space from the beginning and end of all list items. If an item has no non-white-space, it is discarded.
uppercase: Uppercase all list items.

Environment

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

Files

share/html/default.html: The default template used if --template is not provided to -thtml.
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