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

FreeBSD Manual Pages

  
 
  

home | help
LOWDOWN-DIFF(1)		FreeBSD	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 (this
	     further requires -mspdf passed to groff(1)), or Unicode sequence
	     syntax.  The output is compatible with traditional	troff(1).  Ap-
	     plies 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 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-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.

     affiliation
	     Author affiliation	(organisation or institution).	Multiple af-
	     filiations	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 (includ-
	     ing 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	re-
     gardless 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 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.

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.

FreeBSD	13.0		       February	17, 2021		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | 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