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".

To annotate code using calloutlist:

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

  2. Press Alt and Enter (Windows) or Option ⌥ and Enter (Mac) to display the Element Context Menu.

  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.


    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.