RE: Multiplatform toolchain for outputting "nice" PDF

On November 14, 2022 Jean-Christophe wrote:
> Currently, the PDF that's built from our DocBook set is, not visually =
pleasant, to say the least.

When generating outputs you are usually pushed to follow the corporate =
identity. And it is IMHO easier extending the minimalistic default style =
than overriding more complex one.
You can achieve really outstanding outputs, but it requires advanced =
XSLT and XSL-FO skills and also a decent understanding of how DocBook =
stylesheets are structured and layered. All this can work with your =
current toolset.

You can start here: =
http://www.sagehill.net/docbookxsl/CustomizingPart.html

But before diving into the new world, keep in mind PDF has fundamental =
limitations and its use is decreasing. In our company, it is currently =
being phased out because:
- for REST API descriptions we cannot offer the same level of =
interactivity as in case HTML outputs (collapsing sections, selecting =
examples from the dropdown list)
- examples in method descriptions have limited width so lines have to be =
wrapped, but sometimes you have to break the word and put a special =
hyphen character there; such examples cannot be copied/pasted directly =
into your code
- nowadays people open PDF files usually directly in the browser. Chrome =
cannot load the file progressively (like Firefox can) so in case of =
larger file you have to wait until the file is fully downloaded. The =
file has to be parsed and converted into DOM and set of CSS styles, =
which is far less efficient than feeding the browser with HTML + CSS =
directly.
- accessibility: PDF engine is a blackbox and you have limited control =
over the final PDF structure to optimize it for screen readers or =
fulfill WCAG and Section 508 requirements
- problematic support for videos (especially those with subtitles or =
transcriptions)

Regards, Jan