Configure DITA-OT with PrinceXML

eloralon
Posts: 38
Joined: Thu Oct 28, 2010 5:10 pm

Configure DITA-OT with PrinceXML

Post by eloralon » Thu Aug 28, 2014 6:03 pm

Hello oXygen forum users,

Does anyone know how to configure DITA-OT 1.8 or higher to use princexml as pdf formatter? If yes, could you please share your settings?

Thanks for your reply.

Loralon

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Fri Aug 29, 2014 8:32 am

Hi,

The PDF generation plugin which comes bundled with the DITA Open Toolkit is based on producing an XSL-FO file which can then be converted to PDF by a PDF processor like Apache FOP, XEP or Antenna House.
Prince XML cannot convert XSL-FO to PDF. So it cannot be used with this existing PDF generation plugin.

What it can do is convert XML+CSS or XHTML+CSS to PDF.
So there are two approaches:

1) I can disclose we are actively working on a DITA Open Toolkit plugin which takes DITA + CSS and uses Prince XML to produce PDF. The plugin will probably be available in Oxygen 16.1 (in October this year) and possibly also be offered as an open source project. In its initial form the plugin will generate a table of contents and index page for the PDF and its output will look relatively like the output the current DITA OT PDF generation does. Its customization will be quite easily achieved by modifying CSS selectors instead of writing XSLT.

2) Right now you can generate a single XHTML document from the DITA content by setting the chunk="to-content" attribute on the main DITA Map root element.
From that XHTML document with an attached CSS you can try to use Prince XML to generate the PDF.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

HomeGoods
Posts: 87
Joined: Wed Feb 09, 2005 8:57 am

Re: Configure DITA-OT with PrinceXML

Post by HomeGoods » Fri Aug 29, 2014 9:19 am

Radu,

Sounds great!! Will it work with Antenna House too?
Currently I take the second approach with Antenna House and have found it far more efficient than XSL-FO.

Also I hope the index work well with the Japanese language.

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Fri Aug 29, 2014 10:23 am

Hi,

We have not yet made tests with the Antenna House XML+CSS support, probably this will not work out of the box, we are not very familiar with the CSS support Antenna House has.

About the index generation, the plugin we are developing has certain stages copied from the standard PDF generation plugin, one of those stages is the stage which creates the index grouping. Did the index page properly work for you when you generated PDF using the standard support from DITA Japanese content? If so, it should probably work the same with the Prince XML PDF generation but it would need to be tested.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

HomeGoods
Posts: 87
Joined: Wed Feb 09, 2005 8:57 am

Re: Configure DITA-OT with PrinceXML

Post by HomeGoods » Fri Aug 29, 2014 11:25 am

Antenna House CSS Formatter has very good print media XML/HTML+CSS coverage and works pretty well.
I hope your plugin isn't coupled with Prince too tightly, and rather, is developed with possible AH support in mind.

As for the index, I concerned about the sort order's locale awareness and <index-sort-as> awareness. Since the current pdf2 seems to honor them, your plugin will probably be ok.

eloralon
Posts: 38
Joined: Thu Oct 28, 2010 5:10 pm

Re: Configure DITA-OT with PrinceXML

Post by eloralon » Fri Aug 29, 2014 3:41 pm

Thanks Radu.

I will try as suggested.

Loralon

jzucker
Posts: 4
Joined: Wed Oct 15, 2014 10:22 pm

Re: Configure DITA-OT with PrinceXML

Post by jzucker » Wed Oct 15, 2014 10:29 pm

Hi Radu,

I was wondering if there are any documented instructions about how to activate and publish using the Prince PDF plugin that is now available in 16.1 (although experimental). I read the file located in OxygenXML/frameworks/dita/DITA-OT/plugins/com.oxygenxml.pdf.prince/doc, but didn't find a way to use the plugin.

Any guidance that you can provide would be very appreciated!

Thanks!

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Thu Oct 16, 2014 8:23 am

Hi Joe,

Basically you open a DITA Map in the DITA Maps Manager view, click the Configure Transformation Scenarios toolbar button, then choose to create a new scenario of type "DITA OT" and there is a dialog allowing you to select from a range of DITA OT transformation types, including the PDF (Prince XML - Experimental) which you should choose.

http://www.oxygenxml.com/doc/ug-oxygen/ ... ation.html

Before this, you should have the Prince XML application already installed and the path to its executable set in the general system classpath (the plugin will call the executable "prince" directly without searching for a Prince installation).

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Tue Dec 23, 2014 3:05 am

I'm interested in trying out Prince. However, I'm not quite sure how to add prince to my classpath on a Mac. Can you tell me how to do that?

I do have prince installed in /usr/local/bin.

I'm able to run the Prince transformations using the command line, but I'd rather run it from Oxygen directly. Thanks,

Tom

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Tue Dec 23, 2014 3:45 am

If I type

Code: Select all

echo $PATH
I see /usr/local/bin as one of the paths returned. I'm not sure why the prince PDF transform is failing in Oxygen. Any ideas?

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Tue Dec 23, 2014 9:28 am

Hi Tom,

