docbook-apps

For some historical reasons (and maybe others, I don't know), the tool chain used in the project where I'm in charge of the manual uses a very outdated tool chain based on the following elements:

• DocBook XSL Stylesheets 1.75.2 ("dbk") or above
• DocBook XML 4.5 ("docbook-xml-4.5")
• fop 1.1 ("fop-1.1")
• libxml2 2-2.7.7 ("libxml2-2.7.7")
• Saxon 6-5-5 ("saxon")
• XMLmind Web Help Compiler ("whc")
• Ant 1.7.1 or above ("apache-ant")

I'm still investigating the reasons why we're stuck 15 years in the past, but I'd like to move on.

Currently, the PDF that's built from our DocBook set is, not visually pleasant, to say the least.

There are few contributors to the documentation but ideally I'd like something that works equally well on the three major platforms that are Linux / Windows and macOS.

A friend of mine who also is a DITA specialist converted the set to DITA and semi-automatically produced a really nice PDF and there are no reasons why we would not be able to have something equally nice with a modern DocBook toolchain.

So the question is, what are the options?

Thank you in advance for your help.


--
Jean-Christophe Helary @brandelune
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

On 14/11/2022 16:16, Jean-Christophe Helary wrote:
> For some historical reasons (and maybe others, I don't know), the
> tool chain used in the project where I'm in charge of the manual
> uses a very outdated tool chain based on the following elements:
...
> Currently, the PDF that's built from our DocBook set is, not
> visually pleasant, to say the least.

The DocBook stylesheets only aspire to be a starting point. They manage
that fairly successfully.

My example of what can be done is the Markup UK proceedings [2], about
which I wrote a paper. [1]

> There are few contributors to the documentation but ideally I'd like
> something that works equally well on the three major platforms that
> are Linux / Windows and macOS.

The DocBook stylesheets use Ant, which is cross-platform. The Markup UK
proceedings' customisation bundles the (free) fonts used in the PDF so
that the output is identical on Windows and Linux.

The XSL-FO does include some Antenna House Formatter [3] extensions, but
the DocBook stylesheets have had the option to generate Antenna House
Formatter extensions since I don't know when.

I hope that helps.

Regards,


Tony Graham.
--
Senior Architect
XML Division
Antenna House, Inc.
----
Skerries, Ireland
tgraham@antenna.co.jp

[1] https://markupuk.org/webhelp/index.html#ar10.html
[2] https://markupuk.org/pdf/Markup-UK-2021-proceedings.pdf
[3] https://www.antennahouse.com/formatter-v7

As someone who made a similar update, I can provide some perspective. Much of your tool chain may be old, but it's actually "mature," not "outdated." The most limiting element of your tool chain is likely fop. When I migrated from dsssl and jadeTeX to an xsl tool chain, I considered fop alongside Antenna House Formatter and RenderX XEP. As much as I like and admire free tools like fop, the commercial xsl-fo engines are superior. Each of them is available on multiple platforms, and each has a free demo version for evaluation purposes.

The quality of your output may also be much improved by adding a customization layer to the xsl stylesheets. http://www.sagehill.net/docbookxsl/ is a great resource for customization.

Sent from my Verizon, Samsung Galaxy smartphone
Get Outlook for Android<https://aka.ms/AAb9ysg>

________________________________
From: Jean-Christophe Helary <lists@traduction-libre.org>
Sent: Monday, November 14, 2022, 11:16 AM
To: docbook-apps@lists.oasis-open.org <docbook-apps@lists.oasis-open.org>
Subject: [docbook-apps] Multiplatform toolchain for outputting "nice" PDF

For some historical reasons (and maybe others, I don't know), the tool chain used in the project where I'm in charge of the manual uses a very outdated tool chain based on the following elements:

• DocBook XSL Stylesheets 1.75.2 ("dbk") or above
• DocBook XML 4.5 ("docbook-xml-4.5")
• fop 1.1 ("fop-1.1")
• libxml2 2-2.7.7 ("libxml2-2.7.7")
• Saxon 6-5-5 ("saxon")
• XMLmind Web Help Compiler ("whc")
• Ant 1.7.1 or above ("apache-ant")

I'm still investigating the reasons why we're stuck 15 years in the past, but I'd like to move on.

Currently, the PDF that's built from our DocBook set is, not visually pleasant, to say the least.

There are few contributors to the documentation but ideally I'd like something that works equally well on the three major platforms that are Linux / Windows and macOS.

A friend of mine who also is a DITA specialist converted the set to DITA and semi-automatically produced a really nice PDF and there are no reasons why we would not be able to have something equally nice with a modern DocBook toolchain.

So the question is, what are the options?

Thank you in advance for your help.


--
Jean-Christophe Helary @brandelune
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

Hi,

On 14.11.22 19:51, Kevin Dunn wrote:
> As someone who made a similar update, I can provide some perspective. Much of
> your tool chain may be old, but it's actually "mature," not "outdated." The
> most limiting element of your tool chain is likely fop. When I migrated from
> dsssl and jadeTeX to an xsl tool chain, I considered fop alongside Antenna
> House Formatter and RenderX XEP. As much as I like and admire free tools like
> fop, the commercial xsl-fo engines are superior. Each of them is available on
> multiple platforms, and each has a free demo version for evaluation purposes.

FOP has just published version 2.8 a some time ago and I think it has improved
a lot. Of course, depending on what features you need, it may or may not be on
par with commercial formatters. :)


--
Gruß/Regards
Thomas Schraitle

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