The STS (and soon JATS) legend element

Gerrit Imsieke (@gimsieke@mastodon.cloud),
le-tex publishing services (@letexml@fosstodon.org)

Presented at Balisage 2024

https://subversion.le-tex.de/common/presentations/2024-08_Balisage_legend/index.html

Figure legends (a.k.a. keys)

Ubiquitous in standards

Also tables, maps, chemical formulae, charts and other things can have legends, notably formulas (“where lists”)

Example

Annex B.1 of ISO 1463:2003(en). It includes an equation with a where-list and a figure with a legend (and a so-called figure footnote, which is a legend item with lower-alpha numbering)

ISO’s and IEC’s approaches

NISO STS 1.0 IEC/ISO Coding Guidelines

ISO

<fig id="fig_B.1">
  <label>Figure B.1</label>
  <caption>
    <title>Deviation of the cross-section by the angle <italic>α</italic></title>
  </caption>
  <graphic xlink:href="fig_B.1" xlink:type="simple"/>
  <table-wrap content-type="fig-index">
    <caption>
      <title>Key</title>
    </caption>
    <table width="325">
      <colgroup>
        <col align="left" valign="top" width="10%"/>
        <col align="left" valign="top" width="90%"/>
      </colgroup>
      <tbody>
        <tr>
          <td>1</td>
          <td>coating surface</td>
        </tr>
        <tr>
          <td>2</td>
          <td>section</td>
        </tr>
      </tbody>
    </table>
  </table-wrap>
  <fn-group>
    <fn>
      <label>
        <sup>a</sup>
      </label>
      <p>Direction of observation</p>
    </fn>
  </fn-group>
</fig>

IEC

<fig id="fig_B.1">
  <label>Figure B.1</label>
  <caption>
    <title>Deviation of the cross-section by the angle <italic>α</italic></title>
  </caption>
  <graphic xlink:href="fig_B.1" xlink:type="simple"/>
  <def-list list-content="figure">
    <label>Key</label>
    <def-item>
      <term>1</term>
      <def>
        <p>coating surface</p>
      </def>
    </def-item>
    <def-item>
      <term>2</term>
      <def>
        <p>section</p>
      </def>
    </def-item>
  </def-list>
  <fn-group>
    <fn>
      <label>
        <sup>a</sup>
      </label>
      <p>Direction of observation</p>
    </fn>
  </fn-group>
</fig>

Creative legend tagging at other SDOs

Legend title in boldface in in merged table row:

<fig>
  <label>Bild 3</label>
  <caption>…</caption>
  <graphic xlink:href="…"/>
  <array>
    <table>
      <colgroup>…</colgroup>
      <tbody>
        <tr>
          <td colspan="2">
            <p><bold>Legende</bold></p>
          </td>
        </tr>

Creative legend tagging at other SDOs

It’s getting weird (probably a poorly improved conversion from Word):

<fig id="fig-na.f.1">
  <label>Bild NA.F.1</label>
  <caption>…</caption>
  <graphic xlink:href="…"/>
  <def-list list-type="key">
    <title specific-use="Legende"><bold>Legende</bold></title>
  </def-list>
  <table-wrap>
    <table border="0" frame="void">
      <col span="1" width="50.00625315mm"/>
      <col span="1" width="122.00820213mm"/>
      <tbody>[Quantities with calcualation formulas]</tbody>
    </table>
  </table-wrap>
</fig>
<p>Dabei ist</p>
<def-list><!-- where list for the calculation formulas in the figure legend -->
  <def-item>
    <term><italic>N</italic><sub>max</sub></term>
    <def>…</def>
  </def-item>
  …
</def-list>

Shortcomings of def-lists and tables

  • How to differentiate from tables that are actual figure content?
    Only by free-text attribute values?
  • How to tag subheadings?
    • Fine in def-lists (nested def-lists with titles)
    • In tables: merged cells with boldface paras;
      but how to indent subitems?
  • How to tag intermittent prose paras?
    • Ugly workarounds in def-lists
      (def-items with empty terms and special content-types)
    • Merged cells with paras in tables

In 2021, as a member of the NISO STS standing committee, I conducted an extensive survey of 37,841 DIN (incl. EN, ISO) standards

Analysis result

The existing legends can be modeled best

  • with a dedidated container element
  • that may have a title (typically “Key”, or “Légende”, or “Legende”)
  • that is a bag for
    • definition lists
    • paragraphs
    • tables
    • notes
  • but no (nested) sections necessary, def-lists (nested if needed) or tables with headings will suffice

