Provided by: lowdown_1.1.0-1_amd64 bug

NAME

     lowdown — Markdown reference for lowdown

DESCRIPTION

     Markdown is a simple, plain-text formatting language.  “Plain-text” in this case means the
     document input looks similar to the output, less the formatting niceties (boxed tables,
     italics, clickable links, etc.)  provided by the output medium.  For example:

           # How to be a Picard fan

           ## Introduction

           In order to develop fandom skills one must first and foremost
           know *whom* one idolises. Therefore: **who is Captain Picard**?

           1. Picard was named the \*Best Star Trek Captain\*, according
           to a [5-week poll](poll.html).

               > Picard continued his winning ways in the final week,
               > with fans naming him the most inspiring captain.

           2. Picard is handsome. ![Picard](image.jpg)
           3. Picard knows how to code: `make engage`

           ---------------------------------

           ## Picard Fandom

           Here's why everyone wants to be a fan...

     This example consists of a series of block elements: section header, sub-section header,
     paragraph, set of list elements, horizontal rule, then another sub-section header.  Each
     block element contains inline elements: normal text, emphasised text (bold and italised), an
     image, a link, and a span of code.

     This document describes the Markdown syntax accepted by lowdown(1).

TEXT

     Text within Markdown documents must be UTF-8.  The document may have the byte-order mark
     (BOM), although this practice is discouraged by the Unicode standard.  Lines of text may be
     UNIX terminated (‘\n’) or DOS (‘\r\n’).  In the latter case, carriage returns are stripped
     from input if detected at the first line.

