Blogs about Jazz

Blogs > Jazz Team Blog >

Using captions for figures and tables – Getting the most out of IBM ELO Publishing

Using captions for images and tables will make the documents clear, professionally presentable and easy to follow. It is imperative that you create the captions for your tables and figures correctly, so that Table of Tables and Table of Figures are updated correctly. In this article, we will see how to use Figure Caption / Table Caption elements effectively in IBM Engineering Lifecycle Optimization – Publishing (PUB) Document Studio.

Let’s say we want to report on a sample DOORS Next module (shown below). The numbering for the figures should be based on the heading level or section in the module and the caption should include the artifact title.
DOORS Next module

Adding Captions
Adding a basic caption to an image or table in PUB template is pleasingly straightforward. Just insert Figure Caption or Table Caption element in the template and PUB will insert the captions. The default Figure Caption inserted by PUB will look like this:

However, this caption is not per the reporting requirement example stated above. Let us compare Figure Caption element in PUB Studio with the “Insert Caption” option in MS Word.
Insert Caption in Word
Though PUB designer will not see every option provided in Word, template designer should be able to create the same caption as in Word. We will see these options one by one.

  1. Unlike Word, you do not see the option “Exclude label from caption”. Setting blank value for “Field label” property of Figure Caption element in PUB will have the same effect.
  2. In Word, you can also add a title or additional text in Caption. In PUB, the same can be added into a Text element inserted adjacent to Figure Caption element.
  3. In Word, there is option to provide chapter number in your caption (e.g. “Figure 3-2” or “Table 2.1”). If you include chapter numbering in your caption numbers, the caption number consists of two fields – a StyleRef field to pick up the chapter number, and an SEQ field to number the caption. If you press Alt+F9 to display field codes you will see something like: Figure { STYLEREF 1 \s } { SEQ Figure \* ARABIC \s 1 } where “1” implies that you’ve linked your caption to the Heading 1 style. The \s in the STYLEREF field causes the field to display only the number from the style, without any text that may also be defined in the numbering. For example, it displays “1”, and not “Heading 1”. The \s in the SEQ field means “restart numbering whenever you hit this style”. This can be achieved in PUB using Field element with Field code STYLEREF 1 \s before Figure Caption element as shown below:

For this example, I used an alternate approach for numbering. Section value (moduleContext/contextBinding/section) from DOORS Next along with SEQ is used. Also, Field Specific Switch (\r) is used whenever the section changes to reset the sequence number to 1.
SEQ Figure \* ARABIC \r 1

Part of the output generated from Publishing is shown below:

The example template can be downloaded from here.

Subramanya Prasad Pilar
IBM Engineering Lifecycle Optimization – Publishing