view release on metacpan or  search on metacpan

doc/src/reStructuredText.rst  view on Meta::CPAN

a text block.  The same whitespace and punctuation that serves to
delimit words in written text is used to delimit the inline markup
syntax constructs.  The text within inline markup may not begin or end
with whitespace.  Arbitrary `character-level inline markup`_ is
supported although not encouraged.  Inline markup can be nested.

There are nine inline markup constructs.  Five of the constructs use
identical start-strings and end-strings to indicate the markup:

- emphasis_: "*"
- `strong emphasis`_: "**"
- `interpreted text`_: "`"
- `inline literals`_: "``"
- `substitution references`_: "|"

Three constructs use different start-strings and end-strings:

- `inline internal targets`_: "_`" and "`"
- `footnote references`_: "[" and "]_"
- `hyperlink references`_: "`" and "\`_" (phrases), or just a
  trailing "_" (single words)

`Standalone hyperlinks`_ are recognized implicitly, and use no extra
markup.

The inline markup start-string and end-string recognition rules are as
follows.  If any of the conditions are not met, the start-string or
end-string will not be recognized or processed.

1. Inline markup start-strings must start a text block or be
   immediately preceded by whitespace or one of::

       ' " ( [ { < - / :

2. Inline markup start-strings must be immediately followed by
   non-whitespace.

3. Inline markup end-strings must be immediately preceded by
   non-whitespace.

4. Inline markup end-strings must end a text block or be immediately
   followed by whitespace or one of::

       ' " ) ] } > - / : . , ; ! ? \

5. If an inline markup start-string is immediately preceded by a
   single or double quote, "(", "[", "{", or "<", it must not be
   immediately followed by the corresponding single or double quote,
   ")", "]", "}", or ">".

6. An inline markup end-string must be separated by at least one
   character from the start-string.

7. An unescaped backslash preceding a start-string or end-string will
   disable markup recognition, except for the end-string of `inline
   literals`_.  See `Escaping Mechanism`_ above for details.

For example, none of the following are recognized as containing inline
markup start-strings:

- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_*
- double asterisks: **  a**b O(N**2) etc.
- backquotes: ` `` etc.
- underscores: _ __ __init__ __init__() etc.
- vertical bars: | || etc.

It may be desirable to use inline literals for some of these anyhow,
especially if they represent code snippets.  It's a judgment call.

These cases *do* require either literal-quoting or escaping to avoid
misinterpretation::

    *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt

The inline markup recognition rules were devised intentionally to
allow 90% of non-markup uses of "*", "`", "_", and "|" *without*
resorting to backslashes.  For 9 of the remaining 10%, use inline
literals or literal blocks::

    "``\*``" -> "\*" (possibly in another font or quoted)

Only those who understand the escaping and inline markup rules should
attempt the remaining 1%.  ;-)

Inline markup delimiter characters are used for multiple constructs,
so to avoid ambiguity there must be a specific recognition order for
each character.  The inline markup recognition order is as follows:

- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_
  ("*").

- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_
  (leading "_`", trailing "`"), are mutually independent, and are
  recognized before phrase `hyperlink references`_ (leading "`",
  trailing "\`_") and `interpreted text`_ ("`").

- Trailing underscores: Footnote references ("[" + label + "]_") and
  simple `hyperlink references`_ (name + trailing "_") are mutually
  independent.

- Vertical bars: `Substitution references`_ ("|") are independently
  recognized.

- `Standalone hyperlinks`_ are the last to be recognized.


Character-Level Inline Markup
-----------------------------

It is possible to mark up individual characters within a word with
backslash escapes (see `Escaping Mechanism`_ above).  Backslash
escapes can be used to allow arbitrary text to immediately follow
inline markup::

    Python ``list``\s use square bracket syntax.

The backslash will disappear from the processed document.  The word
"list" will appear as inline literal text, and the letter "s" will
immediately follow it as normal text, with no space in-between.

Arbitrary text may immediately precede inline markup using