RE: [docbook-apps] Multiplatform toolchain for outputting "nice" PDF

["Jan Tosovsky" <j.tosovsky@email.cz>]

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