Tracking: Transitioning to Antora from Asciidoctor

[engelben]

This is an overview issue to show all individual issues that need to be addressed prior to making a decision on transitioning from AsciiDoctor to Antora.

The intent is to analyse the existing asciidoc documents in order to determine if there are any foreseen problems when switching to antora. This includes topics such as review, content representation, separation of normative vs non. normative content, etc.

For each of these topics a separate issue is to be created and linked with this one. Sidenote: Even better would be better to make them blocking issues, but not sure if we can do that in this Github license??

Also to be discussed: When do we need to reach a decision?

Issues:

• [x] #133
• [x] #134
• [x] #138
• [x] #148
• [x] #128
• [ ] #131
• [x] #149
• [x] #150
• [x] #152
• [x] Check and change access rights for extensions repo
• [ ] Determine and apply version attribute through Antora extension
• [x] Automatic section numbers for pages
• [x] Section numbers ISO-2145-style
• [x] Special section labels in Antora (done for [appendix])
• [x] Sequential image numbering
• [x] Sequential table numbering
• [x] Extension must consider top-level and included files
• [x] Change inline code block style definition to Asciidoctor default
• [x] Replace local links with global ones
• [x] Use section title in replaced local links
• [x] Exclude pages macro from section counting
• [x] Integrate user-roles form in css
• [ ] IDEA: Make page-to-page navigation with arrow keys possible (through script)
• [x] #153
• [ ] #154
• [ ] #156
• [ ] #157

[engelben]

@philipwindecker fyi

[philipwindecker]

Note: If the topic comes up again, this might be an interesting project for converting Antora to pdf: https://www.ruby-toolbox.com/projects/xantora

[christiangoedert]

Links to Figures, Tables, Examples, and in continuous text

Different xrefstyles for links to Figures, Tables, Examples, and in contentious text are required:

• Figures, tables, and examples shall be displayed using :xrefstyle: short, for example, Figure 1, Table 1, Example 1 and so on.

• Links in continuous text shall be displayed using :xrefstyle: full, for example, Section 1.2.3, "Sausages are so delicious"

• Links to Figures, Tables, and Examples have to be tagged using AsciiDoc syntax, for example, <<fig-d8700b83-c9e9-4205-9df4-b9fc0ada3700>>

• Links within continuous text have to be tagged using Antora xref syntax, for example, xref:domain-model:road_abstractions.adoc#top-roads-class-route[]

The extension shall identify the type of link and its occurrence and generate links on the logic mentioned above.

[philipwindecker]

Note: Content analysis is required for osc2 as anchors are not used consistently. I.e. "sec-" and "top-" may not point towards a page top or section. Since most content will be :xrefstyle: short, this is assumed to be the default. Idea: Make it configurable through site.yml whether replacement will be "short" or "full". However, only section links will be updated for now.

TODO for later: Check if all figures and tables are referenced locally or globally.

[philipwindecker]

Comments and input regarding links for figures, tables, examples, and page/section titles have been moved to issue #153

[philipwindecker]

Additional topic (21.06.2022): Linter for anchors with top- instead of sec-