Provided by: lowdown_1.0.0-2_amd64 bug

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

     --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), 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  Envelope <html> and prologue <head>.

     -tlatex
             Prologue documentclass and usepackage statements, and surrounding begin{document}
             statements.

     -tman, -tms
             Prologue macros.

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

     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

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.