Generate multi-HTML page documentation for website and Eclipse help

Idea

Currently, we generate a single page HTML document for ESCET and each of its languages/tools. This leads to less than ideal results. It is not always clear where you are in the documentation, where you go from one section to another, etc. We want multi-page HTML output.

Some inspiration can be obtained here:

Alternative options

There are multiple options:

asciidoctor-maven-plugin with preserveDirectories
- Idea: generate a .html file per .asciidoc file, separately.
- More info:
- Examples:
  - https://gitlab.eclipse.org/eclipse/comma/comma/-/blob/main/lib/org.eclipse.comma.help/pom.xml#L28
  - https://gitlab.eclipse.org/eclipse/comma/comma/-/blob/main/pom.xml#L166
- Benefits:
  - Seems easy to configure (also in Maven)
  - We already use this Maven plugin
  - Each source file becomes an HTML page (we already have that division in place)
- Downsides:
  - No native cross-document linking. For HTML output, can use <<some_path/some_file.asciidoc#section>> syntax, where .asciidoc is replaced by .html. However, that won't work for PDF, can't also generate single HTML page output then, and since it is an external reference you lose all link validation.
- Conclusion: working solution, if we are willing to drop PDF and single-page HTML output, and don't mind losing link validation

asciidoctor-multipage
- Idea: generates multiple .html files from a single .asciidoc file.
- More info: https://github.com/owenh000/asciidoctor-multipage
- Example: https://github.com/Yuri-Blankenstein-TNO/asciidoctor-maven-examples/tree/asciidoctor-multipage/asciidoctor-multipage-example
- Benefits:
  - You get navigation links (next/previous etc) for free (can also be seen as a downside, depending on ones preferences)
  - Allows fine-grained control over what to include on what page (where to start sub-pages)
- Downsides:
  - Needs configuration in sources to control what content is added to what 'page' (not based on source files)
  - Immature alpha version only
  - Requires more complex Maven configuration
  - Doesn't seem to allow configuration of titles/headers/footers/etc
  - Basically no customization possible
  - No control over output filenames and directory structure
  - No footers for sub-pages (not sure this is fixable)
  - Each page ends with a ul/li list of sub-pages (can't disable, no CSS classes or so to style it such that they are not shown)
  - Document title repeated on every page (can hide with CSS)
  - The source tagging to determine what starts a sub-page is not very intuitive (in my opinion)
  - Crashes if Ruby 9.2.15.0 is configured. Does work with older Ruby 9.2.9.0.
  - Usage of gem-maven-plugin Maven plugin produces various warnings during build.
- Conclusion: lack of customization and control over filenames/structure makes this unsuitable

docbkx-maven-plugin
- Idea: convert single .asciidoc file to DocBook (step 1) and use DocBook Maven plugins to generate single or multiple .html files (step 2).
- More info:
- We tried this before. This was our list of things to look into, if we choose this option:
  - Packaging may need to be adapted, as the chunked HTML approach generates a new plugin (incl plugin.xml).
  - Remove "Part 1" / "Chapter 1".
  - Instead of ch01s04.html filenames we want proper filenames.
  - Links to other parts of the same documentation set are broken.
  - Bibliography references are broken.
  - No TOC at the beginning of each chapter.
  - The division into separated pages needs fine tuning.
  - There were layout issues, but the conversion of our documentation from ReST to AsciiDoc was not even finished, so maybe they are now resolved as well.
  - Extra styling is needed (CSS).
  - Customize page headers.
- Benefits:
  - Allows using full DocBook power to generate .html files.
  - DocBook chain has many (hundreds) of options to control what is generated.
  - DocBook chain supports PDF, single page HTML and multi-page HTML.
  - Mature tooling.
- Downsides:
  - Can base filenames on AsciiDoc section IDs. But not for everything. Then requires customization of generated DocBook .xml file, between steps 1 and 2.
  - Can use 'chunking' to produce multiple .html files. Control over what is on separate or same sub-page only by means of (manually specified) custom Table Of Contents (TOC) file. I tried for several hours, but providing such a custom TOC seems to have no effect.
  - Custom TOC syntax not clear/described it seems, so had to use maketoc.xsl to generate a toc and customize it.
  - Can use <?dbhtml dir="dirname" ?> and <?dbhtml filename="filename.html" ?> directives if we (manually?) modify the generate DocBook .xml file. But doesn't control what is placed in a sub-page and what is not, it seems.
  - The division produced by chunking is weird. For SeText release notes, the first sub-section 'v0.2' (in the same .asciidoc file) is kept on the same sub-page as the parent, while its sibling 'v0.1' that is after that is put in a separate sub-page somehow. I can't explain this behavior.
  - PDF generation produces various debug output on stderr during build.
  - No styling by default at all. Must provide own CSS.
  - No sidebar TOC by default. Is there an option for it? Do we have to add it ourselves?
- Conclusion: can't generate a sub-page division that matches the .asciidoc files/structure we already have

Antora
- More info:
  - https://antora.org/ (official web site)
  - https://gitlab.com/antora/antora (source code)
  - https://docs.antora.org/antora/2.3/ (documentation)
  - https://docs.antora.org/antora/2.3/install-and-run-quickstart/ (quickstart)
  - https://github.com/rmannibucau/geronimo-antora-maven-plugin (Geronimo Antora Maven Plugin)
  - https://abelsromero.github.io/blog/2020/antora-with-maven.html (Building Antora with Maven, tutorial)
- Examples:
- Benefits:
  - Very powerful solution.
  - Allows cross referencing between documentation sets.
  - Allows multiple version of documentation set.
- Downsides:
  - More complex solution.
  - Geronimo Antora Maven Plugin
    - Only 5 commits and no changes since 2018. Seems dead.
    - Seems to be very specific, for specific purpose, not that general.
    - Not a lot of documentation. Have to check source code for all maven configuration options.
    - No releases on github. Not on Maven Central. How to use it?
    - Example at https://github.com/rmannibucau/geronimo-site-tester. Doesn't run as can't find the geronimo-antora-maven-plugin.
  - Building Antora with Maven (tutorial)
    - Followed tutorial, including customization of output directory.
    - Executed mvn compile as suggested in tutorial.
    - Installing node/npm/antora (every time) is quite slow. Installation succeeds, but with various warnings.
    - Execution of Antora during Maven build crashes:
      [...]\my-antora-site\node_modules\.bin\antora:2 basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')") ^^^^^^^ SyntaxError: missing ) after argument list
- Conclusion: no native Maven plugin, and solutions found via Google are not sufficient.

Our own custom solution
- Idea: generate single page HTML as we do now, and convert to multi-page HTML ourselves.
- More info: see #36 (comment 65347)

TOC

A general issue to consider is how to generate an Eclipse Help TOC for multiple HTML files. The current approach may only allow a single HTML file. Some ideas:

Maybe we can build our own in Java, using the org.eclipse.help.toc extension point and org.eclipse.help.AbstractTocProvider?
We could somehow generate a toc.xml, as done for Eclipse CommaSuite, see:

Edited Jun 22, 2021 by Dennis Hendriks