NAME¶

lowdown-diff — view differences in markdown files

SYNOPSIS¶

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

For both -tman and -tms, 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

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

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

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:

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:

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(1), the marker colours are not rendered. The -tgemini output also currently has no way of encoding differences.