Implement behavior for "code-" anchors

[philipwindecker]

Subject

Define expected behavior for the use of the anchor type "code-" regarding Antora extensions.

Description

When the extension for handling anchors was written, only requirements for the anchors "top-", "sec-", "fig-", and "tab-" were specified.
Now, there also is some specification on the use of the anchor "code-": https://asam-ev.github.io/asam-project-guide/asamprojectguide/latest/compendium/Editorial_guide/07_source_code.html

The extension, however, will mark these anchors as "non-standard" and will execute some default behavior for them, which may be incorrect in the context of ASAM.

Suggestion

To change this, specify requirements and implement them accordingly in the respective extensions.
This should mostly be fixed within the content_analyzer.js module, unless some other functionality beyond handling the anchor name is required (e.g. in loft).

Assumptions

• "code-" anchors are correct and should not create a warning
• they need to be enumerated consistently
• they behave similarly to figures or tables
• the "listing-caption" attribute is used to change the label from "Code xx" to sth else, where "xx" is the current number
• source code blocks inside an example block are enumerated by example number, not code number
• currently, examples and code blocks use the same type of anchor;
• check that the following order is fulfilled:
  • anchor
  • title
  • if not section or page title: block delimiter or macro

Rules

• all code blocks (listings) shall have an anchor starting with "code-"
• all code blocks (listings) shall have a title (".title")
• all code blocks (listings) shall have linenumbers, ideally set globally through source-linenums-option
• all documents using code blocks shall set the attribute :listing-caption: "Code" (ideally, this is set globally)
• if any block is nested inside another block, the outer block takes precendence (e.g. a source block inside an example block has no title, since the example block will already use one)
• NOTE: As an example block is technically distinct from a listing/source block, Asciidoctor will apply the :example-caption: and not the :listing-caption: attribute. Therefore, the enumeration will also work differently for source code blocks than for example blocks. IT WILL BE IMPLEMENTED THUS: Example blocks have their own enumeration compared to source/listing blocks. Thus, not only the anchor is analyzed, but also if it is used correctly and is followed by a example or a listing block. Depending on the block type, the respective counter is increased.

CURRENT WORKAROUND

The current implementation has a line added to reset the code counter back to 0 for each file.
The reason is that in osc2 the use of code- anchors is not consistent and, therefore, numbers will jump.
Remove this after osc2 has been released.

[philipwindecker]

First assessment

What works

• Adding "Code" captions to all code blocks by setting the attribute "listing-caption" in the site.yml or any relevant antora.yml
• Identifying all pages where a top- anchor is used for a section
• Identifying all partials where a top- anchor is used
• Identifying all pages where a sec- anchor is used for the title
• Identifying all sec- and top- anchors where the anchor is not immediately followed by a section/title
• Identifying all code- anchors where no title is set immediately after the anchor
• Identifying all code- anchors where no source or example block is set immediately after the title
• Creating info logs for all code- anchors that use an example block instead of a source block

What does not work yet

• Identifying incorrectly used fig- and tab- anchors

What will not work

• Source highlighting in Antora does not allow linenums.
  • Reason: Antora, by default, only supports highlighter.js. highlighter.js, in turn, does not support linenums because of design decisions.
  • Sources:
    • https://docs.antora.org/antora/2.3/asciidoc/source/
    • https://highlightjs.readthedocs.io/en/latest/line-numbers.html
  • Options:
    • Remove line number requirement for Antora documents
    • Add different highlighter library to Antora UI
    • Create custom highlighter.js library with included linenums
    • Create extension that pre- or post-processes code content

[philipwindecker]

Extension update is ready for testing: https://code.asam.net/common/asam-antora-extensions/-/tree/update_loft_and_anchors
Example use: https://code.asam.net/simulation/standard/openscenario-2.0/-/tree/fix_uml2adoc_anchor_names

[christiangoedert]

Suggestion for rules

Use ==== for example blocks
Use "exa-" for anchor prefix
Reference text on example: "Example <number>"

Use ---- for source code blocks
Use "code-" for anchor prefix
Reference text on source code: "Code example <number>"

Comparison of example and source code highlighting

[.underline]#XML example#

*Original File*

[source, xml, linenums]
----
<planView>
    <include file="planview.xml"/>
</planView>
----

*Included File*

[source, xml, linenums]
----
<planView>
    <geometry x="-0.014" y="-0.055" hdg="2.88" length="95.89" s="0.0">
        <arc curvature="-0.000490572"/>
    </geometry>
    <geometry x="-92.10" y="26.64" hdg="2.84" length="46.65" s="95.89">
        <spiral curvStart="-0.000490572" curvEnd="-0.004661241"/>
    </geometry>
</planView>
----

[#exa-uid]
.XML example
====
[#code-uid-1]
.Original File
[source, xml, linenums]
----
<planView>
    <include file="planview.xml"/>
</planView>
----

[#code-uid-2]
.Included File
[source, xml, linenums]
----
<planView>
    <geometry x="-0.014" y="-0.055" hdg="2.88" length="95.89" s="0.0">
        <arc curvature="-0.000490572"/>
    </geometry>
    <geometry x="-92.10" y="26.64" hdg="2.84" length="46.65" s="95.89">
        <spiral curvStart="-0.000490572" curvEnd="-0.004661241"/>
    </geometry>
</planView>
----
====