Metanorma: Aequitate Verum

Author's documentation

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.

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 3. Figure with caption
.Caption
image::logo.jpg[]
Example 4. 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 5. Figure with accessible titleattr title
[titleattr=Title Attribute]
image::logo.jpg

Or

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

Both captions and titles could be used together.

Example 7. 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] [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 8. 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 9. 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.

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 10. 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 [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.6].

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

Note
 Subfigures commonly appear in the ISO/IEC flavors.
Example 12. 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[]
====

Preformatted content

Figures can include preformatted content.

Example 13. Figure with a 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 14. 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 15. 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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2].

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

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

[.source]
<<iso1212>>
====
Example 17. 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.

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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/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)
* ...
====

  1. {filename}.svg is the filename of the SVG image with hyperlinks.

  2. {remapped-link-1} is the desired destination that replaces {original-link-1}, it could be a hyperlink or a cross-reference.

  3. {original-link-1} is an existing hyperlink (content of the href) in the SVG image. The links are separated by a semicolon.

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

Example 18. 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:

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