FreeBSD Manual Pages
LOWDOWN(1) BSD General Commands Manual LOWDOWN(1) NAME lowdown, lowdown-diff -- simple markdown translator SYNOPSIS lowdown [in_opts] [out_opts] [-s] [-o file] [-T mode] [file] lowdown [in_opts] [out_opts] [-o file] [-T mode] -X keyword [file] lowdown-diff [in_opts] [out_opts] [-s] [-o file] [-T mode] oldfile [file] DESCRIPTION Translate from lowdown(5) into diverse output formats. lowdown formats documents, lowdown -X keyword extracts metadata keywords, and lowdown-diff shows differences between 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 pro- viding information to the document envelope. This only applies to -Tgemini, -Thtml, -Tlatex, -Tms, and -Tman. -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. -X keyword Instead of converting the file, extract the given metadata key- word and exit. These will be escaped according to the output mode -T; for example, a title of "<foo>" with -Thtml will be ex- tracted as "<foo>". Metadata is not rendered for -Ttree or -Tnull. oldfile Input Markdown document used as the basis for comparison with lowdown-diff. file Input Markdown document. If not given or if file 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. Otherwise it's considered a regular paragraph. Metadata is escaped according to the output mode. --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-hardwrap Hard-wrap paragraph content by outputting line breaks where ap- plicable. --nroff-no-groff Don't use groff(1) style section headings and PDF hyperlinks. If using -mspdf with groff(1), these will be further rendered as a table of contents and clickable links. Only applies to -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. 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-shortlinks Shorten URLs to only the domain name and final path. This is useful for reading when links aren't clickable. Applies to im- ages, autolinks, and real links. --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. 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 not disabled with --parse-no-metadata, the following metadata keys are used when in standalone (-s) mode. 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. Overriden 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. title Document title, defaulting to "Untitled article". Used in all output modes. Output modes A detailed description of the output modes follows. -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: 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. -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 ouptut: not for general use. Diffing If invoked as lowdown-diff, the traditional Markdown 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. The algorithm used for diffing derives from "Detecting Changes in XML Documents" (2002). The algorithm for computing the shortest edit script between text nodes is "O(NP) sequence comparison algorithm" (1990). EXIT STATUS The lowdown and lowdown-diff utilities exit 0 on success, and >0 if an error occurs. If the -X flag is used, lowdown exits with an error if the given keyword is not found. EXAMPLES To view a Markdown file on an ANSI-compatible, UTF-8 terminal: lowdown -Tterm foo.md | less -R If preferred, the terminal may also be used with groff(1) or mandoc(1) rendering: lowdown -sTms foo.md | groff -tki -mspdf -Kutf8 -Tutf8 | less -R lowdown -sTman foo.md | mandoc | less To emit a standalone HTML5 document: lowdown -s foo.md > foo.html To use groff(1) or mandoc(1) to format as a PS file: lowdown -sTms foo.md | groff -tki -mspdf -Kutf8 > foo.ps lowdown -sTman foo.md | mandoc -Tps > foo.ps Or using a traditional troff(1), use the following: lowdown --nroff-no-groff -sTms foo.md | \ tbl | pic | troff -Tps -ms -mpdfmark > foo.ps Both groff(1) and mandoc(1) support the -Tpdf arguments for PDF output. The former also has pdfroff(1). lowdown -sTms foo.md | \ groff -tki -mspdf -Kutf8 -Tpdf > foo.pdf If the file has PS or EPS images and is being processed by groff(1), the images are not converted and the file needs to be manually converted from PS. lowdown -sTms foo.md | groff -tki -mspdf -Kutf8 > foo.ps ps2dpdf foo.ps UTF-8 support for PDF or PS is limited to groff(1) installations with the appropriate fonts, such as the Unicode Times font. This and other Uni- code 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 pre- fixed with `U'. lowdown -sTms foo.md | \ groff -Tpdf -tki -mspdf -Kutf8 -FU-T > foo.pdf To extract the HTML-escaped title from a file's metadata: lowdown -X title foo.md SEE ALSO lowdown(3), lowdown(5) Gregory Cobena, Serge Abiteboul, and Amelie Marian, Detecting Changes in XML Documents, https://www.cs.rutgers.edu/~amelie/papers/2002/diff.pdf, 2002.
NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | EXAMPLES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lowdown&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>