ASAM Editorial Guide: Refine rule ASM-15

[christiangoedert]

The source code is as follows:

Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in <<sec-283d9649-af8b-4983-b6c9-73cc5f2971a0, Section Modal verbs>>, are normative.

The rendered output is as follows:

Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in Section Modal verbs, are normative.

Syntax for links to chapters or sections

1. Section (noun)
2. Chapter or section name

The syntax for rendering links is implemented in the ASAM Style Resources repository in the preamble.adoc.

https://code.asam.net/common/style-resources

[jmdska]

There are currently two different ways in use how to link a section:

1. see <<sec-8345bf25-d584-4a5b-8fa7-e15c920ab219>>
2. as defined in <<sec-283d9649-af8b-4983-b6c9-73cc5f2971a0, Section Modal verbs>>

The output differs as follows:

1. "see Section 11.5.4"
2. "as defined in Section Modal verbs"

The first cross reference completely generates the output. The second cross reference uses the alternative text given in the inserted link.

[christiangoedert]

I suggest to use ":xrefstyle: full" for links in AsciiDoc documentation. This will generate, for example, links as follows:

• Section 11.6.1, “Road marking types and lines”
• Section 12.3, “Connecting roads”

The link in the documentation is, for example, as follows:

<<top-3e9bb97e-f2ab-4751-906a-c25e9fb7ac4e>>, or a semantic representation

An advantage of using ":xrefstyle: full" is that no specific link text has to be defined when creating a link. The link text is taken from the title of the linked section.

If a specific link text is needed, this specific link text can be added to the link, for example:

<<top-3e9bb97e-f2ab-4751-906a-c25e9fb7ac4e, Sausages are delicious>>

There shall be an exception for figures and tables because defining ":xrefstyle: full" generates, for example, links for figures as follows:

Figure 1, “Relationship between ASAM OpenDRIVE, ASAM OpenCRG, and ASAM OpenSCENARIO”

The link text can be extremely long because the caption is taken for the link text. Just the term Figure followed by the figure number shall be displayed in the documentation, for example, Figure 1. The same applies to links on tables.

[jmdska]

Updated xref rules in commit https://github.com/asam-ev/asam-project-guide-content/commit/cddac629b240da5e1ae93e437d425ba28a3b327b

Current ASM-15 proposes now the use of "xref:" syntax instead of "<<>>" syntax.