[docbook-apps] Assemblies and Directories

[Philo Calhoun]

With DITA topics and a DITA bookmap, I can easily have topics in logical 
directories and create a pdf target that works. 

I tried doing the same thing in a Docbook Assembly and encountered problems. I 
put the Docbook topics in various subdirectories which basically corresponded 
to chapter titles. If any of the Docbook topics had relative references to 
images, crossrefs, etc, these no longer worked when I made an assembly target, 
as it created a new "Untitiled.xml" file where the references and 
cross-references were no longer correct. Rather than just dumping all the 
docbook topics together in the same directory as the docbook assembly, is there 
a way of working so that the links don't get broken?

smime.p7s
Description: S/MIME cryptographic signature

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

[Jan Tosovsky]

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


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

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

[Kevin Dunn]

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


From: Jean-Christophe Helary 
Sent: Monday, November 14, 2022, 11:16 AM
To: 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-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

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

[Tony Graham]

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
tgra...@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

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

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

[Jean-Christophe Helary]

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-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org