Elements for code and software documentation

Paligo inherits a very rich set of elements from DocBook for documenting software. This includes elements for GUI components, as well as code snippets and the like. We'll describe some of the most common here.

Code elements

The most commonly used are programlisting, for code blocks, and code, for inline code snippets inside a para or other textual element.

Code elements preserve line breaks and spacing to represent the code properly. For common output formats like PDF, HTML/HTML5, syntax highlighting and indentation is also available, and can be controlled in the Layout Editor.

You can optionally specify the language attribute for a code snippet to specify the programming language represented.

Examples
Example 1. Programlisting
//This example is in itself using the programlisting element
//to show the code below
public class Factorial
{
public static void main(String[] args)
{       final int NUM_FACTS = 100;
for(int i = 0; i < NUM_FACTS; i++)
System.out.println( i + "! is " + factorial(i));
}

public static int factorial(int n)
{       int result = 1;
for(int i = 2; i <= n; i++)
result *= i;
return result;
}
}

Example 2. Code (inline)

To show hidden files, type defaults write com.apple.finder AppleShowAllFiles TRUE in the terminal.

Tip

There are several other code elements available, like screen, literallayout, userinput, and more. You can explore them in the DocBook documentation following these links.

GUI elements

There are many elements for describing GUI and other software related components as well:

 guilabel: an element generally recommended if you want to keep your markup of gui components simple. Use this to mark up buttons, menus, and the like. keycap: very useful for marking up keyboard shortcuts. If desired, it can also be wrapped in a keycombo element to output the delimiter (like a "+" between keys). filename: for file names and paths. guimenu: if you want to be more granular in marking up your GUI components, you can for example use elements like guimenu, and its sub elements. There are also more related elements like guibutton, guiicon, etc. Using both guimenu and the other granular elements can easily become quite complex though. So unless you have very good reason to be that specific, the recommendation is to keep it simple and just distinguish GUI components with the guilabel element.

These are just a few common examples.

There are many more similar elements available, and it's recommended you explore the full reference if you have a need for a very detailed markup for software documentation.