10 Figures
This section contains editorial rules on how to create figures:
-
Section 10.2, “Naming conventions for files of figures (ASM-81)”
-
Section 10.3, “Make sure that all included figures are shown correctly (ASM-28)”
-
Section 10.4, “Make sure that there are no unused figures in the repository (ASM-29)”
-
Section 10.6.1, “Add an alternative text for every figure with defined size (ASM-118)”
-
Section 10.6.2, “Add a description for each figure (ASM-59)”
-
Section 10.7, “Use global
plantuml-format
attribute (ASM-94)”
10.1 Use figures with the file type SVG (ASM-57)
SVG is the preferred format for figures.
Exceptions
If you cannot use figures of the file type SVG, use the file type PNG.
Example
There is no example.
Source
ASAM specific rule.
10.2 Naming conventions for files of figures (ASM-81)
The following rules apply:
-
File names of figures shall be named based on the caption of the figures.
-
Lowercase letters shall be used for file names.
-
Underscores
_
shall be used as separators. -
The prefix
fig
shall be used in file names to identify that the file is an image. -
Additional qualifiers may be used, for example,
cs
for core specification.
Exceptions
For long captions the file name may be shortened.
Example without an additional qualifier
Caption of the figure: Port definition interfaces of the framework configuration object model File name: fig_port_definition_interfaces.svg
Example with an additional qualifier
Caption of the figure: Port definition interfaces of the framework configuration object model File name: fig_cs_port_definition_interfaces.svg
Source
ASAM specific rule.
10.3 Make sure that all included figures are shown correctly (ASM-28)
Exceptions
There are no exceptions.
Example
There is no example.
Source
ASAM specific rule.
10.4 Make sure that there are no unused figures in the repository (ASM-29)
Exceptions
There are no exceptions.
Example
There is no example.
Source
ASAM specific rule.
10.5. Use one folder _images
(ASM-92)
An _images
folder shall be created in the content
folder of the repository if the document contains images.
A subfolder shall be created in the _images
folder for every section of the document that contains images.
The subfolder shall be named like the subfolder of the section where the AsciiDoc files are located, for example, 09_geometry
.
The subfolder shall contain the images specific for this section.
Exceptions
There are no exceptions.
Example
content/ ├── _images/ │ ├── ... │ ├── 09_geometry/ │ │ ├── fig_adding_primitives.svg │ │ ├── fig_arc.svg │ │ ├── fig_curve_1.svg │ │ └── ... │ └── ... ├── ... ├── 09_geometry/ │ ├── 09_00_geometry.adoc │ ├── 09_01_road_reference_line.adoc │ ├── 09_02_straight_line.adoc │ └── ... └── ...
Source
ASAM specific rule.
10.6 Add figures in a defined sequence (ASM-134)
Elements for figures shall be added in the following sequence:
-
An anchor (see rule ASM-78)
-
A caption to express the essence of the figure
-
An include of the image (see rule ASM-81, see docs.asciidoctor.org/asciidoc/latest/macros/images/)
-
A blank line
-
A description (see rule ASM-59)
Exceptions
There are no exceptions.
Example
Code
[#fig-ad5fd969-c02a-48fc-97dd-84228f630df6] .This is the caption of the figure image::coo_sys_inertial_example.png[Alternative text] <<fig-96f0f940-36bb-4a8c-8d98-98ff3e71c9bb>> shows something that shall be explained in more detail.
Result
Figure 1 shows something that shall be explained in more detail.
Source
ASAM specific rule.
10.6.1 Add an alternative text for every figure with defined size (ASM-118)
-
Add an alternative text to a figure to trigger the scaling of the figure during the rendering process.
-
If there is no specific alternative text available, use
img
as default. -
Figures without alternative text will not be scaled.
Exceptions
There are no exceptions.
Example
[#fig-fe4294ac-022d-4687-bc13-11798a9b4ce5] .The UML notification image::images/uml_notation.drawio.svg[UML notification, 1100]
img
[#fig-69e40be7-7a2a-439f-b1df-db19679675ad] .This is the caption of the figure image::images/uml_notation.drawio.svg[img, 1100]
Source
ASAM specific rule.
10.6.2 Add a description for each figure (ASM-59)
-
The description shall be below the figure.
-
The description shall start with the text [Reference to figure] shows.
-
The description shall not have an initial article.
-
The description shall not contain references to the placement of the figure, for example, before or below.
-
A reference to a figure shall be realized by a figure anchor. Figure references are displayed as a link.
Exceptions
Decorative figures shall not have a description, for example, the ASAM logo.
Example
Code
<<fig-7558b905-679d-4fb9-affa-3b3b72025a18>> shows the offset of the center lane away from the road reference line.
Result
Figure 58 shows the offset of the center lane away from the road reference line.
Source
ASAM specific rule.
10.7. Use global plantuml-format
attribute (ASM-94)
The images generated from the PlantUML diagrams during the creation of the output document shall have SVG format.
This is globally configured with the document attribute :plantuml-format:
in the document header.
Exceptions
There are no exceptions.
Example
:plantuml-format: svg
Source
ASAM specific rule.