BLOCK ELEMENTS

     A block element starts on a new line and extends to the next blank line or block element.  A
     block element contains inline elements.

   Paragraphs and Line Breaks
     A paragraph is made up of one or more lines of text possibly containing inline elements.
     Paragraphs are separated by blank lines.

     To insert a hard line break (i.e., a line-break in the input that is reproduced in the
     output), insert two spaces at the end of the line.  If commonmark input parsing is enabled,
     this may also be effected by escaping the newline:

           Darmok and Jalad...\
           at Tanagra.

   Headers
     There are two styles of headers: underlined (“setext”) and hash-marked (“atx”).  For
     underlined headers, underline the given word using equal signs (“=”) for first-level headers
     and dashes (“-”) for second-level headers.

           This is an underlined header 1
           ==============================

     For hash-marked headers, use the corresponding number of hash characters to the
     corresponding level of header, up to 6 levels, at the start of the line separated by one
     space followed by the header.

           ## This is a hash-marked header 2

     If commonmark input parsing is enabled, the space is required after the hash-marks in any
     hash-marked header.

     Both types support PHP Extra attributes enclosed in curly braces.  These may begin at any
     point and must end at the end of the line.

           ## Star Trek: Enterprise { #stent }

           Star Trek: Enterprise { .reboots }
           ---------------------

     Non-empty values with a leading period are interpreted as HTML (CSS) or OpenDocument
     classes, and values with a leading pound symbol are interpreted as in-document link
     identifiers.

     Extra attribute identifiers override the default mechanism for creating header identifiers.
     They should contain only ASCII alphanumeric characters.

   Block Quotes
     Block quoted sections are invoked with a single right-angle bracket (“>”) followed by a
     space at the start of each line and between paragraphs.

           > The Prime Directive is not just a set of rules;
           > it is a philosophy... and a very correct one.
           >
           > (It goes on for a few paragraphs).

     Block quotes may also have a non-multiline invocation: you need only invoke the right-angle
     bracket at the start of a paragraph and omit it entirely between paragraphs.

           > You cannot explain away a wantonly immoral act because
           you think it is connected to some higher purpose.

           > Here is another paragraph about Picard wisdom.

     Consecutive blockquotes as above will be merged as paragraphs within a single block quote on
     output, even if styles (non-multiline and otherwise) are mixed.

     Block quotes may be nested within other block quotes, as may any other block elements such
     as headers, ordered/unordered lists, and code blocks.

           > ### hash-marked header 3
           >
           > > I'd be delighted to offer any advice
           > > I have on understanding women.
           > > When I have some, I'll let you know.
           >
           > 1.  advice list item 1
           > 2.  advice list item 2
           >
           > Here's the code to implement JLP's advice:

           >     yes | read engage

   Admonitions
     Also called "callouts", these special block quotes call attention to contents.  These are
     generally rendered as-is, but some output modes will specially render admonitions to
     highlight the content.

           > **Note**
           >
           > The computer is voiced by Majel Barrett.

     Callouts begin with a double-emphasis "Note" or "Warning", and omitting the initial newline
     suppresses white-space after the callout type.  This is GFM syntax.  The MDN syntax includes
     an initial phrase following the callout type and colon, and also supports the "Callout"
     type:

           > **Warning:** red alert.
           >
           > Romulan warbird decloaking!

   Lists
     Lists may be specified as ordered (numbered) or unordered.  Ordered lists are invoked as
     numbers followed by periods (e.g., “1.”) and rendered in a similar format.  Note: it does
     not matter which order or which numbers you use in your ordered lists, as all ordered lists
     start at one.

           1. Make.
           2. It.
           1. So. (Not 1. again!)

     If commonmark input parsing is enabled, list items may alternatively terminate with the
     right parenthesis:

           1) Live long
           2) Prosper

     To prevent lists erroneously started by a paragraph beginning with a number and period, use
     a backslash before the period.

           1987. The year TNG premiered.

           1987\. The year TNG premiered.

     Unordered lists, on the other hand, can be invoked using either asterisk (“*”), pluses
     (“+”), or hyphens (“-”), and can be a mix of all three styles.  Regardless the style, list
     items are rendered the same way.

           - Earl Grey tea.
           * Shakespeare.
           + Exotic fish.

     All nested block elements need a new line break, otherwise they will be rendered on the same
     line as the list item on output.  To insert paragraphs into a list item, indent each
     paragraph with either four spaces or one tab.

           - First list item

               Courage can be an emotion too.

               Things are only impossible until they're not.
           + Second list item
           + Third list item

     To insert block quotes into a list item, indent the block quote with four spaces or one tab
     prior to the right-angle bracket (“>”).

           * List item 1
           * List item 2

                > I am Locutus of Borg.

                > That is the cutest of Borg.

     Code blocks need to be indented twice (two tabs or eight leading spaces): once for being
     recognised within the list item, another for the code block itself.

           * Here is a list item for an indented code block:

                   alias path='echo -e ${PATH//:/\n}'

     To make list elements occur in tight sequence — like a grocery list — don't have an empty
     line between the items.

           - Phaser
           - Communicator

     On the other hand, if you want to render lists separated by white-space, use the following
     syntax:

           - A phaser is a type of weapon.

           - A communicator keeps Riker in contact with Troi.

     This applies to ordered and unordered list types.

   Task lists
     One form of an unordered list is task lists, a GFM extension.  These begin with checkboxes
     (checked or not), rendered similarly in the output.

           Star Trek series with episodes in the Delta quadrant:

           - [ ] Original series
           - [x] TNG
           - [ ] DS9
           - [x] Voyager
           - [ ] Enterprise
           - [ ] Discovery

     The check may be upper or lower case.  A space must follow the right square bracket.

   Definition Lists
     Definition lists are a PHP Extra extension.  They're similar to lists except in having key
     and value pairs, with keys being preceded by a blank line:

           Best understated characters:

           *Quark*
           : Armin Shimerman

           *Weyoun*
           : Jeffrey Combs

     Keys consist of a single line and may contain inline elements.  Like other lists, values may
     consist of arbitrary nested blocks.  There may be multiple consecutive values per key.  If
     the key and value are separated by a blank line, the list is emitted as if it contained
     block elements (usually output as spacing between key-value pairs).

   Code Blocks
     Code blocks consist of pre-formatted text, such as source code.  Each code block contains
     opaque/literal text.  This means that new lines and white spaces are retained — they're not
     formatted in any way, and any text inside the code block is not interpreted.  To invoke a
     code block, create a line break then indent each line with four spaces or one tab.

           Here is a paragraph about Bridge protocol

               Here is a code block for the command "Engage"

     Within a code block, text is escaped given the output format.  Therefore, characters that
     would normally need to be escaped in other text processing languages such as ampersands
     (“&”) do not need to be escaped.

           Here is how you start the program xterm:

               xterm &

   Horizontal Rules
     A horizontal rule is a line that goes across an output page.  These are invoked with three
     or more asterisks (“*”), hyphens (“-”), or underscores (“_”) on their own line.  Spaces
     between these characters are disregarded.

           ***
           * * *
           ---
           - - -
           ___
           _ _ _
           ___________________________

   Metadata
     Documents can include metadata that is not part of the main text.  The syntax follows the
     MMD and Pandoc specifications.

     In the MMD syntax, the block begins on the document's first line and continues until the
     first blank line.  Keys and values are separated by a colon, and pairs separated by a
     newline.  A key (and following value) must exist on the line beginning the metadata pair,
     but the value may span multiple lines.

           Title: Captain's log
           Author: Captain J-L Picard
           Summary: As part of an exchange program, we're taking
            aboard a Klingon officer to return the recent visit
            of Commander Riker to the cruiser Pagh.
           Stardate: 43917.4

     Alternatively, a block of MMD metadata may begin with a line of "---" and end with "---" or
     "...".

     If there are multiple lines of text in a metadata value, subsequent lines should (but need
     not) be offset with whitespace.  Otherwise, they must not have a colon in the value, else
     they will be construed as a subsequent pair's key.

     End each line with two spaces to ensure linebreaks are rendered on output for non-conforming
     Markdown renderers.  Moreover, beginning a document with a regular sentence containing a
     colon might invoke metadata.  To escape this, add one blank line to the beginning of the
     document.

     Metadata keys must consist of alphanumeric ASCII characters, the hyphen ("-"), or the
     underscore ("_").  They must have at least one character and are stripped of white-space and
     converted to lower case.

     Metadata values are opaque text: Markdown statements (e.g., italics, entities, etc.) are
     copied as-is.  The values will have leading white-space stripped, i.e., space following the
     colon.

     If multiple metadata keys resolve to the same name, the last invocation is retained.  This
     check happens after canonicalising the name by stripping spaces, converting to lower-case,
     and substituting unknown characters.

     In the Pandoc syntax, the block stops at the first line not starting with a percent sign or
     space.  Metadata is limited to at most three keys: title, author(s), and date.  The first
     line is for title, the second (if provided) for author(s), and the third (also if provided)
     for date.  Lines may continue by having a subsequent line begin with a space.  If only one
     leading-percent line is included, the metadata is only for the title; if two, for a title
     and author(s); and so on.  If a leading-percent line is blank, the corresponding metadata is
     left empty (unspecified).

           % A Skin of Evil
           % Tasha Yar
             Armus
           % 1988-04-2525

           Wow what a day...

     Multiple authors may be separated by multiple white-space (including newlines), a semicolon,
     or both.

     The Pandoc title line is automatically scanned for whether it's a manpage-style title:

           % TREK(6)

     lowdown recognises a manpage title from the open parenthesis followed by a number (or "n"),
     optional following characters, then a closing parenthesis.  If found, the title is broken
     down into title and section.  Any text following the title is further recognised as the
     source and, if a vertical bar is detected, what comes after as the volume.

           % TREK(6) OpenBSD | Games Manual

     These may be accessed with the title and section metadata keys, and optionally volume and
     source.

     Using either syntax, dates should be in the YYYY-MM-DD format, but can be in any format.
     Metadata values may be pasted into a document by referencing the [%key], such as using the
     above example, again with the caveat that Markdown annotations (italics, etc.) are copied
     verbatim:

           date: 43917.4

           It's currently stardate [%date].

     Or using Pandoc:

           %
           %
           % 43917.4
           It's currently stardate [%date].

   Mathematics
     Mathematics support is an extension of Markdown.  The extension only describes how the math
     blocks begin and end: the contained equations are usually in LaTeX and implemented in the
     front-end (e.g., HTML).  There are two types: inline and block.  Both may occur anywhere in
     a text stream.  Inline equations are rendered as part of the text; block equations are
     rendered on their own.

           This is an inline $f(x)$ function.
           This is a block $$f(x)$$ function.
           This is also an inline \\(f(x)\\) function.
           This is also a block \\[f(x)\\] function.

   Tables
     Tables are a GFM (GitHub-flavoured Markdown) extension of the basic syntax.  They consist of
     a table header and body, and columns may be left, right, or centre justified.

           | Officer         | Rank                 |
           | --------------: | -------------------- |
           | Jean-Luc Picard | Captain              |
           | Worf            | Lieutenant Commander |
           | Data            | Lieutenant Commander |
           | William Riker   | Commander            |

     The table header must be followed by a line of hyphens with at least three hyphen/colons per
     column.  Columns are separated by vertical bars.  The colon indicates alignment: a colon at
     the beginning means left justified; at the right for right justified, and both for centred.

     The leading and trailing column separator is superfluous.  Table data is not necessary, but
     the table header is.  The minimum table structure for the above is:

           Officer | Rank
           --:|---
           Jean-Luc Picard | Captain

     Table columns may contain arbitrary inline elements.

   Footnote Definition
     Footnotes are a MMD extension of the basic syntax.  Footnote definitions may occur anywhere
     in the text (except within blocks) and are “pointed to” by a Footnote Reference.  They
     consist of the footnote name (in square brackets, preceded by the caret), a colon, then
     everything remaining in the block is the footnote content.

           [^pt]:
               Klingon insult, meaning something like "weirdo," deriving from
               the verb "to be weird" (**taQ**), with and [sic] you (plural)
               imperative prefix (**pe-**).

     Footnote contents may be on the same line as the colon.  The footnote name is rendered as a
     number.  If a footnote definition is not referred to, it is not printed.

   HTML Blocks
     Embedded HTML is discouraged, as it inhibits formatting into non-HTML output, but is still
     accepted.  Blocks of HTML must begin with a recognised HTML block-level element.

     In the original Markdown, block-level elements were well-defined by HTML4.  HTML5 elements
     are also accepted, but as there is no concept of block-level in HTML5, these are non-
     canonical.  Accepted elements are <address>, <article>, <aside>, <blockquote>, <del>,
     <details>, <dialog>, <dd>, <div>, <dl>, <dt>, <fieldset>, <figcaption>, <figure>, <footer>,
     <form>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <header>, <hgroup>, <iframe>, <ins>, <li>,
     <main>, <math>, <nav>, <noscript>, <ol>, <p>, <pre>, <section>, <script>, <style>, <table>,
     <ul>.  The void elements <br />, <hr />, <link />, and <meta /> are also recognised, and
     need not be self-closed.

