Skip to main content

Annotate Code Blocks

You can annotate code blocks by using the calloutlist element and co elements. In the published output, the callouts act as clickable "hotspots" that highlight parts of the code. When someone selects a "hotspot", they are taken to the callout text explanation for that "hotspot".

For example, in the image below, the code sample has two callout "hotspots" labelled 1 and 2. Below the code sample, there are numbers that match the hotspots, and next to each number is an annotation that explains the purpose of the corresponding code.

A code sample. In the code, there are callout icons labelled 1 and 2. Below the code, there are matching 1 and 2 callout icons, each with a text description of the corresponding line of code.

To annotate code using calloutlist:

  1. Select a position in the code block where you want a callout "hotspot" to appear.

  2. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  3. Select the co element and give it an xml:id value in the Element attributes section. Each co element has to have an xml:id value that is unique in that specific topic. For example, you could give the first co element the xml:id id_1, the second co element the xml:id id_2 and so on.

  4. Add a calloutlist element after the programlisting element that contains your code block.

    Tip

    It can be a good idea to include the programlisting and calloutlist elements inside an example element, so that they are all in a single "container" (the example element).

  5. Give each callout in the calloutlist an xml:id as well, different from the ones in the co elements, e.g "callout_1", "callout_2". Again, these ids need to be unique.

  6. Associate the co elements with the callout elements:

    1. For each co element, add a linkends attribute. Set the value of the linkends attribute to the xml:id value of the callout that you want to associate it with.

    2. For each callout element, add the arearefs attribute. Set the value of the arearefs attribute to the xml:id value of the co that you want to associate it with.