FreeBSD Manual Pages
LOWDOWN-DIFF(1) 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. Results are written to standard output. The short arguments are as follows: -s Produce a standalone document (e.g., a valid HTML document in- cluding document type, head, etc.) around the formatted con- tent. See "Standalone documents" for details. -M metadata Provide a single metadata key-value pair. This may be in the normal syntax or as pairs separated by an equal sign, depending upon which character (a colon or equal sign) comes first. Ex- its with an error if given neither. This overrides -m and what's parsed from the document. See "Metadata". -m metadata Like -M, but 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 "gemtext" format, ms for roff out- put 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 media". 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 long 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 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 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 ti- tle then an open parenthesis, digit followed by optional char- acters, 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 long options. The following are shared by all output media: --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. --template template When producing standalone -s output, use a template file. See "Templates". Currently only for -tgemini, -thtml, -tlatex, -tman, -tms, and -ttree. What follows are per-output long 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 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. --html-titleblock If any were parsed, format the title information (title, au- thor, date) into a header element appearing first in the docu- ment. For both roff formats -tman and -tms (unless as noted), the following apply: --roff-code-font=fonts Override the default constant-width fonts with a tuple of regu- lar, 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. --roff-endnotes Delay printing of footnotes until the end of the document. Only applies to -tms, as -tman only supports endnotes. --roff-no-numbered Don't output numbered headings (.NH NN). Only applies to -tms. --roff-no-skiphtml Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By de- fault, HTML is omitted. --roff-no-links Don't show URLs for images and links (autolinks are still shown). (Link content is still shown.) Overrides --roff-short-links for images and links. Only applies when --roff-traditional is specified. --roff-short-links Shorten URLs for images, links, and autolinks to only the do- main name and final path. Only applies when --roff-traditional is specified. --roff-traditional Don't use hyperlink macros (.pdfhref, .UR, .MT), multi-page ta- bles (.TS H, .TH), Unicode sequence syntax (\[uNNNN]), example block macros (.EX), modern section headings (.NH NN, .SH NN, .pdfhref O NN), or intra-document links (.pdfhref L). The out- put is compatible with traditional troff(1). The argument prefix --nroff, such as in --nroff-traditional, is depre- cated in favour of --roff. The -tterm output has the following: --term-all-metadata If -s is specified, output all metadata instead of just the ti- tle, author, and date. --term-columns=columns The number of columns in the terminal. Useful for when running in a pipe. Defaults to what the terminal reports or 72 if not in a terminal. --term-hmargin=margin The number of left margin characters. Defaults to zero. Can also be auto to set the left margin to half the remaining --term-columns after subtracting --term-width. --term-hpadding=padding The number of left padding characters. Defaults to four. Padding eats into --term-width. --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-no-links Don't show URLs for images and links (autolinks are still shown). (Link content is still shown.) Overrides --term-short-links and --term-no-rellinks. --term-no-rellinks Don't show URLs for relative links. (Link content is still shown.) Overrides --term-short-links. --term-short-links Shorten URLs for images, links, and autolinks to only the do- main name and final path. --term-vmargin=margin The number of top and bottom margin newlines. Defaults to zero. --term-width=width Soft limit on the number of characters per line including (--term-hpadding). This may be exceeded by literal text. If zero or unset, defaults to --term-columns or 80 at most. Trun- cates to --term-columns. 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 near- est 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 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 de- fault, 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 de- fault, 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 media The output media is specified by -t, which defaults to -thtml. -tfodt "Flat" OpenDocument output. Automatic styles (those condi- tional upon document state) are generated with output. Classes specified by PHP extended attributes are not checked for exis- tence. -tgemini Gemini "gemtext" format. -thtml HTML5 output with UTF-8 encoding. -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 differ- ence engine output, and hyperref for links. -tman The man macro package suitable for reading by groff(1), mandoc(1), Heirloom troff, 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 ex- tended 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 programmatic use, as the format may change between versions. Differences The differences between old and new document are illustrated in the following ways: -tfodt "Flat" Differences are rendered using document tracking. -tgemini Differences are not rendered. -tlatex Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). -tman Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). -tms Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). -tterm Differences are rendered by background-colouring in blue (in- sert) and red (delete) (this format is not fixed). -ttree Differences are manually in the tree output. Differences in content metadata use the following rule: deleted meta- data key-value pairs are not processed in the output, so only inserted or retained metadata are processed. Standalone documents When -s is specified, the formatted content is serialised into a self- contained document template as defined by the output type. If not explicitly set with --template, a default template is produced as follows: -tfodt Envelope <office:document> and prologue <office:automatic-styles>, <office:master-styles>, and <office:body>. -thtml HTML5 doctype declaration followed by envelope <html> with op- tional language, then <head>. In order, the <head> consists of charset and viewport <meta> elements; optional <meta> elements from metadata affiliation (creator), author, copyright, and date; optional CSS sources from metadata; optional JavaScript sources from metadata; the possibly-empty <title>; then op- tional arbitrary content from metadata HTML header. -tlatex Prologue documentclass and usepackage statements, optional ar- bitrary content from metadata LaTeX header, then surrounding begin{document} statements. -tman, -tms Prologue macros. -tterm Prologue lines. -ttree Metadata and parsed template. See "Metadata" for metadata values used by the default template. Metadata Metadata keys are canonicalised and de-deduplicated in the following order: -m (overridden by document content and -M), the prologue of the document itself, then -M (overriding document content and -m). After de-duplication, metadata is serialised into document variables and/or standalone -s output. When not using --template, the following metadata keys are used in the default -s template: affiliation Author affiliation (organisation or institution). Multiple af- filiations 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, -tms, and -tterm. baseheaderlevel Added to each header level. Deprecated in favour of shiftheadinglevelby. copyright A document copyright (without the word "Copyright"), for exam- ple, "2017, Kristaps Dzonsons". Used in -tms and -thtml. css A CSS file output in the HTML document head as a <link rel="stylesheet" href="..." /> statement. Multiple CSS files (in order) may be separated by two or more spaces (including newlines) and are output in the given order. Only used in -thtml. date Document date in ISO-8601 YYYY-MM-DD format. Overridden by rcsdate. Used in -tfodt, -thtml, -tlatex, -tman, -tms, and -tterm. htmlheader Arbitrary HTML content output in the HTML document head immedi- ately prior to closing the head element. Only used in -thtml and with -s. This metadata is not processed: it's passed un- changed into the output. javascript A JavaScript file output in the HTML document head as a <script src="..."></script> statement. Multiple script files (in or- der) may be separated by two or more spaces (including new- lines) and are output in the given order. Only used in -thtml. lang Document language in RFC 5646 format. Only used in -thtml. latexheader Arbitrary LaTeX content output in the document prologue immedi- ately prior to the begin{document}. Only used in -tlatex and with -s. This metadata is not processed: it's passed unchanged into the output. manheader Arbitrary roff content output immediately prior to the .TH macro. Only used in -tman and with -s. This metadata is not processed: it's passed unchanged into the output. msheader Arbitrary roff content output immediately prior to the .TL macro. Only used in -tms and with -s. This metadata is not processed: it's passed unchanged into the output. 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. Used in -tfodt, -thtml, -tlatex, -tman, -tms, and -tterm. Default values, such "7" for the section, are not set as metadata val- ues, and will not appear if the metadata key is used as a variable. Templates Some output media accept a template (--template) to customise stand- alone (-s) output. Parsed input content is filled into templates through control statements that support conditionals, loops, and vari- able transformation sequences. Control statements are delimited as $statement$ or ${statement}. Arbi- trary white-space may surround the case-insensitive statement between matching delimiters. Statements without a closing delimiter are con- sidered opaque text. The following statements are available: $$, ${} Output a literal $. This may contain arbitrary white-space. $ifdef(expression)$ Conditional statement. There may not be any white-space be- tween the ifdef and the opening parenthesis. Begins a block that is ended by a else, endif, or the end of file. Its con- tents are output only if expression evaluates to a non-empty string. $else$ Begins a block that is ended by a endif or end of file. Its contents are output only if the condition of a preceding ifdef evaluates to an empty string. An else without a preceding ifdef is not output. $endif$ Closes a block begin with ifdef or else. If not preceded by one of those statements, is silently ignored. $for(expression)$ Looping statement. There may not be any white-space between the for and the opening parenthesis. Begins a block that is ended by an endfor or the end of file. Block contents contents are repeatedly output for each list item evaluated from expression. The anaphoric keyword this may be used to access the current loop expression within the block. $expression$ Replaced by the result of evaluating a template expression. If a control statement ends with two consecutive hyphens before the closing delimiter, input is consumed up to and including the next new- line or until end of file. This allows for line-sensitive output media to use control statements without superfluous blank lines. Expressions consist of initial[([arg]*)]?[.transform[([arg]*)]?]*, or an initial value accepting optional arguments followed by an op- tional series of transforms accepting optional arguments. If an argu- ment list is empty or not provided, it evaluates to an empty list. The initial value is one of the following: and(expression[,expression]*) A non-empty list containing the value true if all expressions evaluate to non-empty lists, otherwise an empty list. An empty expression evaluates to an empty list. "literal string" Evaluates to a singleton list containing the string. An empty string evaluates to an empty list. The double quote character may be escaped, such as "foo\"bar". body The parsed input document body. canonicalised metadata key The value for the given metadata key, if found, otherwise an empty list. body The parsed input document body. meta(key) Produce the metadata value for the canonicalised metadata key. Allows for keys that are also keywords like body or endif. not(expression) A non-empty list containing the value true if the expression evaluates as an empty list, otherwise an empty list. or(expression[,expression]*) A non-empty list containing the value true if one expression evaluates to non-empty lists, otherwise an empty list. An empty expression evaluates to an empty list. this The value of a current loop context or an empty list. If a metadata key is not specified in the input, or if the anaphoric this has not initialised by a looping context, the initial value evalu- ates to an empty list. Otherwise, the value is a singleton list. If transforms are invalid, they will transform into an empty list. The following transformations are available: escapegemini, escapegeminiline Escape list items for gemini (-tgemini), either for multiple lines or compressed to a single line. escapehtml, escapehtmlattr, escapehtmlurl Escape list items for HTML (-thtml) body content, attributes, and URL attributes, respectively. escapelatex Escape list items for LaTeX (-tlatex) body content. escaperoff, escaperoffline Escape list items for roff (-tms, -tman), either for multiple lines or compressed to a single line. escaperoff also escapes initial roff delimiters and those after newlines. join Join a list into a singleton list using two spaces as a join delimiter. lowercase Lowercase all list items. split Split list items on sequences of two or more white-space tokens (space, newline, tab). This is usually invoked on a singleton, but may be repeatedly invoked on a pre-split list. Invokes trim prior to the first split. The resulting list has no items that are only white-space. trim Trim white-space from the beginning and end of all list items. If an item has no non-white-space, it is discarded. uppercase Uppercase all list items. ENVIRONMENT NO_COLOR Do not emit colours when in -tterm mode. Synonym for NO_COLOUR. Same as --term-nocolour. FILES share/html/default.html The default template used if --template is not provided to -thtml. share/latex/default.latex The default template used if --template is not provided to -tlatex. share/man/default.man The default template used if --template is not provided to -tman. share/man/default.ms The default template used if --template is not provided to -tms. share/odt/styles.xml Default styles used when generating standalone -tfodt docu- ments. 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(1), the marker colours are not rendered. The -tgemini output also currently has no way of encod- ing differences. FreeBSD Ports 14.quarterly $Mdocdate$ LOWDOWN-DIFF(1)
NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | EXIT STATUS | EXAMPLES | SEE ALSO | AUTHORS | CAVEATS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lowdown-diff&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>