You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
78 lines
2.2 KiB
78 lines
2.2 KiB
4 years ago
|
////
|
||
|
|
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]
|
||
|
|
====
|