1.13.9. Formatting of listings

To improve the readability of listings, it is often required to format even lines with a different style (e.g. different background-color) than odd lines and/or it is required to add line numbers. This chapter describes how this can be achieved in Docmenta.
As an example we'll format the lines of following HTML listing:
    <title>My first homepage</title>
    Welcome to my homepage!
There are two possibilities to include a listing in a content-node: The first possibility is to directly enter the text in the content-editor, either by typing in the text word for word or by using Copy&Paste. Note that if you type in the listing word for word, a new line has to be started by pressing Shift-Enter (i.e. by inserting a manual line-break). If you press only the Enter key, then a new paragraph is created. However, a listing has to be a single paragraph that consists of multiple lines terminated by manual line-breaks.
For long listings it is preferable to store the listing in a separate text-file and include the content of the text-file via inline-inclusion. To do this, upload the text-file to a folder within the product-tree, e.g. to the root folder Files. Furthermore, an alias name has to be assigned to the file. Thus, open the context-menu by right-clicking the file-node and select "Edit Properties". In the opened dialog enter an alias name. To follow the tutorial enter the alias name "listing_homepage". After having uploaded the listing and assigned an alias name, the result should be as shown in the following screenshot:

Figure 1.13.58. Uploading the listing file

Note: Text file extensions
If the preview-area does not show the content of the selected file-node, then the file-extensions is probably not a registered text-file extension. To register a text-file extension, switch to the Settings tab in the Administration workspace:

Figure 1.13.59. Registering a text-file extension

In the "Text File Extensions" input field, enter the file-extensions that you intend to use for text-files. Click "Save" to store the changes.
Now, open the content-node where the listing shall be included in the content-editor. Create a new paragraph and include the listing via inline-inclusion, i.e. enter the text "[##listing_homepage]" (see Section 1.11.2, “Inline inclusions” for more information on inline-inclusions):

Figure 1.13.60. Including the content of a file

The next step is to assign a user-defined block-style to the listing-paragraph. The block-style is used to define the formatting properties of the listing. To follow the tutorial, assign the style with ID "listing", that you've created in the previous chapter. Therefore, open the content-node that contains the listing in the content-editor, and place the cursor in the listing-paragraph . Then click the "Insert/Edit attributes" button . In the opened dialog select the entry "listing" from the Class list :

Figure 1.13.61. Assigning the listing-style to the paragraph

Save the content-node. As you can see in the preview of the content-node, the content of the file with alias "listing_homepage" appears instead of the text "[##listing_homepage]":

Figure 1.13.62. Previewing the included listing

You may notice, that the lines are not correctly indented. To fix this, create a new block-style with ID "listing_line". This style shall define the CSS properties to be assigned to each line of the listing. Set the following CSS properties for this style:
  • Font: mono, 11pt
  • White-space: pre
  • Height: 15pt

Figure 1.13.63. Setting the text properties of a line

Figure 1.13.64. Setting the line height

Setting the property "white-space" to "pre" (preformatted) is required to have correctly indented lines. Otherwise multiple successive spaces will be rendered as a single space. Furthermore, by explicitely setting the height of a line, it is assured that generated line numbers are correctly aligned with the lines in the listing.
As mentioned in the introduction, we want to add line numbers to the listing. Therefore, we have to configure the listing-style to add line-numbers. Open the style-dialog of the listing-style and click the "Add" button next to the Auto-Format list. In the opened dialog select the Auto-Format class org.docma.plugin.examples.FormatLines and enter the arguments "start=1 line=listing_line nw=22pt" :

Figure 1.13.65. Auto-Format configuration of the listing-style

The argument start=value tells the Auto-Format class, to start the line-numbering with the specified value. The argument line=style_ID defines, that the style style_ID shall be applied to each line of the listing. The argument nw=width sets the horizontal width to be reserved for the line-numbers. Close the dialogs by clicking the "Okay" button.
If the class org.docma.plugin.examples.FormatLines is not available in the Auto-Format Class list, then you first have to register the class. For more information see Section 2.7.6, “Auto-Format class registration” in the reference manual or see the note 'Auto-Format Class Registration' in the chapter Section 1.9.2, “Dynamic Templates” here in this tutorial.
The preview of the node should now show the included listing in monospace font with correctly indented lines and line-numbers:

