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.
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].
[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.
.Caption
image::logo.jpg[]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.
titleattr title[titleattr=Title Attribute]
image::logo.jpgOr
titleattr title declared in imageimage::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?”.
|
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)-
Optional anchor for referencing
-
Title of the figure
-
The image command with path
-
Specification of figure key section
-
Key entry:
{some-description}is text that describes information about the thing represented by{some-id}
.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.
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.
.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].
.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. |
.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.
[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].
[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].
[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].
[figure]
.Rice husk separation
====
image::logo.jpg[]
[.source]
<<iso1212>>, reformatted
====