If you type prince in a command line, does it properly locate and run the executable script?

To make sure Oxygen can find Prince, you can edit the PDF (Prince XML - Experimental) transformation scenario you are using to publish DITA using Prince and in the Parameters tab add a new parameter called princeExecPath with the value pointing to the prince executable script like for example /usr/local/bin/prince.

If this still does not work, edit the transformation scenario, in the Output tab there is a Show console output radio which you can set to Always. After the transformation fails, you will find in the DITA OT console tab logging information which you can paste in a codeblock as reply on this thread.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Tue Dec 23, 2014 10:00 am

Hey, that worked. I added a new parameter called princeExecPath with a value of /usr/local/bin/prince and it worked.

Now, another question. Have you developed a custom stylesheet for Prince that will render user guides well? Particularly, is there a way to get cross references such as "see "Troubleshooting" on page 46"?

I did download some sample CSS stylesheets from http://www.princexml.com/samples/ and can see how they use the @page selector and so on. This is helpful. But it would be great if there were already a stylesheet optimized for all the basics of tech comm.

Are there any limitations in Prince (e.g., no indexes or TOCs?) that make it less optimal than XSLT?

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Tue Dec 23, 2014 3:02 pm

Hi Tom,

I'm glad this works for you, please find some answers below:
Now, another question. Have you developed a custom stylesheet for Prince that will render user guides well? Particularly, is there a way to get cross references such as "see "Troubleshooting" on page 46"?
The published PDF should properly render links, images, it should have a table of contents with clickable links to topics.
As you are using Oxygen 16.1 the special CSSs used for printing can be found in:

OXYGEN_INSTALL_DIR\frameworks\dita\css_classed\print

For example the CSS used to control links pagination-links.css does something like:

Code: Select all

    *[class ~= "topic/xref"][href]:after,
*[class ~= "topic/link"][href]:after {
content: " [page " target-counter(attr(href), page) "]";
link: attr(href);
}
to show the page title on the link.

You can also download the slides I made to present the plugin at the DITA OT Day in Munich this year:

http://www.oxygenxml.com/events/2014/dita-ot_day.html

and the plugin is also available separately on GitHub:

https://github.com/oxygenxml/dita-css

We'll probably make quite some changes to it before we release Oxygen 17 next year in Spring.
Are there any limitations in Prince (e.g., no indexes or TOCs?) that make it less optimal than XSLT?
The experimental PDF (Prince XML - Experimental) type of transformation scenario which comes with Oxygen 16 produces a PDF which has table of contents and also an index page.
Right now the creation of the index page requires two passes through the Prince engine so it is not that optimal. Also producing the PDF using Prince from the same DITA content takes more time than the standard PDF output.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Tue Dec 23, 2014 9:11 pm

Thanks for pointing out the location of the customized CSS stylesheet. You're right -- the table of contents and cross references appear. However, keyrefs don't appear. See http://www.screencast.com/t/VLGQXdetxt.

Additionally, a lot of the links are underline the entire sentence rather than just the anchor text. See http://www.screencast.com/t/e7YuEND08p8C

Also, it includes comments even though I specified that comments should be excluded from the output. See http://www.screencast.com/t/kViozZ5Whn.

If you don't run prince from Oxygen directly, the strategy is to output to XHTML first and then apply the stylesheet. I tried this. I created an XHTML output. Then I ran prince on the output and used all the stylesheets you indicated in the OXYGEN_INSTALL_DIR\frameworks\dita\css_classed\print directory. My command looks like this:

Code: Select all


prince -s pagination-foot-notes.css -s pagination-front-page.css -s pagination-images.css -s pagination-index.css -s pagination-links.css -s vpagination-page-breaks.css -s pagination-page-size.css -s pagination-page-titles-and-numbers.css -s pagination-side-notes.css -s pagination-toc.css -s pagination.css docmap_di.html
However, this method doesn't include any page numbers in the cross references. http://www.screencast.com/t/1xvfoXvqPw

I assume this is because the pagination magic happens prior to the xhtml transform? I know princepdf is still experimental, but are all these issues known? Are you guys finding ways to solve them?

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Mon Dec 29, 2014 12:11 pm

Hi Tom,

Thanks for taking the time to test the PDF generation, please see some answers/questions below:
Thanks for pointing out the location of the customized CSS stylesheet. You're right -- the table of contents and cross references appear. However, keyrefs don't appear. See http://www.screencast.com/t/VLGQXdetxt.
I tried to create a small example with a key defined on a topic reference:

Code: Select all

<topicref keys="TEST_KEY">
<topicmeta>
<keywords>
<keyword>THIS IS TEST</keyword>
</keywords>
</topicmeta>
</topicref>
and then used in a DITA topic like:

Code: Select all

<p>abc<ph keyref="TEST_KEY"/>def</p>
The keyref text was shown in the PDF output.
Could you possibly paste in a reply some small DITA content fragments so that I could reproduce this issue on my side?
Additionally, a lot of the links are underline the entire sentence rather than just the anchor text. See http://www.screencast.com/t/e7YuEND08p8C
Again, could you possibly paste in a reply some small DITA content fragments so that I could reproduce this issue on my side? I need to see how the link XML content looks like. Is it a keyref link or a basic href link?
Also, it includes comments even though I specified that comments should be excluded from the output. See http://www.screencast.com/t/kViozZ5Whn.
We'll try to add a transformation parameter to control whether comments and change tracking made in the DITA content should appear or not in the PDF output.