INLINE ELEMENTS

     Elements within a block element.  Sometimes called (inline) elements.  For example, normal
     text, a span of emphasised text, or a hyperlink.  An inline element cannot contain a block
     element, but can contain other inline elements.

   Emphasis
     There are two different styles of emphasis: strong, usually rendered as bold; and emphasis,
     usually rendered as italics.  This is confusing, so sometimes the former is referred to as a
     “double-emphasis” while the latter is a “single-emphasis”.

     Text surrounded by a single asterisk (“*”) or underscore (“_”), the single-emphasis variant,
     is traditionally rendered with italics.

           *Captain Picard*
           _Captain Picard_

     Text surrounded by a double asterisk (“**”) or underscore (“__”), the double-emphasis
     variant, is traditionally rendered as bold.

           **Jean-Luc Picard**
           __Jean-Luc Picard__

     Emphasis may occur within the middle of a word:

           En*ter*prise

     In order to produce a literal asterisk (“*”) or underscore (“_”) simply surround the
     character by white space.

           The ship * USS Enterprise * will not be emphasized

     Two additional types of double-emphasis are the strike-through and highlight.  These are
     produced by pairs of tilde and equal characters, respectively:

           ~~Kirk~~Picard is the best ==captain==.

     The highlight variant may be enabled in lowdown(1) with highlight parsing enabled.  It's
     disabled by default because if used at the beginning of a line it may be erroneously
     interpreted as a section.

   Links
     There are two types of links: inline and reference.  In both cases, the linked text is
     denoted by square brackets (“[]”).  An inline link uses parentheses (“()”) containing the
     URL immediately following the linked text in square brackets to invoke the link.

           [text to link](https://bsd.lv)

     Local references may be absolute or relative paths:

           [Picard](/Picard)

     A reference link, on the other hand, keeps the URL outside of the text — usually in the
     footnotes.  Define a reference link anywhere in a document by a title in square brackets
     (“[]”) followed a colon (“:”) followed by the corresponding URL or path, then an optional
     title.

           [link1]: https://www.bsd.lv/picard.jpg "Optional Title"

     The title may be delimited with single quotes, double quotes, or parenthesis.  It is only
     rendered in HTML output.  It encompasses all text until the last delimiter before the end of
     line, so it may contain delimiters.  The title may be on its own line.

     Reference the link anywhere in your text using [text to the link] and the same [link title],
     both in square brackets (“[]”) next to each other:

           Text about [Captain Picard][link1].

     References need not follow the definition: both may appear anywhere in relation to the
     other.

     Reference and inline links may be followed by PHP Extra attributes.

           Lowdown [homepage][home] or
           [github](https://github.com/kristapsdz/lowdown){ .gh #link1 }.

           [home]: https://kristaps.bsd.lv/lowdown { .home #link2 }

     For inline links, the open brace must immediately follow the closing parenthesis.
     Attributes are separated by spaces.

     Values with a leading period (".class") are interpreted as HTML (CSS) or OpenDocument
     classes, and values with a leading pound symbol ("#id") are interpreted as in-document link
     identifiers.

   Automatic Links
     Automatic links are links to URLs or emails addresses that do not require text to links;
     rather, the full link or email address is inferred from the text.  To invoke an automatic
     link, surround the link or email address with angle brackets (“<>”), for example:

           <https://bsd.lv/>
           <kristaps@localhost>

   Images
     The image syntax resembles the links syntax.  The key difference is that images require an
     exclamation mark (“!”) before the text to link surrounded by square brackets (“[]”).

           ![Image text](imageurl.jpg)

     Just like with links, there are both inline and reference image links.

     The inline style consists of an exclamation mark (“!”) followed by the alternate text (which
     may be empty) surrounded by square brackets “([])” followed by the URL or the path in
     parentheses “(())”.

     Unlike link text within square brackets, the alternate text is interpreted as-is.  Thus,
     passing Markdown or HTML entities will be passed directly to output (escaped according to
     output medium).  Alternate text may not begin with the caret (“^”) or percent (“%”), else
     they will be interpreted as footnote or metadata references, respectively.

     The parentheses may contain optional dimensions (widthx[height]) starting with an equal sign
     or a quoted (single or double quotes) title in any order after the URL or path.  These
     dimensions are pixel sizes.

           ![Picard](https://bsd.lv/picard.jpg =250x250 'Engage!')

     The reference style definition consists of an image identifier surrounded by square brackets
     “([])” followed by a colon “(:)” followed by an image URL or path to image and optional
     title attribute in double quotation marks.

            [image1]: https://bsd.lv/picard.jpg "Picture of Picard"

     Invoking the image reference is as follows:

           A picture of the captain: ![Captain Picard][image1]

     As with regular reference links, the definition and references may occur anywhere in
     relation to each other.

     Images may also be followed by PHP Extra attributes for classes, identifiers, and width and
     height.  Implementation of these depends on the output medium.

           ![Picard](https://bsd.lv/picard.jpg){width=20% .class}

     The open brace must immediately follow the closing parenthesis.  Attributes are separated by
     spaces.

     Value pairs "width=xx" and "height=xx" are interpreted as HTML (CSS), OpenOffice, or LaTeX
     dimensions.  These override set pixel dimensions.  Percentages are understood by all three
     media; otherwise, dimension units are interpreted according to the medium.

     Values with a leading period (".class") are interpreted as HTML (CSS) or OpenDocument
     classes, and values with a leading pound symbol ("#id") are interpreted as in-document link
     identifiers.

   Code
     In addition to code blocks, inline code spans may be specified within paragraphs or other
     block or inline elements.  To invoke a span of code, surround the code using backtick quotes
     (“`”).

           I need your IP address to scp you Picard pics.
           Use the `ifconfig iwm0` command.

     To include literal backticks (“`”) within a code span, surround the code using multiple
     backticks (“(``”).

           ``Here is a span of code with `backticks` inside it.``

     If you have a literal backtick at the start or end of the span of code, leave a space
     between the literal backtick and the delimiting backticks.

           `` `So many backticks.` ``

   Footnote Reference
     Footnotes are a MMD extension of the basic syntax.  Footnote references point into a block-
     level Footnote Definition.  They consist of the footnote name in square brackets, preceded
     by the caret.

           P'tahk[^pt], tell me who you are, or I will kill you right here!

     The footnote name is rendered as a number.  There may only be one footnote reference per
     definition.  If a footnote reference refers to an unknown definition, or if it has already
     been used in referring to a definition, it is printed as-is.  Footnote definitions without
     references are not printed.  Nested footnotes are not allowed.

   Superscripts
     Uses the caret (“^”) to start a superscript, then another to end it.  Between these, white-
     space is not allowed.  This is the GFM style.

           Though a great book, Q^2^ isn't Star Trek canon.

     If "short" (traditional) style super-scripts are enabled, start with a caret, continuing to
     white-space; or, if starting with an open parenthesis, continuing to the close parenthesis
     with possible white-space.

           Though a great book, Q^2 isn't Star Trek canon.

   HTML Content
     While block-level HTML must begin with a recognised block-level HTML element, span-level
     HTML need only begin and end with angle brackets, and not contain a hyperlink.

     Thus, <p>, <Leonard Nimoy>, and <span class="foo"> are all accepted.  Even malformed
     content, such as <span class="foo> is accepted, so long as it begins and ends with angle
     brackets.

ESCAPES

   Automatic Escapes
     Output is automatically escaped depending upon the medium.  For example, HTML output will
     properly escape angle brackets “(<)” and ampersands “(&)” to produce conformant HTML.  The
     same goes with man(7) output in escaping leading periods and so forth.

   Backslash Escapes
     Backslash escapes render literal characters that would otherwise invoke a particular block
     or inline element.  For example, surrounding a phrase with single asterisks renders it as an
     emphasis:

           *Captain Picard*

     However, if you want to invoke those italics as literal characters, escape those asterisks
     using backslashes (“\”).

           \*Captain Picard\*

     The following characters may be escaped to produce literal text:

           *       asterisk
           \       backslash
           `       backtick
           {       curly brace
           !       exclamation mark
           #       hash mark
           -       minus sign
           (       parentheses
           .       period
           +       plus sign
           [       square bracket
           _       underscore

TYPOGRAPHY

     lowdown(1) renders certain character sequences for easier reading.  This is called "smart
     formatting".  The following character sequences are converted to output-specific glyphs.
     The table shows whether the sequences must be on word boundaries.

           (c)      copyright
           (r)      registered
           (tm)     trademark
           (sm)     service mark
           ...      ellipsis
           . . .    ellipsis
           ---      em-dash
           --       en-dash
           1/4      one-quarter      full word boundary
           1/4th    one-quarter      full word boundary
           3/4      three-quarters   full word boundary
           3/4th    three-quarters   full word boundary
           3/4ths   three-quarters   full word boundary
           1/2      one-half         full word boundary
           "        left-double      left word boundary
           "        right-double     right word boundary
           '        left-single      left word boundary
           '        right-single     not left word boundary

     Word boundaries are defined by white-space (including the end of blocks, such as paragraphs,
     or end of file) or punctuation.  Left word boundary refers to white-space or a left
     parenthesis or square bracket to the left of the sequence.  Right refers to white-space or
     punctuation to the right.

     Smart quotes (single and double) are not context aware: using a left or right quote depends
     upon the characters surrounding the quote, not whether a prior quote mark has already been
     used.

SEE ALSO

     lowdown(1)

STANDARDS

     The Markdown syntax accepted by lowdown(1) conforms to John Gruber's original Markdown
     implementation.  Extensions to the language are specifically noted.  They include:

     CommonMark: http://commonmark.org

     GFM: https://github.github.com/gfm

     Multimarkdown (MMD): http://fletcherpenney.net/multimarkdown

     Pandoc: https://pandoc.org/MANUAL.html

     PHP Extra: https://michelf.ca/projects/php-markdown/extra

AUTHORS

     The lowdown reference was originally written by Christina Sophonpanich and is maintained by
     Kristaps Dzonsons <kristaps@bsd.lv>.