view release on metacpan or  search on metacpan

t/40_writers/html.init/reStructuredText.rst  view on Meta::CPAN

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 markup is not supported;
it is not possible to mark up individual characters within a word.
Inline markup cannot 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.


Emphasis
--------

DTD element: emphasis.

Start-string = end-string = "*".

Text enclosed by single asterisk characters is emphasized::

    This is *emphasized text*.

Emphasized text is typically displayed in italics.


Strong Emphasis