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

[Alexey K. <ak...@ib...>]

Hello,

I think we don't need chuncked html.

Regards,
Alexey


On 08.03.2020 16:13, Mark Rotteveel wrote:
> 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