Software and Code Documentation

3 min read

Code Blocks in Your Content

One of the most common needs when documenting software is to write code blocks. The main element for this is programlisting.

To add a programlisting element:

  1. Position the cursor at the start of the line where you want to add the code block.

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

  3. Search for the programlisting element and select it.

    When you add a programlisting element, a code snippet box appears in the topic.

  4. Add your code inside the code snippet box.

The programlisting element is sometimes referred to as "verbatim", as the code you add inside the element will be rendered exactly how it appears in the editor. For example, it will keep spaces and line breaks to represent the code properly. Some other elements also work like this, such as screen and literallayout.

Example 49. Programlisting sample

Here, a javascript function has been added inside a programlisting element. This is how the code looks in the output.

function myFunction() { ①
    var x = "", i;
    for (i=0; i<5; i++) {
        x = x + "The number is " + i + "<br>";
    }
    document.getElementById("demo").innerHTML = x; ②
}
①

This is a javascript function

②

This sets a value to an element using the DOM model.

In the sample shown , a code block is added inside the programlisting element. The javascript function contains (1) on the first line and (2) on the last line. These are callouts, which you can use to Annotate Code Blocks.

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.

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.

  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.