Getting Started with Paligo

Table of Contents

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 1. 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 2. 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 3. 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
}

1

This is a javascript function

2

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.

Tip

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