Articles in this section

Code Blocks in Your Content

Avatar
Anders
  • Updated
Follow

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.

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

  3. Search for the programlisting element and select it.

    programlisting-element-added.jpg

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

    code-snippet-box-added.jpg

  4. Add your code inside the code snippet box.

    programlisting-show.jpg

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 35. Programlisting sample

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

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

1

This is a javascript function

2

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.

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.

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk