Chapter 7. Fancy code blocks

This section explains how you can automatically add line numbers, “expand” tab characters and colorize the source code contained in <pre>, <codeblock> or any other element specializing <pre>.

Adding line numbers, “expanding” tab characters and colorizing the source code contained in <pre>, <codeblock> or any other element specializing <pre> is done by adding one or more of the following classes to the @outputclass attribute of this element:
line-numbers
line-numbers-N (where N is an integer > 0)
show-line-numbers
Give a number to the lines contained in the <pre> element.
By default, first line number is 1. This first line may be specified using the second form of the line-numbers class, for example, line-numbers-100 specifies that lines are to be numbered and that first line number is 100.
show-line-numbers, an alias for line-numbers-1, is also accepted for compatibility with the DITA-OT Opens in new window.
language-L (where L is language name)
Colorize the source code contained in the <pre> element. L, a “programming language” such as c, java, css, xml, specifies how the source code should be colorized.
More information about this feature, commonly called syntax highlighting, in next section.
tab-width-W (where W is an integer >= 0)
normalize-space
Specifies whether tab characters should be expanded to a number of space characters. W is the maximum number of space characters for an expanded tab character, hence this value specifies the location of “tab stops”. Examples: tab-width-4 means: expand tabs to up to 4 space characters; tab-width-0 means: do not replace tabs by space characters.
In addition to replacing tab characters by a number of space characters, tab-width-W (where W > 0) also removes the space characters which are common to the beginning of all text lines. That is, it removes the superfluous “indentation” in the <pre> element, if any. See example below.
Moreover tab-width-W (where W > 0) also removes the (useless) space characters found just before newline characters.
normalize-space, an alias for tab-width-8, is also accepted for compatibility with the DITA-OT Opens in new window.
Remember
Remember
When the <outputclass> attribute of any element specializing <pre> contains class line-numbers/line-numbers-N and/or class language-L , then class tab-width-8 is implicitly specified too, that is, whitespace normalization is automatically performed. If this is not what you want, please explicitly add class tab-width-0 to @outputclass.

§ Example: a simple C program featuring line numbering and syntax highlighting

In the following C program, lines are indented using tab characters.
1
2
3
4
5
6
7
8
<pre class="language-c line-numbers tab-width-4">/* Hello World */
#include &lt;stdio.h&ght;

int main()
{
        printf("Hello World\n");
        return 0;
}</pre>
is rendered as:
1
2
3
4
5
6
7
8
/* Hello World */
#include <stdio.h>

int main()
{
    printf("Hello World\n");
    return 0;
}

§ Example: superfluous indentation is removed by tab-width-N (where N > 0)

Attribute @outputclass implicitly also contains tab-width-8. First line "    /tmp/" starts with 4 space characters.
1
2
3
4
5
6
7
8
9
10
11
<pre outputclass="line-numbers">    /tmp/
    /usr/                            
        bin/
        lib/
        <b>local/</b>
                <b>bin/</b>
                <b>lib/</b>
                <b>src/</b>
        src/
    /var/                            
</pre>
is rendered as:
1
2
3
4
5
6
7
8
9
10
11
/tmp/
/usr/
    bin/
    lib/
    local/
            bin/
            lib/
            src/
    src/
/var/

Child topics: