DITA to PDF Customization

[gwhite]

I am trying to customize the appearance of my PDF output. In the help topic titled "DITA to PDF Customization," a procedure is presented for customizing the custom.xsl file in the Customization folder.

In this procedure, steps 5 and 6 state:

5. Rename the file: C:\Customization\fo\xsl\custom.xsl.orig to:
C:\Customization\fo\xsl\custom.xsl
6. Open the custom.xsl file in Oxygen XML and create the template
called createFrontMatter_1.0. This will override the same template
from the OXYGEN_INSTALL_DIR/frameworks/dita/DITA-
OT/demo/fo/xsl/fo/front-matter.xsl. Now, custom.xsl has the
content: ...

I do not understand step 6. What does it mean to say, "Open the custom.xsl file in Oxygen XML and create the template called createFrontMatter_1.0"? Could you more explicitly give the steps? What I see when I open custom.xsl is maybe six lines of code (see below). I don't get it.

Also, how does making a change in a file copied to c:\Customization make a change the same file in an ..<installation folder>\frameworks\ subfolder? This procedure is very mysterious.

Thanks,

Gary

--- custom.xsl contents ---

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.1">

</xsl:stylesheet>

[Radu]

Hi Gary,

Basically the topic in our user manual tries to explain a concrete customization situation, the case in which you want to add a company logo image in the front matter of the book.
So in step (6) you start with an empty custom.xsl XSLT stylesheet and you copy to it an xslt template called createFrontMatter_1.0 which resides in:

OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/demo/fo/xsl/fo/front-matter.xsl.

Then the XSLT template content can be changed at will in the custom.xsl and it will overwrite the original template content.

Also, how does making a change in a file copied to c:\Customization make a change the same file in an ..<installation folder>\frameworks\ subfolder? This procedure is very mysterious.

As explained in step (7), you send to the DITA OT as a parameter the location of the customization folder.
The stylesheets used for PDF generation like OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/demo/xsl/fo/topic2fo_shell.xsl have imports like:

Code: Select all

 <xsl:import href="cfg:fo/attrs/custom.xsl"></xsl:import>

which will get resolved through your custom catalog (edited in step (4)) to your custom stylesheet.

Regards,
Radu

[gwhite]

Thanks for the response. I'll try it out!

Gary

[gwhite]

After a hiatus, I'm trying again to add a company logo to the title page of a PDF using the help topic devoted to that subject ("DITA to PDF Output Customization").

I have gone through the steps as detailed in the help, but no logo on title page. Here is the text the help topic suggests to add to the custom.xsl file, within the createFrontMatter_1.0 xsl code block:

<fo:block text-align="center" width="100%">
<fo:external-graphic src="urlconcat$artworkPrefix, '/Customization/OpenTopic/common/artwork/logo.png')})"/>
</fo:block>

My customization folder is at C:\Customization. I'm wondering whether
'/Customization/OpenTopic/common/artwork/logo.png' is really correct? My graphic is indeed logo.png, and it is in the common/artwork folder. But where does the OpenTopic reference come from?

Should this work? Do you see any other problems?

Thanks,

Gary

[gwhite]

Never mind! It worked. I thought I had uncommented the correct line in the catalog.xml file, but it was still commented. When I uncommented it, the graphic appeared.

Thanks,

Gary

[steveinfrance]

*** Newbie Alert ***

I'm also trying to customize the PDF output for DITA.

The thing is that it seems that with the DITA-OT v1.6, they have (re)moved the Demo folder and created the Customization folder.

However there doesn't seem to be any .orig files and customization/fo/xsl folder does not contain the fo subfolder to store the new front-matter.xsl file.

Does anyone have a link to more info on how to customize with v1.6 of the toolkit?

Thanks,
Steve

[Radu]

Hi Steve,

The thing is that it seems that with the DITA-OT v1.6, they have (re)moved the Demo folder and created the Customization folder.

The PDF publishing is implemented in the DITA Open Toolkit as a plugin.
In previous versions, this plugin was located in the DITA-OT\demo\fo folder. Now it is located in the DITA-OT\plugins\org.dita.pdf2 folder. The folder structure inside the plugin was preserved.

An entire list of changes in DITA OT 1.6 can be found here:

http://dita-ot.sourceforge.net/1.6/read ... el1.6.html

