////
Included in:

- user-manual: Listing and Source Code Blocks
////

Like literal blocks, the content in listing blocks is displayed exactly as you entered it.
Listing block content is converted to `<pre>` text.
The content in listing blocks is only subject to <<user-manual#special-characters,special character>> and callout substitutions.

The `listing` block name can be applied to content two ways.

. Set the `listing` attribute on the element.
. Contain the content within a delimited listing block.

The listing block name is applied to an element, such as a paragraph, by setting the `listing` attribute on that element.

.Listing paragraph syntax
[source]
----
include::ex-listing.adoc[tag=para]
----

.Result: Listing paragraph
====
include::ex-listing.adoc[tag=para]
====

A delimited listing block is surrounded by lines composed of four hyphens (`----`).

.Delimited listing block syntax
[source]
....
include::ex-listing.adoc[tag=bl]
....

Here's how the block above appears when rendered as HTML.

.Result: Listing block
====
include::ex-listing.adoc[tag=bl]
====

You should notice a few things about how the content is processed.

* the HTML tag `<pre>` is escaped
* then endlines are preserved
* the phrase _listing block_ is not italicized, despite having underscores around it.

Listing blocks are good for displaying raw source code, especially when used in tandem with the `source` and `source-highlighter` attributes.
The example below shows a listing block with `source` and the language `ruby` applied to its content.

.Source block syntax
[source]
....
include::ex-src.adoc[tag=src-base]
....

.Result: Listing block with the source attribute set
====
include::ex-src.adoc[tag=src-base]
====

Detailed instructions for using the source and source-highlighter attributes are provided in the <<user-manual#source-code-blocks,source code blocks>> section.

[listing]
.Listing block with custom substitutions syntax
....
include::ex-listing.adoc[tag=subs]
....

.Result: Listing block with custom substitutions applied
====
// the attribute value is hard-coded in this result since the example depends
// on a hypothetical document attribute
include::ex-listing.adoc[tag=subs-out]
====