Wednesday, April 29, 2015

DITA PDF publishing - Force page breaks between two block elements

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Let's say that at some point in your DITA content you have two block level elements, like for example two paragraphs:
        <p>First para</p>
        <p>Second para</p>
and you want to force in the PDF output a page break between them.
Here's how a DITA Open Toolkit plugin which would achieve this could be implemented:
  1. You define your custom processing instruction which marks the place where a page break should be inserted in the PDF, for example:
            <p>First para</p>
            <?pagebreak?>
            <p>Second para</p>
  2. In the DITA Open Toolkit distribution in the plugins directory you create a new plugin folder named for example pdf-page-break.
  3. In this new folder create a new plugin.xml file with the content:
    <plugin id="com.yourpackage.pagebreak">
      <feature extension="package.support.name" value="Force Page Break Plugin"/>
      <feature extension="package.support.email" value="support@youremail.com"/>
      <feature extension="package.version" value="1.0.0"/>
      <feature extension="dita.xsl.xslfo" value="pageBreak.xsl" type="file"/>
    </plugin>
    The most important feature in the plugin is that it will add a new XSLT stylesheet to the XSL processing which produces the PDF content.
  4. Create in the same folder an XSLT stylesheet named pageBreak.xsl with the content:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:fo="http://www.w3.org/1999/XSL/Format"
        version="1.0">
      <xsl:template match="processing-instruction('pagebreak')">
        <fo:block break-after="page"/>
      </xsl:template>
    </xsl:stylesheet>
  5. Install your plugin in the DITA Open Toolkit by running the DITA OT ANT integrator task.

    If you are running the publishing from Oxygen XML Editor you can use the predefined transformation scenario: http://www.oxygenxml.com/doc/ug-oxygen/#topics/dita-ot-install-plugin.html.

    If you run DITA OT from the command line please follow these guidelines: http://www.dita-ot.org/2.0/dev_ref/plugins-installing.html.

The plugin code was also made available by Roger Sheen on GitHub:
https://github.com/dita-community/org.dita-community.pdf-page-break

4 comments:

  1. Worked perfectly! Thanks!

    ReplyDelete
    Replies
    1. Don, I'm confused about the dita-ot-install-plugin.html. Where is this file? I'm using Oxygen 16.1. Any advice is much appreciated! I'm not doing something right. I created the plugin and style sheet and added them into the plugin folder. I ran the DITA OT ANT scenario. Do I now need another scenario, dita-ot-install-plugin.html? Thanks, Evelyn

      Delete
    2. Hi Evelyn,

      I see you already contacted us via email, we'll try to give you more details there.

      Regards,
      Radu

      Delete
  2. One more thing I wanted to add to this post, an issue about adding this kind of support for special processing instructions directly in the DITA Open Toolkit is opened here:

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

    As David Hollis mentioned there, if you want to keep elements on the same page, using "keep-within-next" is more appropriate.

    ReplyDelete