Now, the proper way to implement a customization is to have it in a folder which is not located in the DITA OT folder and reference it from the transformation scenario. We have a topic in our user manual covering this:

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

Indeed there were some .orig stylesheets in the customization folder which seem to have been remove in the DITA OT 1.6.1, I added a bug for this:

https://github.com/dita-ot/dita-ot/issues/1411

but you can create the custom.xsl yourself, the initial content in the .orig is really simple:

Code: Select all

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

    xmlns:fo="http://www.w3.org/1999/XSL/Format"

    version="1.1">



</xsl:stylesheet>

Regards,
Radu

[plumblei]

I made all the steps from http://www.oxygenxml.com/doc/ug-editor/ ... ation.html , but still get no logo.
What I did specifically:
1. Put logo.png to C:\Customization\common\artwork
2. Created in C:\Customization catalog.xml that looks like this:

Code: Select all

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

    xmlns:fo="http://www.w3.org/1999/XSL/Format"

    version="1.1">

<uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/>

</xsl:stylesheet>

3. In C:\Customization\fo\xsl created an empty custom.xsl and pasted code from step 6 to it.
4. Created a duplicate of the Dita Map PDF scenario, and in its Parameters entered C:\Customization\ for customization.dir.

When I run this scenario I get a pdf output without any logo on the front page. What am I missing?

[plumblei]

OK, the problem might be with catalog.xml. I copied it from C:\Program Files\Oxygen XML Editor 14\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\cfg\catalog.xml and deleted all lines except this

Code: Select all

catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="system">



    <uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"></uri>

  



</catalog>

But now the build fails and I get the following errors:

Code: Select all

BUILD FAILED

C:\Program Files\Oxygen XML Editor 14\frameworks\dita\DITA-OT\build.xml:56: The following error occurred while executing this line:

C:\Program Files\Oxygen XML Editor 14\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\build.xml:172: The following error occurred while executing this line:

C:\Program Files\Oxygen XML Editor 14\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\build.xml:349: java.lang.reflect.InvocationTargetException

....

[plumblei]

Sorry, the catalog.xml is
<uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"></uri>
But still the same errors...

[Radu]

Hi,

So in Step (2) the exact content of the "Customization/catalog.xml" should be:

Code: Select all

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="system">

  <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/>

</catalog>

Following the exact steps in the online documentation worked for me.
What version of Oxygen are you using? Are you using the bundled DITA Open Toolkit? If not, what DITA OT version are you using?

If you edit the "Customization/fo/xsl/custom.xsl" and make it not wellformed XML (like deleting a <), then save and perform the transformation, does the transformation break? This would be an indication that the catalog is used.

Are you publishing to PDF a bookmap or a dita map?

Regards,
Radu

[plumblei]

Radu, thanks a lot! I inserted the code from your catalog.xml and it did the trick. Could you point me to sources that explain the customization of PDF output in more detail? Specifically, I need to add headers/footers, put the logo on the front page to the upper left corner and change the layout of the first page of each chapter.

[Radu]

Hi Ilya,

The Yahoo Groups DITA Users List is a very good place where to ask customization questions.
I do not know a very good tutorial, that's why we decided to add a topic about this in our user manual. On the DITA Users List there has recently been a discussion about this:

http://tech.dir.groups.yahoo.com/group/ ... sage/30049

As an alternative instead of creating a customization directory you also have the option to create a DITA OT plugin which customizes the PDF plugin.
Jarno Elovirta developed a web interface which lets you create such a plugin by specifying different settings:

http://dita-generator-hrd.appspot.com/pdf-plugin/

Regards,
Radu

[plumblei]

Thank you! I'll give it a look.

[BobbyG66]

I am still completely lost on step 6.
"create the template called createFrontMatter_1.0"

Is this a .xsl file?
What are the contents of this file and where does it go?

Thanks
BobbyG66

[Radu]

Hi,

The help topic explaining the PDF customization is this one:

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

Regards,
Radu

[BobbyG66]

ok, I got it working!
I copy the code in step 6 to the custom.xsl file.

I then had a problem in step 7.
I created a new parameter with a different name.
I should have noticed that there was a parameter "customization.dir" and edited that.
Once I edited "customization.dir" it worked.

Thanks
BobbyG66

[Radu]

Hi Bobby,

Thanks for the feedback, the documentation is indeed unclear in step 7, we'll rectify that.

Regards,
Radu