1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 15. Paragraphs</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ch14.html" title="Chapter 14. AttributeList Element" /><link rel="next" href="ch16.html" title="Chapter 16. Delimited Blocks" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch14.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch16.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_paragraphs"></a>Chapter 15. Paragraphs</h1></div></div></div><p>Paragraphs are blocks of text terminated by a blank line, the end of
file, or the start of a delimited block or a list. There are three
paragraph syntaxes: normal, indented (literal) and admonition which
are rendered, by default, with the corresponding paragraph style.</p><p>Each syntax has a default style, but you can explicitly apply any
paragraph style to any paragraph syntax. You can also apply
<a class="link" href="ch16.html" title="Chapter 16. Delimited Blocks">delimited block</a> styles to single paragraphs.</p><p>The built-in paragraph styles are: <span class="emphasis"><em>normal</em></span>, <span class="emphasis"><em>literal</em></span>, <span class="emphasis"><em>verse</em></span>,
<span class="emphasis"><em>quote</em></span>, <span class="emphasis"><em>listing</em></span>, <span class="emphasis"><em>TIP</em></span>, <span class="emphasis"><em>NOTE</em></span>, <span class="emphasis"><em>IMPORTANT</em></span>, <span class="emphasis"><em>WARNING</em></span>, <span class="emphasis"><em>CAUTION</em></span>,
<span class="emphasis"><em>abstract</em></span>, <span class="emphasis"><em>partintro</em></span>, <span class="emphasis"><em>comment</em></span>, <span class="emphasis"><em>example</em></span>, <span class="emphasis"><em>sidebar</em></span>, <span class="emphasis"><em>source</em></span>,
<span class="emphasis"><em>music</em></span>, <span class="emphasis"><em>latex</em></span>, <span class="emphasis"><em>graphviz</em></span>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_normal_paragraph_syntax"></a>15.1. normal paragraph syntax</h2></div></div></div><p>Normal paragraph syntax consists of one or more non-blank lines of
text. The first line must start hard against the left margin (no
intervening white space). The default processing expectation is that
of a normal paragraph of text.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X85"></a>15.2. literal paragraph syntax</h2></div></div></div><p>Literal paragraphs are rendered verbatim in a monospaced font without
any distinguishing background or border. By default there is no text
formatting or substitutions within Literal paragraphs apart from
Special Characters and Callouts.</p><p>The <span class="emphasis"><em>literal</em></span> style is applied implicitly to indented paragraphs i.e.
where the first line of the paragraph is indented by one or more space
or tab characters. For example:</p><pre class="screen"> Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</pre><p>Renders:</p><pre class="literallayout">Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</pre><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Because <a class="link" href="ch17.html" title="Chapter 17. Lists">lists</a> can be indented it’s possible for your
indented paragraph to be misinterpreted as a list — in situations
like this apply the <span class="emphasis"><em>literal</em></span> style to a normal paragraph.</p></td></tr></table></div><p>Instead of using a paragraph indent you could apply the <span class="emphasis"><em>literal</em></span>
style explicitly, for example:</p><pre class="screen">[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</pre><p>Renders:</p><pre class="literallayout">Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X94"></a>15.3. quote and verse paragraph styles</h2></div></div></div><p>The optional <span class="emphasis"><em>attribution</em></span> and <span class="emphasis"><em>citetitle</em></span> attributes (positional
attributes 2 and 3) specify the author and source respectively.</p><p>The <span class="emphasis"><em>verse</em></span> style retains the line breaks, for example:</p><pre class="screen">[verse, William Blake, from Auguries of Innocence]
To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.</pre><p>Which is rendered as:</p><div class="blockquote"><table border="0" class="blockquote" style="width: 100%; cellspacing: 0; cellpadding: 0;" summary="Block quote"><tr><td width="10%" valign="top"> </td><td width="80%" valign="top"><div class="literallayout"><p>To see a world in a grain of sand,<br />
And a heaven in a wild flower,<br />
Hold infinity in the palm of your hand,<br />
And eternity in an hour.</p></div></td><td width="10%" valign="top"> </td></tr><tr><td width="10%" valign="top"> </td><td colspan="2" align="right" valign="top">--<span class="attribution">
William Blake
<em class="citetitle">from Auguries of Innocence</em>
</span></td></tr></table></div><p>The <span class="emphasis"><em>quote</em></span> style flows the text at left and right margins, for
example:</p><pre class="screen">[quote, Bertrand Russell, The World of Mathematics (1956)]
A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.</pre><p>Which is rendered as:</p><div class="blockquote"><table border="0" class="blockquote" style="width: 100%; cellspacing: 0; cellpadding: 0;" summary="Block quote"><tr><td width="10%" valign="top"> </td><td width="80%" valign="top"><p>A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.</p></td><td width="10%" valign="top"> </td></tr><tr><td width="10%" valign="top"> </td><td colspan="2" align="right" valign="top">--<span class="attribution">
Bertrand Russell
<em class="citetitle">The World of Mathematics (1956)</em>
</span></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X28"></a>15.4. Admonition Paragraphs</h2></div></div></div><p><span class="emphasis"><em>TIP</em></span>, <span class="emphasis"><em>NOTE</em></span>, <span class="emphasis"><em>IMPORTANT</em></span>, <span class="emphasis"><em>WARNING</em></span> and <span class="emphasis"><em>CAUTION</em></span> admonishment
paragraph styles are generated by placing <code class="literal">NOTE:</code>, <code class="literal">TIP:</code>,
<code class="literal">IMPORTANT:</code>, <code class="literal">WARNING:</code> or <code class="literal">CAUTION:</code> as the first word of the
paragraph. For example:</p><pre class="literallayout">NOTE: This is an example note.</pre><p>Alternatively, you can specify the paragraph admonition style
explicitly using an <a class="link" href="ch14.html" title="Chapter 14. AttributeList Element">AttributeList element</a>. For example:</p><pre class="literallayout">[NOTE]
This is an example note.</pre><p>Renders:</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>This is an example note.</p></td></tr></table></div><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>If your admonition requires more than a single paragraph use an
<a class="link" href="ch16.html#X22" title="16.9. Admonition Blocks">admonition block</a> instead.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="X47"></a>15.4.1. Admonition Icons and Captions</h3></div></div></div><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>Admonition customization with <code class="literal">icons</code>, <code class="literal">iconsdir</code>, <code class="literal">icon</code> and
<code class="literal">caption</code> attributes does not apply when generating DocBook output. If
you are going the DocBook route then the <a class="link" href="ch05.html#X43" title="5.2. a2x Toolchain Wrapper">a2x(1)</a> <code class="literal">--no-icons</code>
and <code class="literal">--icons-dir</code> options can be used to set the appropriate XSL
Stylesheets parameters.</p></td></tr></table></div><p>By default the asciidoc(1) HTML backends generate text captions
instead of admonition icon image links. To generate links to icon
images define the <a class="link" href="aph.html#X45"><code class="literal">icons</code></a> attribute, for example using the <code class="literal">-a
icons</code> command-line option.</p><p>The <a class="link" href="aph.html#X44"><code class="literal">iconsdir</code></a> attribute sets the location of linked icon
images.</p><p>You can override the default icon image using the <code class="literal">icon</code> attribute to
specify the path of the linked image. For example:</p><pre class="literallayout">[icon="./images/icons/wink.png"]
NOTE: What lovely war.</pre><p>Use the <code class="literal">caption</code> attribute to customize the admonition captions (not
applicable to <code class="literal">docbook</code> backend). The following example suppresses the
icon image and customizes the caption of a <span class="emphasis"><em>NOTE</em></span> admonition
(undefining the <code class="literal">icons</code> attribute with <code class="literal">icons=None</code> is only necessary
if <a class="link" href="aph.html#X45">admonition icons</a> have been enabled):</p><pre class="literallayout">[icons=None, caption="My Special Note"]
NOTE: This is my special note.</pre><p>This subsection also applies to <a class="link" href="ch16.html#X22" title="16.9. Admonition Blocks">Admonition Blocks</a>.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch14.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch16.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/icons/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
|
