Getting Started

Documenting Software and Code

The content model of Paligo has very good support for documenting software and code snippets. We will just describe some of the most common here. Refer to the standard DocBook Element Reference for the full set of elements available.

General software elements

Even if you are not documenting much code, if you document software you'll often have to refer to parts of the software product, such as UI components, file names, tags, keyboard shortcuts, etc. Here are some common elements to use:

Example 2. UI components

The easiest way to refer to UI components (buttons, menus, toolbars, etc) is to use one element as a generic UI element: guilabel. Here's an example:

Click on the Ok button.

Since this is so common (and recommended practice instead of using bold or italic for such terms), there is also a keyboard shortcut for it: AltG.

If you want to be more granular, you can use very specific elements instead, using guilabel only for labels, guibutton for buttons, guimenu and its sub elements for menus, etc.

Another common need is to write file names and paths, and for this you have the element filename.

Example 3. Keyboard shortcuts

To write keyboard shortcuts properly, and give you the option for how to style them now or change it later, or use different styling for different outputs, use the keycap element:

Hit AltK to add a keycap element.

As you can see, this element can be styled, and here it is styled as keyboard keys, and as the example shows this element has a keyboard shortcut itself for convenience.

If you want, you can use it separately, or in combination with the keycombo element. If keycap elements are wrapped in a keycombo element, by default it will output a "+" symbol between the keys (which can be customized in stylesheets if needed).

Code elements

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

Example 4. Programlisting sample
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


This is a javascript function


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

These elements are sometimes referred to as "verbatim", as they will be rendered exactly like they are formatted in your source content, i.e keeping spaces and line breaks to represent the code properly. Other such elements also available are e.g screen and literallayout.


You can annotate code using the list type calloutlist, as above. Click the list items to show "hot spots" highlighting the parts of the code they refer to.

To annotate code using calloutlist, do as follows:

  1. In the code, insert co elements where you want the callout "bugs".

  2. Give each co an xml:id (e.g "id_1", "id_2", etc. Just make sure they are unique in the topic). 

  3. Add the calloutlist after the programlisting, and preferably wrapped like above in an example or the like to keep them associated as a whole.

  4. 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" or whatever works to keep them unique.

  5. Next, link them to one another:

    1. In the co elements, link to the callout elements, using the linkends attribute, i.e with the value "callout_1" etc as in this example.

    2. In the callout elements, link to the co elements using the arearefs attribute.

If the code snippet you need to include is not a full block of code, but only a small snippet in line with the text in a paragraph for instance, you have other elements available. The most common is simply called code:

Example 5. Inline code sample

To log into another machine type ssh -l username remote-address and hit Enter.

Although it may be best not to get too granular, in fact there are even more specific elements for the above example. Since it is a terminal command, the element command could have been used. The important thing is to be consistent in what you choose to use. There are also elements like synopsis, cmdsynopsis, userinput, varname, replaceable, constant, and many more that you can read more about in the standard Element Reference.

Embedding code from external source

If you have a repository of code samples (for example in GitHub or BitBucket) and want to be able to have your help updated dynamically if the samples in that repository changes, you can add dynamic code snippets.


  • Such code snippets are fully dynamic for HTML5 output, meaning your published site will update if you update the code, without having to republish your help.

    If you publish to other outputs such as PDF as well, the embedded code will still be fetched dynamically at publish time, but if you change the code samples in your repository you need to republish to have Paligo fetch the latest changes.

  • The code samples need to be in an "https" URL.

  1. Make sure you have the option Output role attribute as class names enabled in the Layout Editor.

  2. Add two attributes on the code element (programlisting or screen):

    1. A role attribute with the value embedcode

    2. An xlink:href attribute with the URL to the code snippet in your repository.


    You can add a programlisting element with these attributes added by the shortcut Alt,. Then you just need to add the URL value.

  3. Optional: If you want or need fallback code for other output formats, add the code snippet in the programlisting or screen element as well.

When you publish, your code will be fetched from the repository and will be automatically updated if that code changes.

Search results

    No results found