<commit_before>.\"	$Id$
.\"
.\" Copyright (c) 2017 <NAME> <<EMAIL>>
.\" Copyright (c) 2017 <NAME> <<EMAIL>>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN 5
.Os
.
.
.Sh NAME
.Nm lowdown
.Nd Markdown reference for lowdown
.
.
.Sh DESCRIPTION
Markdown is a simple, plain-text formatting language.
.Dq Plain-text
in this case means the document input looks similar to the output, less
the formatting niceties (boxed tables, clickable links, etc.) provided
by the output medium.
For example:
.Bd -literal -offset indent
# 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 \e*Best Star Trek Captain\e*, 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...
.Ed
.Pp
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 span elements: normal text, emphasised text
(bold and italised), an image, a link, and a span of code.
.Pp
This document describes the Markdown syntax accepted by
.Xr lowdown 1 .
.
.
.Sh BLOCK ELEMENTS
A block element starts on a new line and extends to the next blank line
or block element.
A block element contains span elements.
.
.Ss Paragraphs and Line Breaks
A paragraph is made up of one or more lines of text possibly containing
span elements.
Paragraphs are separated by blank lines.
To insert a hard line break, insert two spaces at the end of the line.
.
.Ss Headers
Markdown specifies two styles of headers: underlined
.Pq Dq setext
hash-marked
.Pq Dq atx .
For underlined headers, underline the given word using equal signs
.Pq Dq =
for first-level headers and dashes
.Pq Dq \&-
for second-level headers.
.Bd -literal -offset indent
This is an underlined header 1
==============================
.Ed
.Pp
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.
.Bd -literal -offset indent
## This is a hash-marked header 2
.Ed
.
.Ss Block Quotes
Markdown supports block quoting by invoking a single right-angle bracket
(>) followed by a space at the start of each line and between paragraphs.
.Bd -literal -offset indent
> 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).
.Ed
.Pp
Markdown also allows you to be lazy with block quotes: you can choose to
only invoke the right-angle bracket at the start of a paragraph and omit
it entirely between paragraphs.
.Bd -literal -offset indent
> 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.
.Ed
.Pp
Consecutive blockquotes as above will be merged as paragraphs within a
single block quote on output, even if styles ("lazy" and otherwise) are
mixed.
.Pp
Markdown supports nested block quotes as well as other Markdown elements
within block quotes, such as headers, ordered/unordered lists, and code
blocks.
.Bd -literal -offset indent
> ### atx 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:

>     return shell_exec("echo $input | $womenadvice_script")
.Ed
.
.Ss Lists
Markdown supports both ordered and unordered lists.
Ordered lists are invoked as numbers followed by periods (1.) and
rendered in the same format.
Note: it does not matter which order or which numbers you use in your ordered
lists, Markdown will generate an ordinal list from your input as long as you
start your list with number one (1.).
.Bd -literal -offset indent
1. Make.
2. It.
1. So. (Not 1. again!)
.Ed
.Pp
Note that starting a line with a single word that consists of any number and
ending it with a period could invoke an ordered list.
To escape this, use a blackslash before the period.
.Bd -literal -offset indent
1987. The year TNG premiered.

1987\e. The year TNG premiered.
.Ed
.Pp
Unordered lists, on the other hand, can be invoked using either
asterisks (*), pluses (+), or hyphens (-), and can be a mix of all
three, but are rendered as bullet points.
.Bd -literal -offset indent
- Earl Grey tea.
* Shakespeare.
+ Exotic fish.
.Ed
.Pp
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.
.Bd -literal -offset indent
- First list item

    Courage can be an emotion too.

    Things are only impossible until they're not.
