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:

• Integration of rich HTML deliverables (Enterprise Architect HTML Export, Doxygen HTML Export, ...) #133
• HTML includes (doxygen, EA) also searchable #134
• Embedding of source elements (xml schema, ...) with display and download #138
• Antora document in Review Process #148
• marking of normative and non-normative sections #128
• Bibtex in Antora #131
• Automatic nav.adoc generation from main.adoc/index.adoc (include:: -> xref:) #149
• Convert LOFT script to Antora extension #150
• List all unused partials and pages with draft sections #152
• Check and change access rights for extensions repo
• Determine and apply version attribute through Antora extension
• Automatic section numbers for pages
• Section numbers ISO-2145-style
• Special section labels in Antora (done for [appendix])
• Sequential image numbering
• Sequential table numbering
• Extension must consider top-level and included files
• Change inline code block style definition to Asciidoctor default
• Replace local links with global ones
• Use section title in replaced local links
• Exclude pages macro from section counting
• Integrate user-roles form in css
• IDEA: Make page-to-page navigation with arrow keys possible (through script)
• Extensions for varying link style application #153
• Implement behavior for "code-" anchors #154
• Create custom bibliography features based on osc2 solution #156
• Add numlines to highlighter #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

[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-