[Firebird-docs] Do we need/want chunked HTML?

[Mark R. <ma...@la...>]

As I'm looking at the asciidoc conversion, our current choice of having 
a (single) PDF and a chunked HTML output on the website is a bit of a 
pain point.

Asciidoctor does not support chunked HTML output (there is an 
experimental, third-party plugin, but that plugin is tied to a specific, 
out-of-date asciidoctor version).

The current options to produce chunked HTML output are:

1. Use separate asciidoc files per section
2. Generate docbook from asciidoc and then use xsl to generate chunked HTML

Option 1 has the downsides that to generate a PDF, an additional 
'include' file needs to be maintained to be able to generate a single 
document in addition to the 'chunked' files. This has maintenance 
overhead and could be something that can easily be overlooked when 
adding sections. I also haven't yet figured out how to have navigation 
between sections in the (faked) chunked output this way.

This last concern might be addressable by using 
Antora[https://antora.org/] to generate the HTML documentation (eg see 
https://docs.antora.org/antora/2.2/ for an example), but that feels like 
a huge increase in scope.

Option 2 might run into some problems as asciidoctor generates docbook 
5, not docbook 4.5, so I'm not sure if this would cause problems with 
our current stylesheets.

Option 2 seems to be the least intrusive way to retain chunked HTML 
output. However, before I spend a lot of time going that route, I'm 
wondering:

- Do we need to retain the ability to generate chunked HTML output?
- And, what is the reason that we currently use chunked HTML output?

Personally, I'm not really a fan of chunked HTML (searching through a 
single page HTML document is much simpler), but maybe I'm overlooking 
something.

Mark
-- 
Mark Rotteveel