Figure 1.13.66. Listing with line-numbers

Notice that the style with ID "listing_line" is not directly applied by the user. Therefore you can define it to be a hidden style. See the chapter Section 1.9.2, “Dynamic Templates” in this tutorial on how to hide styles.
Marking lines
A special feature of the org.docma.plugin.examples.FormatLines class is, that you can define a character sequence to be used to mark lines. Lines that start or end with the specified character sequence are then formatted with a user-defined style.
In our example we want to define the character sequence "***" to be used to mark lines. The line numbers of marked lines shall be highlighted with a dark blue background-color and a white font-color. Therefore, create a new block-style with ID "marked_num" and set the background-color "#0000A8" and the font-color "#FFFFFF" for this style. Also set the same font-size as for the non-marked line-numbers (11 points). Then open the style-dialog of the listing-style, select the previously created entry in the Auto-Format list and click the "Edit" button next to the list:

Figure 1.13.67. Editing the Auto-Format entry

In the arguments input field, add the text "m=*** mnum=marked_num" after the existing arguments. The argument m=pattern defines the character sequence to be used for marking lines. The argument mnum=style_ID defines the style to be applied to the line-numbers of marked lines.
Close the dialogs by clicking "Okay". To test the marking of lines, select the file-node that contains the listing, click the "Edit" button in the bottom bar of the preview-area and add the character sequence "***" at the end of a line . Then click the "Save" button in the bottom bar to save the modified listing:

Figure 1.13.68. Adding a marker to the listing

Now, select the content-node that includes the listing to see if the lines are marked as expected:

Figure 1.13.69. Preview of the marked line

As you can see, the style marked_num is applied to the line-number of the marked line. Note that the marker "***" has been removed.
Referencing lines
In Docmenta you can reference a marked line in the listing from within the text. To be able to reference a marked line, you first have to assign an ID to the marked line. To do this, add an ID value enclosed in square brackets after the marker sequence. To follow the tutorial use the line-ID "line_a", i.e. use the character sequence "***[line_a]" as marker:

Figure 1.13.70. Setting a marker with ID

Save the changed listing and open a content-node from where you want to reference the line. Create a new paragraph and enter the text "See line here", select the word "here" and click the "Insert/Edit Link" button. In the opened dialog enter the URL "#line_a" and check the "Use target title" box:

Figure 1.13.71. Referencing the marked line

Click "Insert" to close the dialog. Finally, save the content and preview the node. As you can see, the HTML preview still shows the link text "here". This is because the link text replacement is done during export but not for HTML preview. However, you can check that the correct line-number is referenced by creating a PDF preview of the content-node. In the PDF preview the text "here" should be replaced by the line-number of the referenced line:

Figure 1.13.72. Referencing marked lines (PDF preview)

Inline arguments
Sometimes it might be required to use different line-numbering start values for different listings. To allow this without having to create a separate style for each required setting, you can overwrite the Auto-Format class arguments of a listing, by supplying the arguments as first line of the listing in the format
  [args: argument1 argument2 ... ]
Note that the arguments set in the first line of a listing have higher priority than the arguments that are set in the style configuration. In other words, if the same argument is set in the style configuration and in the first line of a listing, than the later takes precedence.
For example, to set a new line-numbering start-value for our listing, without changing the style configuration, select the listing file-node and click the "Edit" button in the bottom bar of the preview area. Then add following line as first line of the listing :
  [args: start=2]
Click the "Save" button to save the changed listing:

Figure 1.13.73. Setting arguments in the first line of the listing

When you preview the content-node, you'll see that the line-numbering starts with 2:

Figure 1.13.74. Changed line-numbering start value

This was a short introduction to using the Auto-Format class org.docma.plugin.examples.FormatLines. Additional features of this class are:
  • Apply different styles to even and odd lines
  • Translate tab characters to spaces
  • Allow or disallow page breaks within a listing
  • Apply a style to the box that encloses line-numbers and content
  • Set maximum characters per line with insertion of automatic line-breaks
For more information see chapter Section 2.8.2, “org.docma.plugin.examples.FormatLines” in the reference manual.