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.

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 metanorma-standoc ≥ v2.0.7.

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.

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.

Figure with caption

.Caption
image::logo.jpg[]

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.

Figure with accessible `titleattr` title

[titleattr=Title Attribute]
image::logo.jpg

Figure with accessible `titleattr` title declared in image

image::logo.jpg[titleattr=Title Attribute]

Both captions and titles could be used together.

Figure with both caption and title

.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?”.

Supplementary components

A figure allows the following supplementary components:

Key
Text
Notes
Footnotes

The order of rendering of these components are in the following order:

Key > Text > Note > Footnote

Note

This order aligns with ISO's editorial practice.

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] metanorma-standoc ≥ 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>

.Figure containing a key / legend (from ISO Rice document)

Example

.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.

A key can also be a paragraph preceding, following, or instead of the definition list; the following syntax is also allowed metanorma-standoc ≥ v3.3.0

[%key]
Paragraph used instead of definition list

[%key]
--
Open block allowing multiple paragraphs and definition lists to be combined into a single key
a::b
c::d
Text may also follow after the definition list in a key
--

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

.Figure containing a key / legend using Key syntax (from ISO Rice document)

Example

.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.

Notes and footnotes

Notes and footnotes can be encoded as part of a figure. Both types are rendered in the figure footer, below the Key.

To encode figure notes and footnotes:

Notes (NOTE: ...) entered immediately a figure is considered to be a figure note, and hence included in the figure.
Footnotes (footnote:[...]) part of the textual content of the figure or notes are included in the figure.

Example of a figure with a note and a footnote

.Amount of gelatinization of husked rice through time footnote:[at 1 Pa]
image::rice_images/rice_image10-1.png[]
[NOTE]
Husked rice gelatinized through the Verrol process.

Tip

Figure C.1 in the Metanorma ISO Rice example document illustrates a large range of figure formatting options.

Statement concerning units

A statement concerning units used can be added to a figure, indicating the units of measurement used in the figure.

Note

This currently applies to the ISO, IEC and BSI flavors, and flavors that inherit from them.

The units statement is encoded as a NOTE of type units ([NOTE,type=units]).

The statement is rendered in the top-right corner of the figure metanorma-iso ≥ v2.3.6.

Figure with a statement concerning units

.Amount of gelatinization of husked rice through time
image::rice_images/rice_image10-1.png[]
[NOTE,type=units]
Amount in grams; time in seconds.

Subfigures

Subfigures are entered by including multiple images in an example block. If this markup is used, the images will be rendered one vertically after another.

Note

Subfigures commonly appear in the ISO/IEC flavors.

.Figure with 3 subfigures (from ISO Rice document)

Example

.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[]
====

It is also possible to arrange the subfigures of a figure as a table; this allows both subfigures to be aligned horizontally, and as a table with multiple rows and/or columns, possibly with a subfigure spanning multiple rows or columns metanorma-standoc ≥ v3.1.9. In order to do so, the table containing the subfigures needs to be embedded in an example block marked as [figure].

.Figure with 3 subfigures, in tabular format

Example

[figure]
.Stages of gelatinization
====
[cols="1,3"]
|===
a|.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels)
image::spec/examples/rice_images/rice_image3_1.png[]
a|.Intermediate stages: Some fully gelatinized kernels are visible
image::spec/examples/rice_images/rice_image3_2.png[]
2+a|.Final stages: All kernels are fully gelatinized
image::spec/examples/rice_images/rice_image3_3.png[]
|===
[%key]
A:: B
====

Preformatted content

Figures can include preformatted content.

.Figure with a preformatted block

Example

[figure]
.Hexagram 46 "Ascending"
====
....
|===| |===|
|===| |===|
|===| |===|
|=========|
|=========|
|===| |===|
....
====

For accessibility, preformatted blocks can be provided with an alt text attribute metanorma-standoc ≥ v1.3.10.

.Figure with preformatted block with alt text

Example

[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 metanorma-standoc ≥ v2.2.5.

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.

The source is expected to be a bibliographical reference metanorma-standoc ≥ v2.4.2.

Multiple sources can be given with separate [.source] blocks.

Figure with a single source

[figure]
.Rice husk separation
====
image::logo.jpg[]
[.source]
<<iso1212>>
====

Figure with multiple sources

[figure]
.Rice husk separation
====
image::logo.jpg[]
[.source]
<<iso1212>>, reformatted
[.source]
<<iso1213>>,
====

The first source will indicate it is "reformatted" as the text after the comma is treated as the modification, while the second source will indicate it is "modified" since there is a trailing comma but no description of modification.

Note

The mechanism for indicating source is identical for terminology sources and table sources.

SVG: re-mapping hyperlinks

Metanorma supports the inclusion of SVG images.

SVGs can include hyperlinks on parts of the image, expressed as <a href="...">. When an SVG image is created independently of the current document, the hyperlinks may point to arbitrary destinations.

A document author may want to update these hyperlinks to point to anchors within the document. Metanorma supports the re-mapping of SVG hyperlinks to have them point to parts of a Metanorma document.

The svgmap function supports the re-mapping of SVG hyperlinks metanorma-standoc ≥ v1.8.3. To use this, the SVG image is wrapped in a figure block with the role attribute [.svgmap] instead of [figure].

The syntax of svgmap is as follows.

 [.svgmap]
====
image::{filename}.svg[] <1>
* {remapped-link-1}; {original-link-1} <2> <3>
* ...
====

This allows the author to easily update the hyperlinks within the SVG image to point to the appropriate locations in the current document.

Example of `svgmap` usage

In this block:

 [.svgmap]
====
image::action_schemaexpg1.svg[]
* <<ref1,Computer>>; mn://action_schema
* http://www.example.org[]; http://www.example.com
* <<express:action_schema:action_schema.basic>>; 3
====

The image SVG file is action_schemaexpg1.svg, and it contains hyperlinks to three destinations:

mn://action_schema
http://www.example.com
3

This block instructs Metanorma to rewrite those hyperlink destinations in the SVG, expressed as <a href="...">, to point to the location of the references on the left side:

mn://action_schema is rewritten to the location in the document of the ref1 anchor (or bibliographic reference); the optional cross-reference text, Computer, is inserted in the SVG hyperlink, replacing whatever text is already there, and can be used as a mouseover tip.
http://www.example.com is rewritten to http://www.example.org.
3 is rewritten as the destination of the implicit cross-reference express:action_schema:action_schema.basic.

Edit this page on GitHub →