Cover image in PDF for DITA 1.2

[anderszvensson]

Hi,

I am a bit confused as to how the cover image is rendered in PDF with the Dita 1.2 provided with Oxygen.

Before there was a call to dita2fo-shell.xsl in the rendering process, which had a template called "place-cover-art". This does not seem to be called at all in the Oxygen rendering process (as seen partly by the fact that there is a placeholder text in that template which I don't get in my output). I even tried renaming the dita2fo-shell.xsl to see if it would break the transformation, but it had no effect. Here's the template from that file:

Code: Select all

<xsl:template name="place-cover-art">
   
    <fo:block margin-top="2pc" font-family="Helvetica" border-style="dashed" border-color="black" border-width="thin" padding="6pt">
      <fo:block font-size="12pt" line-height="100%" margin-top="12pc" margin-bottom="12pc" text-align="center">
        <fo:inline color="purple" font-weight="bold">[cover art/text goes here]</fo:inline>
       
      </fo:block>
    </fo:block>
  </xsl:template>

So how are cover images rendered in this process? I would need to know which template does this, and I would also like to know what is the starting xsl in the chain of processing now, since it doesn't seem to be dita2fo-shell.xsl anymore.

I would also like to know if there is a new standard way to place cover images on the front page by using an element in the bookmap. I.e. if I get an answer to the above question I could always insert a graphic there in the template to place a static cover image. But in the end I really need to be able to use different cover images for different publications, so the reference should be made e.g. in the bookmap, so it can be different for different publications. And then the template could render that element. Early on there was a dita topic type called bkinfo that had elements for bkcover and fig elements. But that is gone now, so is there another mechanism for this to use now?

Regards,

Anders

[Radu]

Hi Anders,

The customizations which are made to the dita2fo-shell.xsl are only used when the Legacy PDF transformation is used. This is still available as an option when you create a new DITA Map transformation scenario (at the bottom of the list).
The defaults PDF transformation scenario was previously named IDIOM PDF.
These are changes which happened in the DITA Open Toolkit as it evolved from version to version.

So, in order to make modifications to the PDF transformation now the entry point is this file: OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/demo/fo/xsl/fo/front-matter.xsl.
This tutorial seems to explain in details how to do this:
http://wrycan.blogspot.com/2009/02/how-to-modify-cover-page-in-dita-open.html

From what I know there is no means to link to the image directly from the bookmap. Maybe you can search and ask more details about this on the DITA Users List:
http://tech.groups.yahoo.com/group/dita-users/

Regards,
Radu

[anderszvensson]

Hi Radu,

Ok, well I investigated a bit further in the xsl files as well as the build files, and I actually don't think the frontmatter.xsl is the entry point, but rather it seems to be topic2fo-shell.xsl now. That file has all the necessary imports for an entry file, and also calls root-processing.xsl, which in turn calls frontmatter.xsl.

I actually did search the DITA users forum already, and surprisingly this is a question that seems to be rather hard to get an answer to. But I think I can work it out now that I found the new entrypoint.

Thanks anyway!

Regards,

Anders

[Radu]

Hi Anders,

Sorry for the misunderstanding, you were referring to the main XSLT used in the transformation and I was referring to the XSL you had to modify in order to accommodate for the intended changes.
The main entry point should be this one: OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/demo/fo/xsl/fo/topic2fo_shell_1.0.xsl.
It is called as a step from this build file OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\demo\fo\build.xml in the target called transform.topic2fo.

Regards,
Radu

[anderszvensson]

Ok, thanks for the clarification.

Regards,

Anders

[Leodong]

Hi Anders,

I am currently working on customization of header and footer in Cover Page using DITA transformation to PDF.

As you have indicated do the modification to "root-processing" and "topic2fo_shell_1.0". Can you be more specific on how to do it?

I explored both files but end up getting nothing.

Appreciate,

Leo

[sorin_ristache]

Hello Leodong,

Did you apply the steps from the blog suggested by Radu? That blog contains instructions for adding a logo image on the cover page. If your logo does not appear on the cover page please specify the modifications that you did in the XSL file and the result that you get in the XSL-FO file from which the final PDF is generated. Can you post here some code fragments with the modifications that you tried?


Regards,
Sorin

[Leodong]

Hi Sorin,

I did follow the blog you have mentioned, but it didn't work.

Below are the code in custom.xsl:

Code: Select all

<?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:call-template name="createFrontMatter"/>
    <fo:block text-align="center" width="100%">
        <fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/image2.jpeg')})"/>
        </fo:block>
</xsl:stylesheet>

I followed the steps as indicated. But the PDF I have has no image in it. I wondered is that because the version I used is 1.0?

Thanks for viewing,

Leodong

[sorin_ristache]

Hi Leodong,

The version number is not important. You did not create a valid XSLT stylesheet. Please insert your custom code in an XSLT template (an xsl:template element), not directly in the xsl:stylesheet element. In step 3 of the blog post you can see that you have to copy the createFrontMatter template from DITA-OT/demo/fo/xsl/front-matter.xsl to your custom stylesheet and modify it as specified in that blog post.

If you don't know how to create a valid XSLT stylesheet or you are not sure what an XSLT template is (like the createFrontMatter template which you have to customize) please read an XSLT tutorial from here or here.

Please make sure that the file image2.jpeg exists in the [Oxygen-install-dir]\frameworks\dita\DITA-OT\demo\fo\Customization\common\artwork directory. Otherwise the PDF transformation cannot find the image file for adding it to the cover page. This addition is done exactly by the customization inside the createFrontMatter XSLT template which should be the following:

Code: Select all

<fo:block text-align="center" width="100%">
    <fo:external-graphic src="url({concat($artworkPrefix, 'Customization/OpenTopic/common/artwork/image2.jpeg')})"/>
</fo:block>

Did you modify the DITA-OT/demo/fo/Customization/catalog.xml file as specified in that blog post?


Regards,
Sorin

[Leodong]

I guess step 3 is where I find confusing.

It didn't mention creating a new stylesheet, but mentioned modify custom.xsl.orig to custom.xsl.

I did create the custom.xsl(Is this the way of creating new stylesheet you have talked about?). And put the "xsl:template" element into the custom.xsl, with the customized code the blog provided,

so the custom.xsl looks like:(some modification compared to previous one)

<?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:template name="createFrontMatter">
<fo:block text-align="center" width="100%">
<fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/numerix_image2.jpeg')})"/>
</fo:block>
</xsl:template>
</xsl:stylesheet>


But I didn't get clear about the "subtitle" thing in step 3. I didn't see any subtitle-related code in either "root-processing.xsl" or "custom.xsl". Do I need to create a new one? and how?

I did the rest you have said, such as put image2.jpeg in the destination folder; and modify the catalog.xml(actually it was modified before).

But I still didn't get the result. I guess I didn't fully understand step 3 of that blog.

[sorin_ristache]

Hi Leodong,

I guess step 3 is where I find confusing.

It didn't mention creating a new stylesheet, but mentioned modify custom.xsl.orig to custom.xsl. I did create the custom.xsl(Is this the way of creating new stylesheet you have talked about?).

It is the same thing. You copy custom.xsl.orig to custom.xsl or you create a new file custom.xsl. The idea is to have a new file called custom.xsl in the folder specified in that post.

But I didn't get clear about the "subtitle" thing in step 3. I didn't see any subtitle-related code in either "root-processing.xsl" or "custom.xsl". Do I need to create a new one? and how?

I did the rest you have said, such as put image2.jpeg in the destination folder; and modify the catalog.xml(actually it was modified before).

But I still didn't get the result. I guess I didn't fully understand step 3 of that blog.

Did you ask on that blog? I see that they accept user comments and questions.


Regards,
Sorin

[BobbyG66]

Going back to the original question, I am also looking for a way to add a different PRODUCT image to each publications cover.
I am able to add the company logo, not a problem.

But each product has a unique image.
Looking to store this image somewhere in with the product files and folders, not in the plugin folder.
It appears that frontmatter.xsl only pulls info from the bookmap.
Can you create an image link there and access that?

Thanks
BG66

[Radu]

Hi,

Your bookmap could have some metadata which specifies the image to appear on the front matter:

Code: Select all

  <bookmeta>
    <data name="cover-image" href="test.png"/>
  </bookmeta>


In order for the image to be copied to the output folder you can also link to it further down in the bookmap:

Code: Select all

  <topicref href="test.png" processing-role="resource-only" toc="no"/>

and then the XSLT customization could look for that specific <data> value and refer to that image.

Regards,
Radu

[BobbyG66]

Thanks Radu, Getting close, but not working yet.

In my bookmap I have the following lines of code.

In the bookmetadata:

Code: Select all

<data name="cover-image" href="/Content/cover_image.png"/>

In the frontmatter:

Code: Select all

<topicref href="/Content/cover_image.png" format="png" processing-role="resource-only" toc="no"/>

In frontmatter.xsl:

Code: Select all

                  <fo:block-container xsl:use-attribute-sets="__frontmatter__cover__image__container">
                  <fo:block xsl:use-attribute-sets="__frontmatter__cover__image">
                     <xsl:value-of select="//*[contains(@class,' frontmatter/topicref ')]"/>
                        </fo:block>
                        </fo:block-container>

Where is the code wrong?
Not seeing how the "data name" is used.

Thanks
BG66

[Radu]

Hi,

First about the changes in the DITA Map, the @href attribute value needs to be relative to the current DITA Map like:

href="Content/cover_image.png"

You seemed to have added an extra / at the beginning of the @href which should be removed.
One thing I forgot, you should also set the @format attribute on the <data> element like:

Code: Select all

<data name="cover-image" href="Content/cover_image.png" format="png"/>

This should be enough for the image to be copied to the temporary files folder so you will not need to add that extra topicref to the image.

Now on the XSLT side, we have a topic which discusses front matter customization:

https://www.oxygenxml.com/doc/versions/17.0/ug-editor/#topics/dita_pdf_output_customization.html

so at some point in your XSLT customization you will need to use something like:

Code: Select all

                    <fo:block text-align="center" width="100%">
                        <fo:external-graphic src="url({(//data[@name='cover-image'])[1]/@href})"/>
                     </fo:block>

in order to refer to the image in the XSL-FO file.

There is a book called DITA For Print:

http://xmlpress.net/publications/dita/dita-for-print/

which is quite useful for finding different solutions for PDF customizations.

Regards,
Radu

[BobbyG66]

Thanks Radu!
I was able to get it to work with a modification.
We are using XDocs as a CCMS, that may be related to our change.

For the URL reference in front-matter.xsl we changed the code to:

Code: Select all

<fo:external-graphic src="url(../images/cover_image.png)"/>

Thanks
BG66

[BobbyG66]

We now have an issue with localized files.
We have localized our manuals, but the image is not linking correctly.
The source file is in our English images folder.

In our bookmap we created a <data> element

Code: Select all

<data name="cover_image" href="/Content/cover_image_xi68866.png"/>

Here is the code from /cfg/fo/xsl/front-matter.xsl

Code: Select all

                  <fo:block-container xsl:use-attribute-sets="__frontmatter__cover__image__container">
                  <fo:block xsl:use-attribute-sets="__frontmatter__cover__image">
                     <fo:external-graphic src="url(../images/cover_image.png)" content-height="scale-to-fit" height="6in"  content-width="6in"/>
                        </fo:block>
                        </fo:block-container>

When linking the <data> element there is an option to "Use path relative to file location".
I tried this both checked and unchecked and it has no effect.

Is there a way to link to the image in the English folder?
Or do we need to duplicate the image in each localized folder?
(This was the only way to get it to work. Looking for a more elegant solution, rather than duplicate an image for each language and edit each bookmap)

Thanks
BG66

[Radu]

Hi,

Besides duplicating the image in each translated folder (which is not that bad) you could for example write your own ANT build file which wraps the DITA OT build file and copies the image to the output folder before the transformation is started:

https://www.oxygenxml.com/doc/versions/18.0/ug-editor/topics/dita-map-use-your-own-build-file.html

Regards,
Radu