view release on metacpan or  search on metacpan

t/40_writers/html.init/reStructuredText.html  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 markup is not supported;
it is not possible to mark up individual characters within a word.
Inline markup cannot be nested.</p>
<p>There are nine inline markup constructs.  Five of the constructs use
identical start-strings and end-strings to indicate the markup:</p>
<ul class="simple">
<li><a class="reference" href="#emphasis">emphasis</a>: "*"</li>
<li><a class="reference" href="#strong-emphasis">strong emphasis</a>: "**"</li>
<li><a class="reference" href="#interpreted-text">interpreted text</a>: "`"</li>
<li><a class="reference" href="#inline-literals">inline literals</a>: "``"</li>
<li><a class="reference" href="#substitution-references">substitution references</a>: "|"</li>
</ul>
<p>Three constructs use different start-strings and end-strings:</p>
<ul class="simple">
<li><a class="reference" href="#inline-internal-targets">inline internal targets</a>: "_`" and "`"</li>
<li><a class="reference" href="#footnote-references">footnote references</a>: "[" and "]_"</li>
<li><a class="reference" href="#hyperlink-references">hyperlink references</a>: "`" and "`_" (phrases), or just a
trailing "_" (single words)</li>
</ul>
<p><a class="reference" href="#standalone-hyperlinks">Standalone hyperlinks</a> are recognized implicitly, and use no extra
markup.</p>
<p>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.</p>
<ol class="arabic">
<li><p class="first">Inline markup start-strings must start a text block or be
immediately preceded by whitespace or one of:</p>
<pre class="literal-block">' " ( [ { &lt; - / :
</pre>
</li>
<li><p class="first">Inline markup start-strings must be immediately followed by
non-whitespace.</p>
</li>
<li><p class="first">Inline markup end-strings must be immediately preceded by
non-whitespace.</p>
</li>
<li><p class="first">Inline markup end-strings must end a text block or be immediately
followed by whitespace or one of:</p>
<pre class="literal-block">' " ) ] } &gt; - / : . , ; ! ?
</pre>
</li>
<li><p class="first">If an inline markup start-string is immediately preceded by a
single or double quote, "(", "[", "{", or "&lt;", it must not be
immediately followed by the corresponding single or double quote,
")", "]", "}", or "&gt;".</p>
</li>
<li><p class="first">An inline markup end-string must be separated by at least one
character from the start-string.</p>
</li>
<li><p class="first">An unescaped backslash preceding a start-string or end-string will
disable markup recognition, except for the end-string of <a class="reference" href="#inline-literals">inline
literals</a>.  See <a class="reference" href="#escaping-mechanism">Escaping Mechanism</a> above for details.</p>
</li>
</ol>
<p>For example, none of the following are recognized as containing inline
markup start-strings:</p>
<ul class="simple">
<li>asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_*</li>
<li>double asterisks: **  a**b O(N**2) etc.</li>
<li>backquotes: ` `` etc.</li>
<li>underscores: _ __ __init__ __init__() etc.</li>
<li>vertical bars: | || etc.</li>
</ul>
<p>It may be desirable to use inline literals for some of these anyhow,
especially if they represent code snippets.  It's a judgment call.</p>
<p>These cases <em>do</em> require either literal-quoting or escaping to avoid
misinterpretation:</p>
<pre class="literal-block">*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt
</pre>
<p>The inline markup recognition rules were devised intentionally to
allow 90% of non-markup uses of "*", "`", "_", and "|" <em>without</em>
resorting to backslashes.  For 9 of the remaining 10%, use inline
literals or literal blocks:</p>
<pre class="literal-block">"``\*``" -&gt; "\*" (possibly in another font or quoted)
</pre>
<p>Only those who understand the escaping and inline markup rules should
attempt the remaining 1%.  ;-)</p>
<p>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:</p>
<ul class="simple">
<li>Asterisks: <a class="reference" href="#strong-emphasis">Strong emphasis</a> ("**") is recognized before <a class="reference" href="#emphasis">emphasis</a>
("*").</li>
<li>Backquotes: <a class="reference" href="#inline-literals">Inline literals</a> ("``"), <a class="reference" href="#inline-internal-targets">inline internal targets</a>
(leading "_`", trailing "`"), are mutually independent, and are
recognized before phrase <a class="reference" href="#hyperlink-references">hyperlink references</a> (leading "`",
trailing "`_") and <a class="reference" href="#interpreted-text">interpreted text</a> ("`").</li>
<li>Trailing underscores: Footnote references ("[" + label + "]_") and
simple <a class="reference" href="#hyperlink-references">hyperlink references</a> (name + trailing "_") are mutually
independent.</li>
<li>Vertical bars: <a class="reference" href="#substitution-references">Substitution references</a> ("|") are independently
recognized.</li>
<li><a class="reference" href="#standalone-hyperlinks">Standalone hyperlinks</a> are the last to be recognized.</li>
</ul>
<div class="section" id="emphasis">
<h3><a class="toc-backref" href="#id53" name="emphasis">Emphasis</a></h3>
<p>DTD element: emphasis.</p>
<p>Start-string = end-string = "*".</p>
<p>Text enclosed by single asterisk characters is emphasized:</p>
<pre class="literal-block">This is *emphasized text*.
</pre>
<p>Emphasized text is typically displayed in italics.</p>
</div>
<div class="section" id="strong-emphasis">
<h3><a class="toc-backref" href="#id54" name="strong-emphasis">Strong Emphasis</a></h3>
<p>DTD element: strong.</p>
<p>Start-string = end-string = "**".</p>
<p>Text enclosed by double-asterisks is emphasized strongly:</p>
<pre class="literal-block">This is **strong text**.
</pre>
<p>Strongly emphasized text is typically displayed in boldface.</p>
</div>
<div class="section" id="interpreted-text">
<h3><a class="toc-backref" href="#id55" name="interpreted-text">Interpreted Text</a></h3>
<p>DTD element: interpreted.</p>
<p>Start-string = end-string = "`".</p>
<p>Text enclosed by single backquote characters is interpreted:</p>
<pre class="literal-block">This is `interpreted text`.