Jazz Jazz Community 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

1 Star2 Stars3 Stars4 Stars5 Stars (4 votes, average: 4.00 out of 5)
Loading...
3 Comments
  1. Dan Ani May 25, 2020 @ 12:46 pm

    Great article Prasad. It’s working nicely if you have only 1 image in an artifact. But how PUB can handle the mixed artifacts where you have both text and image embedded (or 2 or more images places in the same artifact).
    Any ideas on how we could export those images and place a figure caption below each image?

  2. Subramanya Prasad Pilar March 25, 2021 @ 8:07 am

    I dont see an option to insert figure caption in DOORS Next. Hence the XHTML retuened from DOORS Next will not include figure captions.
    Using following script expression, figure captions can be added for each image:

    Note: The resource UUID will be used as caption. You can make GET reuest for each wrapper resource and get the artifact title and use it as caption.

  3. Subramanya Prasad Pilar March 25, 2021 @ 8:17 am

    Also, if you do not want to include labels and numbers in TOF / TOT, change the value for “TOC code” property in RPE template.
    Use \h \z \a "Table" instead of \h \z \c "Table" for Table Of Tables element.
    Use \h \z \a "Figure" instead of \h \z \c "Figure" for Table Of Figures element.

You must be logged in to post a comment.