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
_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs