Support for ISO/IEC full subfigures (ISO DIR 2:2021 28.3.2) (was: Subfigures not working if Key is included)

[ronaldtse]

(UPDATED: 20220731)

ISO/IEC DIR 2 supports Figure with subfigures

ISO/IEC DIR 2, 28.3.2 describes "subfigures"here. This feature has been in DIR 2 since at least 2011.

A figure that contains subfigures supports the following elements:

• a statement concerning units
• multiple subfigures
• a key for the subfigures, as a definition list
• additional paragraphs that describe the subfigures (normal clause text with NOTEs, but without tables, figures, examples)
• footnotes (which are referred to by content in the subfigure captions, paragraphs and NOTEs within the figure)

Metanorma current support of subfigures

Currently in Metanorma subfigures are supported in ISO but only the simplest form, of multiple images/figures.

Here, it describes that the "Key" content exists within the Figure.

Note that the subfigure example we have currently lacks a few things:

1. a "Statement concerning units" before the first subfigure.
2. a "Key" container that has paragraphs/lists after the last subfigure
3. Footnotes to the figure.

Metanorma also supports a figure with non-images:

This is the intended layout:

However, including the "Key" in the Figure doesn't work in Word, and PDF generation crashes.

[[fig-C17-2]]
.Use of horizontal pattern and strata
====
.Grass with scattered patches of trees
image::img-C17-2a.png[]

.Grass with trees and grass without trees composed of 3-dimensional elementary features
image::img-C17-2b.png[]

.LCML horizontal pattern
image::img-C17-2c.png[]

*Key*:

This is an illustration of the approach of using horizontal pattern and
strata.

. The portion of the grass beneath the trees has different plant composition and
characteristics (density, height).

. The grass with trees and grass without trees, are treated as separate physical
features composed by 3-dimensional elementary features (tegons). This results in an
intrinsic (functional entity) mix between two types of land cover features having
different strata,

. It is described in LCML with the "horizontal pattern".
====

It becomes an EXAMPLE with 3 inner Figures, which is wrong:

If I move the "Key" outside of the Figure, it works:

[[fig-C17-2]]
.Use of horizontal pattern and strata
====
.Grass with scattered patches of trees
image::img-C17-2a.png[]

.Grass with trees and grass without trees composed of 3-dimensional elementary features
image::img-C17-2b.png[]

.LCML horizontal pattern
image::img-C17-2c.png[]

====

*Key*:

This is an illustration of the approach of using horizontal pattern and
strata.

. The portion of the grass beneath the trees has different plant composition and
characteristics (density, height).

. The grass with trees and grass without trees, are treated as separate physical
features composed by 3-dimensional elementary features (tegons). This results in an
intrinsic (functional entity) mix between two types of land cover features having
different strata,

. It is described in LCML with the "horizontal pattern".

Metanorma with full subfigure support

We need to implement a complete [figure] block syntax to support figures with subfigures and their associated content.

Some functionality needed:

• Cross referencing from within the text in the figure to the subfigures
• Full [figure] syntax
• Recognition and rendering of units statement
• Recognition and rendering of key
• Rendering of footnotes within the figure
• Explicit and implicit

Full figure syntax

[figure]
====
[%units]
A statement concerning units. footnote:[Footnote]

// explicit subfigure
[figure]
[[subfigure-a]]
.An explicit subfigure "a)"
======
image::rice_images/rice_image1.png[alt text]

Some content.
======

// implicit subfigure
.An implicit subfigure "b)"
image::rice_images/rice_image2.png[alt text]

[%key]
stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent
stem:[t]:: cooking time, expressed in minutes
stem:[t_90]:: time required to gelatinize 90 % of the kernels footnote:[Another footnote]
P:: point of the curve corresponding to a cooking time of stem:[t_90]

Some paragraph text. <<subfigure-a>> describes...

NOTE: These results are based on a study carried out on three different types of kernel. footnote:[More footnotes]
====

While this is the full syntax for a figure/subfigures, there are "convenience syntaxes" for simpler figure inclusion.

Figure with multiple images only => auto subfigures

We have this now:

[figure]
====
.An explicit subfigure "a)"
image::rice_images/rice_image1.png[alt text]

.An implicit subfigure "b)"
image::rice_images/rice_image2.png[alt text]
====

Figure with image + text => one figure

We have this now:

[figure]
====
image::rice_images/rice_image1.png[alt text]

Some text.
====

Figure with key after => one figure with key

We support this.

[figure]
.Some caption
====
image::rice_images/rice_image1.png[alt text]
====

[%key]
one:: one
two:: two

Image with key after => one figure with key

We support this.

.Some caption
image::rice_images/rice_image1.png[alt text]

[%key]
one:: one
two:: two

Figure with subfigures with key after => multiple figures with key

We don't support this.

[figure]
====
.An explicit subfigure "a)"
image::rice_images/rice_image1.png[alt text]

.An explicit subfigure "b)"
image::rice_images/rice_image2.png[alt text]
====

