Metanorma: Aequitate Verum

Figures

Figures

General

Figures are document elements that present non-textual material.

Figures are independently referable, and are considered to be referenceable document blocks.

In Metanorma, a figure in Metanorma is defined as a block (implied or explicitly defined) that contains at least one image.

A figure can contain the following content:

  • image (mandatory)

  • paragraph

  • admonition

  • key / legend

  • preformatted text

Please refer to images for details of the image command.

Note
This page discusses only the markup specific to figures as blocks, using the image command image::[].

Basic figure

A block image in isolation is automatically considered as a figure containing an image.

Example 1. Basic figure composed of just one image

A single block image in isolation is treated as a figure.

.Figure title
image::{PATH}.png[]

Figure block

A figure block can contain multiple types and instances of content, such as images, paragraphs and admonitions.

A figure block is encoded as an example block with the [figure] role [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7].

Example 2. Explicit figure declaration
[figure]
.Figure title
====
image::{PATH}.png[alt text]

This is explanatory text.

NOTE: And this is a note.
====
Note
Previously the explicit declaration on the example block uses the [.figure] role.

Key

Figures can be followed by a definition list for the variables used in the figure, just like formulae.

This definition list is marked up with [%key] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3].

The syntax is as follows:

[[some-anchor]] (1)
.Figure title (2)
image::figure-path.png[] (3)

[%key] (4)
{some-id}:: {some-description} (5)
  1. Optional anchor for referencing

  2. Title of the figure

  3. The image command with path

  4. Specification of figure key section

  5. Key entry: {some-description} is text that describes information about the thing represented by {some-id}

Example 3. Figure containing a key / legend (from ISO Rice document)
.Typical gelatinization curve
image::rice_images/rice_image2.png[]
footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]

[%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
P:: point of the curve corresponding to a cooking time of stem:[t_90]

NOTE: These results are based on a study carried out on three different types of kernel.

The key definition list can also be preceded by a paragraph consisting of *Key*, though that is not recommended.

Example 4. Figure containing a key / legend using Key syntax (from ISO Rice document)
.Typical gelatinization curve
image::rice_images/rice_image2.png[alt text]
footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]

*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
P:: point of the curve corresponding to a cooking time of stem:[t_90]

NOTE: These results are based on a study carried out on three different types of kernel.

Subfigures

Subfigures are entered by including multiple images in an example block.

Note
Subfigures commonly appear in the ISO/IEC flavors.
Example 5. Figure with 3 subfigures (from ISO Rice document)
.Stages of gelatinization
====
.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels)
image::rice_images/rice_image3_1.png[]

.Intermediate stages: Some fully gelatinized kernels are visible
image::rice_images/rice_image3_2.png[]

.Final stages: All kernels are fully gelatinized
image::rice_images/rice_image3_3.png[]
====

Captions and titles

General

A caption and a title on a figure block are different things.

  • The caption is a textual description describing the figure.

  • The title is a name of the figure.

Caption

As elsewhere in Metanorma, the caption of an image (of the figure containing the image) is set with a line prefixed with dot above the image.

Example 6. Figure with caption
.Caption
image::logo.jpg[]
Example 7. Figure with caption declared in the image
image::logo.jpg[title=Caption]
Note
Similar to Asciidoctor AsciiDoc, the title attribute is treated as identical to the dot-prefixed caption.

Title

Metanorma supports a title attribute on images for accessibility, which is distinct from the figure caption.

This is entered in Metanorma as the titleattr attribute.

Example 8. Figure with accessible titleattr title
[titleattr=Title Attribute]
image::logo.jpg

Or

Example 9. Figure with accessible titleattr title declared in image
image::logo.jpg[titleattr=Title Attribute]

Both captions and titles could be used together.

.Rice husk separation in rice farm at Breton near Dinan
image::logo.jpg[titleattr=Photo of rice husks being separated]
Note
Word exception. The titleattr attribute does not get rendered in Word output due to Word limitations. Word only supports a single image “Alt Text”, which would be set by the caption. Word’s description of “Alt Text” is: “How would you describe this object and its context to someone who is blind?”.

Preformatted blocks

Figures can include preformatted blocks.

Example 10. Figure with preformatted block
[figure]
.Hexagram 46 "Ascending"
====
....
|===| |===|
|===| |===|
|===| |===|
|=========|
|=========|
|===| |===|
....
====

For accessibility, preformatted blocks can be provided with an alt text attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].

Example 11. Figure with preformatted block with alt text
[figure]
====
[alt=ASCII art of a dog]
....
     ___^_
   /    | \__/\
    \   /  ^ ^|
   / \_/   0  0_
  /             \
 /     ___     0 |
/      /  \___ _/
....
====

Class

Figures in documents can belong to different classes (e.g. Plate, Chart, Diagram), each of which can be auto-numbered and captioned differently.

To set this, the desired class can be indicated through the class attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.5].

Example 12. Figure with specific class
[class=plate]
.Rice husk separation in rice farm at Breton near Dinan
image::logo.jpg[]

Source

A figure block can incorporate an indication of its source.

To set this, the source is expected to be a bibliographical reference, just as with term sources [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2].

Example 13. Figure with source
[figure]
.Rice husk separation
====
image::logo.jpg[]

[.source]
<<iso1212>>, reformatted
====