+ Second list item
+ Third list item
.Ed
.Pp
To insert block quotes into a list item, indent the block quote with
four spaces or one tab prior to the right-angle bracket.<commit_msg>Use more mdoc(7) for character escapes.  Fix erroneous statement that lists need to be started with "1.": they can start with any number.  Change code block to be more in tune with the manpage's... humour.<commit_after>.\"	$Id$
.\"
.\" Copyright (c) 2017 <NAME> <<EMAIL>>
.\" Copyright (c) 2017 <NAME> <<EMAIL>>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt LOWDOWN 5
.Os
.
.
.Sh NAME
.Nm lowdown
.Nd Markdown reference for lowdown
.
.
.Sh DESCRIPTION
Markdown is a simple, plain-text formatting language.
.Dq Plain-text
in this case means the document input looks similar to the output, less
the formatting niceties (boxed tables, clickable links, etc.) provided
by the output medium.
For example:
.Bd -literal -offset indent
# 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 \e*Best Star Trek Captain\e*, 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...
.Ed
.Pp
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 span elements: normal text, emphasised text
(bold and italised), an image, a link, and a span of code.
.Pp
This document describes the Markdown syntax accepted by
.Xr lowdown 1 .
.
.
.Sh BLOCK ELEMENTS
A block element starts on a new line and extends to the next blank line
or block element.
A block element contains span elements.
.
.Ss Paragraphs and Line Breaks
A paragraph is made up of one or more lines of text possibly containing
span elements.
Paragraphs are separated by blank lines.
To insert a hard line break, insert two spaces at the end of the line.
.
.Ss Headers
Markdown specifies two styles of headers: underlined
.Pq Dq setext
hash-marked
.Pq Dq atx .
For underlined headers, underline the given word using equal signs
.Pq Dq =
for first-level headers and dashes
.Pq Dq \&-
for second-level headers.
.Bd -literal -offset indent
This is an underlined header 1
==============================
.Ed
.Pp
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.
.Bd -literal -offset indent
## This is a hash-marked header 2
.Ed
.
.Ss Block Quotes
Markdown supports block quoting by invoking a single right-angle bracket
.Pq Dq >
followed by a space at the start of each line and between paragraphs.
.Bd -literal -offset indent
> 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).
.Ed
.Pp
Markdown allows you to be lazy with block quotes: you need only invoke
the right-angle bracket at the start of a paragraph and omit it entirely
between paragraphs.
.Bd -literal -offset indent
> 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.
.Ed
.Pp
Consecutive blockquotes as above will be merged as paragraphs within a
single block quote on output, even if styles
.Dq ( lazy
and otherwise) are mixed.
.Pp
Markdown supports nested block quotes as well as other block elements
within block quotes, such as headers, ordered/unordered lists, and code
blocks.
.Bd -literal -offset indent
> ### 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
.Ed
.
.Ss Lists
Markdown supports ordered and unordered lists.
Ordered lists are invoked as numbers followed by periods
.Pq e.g., Dq 1.
and rendered in a similar format.
.Em Note :
it does not matter which order or which numbers you use in your ordered
lists, as Markdown will generate an ordinal list from your input
regardless.
.Bd -literal -offset indent
1. Make.
2. It.
1. So. (Not 1. again!)
.Ed
.Pp
To prevent lists erroneously started by a paragraph beginning with a
number and period, use a backslash before the period.
.Bd -literal -offset indent
1987. The year TNG premiered.

1987\e. The year TNG premiered.
.Ed
.Pp
Unordered lists, on the other hand, can be invoked using either
asterisk
.Pq Dq * ,
pluses
.Pq Dq + , 
or hyphens
.Pq Dq \- ,
and can be a mix of all three styles.
Regardless the style, list items are rendered the same way.
.Bd -literal -offset indent
- Earl Grey tea.
* Shakespeare.
+ Exotic fish.
.Ed
.Pp
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.
.Bd -literal -offset indent
- First list item

    Courage can be an emotion too.

    Things are only impossible until they're not.
+ Second list item
+ Third list item
.Ed
.Pp
To insert block quotes into a list item, indent the block quote with
four spaces or one tab prior to the right-angle bracket
.Pq Dq > .
{'fraction_non_alphanumeric': 0.07677825980191537, 'fraction_numerical': 0.005975280347057379, 'mean_word_length': 3.591506952273581, 'pattern_counts': {'":': 1, '<': 15, '<?xml version=': 0, '>': 62, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3772873', 'n_tokens_mistral': 3587, 'n_tokens_neox': 3359, 'n_words': 1949}