Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LOWDOWN-DIFF(1)		  BSD General Commands Manual	       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.  Re-
     sults 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	pro-
	     viding 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 sepa-
	     rated 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 over-
	     rides -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	sup-
	     port, 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 be-
	     cause 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 ex-
	     hausted.  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 us-
	     ing 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 ap-
	     plicable.

     --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-nocolour
	     Don't show	colours.  This will still decorate text	with under-
	     lines, 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 af-
	     ter the nearest block element.

     --gemini-link-inline
	     Render all	links within the flow of text.	This will cause	break-
	     age 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	in-
	     stead 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.

   Metadata
     If	parsed from the	document or as given by	-m or -M, the following	meta-
     data keys are recognised by output	front-ends.  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 af-
	     filiations	may be separated by two	or more	spaces (including new-
	     lines).  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	-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 (includ-
	     ing newlines).  Only used in -Thtml.

     date    Document date in ISO-8601 YYYY-MM-DD format.  Overridden by
	     rcsdate.  Used in -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
	     -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
	     -Thtml, -Tlatex, -Tman, and -Tms.

     Metadata values are parsed	and may	be used	as variables in	markdown docu-
     ments 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.

   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 in-
	     put, 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 tradi-
	     tional 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	inter-
	     mingled.

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

ENVIRONMENT
     The following environment variables affect	the execution of lowdown-diff:

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

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 al-
     ways 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 dif-
     ferences.

BSD			       January 26, 2022				   BSD

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | EXIT STATUS | EXAMPLES | SEE ALSO | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lowdown-diff&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help