Chapter 20. Callouts

Callouts are a mechanism for annotating verbatim text (for example: source code, computer output and user input). Callout markers are placed inside the annotated text while the actual annotations are presented in a callout list after the annotated text. Here’s an example:

 .MS-DOS directory listing
 -----------------------------------------------------
 10/17/97   9:04         <DIR>    bin
 10/16/97  14:11         <DIR>    DOS            <1>
 10/16/97  14:40         <DIR>    Program Files
 10/16/97  14:46         <DIR>    TEMP
 10/17/97   9:04         <DIR>    tmp
 10/16/97  14:37         <DIR>    WINNT
 10/16/97  14:25             119  AUTOEXEC.BAT   <2>
  2/13/94   6:21          54,619  COMMAND.COM    <2>
 10/16/97  14:25             115  CONFIG.SYS     <2>
 11/16/97  17:17      61,865,984  pagefile.sys
  2/13/94   6:21           9,349  WINA20.386     <3>
 -----------------------------------------------------

 <1> This directory holds MS-DOS.
 <2> System startup code for DOS.
 <3> Some sort of Windows 3.1 hack.

Which renders:

MS-DOS directory listing.

10/17/97   9:04         <DIR>    bin
10/16/97  14:11         <DIR>    DOS            
10/16/97  14:40         <DIR>    Program Files
10/16/97  14:46         <DIR>    TEMP
10/17/97   9:04         <DIR>    tmp
10/16/97  14:37         <DIR>    WINNT
10/16/97  14:25             119  AUTOEXEC.BAT   
 2/13/94   6:21          54,619  COMMAND.COM    
10/16/97  14:25             115  CONFIG.SYS     
11/16/97  17:17      61,865,984  pagefile.sys
 2/13/94   6:21           9,349  WINA20.386

	This directory holds MS-DOS.
	System startup code for DOS.
	Some sort of Windows 3.1 hack.

Explanation

The callout marks are whole numbers enclosed in angle brackets — they refer to the correspondingly numbered item in the following callout list.
By default callout marks are confined to LiteralParagraphs, LiteralBlocks and ListingBlocks (although this is a configuration file option and can be changed).
Callout list item numbering is fairly relaxed — list items can start with <n>, n> or > where n is the optional list item number (in the latter case list items starting with a single > character are implicitly numbered starting at one).
Callout lists should not be nested.
Callout lists cannot be used within tables.
Callout lists start list items hard against the left margin.
If you want to present a number inside angle brackets you’ll need to escape it with a backslash to prevent it being interpreted as a callout mark.


	Define the AsciiDoc icons attribute (for example using the `-a icons` command-line option) to display callout icons.

20.1. Implementation Notes

Callout marks are generated by the callout inline macro while callout lists are generated using the callout list definition. The callout macro and callout list are special in that they work together. The callout inline macro is not enabled by the normal macros substitutions option, instead it has its own callouts substitution option.

The following attributes are available during inline callout macro substitution:

{index}: The callout list item index inside the angle brackets.
{coid}: An identifier formatted like CO<listnumber>-<index> that uniquely identifies the callout mark. For example CO2-4 identifies the fourth callout mark in the second set of callout marks.

The {coids} attribute can be used during callout list item substitution — it is a space delimited list of callout IDs that refer to the explanatory list item.

20.2. Including callouts in included code

You can annotate working code examples with callouts — just remember to put the callouts inside source code comments. This example displays the test.py source file (containing a single callout) using the source (code highlighter) filter:

AsciiDoc source.

 [source,python]
 -------------------------------------------
 \include::test.py[]
 -------------------------------------------

 <1> Print statement.

Included test.py source.

print 'Hello World!'   # <1>