Makeshift legend container approaches compatible with 1.0

  • Standards Norway: 
    <fig>
  <label>Figure 1</label>
  <caption><title>…</title></caption>
  <graphic xlink:href="graphic_0001.png"/>
  <non-normative-note content-type="explanatory">
    <label>key</label>
    <def-list>…</def-list>
    <p>…</p>
    <def-list>…</def-list>
  • DIN: 
    <fig id="fig-2" orientation="portrait">
  <label>Bild 2</label>
  <caption>…</caption>
  <graphic xlink:href="fig-2.png"/>
  <normative-note content-type="legend"><!--NISO STS 1.0 placeholder for the legend element-->
    <title>Legende</title>
    <def-list>…</def-list>
    <non-normative-note>
      <label>ANMERKUNG</label>
      <p>…</p>
    </non-normative-note>
    <def-list list-content="footnotes">…</def-list>
  </normative-note>
</fig>

Proposed and accepted for NISO STS 1.2: legend

  • Standards Norway example: 
    <fig>
  <label>Figure 1</label>
  <caption><title>…</title></caption>
  <legend>
    <label>key</label>
    <def-list>…</def-list>
    <p>…</p>
    <def-list>…</def-list>
  </legend>
  <graphic xlink:href="graphic_0001.png"/>
  • DIN example: 
    <fig id="fig-2" orientation="portrait">
  <label>Bild 2</label>
  <caption>…</caption>
  <legend>
    <title>Legende</title>
    <def-list>…</def-list>
    <non-normative-note>
      <label>ANMERKUNG</label>
      <p>…</p>
    </non-normative-note>
    <def-list list-content="footnotes">…</def-list>
  </legend>
  <graphic xlink:href="fig-2.png"/>
</fig>

The weird example, retagged

<fig id="fig-na.f.1">
  <label>Bild NA.F.1</label>
  <caption><title>…</title></caption>
  <legend>
    <title>Legende</title>
    <table-wrap>
      <legend><!-- where list for the calculation formulas below -->
        <title>Dabei ist</title>
        <def-list>
          <def-item>
            <term><italic>N</italic><sub>max</sub></term>
            <def>…</def>
          </def-item>
          … 
        </def-list>
      </legend>
      <table border="0" frame="void">
        <col span="1" width="50.00625315mm"/>
        <col span="1" width="122.00820213mm"/>
        <tbody>[Quantities with calcualation formulas]</tbody>
      </table>
    </table-wrap>
  </legend>
  <graphic xlink:href="…"/>
</fig>

The weird example, retagged, with def-list instead of table-wrap

<fig id="fig-na.f.1">
  <label>Bild NA.F.1</label>
  <caption><title>…</title></caption>
  <legend>
    <title>Legende</title>
    <def-list>
      [Quantities with calcualation formulas, as def-items]
      <def-list>[Unsure whether a nested def-list is best here – may
        be regarded as subitem to the last def-item. 
        But legend is not allowed in a def-list (yet?)] 
        <title>Dabei ist</title>
        <def-item>
          <term><italic>N</italic><sub>max</sub></term>
          <def>…</def>
        </def-item>
         … 
      </def-list>
  </legend>
  <graphic xlink:href="…"/>
</fig>

Formula where list in the wild

<p style-type="indent"><italic>d</italic> = <italic>d</italic>′ cos<italic>α</italic></p>
<p>where</p>
<array>
  <table width="650">
    <colgroup>
      <col align="left" valign="top" width="10%"/>
      <col align="left" valign="top" width="90%"/>
    </colgroup>
    <tbody>
      <tr>
        <td><italic>d</italic></td>
        <td>is the coating thickness when <italic>α</italic> = 0;</td>
      </tr>
      …

Formula where list, ISO/IEC style

<disp-formula><italic>d</italic> = <italic>d</italic>′ cos<italic>α</italic></disp-formula>
<def-list list-content="formula">
  <label>where</label>
  <def-item>
    <term><italic>d</italic></term>
    <def>
      <p>is the coating thickness when <italic>α</italic> = 0;</p>
    </def>
  </def-item>
  … 
</def-list>

Formula where list, as legend

<disp-formula><italic>d</italic> = <italic>d</italic>′ cos<italic>α</italic>
  <legend>
    <title>where</title>
    <def-list>
      <def-item>
        <term><italic>d</italic></term>
        <def><p>is the coating thickness when <italic>α</italic> = 0;</p></def>
      </def-item>
      …
    </def-list>
  </legend>
</disp-formula>

JATS 1.4

The NISO voting pool will be formed in a week’s time, so 1.4 is just around the corner

You can already try out legend in 1.4d1

In contrast to the NISO STS legend, it may not contain non-normative-note and normative-note since these elements are specific to STS

How do you tag figure legends in DocBook?