` tags in the HTML output. For example, this input:
-.Bd -literal -offset indent
- * Bird
- * Magic
-.Ed
-.Pp
-will turn into:
-.Bd -literal -offset indent
-
-.Ed
-.Pp
-It's worth noting that it's possible to trigger an ordered list by
-accident, by writing something like this:
-.Bd -literal -offset indent
- 1986. What a great season.
-.Ed
-.Pp
-In other words, a *number-period-space* sequence at the beginning of a
-line. To avoid this, you can backslash-escape the period:
-.Bd -literal -offset indent
- 1986\\. What a great season.
-.Ed
-.Pp
-.Ss Code Blocks
-Pre-formatted code blocks are used for writing about programming or
-markup source code. Rather than forming normal paragraphs, the lines
-of a code block are interpreted literally. Markdown wraps a code block
-in both `` and `` tags.
-.Pp
-To produce a code block in Markdown, simply indent every line of the
-block by at least 4 spaces or 1 tab. For example, given this input:
-.Bd -literal -offset indent
- This is a normal paragraph:
-
- This is a code block.
-.Ed
-.Pp
-.Nm
-will generate:
-.Bd -literal -offset indent
- This is a normal paragraph:
-
- This is a code block.
-
-.Ed
-.Pp
-One level of indentation -- 4 spaces or 1 tab -- is removed from each
-line of the code block. For example, this:
-.Bd -literal -offset indent
- Here is an example of AppleScript:
-
- tell application "Foo"
- beep
- end tell
-.Ed
-.Pp
-will turn into:
-.Bd -literal -offset indent
- Here is an example of AppleScript:
-
- tell application "Foo"
- beep
- end tell
-
-.Ed
-.Pp
-A code block continues until it reaches a line that is not indented
-(or the end of the article).
-.Pp
-Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
-are automatically converted into HTML entities. This makes it very
-easy to include example HTML source code using Markdown -- just paste
-it and indent it, and Markdown will handle the hassle of encoding the
-ampersands and angle brackets. For example, this:
-.Bd -literal -offset indent
-
-.Ed
-.Pp
-will turn into:
-.Bd -literal -offset indent
- <div class="footer">
- © 2004 Foo Corporation
- </div>
-
-.Ed
-.Pp
-Regular Markdown syntax is not processed within code blocks. E.g.,
-asterisks are just literal asterisks within a code block. This means
-it's also easy to use Markdown to write about Markdown's own syntax.
-.Ss Horizontal Rules
-You can produce a horizontal rule tag (`
`) by placing three or
-more hyphens, asterisks, or underscores on a line by themselves. If you
-wish, you may use spaces between the hyphens or asterisks. Each of the
-following lines will produce a horizontal rule:
-.Bd -literal -offset indent
- * * *
-
- ***
-
- *****
-
- - - -
-
- ---------------------------------------
-.Ed
-.Pp
-.Sh Span Elements
-.Ss Links
-.Nm
-supports two style of links:
-.Em inline
-and
-.Em reference .
-.Pp
-In both styles, the link text is delimited by [square brackets].
-.Pp
-To create an inline link, use a set of regular parentheses immediately
-after the link text's closing square bracket. Inside the parentheses,
-put the URL where you want the link to point, along with an *optional*
-title for the link, surrounded in quotes. For example:
-.Bd -literal -offset indent
- This is [an example](http://example.com/ "Title") inline link.
-
- [This link](http://example.net/) has no title attribute.
-.Ed
-.Pp
-Will produce:
-.Bd -literal -offset indent
- This is
- an example inline link.
-
- This link has no
- title attribute.
-.Ed
-.Pp
-If you're referring to a local resource on the same server, you can
-use relative paths:
-.Bd -literal -offset indent
- See my [About](/about/) page for details.
-.Ed
-.Pp
-Reference-style links use a second set of square brackets, inside
-which you place a label of your choosing to identify the link:
-.Bd -literal -offset indent
- This is [an example][id] reference-style link.
-.Ed
-.Pp
-You can optionally use a space to separate the sets of brackets:
-.Bd -literal -offset indent
- This is [an example] [id] reference-style link.
-.Ed
-.Pp
-Then, anywhere in the document, you define your link label like this,
-on a line by itself:
-.Bd -literal -offset indent
- [id]: http://example.com/ "Optional Title Here"
-.Ed
-.Pp
-That is:
-.Bl -bullet
-.It
-Square brackets containing the link identifier (optionally
-indented from the left margin using up to three spaces);
-.It
-followed by a colon;
-.It
-followed by one or more spaces (or tabs);
-.It
-followed by the URL for the link;
-.It
-optionally followed by a title attribute for the link, enclosed
-in double or single quotes, or enclosed in parentheses.
-.El
-.Pp
-The following three link definitions are equivalent:
-.Bd -literal -offset indent
- [foo]: http://example.com/ "Optional Title Here"
- [foo]: http://example.com/ 'Optional Title Here'
- [foo]: http://example.com/ (Optional Title Here)
-.Ed
-.Pp
-.Em Note :
-There is a known bug in Markdown.pl 1.0.1 which prevents
-single quotes from being used to delimit link titles.
-.Pp
-The link URL may, optionally, be surrounded by angle brackets:
-.Bd -literal -offset indent
- [id]: "Optional Title Here"
-.Ed
-.Pp
-You can put the title attribute on the next line and use extra spaces
-or tabs for padding, which tends to look better with longer URLs:
-.Bd -literal -offset indent
- [id]: http://example.com/longish/path/to/resource/here
- "Optional Title Here"
-.Ed
-.Pp
-Link definitions are only used for creating links during Markdown
-processing, and are stripped from your document in the HTML output.
-.Pp
-Link definition names may constist of letters, numbers, spaces, and
-punctuation -- but they are
-.Em not
-case sensitive. E.g. these two
-links:
-.Bd -literal -offset indent
- [link text][a]
- [link text][A]
-.Ed
-.Pp
-are equivalent.
-.Pp
-The
-.Em implicit link name
-shortcut allows you to omit the name of the
-link, in which case the link text itself is used as the name.
-Just use an empty set of square brackets -- e.g., to link the word
-.Qq Google
-to the google.com web site, you could simply write:
-.Bd -literal -offset indent
- [Google][]
-.Ed
-.Pp
-And then define the link:
-.Bd -literal -offset indent
- [Google]: http://google.com/
-.Ed
-.Pp
-Because link names may contain spaces, this shortcut even works for
-multiple words in the link text:
-.Bd -literal -offset indent
- Visit [Daring Fireball][] for more information.
-.Ed
-.Pp
-And then define the link:
-.Bd -literal -offset indent
- [Daring Fireball]: http://daringfireball.net/
-.Ed
-.Pp
-Link definitions can be placed anywhere in your Markdown document. I
-tend to put them immediately after each paragraph in which they're
-used, but if you want, you can put them all at the end of your
-document, sort of like footnotes.
-.Pp
-Here's an example of reference links in action:
-.Bd -literal -offset indent
- I get 10 times more traffic from [Google] [1] than from
- [Yahoo] [2] or [MSN] [3].
-
- [1]: http://google.com/ "Google"
- [2]: http://search.yahoo.com/ "Yahoo Search"
- [3]: http://search.msn.com/ "MSN Search"
-.Ed
-.Pp
-Using the implicit link name shortcut, you could instead write:
-.Bd -literal -offset indent
- I get 10 times more traffic from [Google][] than from
- [Yahoo][] or [MSN][].
-
- [google]: http://google.com/ "Google"
- [yahoo]: http://search.yahoo.com/ "Yahoo Search"
- [msn]: http://search.msn.com/ "MSN Search"
-.Ed
-.Pp
-Both of the above examples will produce the following HTML output:
-.Bd -literal -offset indent
- I get 10 times more traffic from Google than from
- Yahoo
- or
- MSN.
-.Ed
-.Pp
-For comparison, here is the same paragraph written using
-Markdown's inline link style:
-.Bd -literal -offset indent
- I get 10 times more traffic from
- [Google](http://google.com/ "Google") than from
- [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
- [MSN](http://search.msn.com/ "MSN Search").
-.Ed
-.Pp
-The point of reference-style links is not that they're easier to
-write. The point is that with reference-style links, your document
-source is vastly more readable. Compare the above examples: using
-reference-style links, the paragraph itself is only 81 characters
-long; with inline-style links, it's 176 characters; and as raw HTML,
-it's 234 characters. In the raw HTML, there's more markup than there
-is text.
-.Pp
-With Markdown's reference-style links, a source document much more
-closely resembles the final output, as rendered in a browser. By
-allowing you to move the markup-related metadata out of the paragraph,
-you can add links without interrupting the narrative flow of your
-prose.
-.Ss Emphasis
-Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
-emphasis. Text wrapped with one `*` or `_` will be wrapped with an
-HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML
-`` tag. E.g., this input:
-.Bd -literal -offset indent
- *single asterisks*
-
- _single underscores_
-
- **double asterisks**
-
- __double underscores__
-.Ed
-.Pp
-will produce:
-.Bd -literal -offset indent
- single asterisks
-
- single underscores
-
- double asterisks
-
- double underscores
-.Ed
-.Pp
-You can use whichever style you prefer; the lone restriction is that
-the same character must be used to open and close an emphasis span.
-.Pp
-Emphasis can be used in the middle of a word:
-.Bd -literal -offset indent
- un*fucking*believable
-.Ed
-.Pp
-But if you surround an `*` or `_` with spaces, it'll be treated as a
-literal asterisk or underscore.
-.Pp
-To produce a literal asterisk or underscore at a position where it
-would otherwise be used as an emphasis delimiter, you can backslash
-escape it:
-.Bd -literal -offset indent
- \\*this text is surrounded by literal asterisks\\*
-.Ed
-.Pp
-.Ss Code
-To indicate a span of code, wrap it with backtick quotes (`` ` ``).
-Unlike a pre-formatted code block, a code span indicates code within a
-normal paragraph. For example:
-.Bd -literal -offset indent
- Use the `printf()` function.
-.Ed
-.Pp
-will produce:
-.Bd -literal -offset indent
- Use the printf()
function.
-.Ed
-.Pp
-To include a literal backtick character within a code span, you can use
-multiple backticks as the opening and closing delimiters:
-.Bd -literal -offset indent
- ``There is a literal backtick (`) here.``
-.Ed
-.Pp
-which will produce this:
-.Bd -literal -offset indent
- There is a literal backtick (`) here.
-.Ed
-.Pp
-The backtick delimiters surrounding a code span may include spaces --
-one after the opening, one before the closing. This allows you to place
-literal backtick characters at the beginning or end of a code span:
-.Bd -literal -offset indent
- A single backtick in a code span: `` ` ``
-
- A backtick-delimited string in a code span: `` `foo` ``
-.Ed
-.Pp
-will produce:
-.Bd -literal -offset indent
- A single backtick in a code span: `
-
- A backtick-delimited string in a code span: `foo`
-.Ed
-.Pp
-With a code span, ampersands and angle brackets are encoded as HTML
-entities automatically, which makes it easy to include example HTML
-tags. Markdown will turn this:
-.Bd -literal -offset indent
- Please don't use any `