[%key]
one:: one
two:: two

Once this task is done we should also update the Metanorma site to provide a full example of subfigure with text/paragraphs.

NOTE: This is a blocker to https://github.com/metanorma/iso-19144-2.

[opoudjis]

Subfigures are recognised as examples containing only figures.

Figure keys are supposed to be definition lists, and are recognised as such.

DISCURSIVE PARAGRAPHS ARE NOT DEFINITION LISTS.

This is the first time I've seen any indication that anything other than definition lists is supposed to be a figure key. Every single other example in ISO/IEC DIR 2 of a table or figure key is a definition list, and the cited subfigure "key" is an umbrella description of notes and footnotes.

I take very strong exception to being told that I should have magically anticipated random markup that does not correspond to the common sense understanding of ISO/IEC DIR 2. This is not a key as far as Metanorma is concerned, and it is not encompassed by Metanorma syntax. I REFUSE to implement this without EXPLICIT feedback from ISO editorial that this is a legitimate instance of a key. As it is, if I were to implement this, it would NOT be with that existing markup: I would need to introduce a new open block syntax, and a much looser syntax.

I VEHEMENTLY recommend you do not disrupt Metanorma parsing and syntax over addle-headed frivolous and one-off use of ISO formatting. This is not a key. This is a note. And it should be treated as such.

[ronaldtse]

Figure keys are supposed to be definition lists, and are recognised as such.

The image from ISO DIR 2 explicitly describes the "key" to contain "paragraphs".

This is not a key. This is a note.

ISO DIR 2 says: "Separate keys, notes and footnotes for subfigures are not permitted."

I REFUSE to implement this without EXPLICIT feedback from ISO editorial that this is a legitimate instance of a key.

Sorry, but ISO editorial are bound by ISO DIR 2. When ISO DIR 2 says it is the correct form, it is the correct form.

if I were to implement this, it would NOT be with that existing markup: I would need to introduce a new open block syntax, and a much looser syntax.

I don't see why we cannot reuse the existing ==== block syntax with a role of "figure".

From the above reply I am not confident whether you have read the image:

[opoudjis]

We are seeking confirmation on whether keys can be free text. The image is not a definition of keys, and it contradicts the definition of keys for tables. ISO DIR 2 is not explicit that the foregoing is a definition of keys; in fact, in its source diagram (in IEC, keys are mutually exclusive from requirement paragraphs and notes.

It does turn out that definition lists will incorrectly be embedded within subfigures (as nearest neighbours). That needs to be prevented, as it violates ISO/IEC DIR 2.

[ronaldtse]

I have updated the original ticket to update our current understanding. Will also update this once we receive feedback from ISO Editorial.

[ronaldtse]

I think we know what Keys are, they are the ones shown in the Rice document, which is not free text.

It does turn out that definition lists will incorrectly be embedded within subfigures (as nearest neighbours). That needs to be prevented, as it violates ISO/IEC DIR 2.

I think we should stop merging the nearest definition list into the figure, it is very confusing for the author, especially when the definition list often is not part of the figure.

[opoudjis]

In fact we now also support this:

[figure]
====
.An explicit subfigure "a)"
image::rice_images/rice_image1.png[alt text]

.An explicit subfigure "b)"
image::rice_images/rice_image2.png[alt text]

[%key]
one:: one
two:: two

NOTE: Note
====

In fact, so will:

[figure]
====

.An explicit subfigure "a)"
=====
image::spec/assets/rice_image1.png[alt text]
=====

.An explicit subfigure "b)"
=====
image::spec/assets/rice_image1.png[alt text]
=====

[%key]
one:: one
two:: two

NOTE: Note
====

At issue is whether we allow [%key] to mark up open blocks of text as well.

I think we should stop merging the nearest definition list into the figure, it is very confusing for the author, especially when the definition list often is not part of the figure.

We aren't: we are only merging definition lists marked with [%key] — signalling explicitly that they are associated with a figure or table.

We also have the original syntax

*Key*

a:: b

But I'm happy for that to be dropped from documentation, and kept only as legacy.

[ronaldtse]

At issue is whether we allow [%key] to mark up open blocks of text as well.

I would say we should only allow text blocks in the figure if it was explicitly put in the figure block.

I don’t think DIR 2 specified exactly what a “Key” is.

*Key* syntax

Let’s make this legacy. And keep it as a note in documentation.

BTW, does the Key syntax work the same way for Formulas?

[opoudjis]

I would say we should only allow text blocks in the figure if it was explicitly put in the figure block.

That's not answering my question. Should text blocks be recognised as keys? That's your pending query to ISO.

Formulas work the same way: "where", or [%key], and again, what follows is expected to be a definition list.

[ronaldtse]

Should text blocks be recognised as keys? That's your pending query to ISO.

According to the figure, yes generic paragraphs (containing requirements) can be a key. This means that it would be better if the "key" is specified as an open block.

[opoudjis]

Units notes implemented: metanorma/metanorma-standoc#688