Chapter 15. Paragraphs

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.

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.

The literal 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:

  Consul *necessitatibus* per id,
  consetetur, eu pro everti postulant
  homero verear ea mea, qui.

Renders:

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

	Because lists can be indented it’s possible for your indented paragraph to be misinterpreted as a list — in situations like this apply the literal style to a normal paragraph.

Instead of using a paragraph indent you could apply the literal style explicitly, for example:

[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Renders:

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

The optional attribution and citetitle attributes (positional attributes 2 and 3) specify the author and source respectively.

The verse style retains the line breaks, for example:

[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.

Which is rendered as:

The quote style flows the text at left and right margins, for example:

[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.

Which is rendered as:

TIP, NOTE, IMPORTANT, WARNING and CAUTION admonishment paragraph styles are generated by placing NOTE:, TIP:, IMPORTANT:, WARNING: or CAUTION: as the first word of the paragraph. For example:

NOTE: This is an example note.

Alternatively, you can specify the paragraph admonition style explicitly using an AttributeList element. For example:

[NOTE]
This is an example note.

Renders:

	This is an example note.

	If your admonition requires more than a single paragraph use an admonition block instead.

15.4.1. Admonition Icons and Captions

	Admonition customization with icons, iconsdir, icon and caption attributes does not apply when generating DocBook output. If you are going the DocBook route then the a2x(1) --no-icons and --icons-dir options can be used to set the appropriate XSL Stylesheets parameters.

By default the asciidoc(1) HTML backends generate text captions instead of admonition icon image links. To generate links to icon images define the icons attribute, for example using the -a icons command-line option.

The iconsdir attribute sets the location of linked icon images.

You can override the default icon image using the icon attribute to specify the path of the linked image. For example:

[icon="./images/icons/wink.png"]
NOTE: What lovely war.

Use the caption attribute to customize the admonition captions (not applicable to docbook backend). The following example suppresses the icon image and customizes the caption of a NOTE admonition (undefining the icons attribute with icons=None is only necessary if admonition icons have been enabled):

[icons=None, caption="My Special Note"]
NOTE: This is my special note.

This subsection also applies to Admonition Blocks.