The CSS which styles those side notes is this one:

OXYGEN_INSTALL_DIR\frameworks\dita\css_classed\print\pagination-side-notes.css

and you can for example comment or remove all the CSS selectors from the print media type and replace them with:

Code: Select all

comment-date, comment, comment-text, comment-author {
display:none;
}
If you don't run prince from Oxygen directly, the strategy is to output to XHTML first and then apply the stylesheet. I tried this. I created an XHTML output. Then I ran prince on the output and used all the stylesheets you indicated in the OXYGEN_INSTALL_DIR\frameworks\dita\css_classed\print directory. My command looks like this:....

However, this method doesn't include any page numbers in the cross references. http://www.screencast.com/t/1xvfoXvqPw

I assume this is because the pagination magic happens prior to the xhtml transform? I know princepdf is still experimental, but are all these issues known? Are you guys finding ways to solve them?
The CSSs we designed for the PDF output were intended to be applied directly on DITA sources.
As an example, the following CSS:

OXYGEN_INSTALL_DIR\frameworks\dita\css_classed\print\pagination-links.css

has a selector like this:

Code: Select all

    *[class ~= "topic/xref"][href]:after,
*[class ~= "topic/link"][href]:after {
content: " [page " target-counter(attr(href), page) "]";
link: attr(href);
}
which works when applied directly over DITA content. But when you generate XHTML from DITA, the links become something like:

Code: Select all

<a class="xref" href="../target.html#reference_cvc_4yj_4q">Link Text</a>
and the CSS selectors fail to apply on the link because the @class attribute is missing the topic/ value. So yes, it is not surprising that the CSSs we created to style directly DITA content cannot be used as-they-are to style XHTML content. Actually on what you tried to do (DITA to XHTML to PDF) probably most of the CSS selectors we wrote do not apply at all.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Wed Dec 31, 2014 12:19 am

Sure, here's how you can reproduce the keyref bug.

1. Create a map with this code:

Code: Select all


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<title>DITA Topic Map</title>

<topicref href="version_test.dita"/>

<keydef keys="versionx">
<topicmeta>
<keywords>
<keyword>5.3</keyword>
</keywords>
</topicmeta>
</keydef>

</map>
2. Create a topic called version_test.dita with this code:

Code: Select all


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic_srv_2x5_4q">
<title>Test</title>
<body>
<p>This is a test of the <keyword keyref="versionx"/>.</p>
</body>
</topic>
Here's the result:

http://www.screencast.com/t/tWPwKkDfpr

I'll try out the tip for hiding the comments.

Re the underlining, I'll troubleshoot that later once I can verify that keyrefs work. If keyrefs won't work, then the other troubleshooting is hardly worth it.

Thanks for your help.

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Wed Dec 31, 2014 12:45 am

I realize that the keyref does resolve, but for some reason the keyref name appears before it. Maybe I can just add a display:none to whatever is styling the [versionx] part?

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Mon Jan 05, 2015 9:46 am

Hi Tom,

Right, we'll rectify this.
Indeed as a quick fix in a CSS used for print like pagination-links.css you can add in the print media type these CSS selectors:

Code: Select all

*[keyref]:before,
*[keyref][href]:before{
content:"";
}
Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Mon Jan 05, 2015 8:31 pm

Thanks for the fix. BTW, what about all the link underlining (even in non-links)? Do you have a fix for that as well?

Radu
Posts: 6179
Joined: Fri Jul 09, 2004 5:18 pm

Re: Configure DITA-OT with PrinceXML

Post by Radu » Tue Jan 06, 2015 12:03 pm

Hi Tom,

In Oxygen 17 (which we plan to release probably in April-May 2015) we fully redesigned the CSS stylesheets used both for editing and for print. So these issues are already fixed there, the links are no longer underlined, they have a blue foreground color.
It's hard for me to map the huge amount of changes we made to the CSSs for version 17 to the CSSs which are used in 16.1, probably in the same pagination-links.css you can add selectors like:

Code: Select all

    *[class ~= "topic/xref"][href]{
color:blue;
font-style:italic;
text-decoration:none;
}

*[class ~= "topic/keyword"]{
font-weight:normal;
}
to remove the underline, give the xref link a certain color and to avoid the keyword being displayed with bold text.

I'm not sure if I understand the suggestion about the non-links underlining, do you mean that when you make keyword keyrefs there are still underlines for that content? I cannot reproduce this.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

tomjohnson1492
Posts: 132
Joined: Thu Apr 17, 2014 1:55 am

Re: Configure DITA-OT with PrinceXML

Post by tomjohnson1492 » Fri Jan 09, 2015 9:16 pm

It's good to know there's a lot of progress on developing a more robust stylesheet. I'm eagerly awaiting your upcoming release.

Post Reply