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            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    3
10/16/97  14:25             115  CONFIG.SYS     4
11/16/97  17:17      61,865,984  pagefile.sys
 2/13/94   6:21           9,349  WINA20.386     5

1

This directory holds MS-DOS.

2 3 4

System startup code for DOS.

5

Some sort of Windows 3.1 hack.

Explanation

[Note]

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>