1LOWDOWN-DIFF(1) BSD General Commands Manual LOWDOWN-DIFF(1)
2
4 lowdown-diff — view differences in markdown files
5
7 lowdown-diff [input_options] [output_options] [-s] [-M metadata]
8 [-m metadata] [-o file] [-t mode] oldfile [newfile]
9
11 Shows differences between lowdown(5) documents as formatted output. Re‐
12 sults are written to standard output.
13 The arguments are as follows:
15 -s Standalone mode. This emits a document envelope surrounding the
17 output by drawing from document metadata. See Metadata on pro‐
18 viding information to the document envelope. This applies to
19 -tgemini, -thtml, -tlatex, -tms, -tman, and -tfodt.
20 -M metadata
22 Provide a single metadata key-value pair. This may be in the
23 syntax specified by lowdodwn(5) or as pairs separated by an equal
24 sign, depending upon which character (a colon or equal sign)
25 comes first. Exits with an error if given neither colon nor
26 equal sign. May be invoked multiple times for each pair. This
27 overrides -m and what's parsed from the document.
28 -m metadata
30 Like -M, but is overridden by what's parsed the document, then
31 -M.
32 -o file
34 Send output to file unless it's “-”, in which case fall back to
35 the default of standard output.
36 -t mode, -T mode
38 The output mode. This may be html for HTML5 output, latex for
39 LaTeX, gemini for the Gemini format, ms for roff output using the
40 classic (i.e., no-extension) -ms package and needing table sup‐
41 port, term for ANSI-compatible UTF-8 terminal output, man for
42 roff output using the classic -man package, tree, to show the
43 parse tree of the input document, and null to parse the document
44 but do no rendering. See Output modes. The -T mode form is re‐
45 tained for backward compatibility.
46 oldfile, newfile
48 Markdown documents used for comparison. If newfile is not given
49 or “-”, it is read from standard input.
50 The following are options for input parsing. These affect the parse tree
52 passed to all outputs.
53 --parse-hilite
55 Enable highlight span support. This are disabled by default be‐
56 cause it may be erroneously interpreted as section headers.
57 --parse-math
59 Recognise mathematics equations.
60 --parse-maxdepth=depth
62 The maximum depth of nested elements. This defaults to 128,
63 which is probably more than enough for any real-world document.
64 If the maximum is hit, the system exits as if memory were ex‐
65 hausted. Set to zero for no maximum.
66 --parse-no-autolink
68 Do not parse http, https, ftp, mailto, and relative links or link
69 fragments.
70 --parse-no-cmark
72 Do not parse with CommonMark constraints. This also disables us‐
73 ing the first ordered list value instead of starting all lists at
74 one.
75 --parse-no-codeindent
77 Do not parse indented content as code blocks.
78 --parse-no-deflists
80 Do not parse PHP extra definition lists.
81 --parse-no-ext-attrs
83 Do not parse PHP extra extended attributes.
84 --parse-no-fenced
86 Do not parse GFM fenced (language-specific) code blocks.
87 --parse-no-footnotes
89 Do not parse MMD footnotes.
90 --parse-no-img-ext
92 Deprecated. See --parse-no-ext-attrs.
93 --parse-no-intraemph
95 Do not parse emphasis within words and links.
96 --parse-no-mantitle
98 Do not parse manpage title, section, source, and volume from Pan‐
99 doc title metadata. Manpages titles are indicated by a title
100 then an open parenthesis, digit followed by optional characters,
101 then a closed parenthesis.
102 --parse-no-metadata
104 Do not parse metadata. This does not affect metadata given on -m
105 or -M.
106 --parse-no-strike
108 Do not parse strikethroughs.
109 --parse-no-super
111 Do not parse super-scripts.
112 --parse-no-tables
114 Do not parse GFM tables.
115 --parse-no-tasklists
117 Do not parse GFM task lists.
118 There are many output options. The following are shared by all output
120 modes:
121 --out-standalone
123 Alias for -s.
124 --out-no-smarty
126 Do not use the smart typography filter. By default, certain
127 character sequences are translated into output-specific glyphs.
128 What follows are per-output options. For HTML with -thtml, these are as
130 follows:
131 --html-hardwrap
133 Hard-wrap paragraph content by outputting line breaks where ap‐
134 plicable.
135 --html-no-escapehtml
137 If --html-no-skiphtml has been specified, this causes embedded
138 HTML not to be escaped, and is instead output verbatim. This has
139 no effect if --html-no-skiphtml has not been specified.
140 --html-no-head-ids
142 Do not output id attributes for headers.
143 --html-no-num-ent
145 Don't normalise HTML entities (when possible) as numeric ones and
146 instead use the entities as given on input.
147 --html-no-owasp
149 Don't follow the OWASP recommendations for escaping text, and do
150 only the minimal escaping to make sure that regular content isn't
151 interpreted as HTML.
152 --html-no-skiphtml
154 Output embedded HTML. By default, embedded HTML is not output at
155 all. See --html-no-escapehtml.
156 For both -tman and -tms, the following apply:
158 --nroff-no-groff
160 Don't use groff(1) style section headings, PDF hyperlinks and
161 multi-page tables (these further require -tms mode and -mspdf
162 passed to groff(1)), or Unicode sequence syntax. The output is
163 compatible with traditional troff(1). Applies to -tman and -tms.
164 --nroff-no-numbered
166 Don't output numbered headings. Only applies to -tms.
167 --nroff-no-skiphtml
169 Output embedded HTML. This usually doesn't make sense because
170 the HTML won't be interpreted by the output reader. By default,
171 HTML is omitted.
172 --nroff-nolinks
174 Don't show URLs for images and links (autolinks are still shown).
175 (Link content is still shown.) Overrides --nroff-shortlinks for
176 images and links. Applies to -tman or when -nroff-no-groff is
177 specified.
178 --nroff-shortlinks
180 Shorten URLs for images, links, and autolinks to only the domain
181 name and final path. Applies to -tman or when -nroff-no-groff is
182 specified.
183 The -tterm output has the following:
185 --term-columns=columns
187 The number of columns in the screen. Useful for when running in
188 a pipe. Defaults to what the terminal reports or 72 if in a
189 pipe.
190 --term-hmargin=margin
192 The number of left margin spaces. Truncated to the number of
193 columns. Defaults to zero.
194 --term-no-ansi
196 Don't show ANSI styles at all. This implies --term-no-colour.
197 --term-no-colour
199 Don't show ANSI colours. This will still decorate text with un‐
200 derlines, bolds, and italics, but not emit any colour codes.
201 --term-nolinks
203 Don't show URLs for images and links (autolinks are still shown).
204 (Link content is still shown.) Overrides --term-shortlinks for
205 images and links.
206 --term-shortlinks
208 Shorten URLs for images, links, and autolinks to only the domain
209 name and final path.
210 --term-vmargin=margin
212 The number of top and bottom margin newlines. Defaults to zero.
213 --term-width=width
215 Set the soft limit on the number of characters per line. This
216 may be exceeded by literal text. The default (or if zero) is the
217 number of terminal columns or 80 at most.
218 The -tgemini output has several flags that control the placement of
220 links. By default, links (images, autolinks, and links) are queued when
221 specified in-line then emitted in a block sequence after the nearest
222 block element.
223 --gemini-link-end
225 Emit the queue of links at the end of the document instead of af‐
226 ter the nearest block element.
227 --gemini-link-inline
229 Render all links within the flow of text. This will cause break‐
230 age when nested links, such as images within links, links in
231 blockquotes, etc. It should not be used unless in carefully
232 crafted documents.
233 --gemini-link-noref
235 Do not format link labels. Takes precedence over
236 --gemini-link-roman.
237 --gemini-link-roman
239 When formatting link labels, use lower-case Roman numerals in‐
240 stead of the default lower-case hexavigesimal (i.e., “a”, “b”,
241 ..., “aa”, “ab”, ...).
242 --gemini-metadata
244 Print metadata as the canonicalised key followed by a colon then
245 the value, each on one line (newlines replaced by spaces). The
246 metadata block is terminated by a double newline. If there is no
247 metadata, this does nothing.
248 The -tlatex output has the following options:
250 --latex-no-numbered
252 Don't number sections (and subsections, etc.).
253 --latex-no-skiphtml
255 Output embedded HTML. This usually doesn't make sense because
256 the HTML won't be interpreted by the output reader. By default,
257 HTML is omitted.
258 The -tfodt output has the following options:
260 --odt-no-skiphtml
262 Output embedded HTML. This usually doesn't make sense because
263 the HTML won't be interpreted by the output reader. By default,
264 HTML is omitted.
265 --odt-style=file
267 Specify an OpenDocument style file, which must consist of at
268 least <office:font-face-decls>, <office:scripts>, and
269 <office:styles> XML elements in the root of the document. This
270 is not syntax-checked in any way.
271 Output modes
273 The output media is specified by -t, which defaults to -thtml.
274 -tfodt “Flat” OpenDocument output. Automatic styles (those conditional
276 upon document state) are generated with output. Classes speci‐
277 fied by PHP extended attributes are not checked for existence.
278 Differences are rendered using document tracking.
279 -tgemini
281 Gemini protocol output. This output mode is experimental. Dif‐
282 ferences are not currently rendered.
283 -thtml HTML5 output with UTF-8 encoding. Differences are rendered using
285 the <ins> and <del> elements.
286 -tlatex
288 Simple LaTeX output. The following packages are required:
289 amsmath and amssymb for maths, graphicx for images, inputenc
290 (utf8) for UTF-8 input, fontend (T1) and textcomp for output
291 glyphs, lmodern for Latin modern font, xcolor for the difference
292 engine output, and hyperref for links. Differences are rendered
293 by colouring in blue (insert) and red (delete) (this format is
294 not fixed).
295 -tman The man macro package suitable for reading by groff(1),
297 mandoc(1), or traditional troff(1). Does not support equations
298 and images. Table support is provided by tbl(1). Since UTF-8
299 may be passed as input values, preconv(1) may need to be used.
300 Differences are rendered by colouring in blue (insert) and red
301 (delete) (this format is not fixed).
302 -tms The ms macro package suitable for reading by groff(1) or tradi‐
304 tional troff(1). Does not support equations and limited image
305 support for encapsulated postscript (PS and EPS suffix) images.
306 Images are always block-formatted. Image dimensions and extended
307 attributes are ignored, though images are downsized if larger
308 than the current text width. Table support is provided by
309 tbl(1). Since UTF-8 may be passed as input values, preconv(1)
310 may need to be used. Differences are rendered by colouring in
311 blue (insert) and red (delete) (this format is not fixed).
312 -tterm ANSI-escaped UTF-8 output suitable for reading on the terminal.
314 Images and equations not supported. Differences are rendered by
315 background-colouring in blue (insert) and red (delete) (this for‐
316 mat is not fixed).
317 -ttree Debugging output: not for general use.
319 Standalone documents
321 When -s is specified, additional content may be added to output:
322 -tfodt Envelope <office:document> and prologue
324 <office:automatic-styles>, <office:master-styles>, and
325 <office:body>.
326 -thtml Envelope <html> and prologue <head>.
328 -tlatex
330 Prologue documentclass and usepackage statements, and surrounding
331 begin{document} statements.
332 -tman, -tms
334 Prologue macros.
335 If parsed from the document or as given by -m or -M, the following meta‐
337 data keys are used by additional content. The metadata keys are canoni‐
338 calised in lowercase and without spaces.
339 Metadata values should not be encoded in their output format, e.g., “css:
341 foo&bar”. The renderer will perform any necessary output encoding.
342 affiliation
344 Author affiliation (organisation or institution). Multiple af‐
345 filiations may be separated by two or more spaces (including new‐
346 lines). Used in -thtml, -tlatex, and -tms.
347 author Document author. Multiple authors may be separated by two or
349 more spaces (including newlines). Overridden by rcsauthor. Used
350 in -tfodt, -thtml, -tlatex, and -tms.
351 baseheaderlevel
353 Added to each header level. Deprecated in favour of
354 shiftheadinglevelby.
355 copyright
357 A document copyright (without the word “Copyright”), for example,
358 “2017, Kristaps Dzonsons”. Used in -tms and -thtml.
359 css A CSS file included in the HTML5 document head. Multiple CSS
361 files (in order) may be separated by two or more spaces (includ‐
362 ing newlines). Only used in -thtml.
363 date Document date in ISO-8601 YYYY-MM-DD format. Overridden by
365 rcsdate. Used in -tfodt, -thtml, -tlatex, -tman, and -tms.
366 javascript
368 A JavaScript file included in the HTML5 document head. Multiple
369 script files (in order) may be separated by two or more spaces
370 (including newlines). Only used in -thtml.
371 rcsauthor
373 Like author, but in RCS author format. Overrides author.
374 rcsdate
376 Like date, but in RCS date format. Overrides date.
377 section
379 Man page section, defaulting to “7”. Only used in -tman.
380 shiftheadinglevelby
382 Shift all headers by the given number. For example, a value of 1
383 causes headers originally at level 1 (“<h1>”) to be level 2
384 (“<h2>”), while a value of -1 moves level 2 to 1. Levels will
385 not move to less than 1. Takes precedence over baseheaderlevel.
386 If unset or not a valid number, defaults to zero. Used in
387 -tfodt, -thtml, -tlatex, -tman, and -tms.
388 source Man page source (organisation providing the manual). Only used
390 in -tman.
391 volume Man page volume (describes the manual page section). Only used
393 in -tman.
394 title Document title. Used in -tfodt, -thtml, -tlatex, -tman, and
396 -tms.
397 Metadata values are parsed and may be used as variables in markdown docu‐
399 ments regardless of whether -s is specified or not.
400 Default values, such “7” for the section, are not set as metadata values,
402 and will not appear if the metadata key is used as a variable.
403 Differences in additional content metadata are rendered differently than
405 in the document body: deleted metadata key-value pairs are not processed
406 in the output, so only inserted or retained metadata are processed.
407 In formats where metadata are part of the document body, such as -tterm
409 and -ttree, all metadata are shown as if in the document body.
410
412 NO_COLOR
413 Do not emit colours when in -tterm mode. Synonym for NO_COLOUR.
414 Same as --term-nocolour.
415
417 share/odt/styles.xml
418 Default styles used when generating standalone -tfodt documents.
419 Template for --odt-style styles.
420
422 The lowdown-diff utility exits 0 on success, and >0 if an error occurs.
423
425 To view Markdown differences on an ANSI-compatible, UTF-8 terminal:
426 lowdown-diff -tterm old.md new.md | less -R
428 The terminal may also be used with groff(1) rendering:
430 lowdown-diff -stms old.md new.md | \
432 groff -itk -mspdf -Tutf8 | less -R
433 lowdown-diff -stman old.md new.md | \
434 groff -itk -man -Tutf8 | less -R
435 To emit a standalone HTML5 document:
437 lowdown-diff -s old.md new.md > foo.html
439 To use groff(1) to format as a PS file:
441 lowdown-diff -stms old.md new.md | \
443 groff -itk -mspdf > foo.ps
444 Or with LaTeX:
446 lowdown-diff -stlatex old.md new.md > foo.latex
448 pslatex foo.latex
449 PDF generation follows similar logic:
451 lowdown-diff -stms old.md new.md | \
453 pdfroff -itk -mspdf > foo.pdf
454 lowdown-diff -stlatex old.md new.md > foo.latex
455 pdflatex foo.latex
456 UTF-8 support for groff(1) PDF or PS output requires appropriate fonts,
458 such as the Unicode Times font. This and other Unicode fonts are not al‐
459 ways installed by default. They may be found, for PDF output, in the
460 devpdf set of the groff(1) font directory and are prefixed with ‘U’.
461 lowdown-diff -stms old.md new.md | \
463 pdfroff -itk -mspdf -FU-T > foo.pdf
464
466 lowdown(1), lowdown(3), lowdown(5)
467
469 lowdown-diff was written by Kristaps Dzonsons, kristaps@bsd.lv.
470
472 When viewing -tman differences with mandoc(1), the marker colours are not
473 rendered. The -tgemini output also currently has no way of encoding dif‐
474 ferences.
475BSD December 17, 2023 BSD