Callouts

Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block.

Callout syntax

Each callout number used in a verbatim block must appear twice. The first use, which goes within the verbatim block, marks the line being annotated (i.e., the target). The second use, which goes below the verbatim block, defines the annotation text. Multiple callout numbers may be used on a single line.

The callout number (at the target) must be placed at the end of the line.

Here’s a basic example of a verbatim block that uses callouts:

Example 1. Callout syntax

[source,ruby]
----
require 'sinatra' <1>

get '/hi' do <2> <3>
  "Hello World!"
end
----
<1> Library import
<2> URL mapping
<3> Response block

The result of Example 1 is rendered below.

require 'sinatra' (1)

get '/hi' do (2) (3)
  "Hello World!"
end

1	Library import
2	URL mapping
3	Response block

Since callout numbers can interfere with the syntax of the code they are annotating, an AsciiDoc processor provides several features to hide the callout numbers from both the source and the converted document. The sections that follow detail these features.

Copy and paste friendly callouts

If you add callout numbers to example code in a verbatim (e.g., source) block, and a reader selects that source code in the generated HTML, we don’t want the callout numbers to get caught up in the copied text. If the reader pastes that example code into a code editor and tries to run it, the extra characters that define the callout numbers will likely lead to compile or runtime errors. To mitigate this problem, and AsciiDoc processor uses a CSS rule to prevent the callouts from being selected. That way, the callout numbers won’t get copied.

On the other side of the coin, you don’t want the callout annotations or CSS messing up your raw source code either. You can tuck your callouts neatly behind line comments. When font-based icons are enabled (e.g., icons=font), the AsciiDoc processor will recognize the line comments characters in front of a callout number—optionally offset by a space—and remove them when converting the document. When font-based icons aren’t enabled, the line comment characters are not removed so that the callout numbers remain hidden by the line comment.

Here are the line comments that are supported:

Example 2. Prevent callout copy and paste

----
line of code // <1>
line of code # <2>
line of code ;; <3>
line of code <!--4-->
----
<1> A callout behind a line comment for C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure.
<4> A callout behind a line comment for XML or SGML languages like HTML.

The result of Example 2 is rendered below.

line of code (1)
line of code (2)
line of code (3)
line of code (4)

1	A callout behind a line comment for C-style languages.
2	A callout behind a line comment for Ruby, Python, Perl, etc.
3	A callout behind a line comment for Clojure.
4	A callout behind a line comment for XML or SGML languages like HTML.

Custom line comment prefix

An AsciiDoc processor recognizes the most ubiquitous line comment prefixes as a convenience. If the source language you’re embedding does not support one of these line comment prefixes, you can customize the prefix using the line-comment attribute on the block.

Let’s say we want to tuck a callout behind a line comment in Erlang code. In this case, we would set the line-comment character to %, as shown in this example:

Example 3. Custom line comment prefix

[source,erlang,line-comment=%]
----
-module(hello_world).
-compile(export_all).

hello() ->
    io:format("hello world~n"). % <1>
----
<1> A callout behind a custom line comment prefix.

The result of Example 3 is rendered below.

-module(hello_world).
-compile(export_all).

hello() ->
    io:format("hello world~n"). (1)

1	A callout behind a custom line comment prefix.

Even though it’s not specified in the attribute, one space is still permitted immediately following the line comment prefix.

Disable line comment processing

If the source language you’re embedding does not support trailing line comments, or the line comment prefix is being misinterpreted, you can disable this feature using the line-comment attribute.

Let’s say we want to put a callout at the end of a block delimiter for an open block in AsciiDoc. In this case, the processor will think the double hyphen is a line comment, when in fact it’s the block delimiter. We can disable line comment processing by setting the line-comment character to an empty value, as shown in this example:

Example 4. No line comment prefix

[source,asciidoc,line-comment=]
----
-- <1>
A paragraph in an open block.
--
----
<1> An open block delimiter.

The result of Example 4 is rendered below.

-- (1)
A paragraph in an open block.
--

1	An open block delimiter.

Since the language doesn’t support trailing line comments, there’s no way to hide the callout number in the raw source.

XML callouts

XML doesn’t have line comments, so our “tuck the callout behind a line comment” trick doesn’t work here. To use callouts in XML, you must place the callout’s angled brackets around the XML comment and callout number.

Here’s how it appears in a listing:

Example 5. XML callout syntax

[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.

The result of Example 5 is rendered below.

<section>
  <title>Section Title</title> (1)
</section>

1	The section title is required.

Notice the comment has been replaced with a circled number that cannot be selected (if not using font icons it will be rendered differently and selectable). Now both you and the reader can copy and paste XML source code containing callouts without worrying about errors.

Callout icons

The font icons setting also enables callout icons drawn using CSS.

= Document Title
:icons: font (1)

NOTE: Asciidoctor supports font-based admonition
icons, powered by Font Awesome! (2)

1	Activates the font-based icons in the HTML5 backend.
2	Admonition block that uses a font-based icon.