LOWDOWN-DIFF(1)

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 only applies to -Tgemini, -Thtml, -Tlatex, -Tms, and -Tman.

-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
    Do not parse PHP extra image extended attributes.

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

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 (this further requires -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-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-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.

  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.

affiliation
    Author affiliation (organisation or institution). Multiple affiliations may be separated by more than one space (including newlines). Used in all output modes but -Tman.

author
    Document author. Multiple authors may be separated by more than one space (including newlines). Overridden by rcsauthor. Used in all output modes but -Tman.

baseheaderlevel
    The “top-most” header level. For example, having a base header level of 2 will cause all headers originally level 1 to be level 2. So for -Thtml, any instance of <h1> would be instead <h2>. If unset or less than one, defaults to one.

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 more than one space (including newlines). Only used in -Thtml.

date
    Document date in ISO-8601 YYYY-MM-DD format. Overridden by rcsdate. Used in all output modes.

javascript
    A JavaScript file included in the HTML5 document head. Multiple script files (in order) may be separated by more than one space (including newlines). Only used in -Thtml.

rcsauthor
    Document author in RCS author format. Overrides author. Used in all output modes.

rcsdate
    Document date in RCS date format. Overrides date. Used in all output modes.

section
    Man page section, defaulting to “7”. Only used in -Tman.

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 all output modes.

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

  Output modes
A detailed description of the output modes follows.

-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 used by lowdown-diff: 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.

Output is augmented with features for viewing file differences. These depend upon the output mode.

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

EXIT STATUS

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.