Insert a page break to keep pages "nice" inside PDF

[BogdanM777]

Hi,

I managed right now, with the help of the oXygen help team, and with what I found also on the Internet, to have nice PDF documentation, and everybody in the company is very happy about that. So, thank you.
I have however a small problem with the printed documentation in the sense that sometimes, the form of the page is not kept quite proper. What I mean by that?
I have the topics following one after the other, and sometimes, if let's say a picture or a table is too big and has to be on the next page, then there is just a title on the previous page with little or no text, and the picture or the table in on the next page.
It would have been nice to be able to insert a "page break" before the title so that the shape of the document would remain nice, I thought.
Is there something like this available in DITA?
I found an older article on the Internet originated from the oXygen forum about that at: http://blog.oxygenxml.com/2015/04/dita- ... mment-form
I also tried to implement it, created the xml, xsl files for the plugin and published the plugin, however when I insert the <?pagebreak?> in the document, the desired page break does not happen.
I was wondering if I need to do something more than that.
Would you pleas be so kind and help me with this?
Thank you very much.

[tavy]

Hello,

The page-break plugin can be used only between two block elements, for example between two <p> elements. If you want to have also the title on the next page, and you add <?pagebreak?> before the <title> or the <topic> element, the page-break will not work. But you can add the <?pagebreak?> after the last paragraph from the previous topic, and the next topic title will be added on a new page.

The problem with this approach is that if you add other paragraphs in your topics then is it possible that your page break will not be in the right place. A better solution for this, if you want to keep elements on the same page, is using "keep-within-next". There is a discussion on GitHub about this: https://github.com/dita-ot/dita-ot/issues/1878
For this you will need to customize the DITA-OT plugin that creates the PDF output when a DITA Map PDF transformation is executed. This plugin is located in directory [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\org.dita.pdf2
For example I customized the [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\xsl\fo\commons.xsl stylesheet and added the attribute keep-with-next="always" on the fo:bock generated for the title element. This will ensure that the title and the next image, for example, will stay together.

Best Regards,
Octavian

[BogdanM777]

Thank you so much Octavian!
It worked like a charm.
And I guess I can use the same technique for all blocks, right? I mean adding this attribute keep-with-next="always".
I am interested to keep also pictures from being sent to the next page and the description of it, sometimes at the top of the image, being left on the previous page. Would it be possible to keep a paragraph with the next?

Thank you again,
Bogdan

[tavy]

Hello Bogdan,

Yes, you can use the "keep-with-next" attribute and also the "keep-with-previous" attribute for other blocks. For example you can set the "keep-with-previous" attribute with the value "always" on the block element that contains the image.

Best Regards,
Octavian

[BogdanM777]

This is what I did, and it worked very nicely w/o having to implement I don't know what plugin.
Thank you again Octavian

[Michael95]

Hi,

I'm new to DITA and would really like to be able to provide PDF output that allows for the keep with next/previous feature. I have located commons.xsl but I'm not sure what exactly I should be changing. Please can you give an example on what should be changes in this file for the transformation to keep title text with its next paragraph.

Thanks,
Michael

[BogdanM777]

Hi Michael,

You could eventually look for the parts where you want to insert this type of functionality, e.g.

<xsl:attribute-set name="fig.title" use-attribute-sets="base-font common.title">
<xsl:attribute name="font-weight">bold</xsl:attribute>
<xsl:attribute name="space-before">5pt</xsl:attribute>
<xsl:attribute name="space-after">10pt</xsl:attribute>
<xsl:attribute name="keep-with-previous.within-page">always</xsl:attribute>
</xsl:attribute-set>

And you could mark it with a comment to know to restore it to its original status, if necessary.
However, the guys from oXygen are very knowledgeable, and they will give you more reliable information.

Cheers,

Bogdan

[Radu]

Hi Michael,

Besides what Bogdan said, could you tell us the precise case in which you want the title to be on the same page with the following text content?
Because by default the DITA to PDF XSLT stylesheets already do this for most cases.

Regards,
Radu

[Dan_K]

Hello,

The page-break plugin can be used only between two block elements, for example between two <p> elements. If you want to have also the title on the next page, and you add <?pagebreak?> before the <title> or the <topic> element, the page-break will not work. But you can add the <?pagebreak?> after the last paragraph from the previous topic, and the next topic title will be added on a new page.

The problem with this approach is that if you add other paragraphs in your topics then is it possible that your page break will not be in the right place. A better solution for this, if you want to keep elements on the same page, is using "keep-within-next". There is a discussion on GitHub about this: https://github.com/dita-ot/dita-ot/issues/1878
For this you will need to customize the DITA-OT plugin that creates the PDF output when a DITA Map PDF transformation is executed. This plugin is located in directory [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\org.dita.pdf2
For example I customized the [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\xsl\fo\commons.xsl stylesheet and added the attribute keep-with-next="always" on the fo:bock generated for the title element. This will ensure that the title and the next image, for example, will stay together.

Best Regards,
Octavian

Hello.
I am curruntly experiencing the same obstacle. I have opened my file: C:\Program Files\Oxygen XML Editor 18\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\xsl\fo\commons.xsl.
But I do not know where to place the attribute "keep-with-next=always", just as you have suggested.
So my question is, in which code-line / <fo:block> do I type in this attribute?
Please help - I am more a novice than an expert, so some coding would be helpful ..
Danny

[Radu]

Hi Danny,

Usually a PDF customization is done using a plugin or a customization folder in order to avoid making direct changes to the XSLTs:

https://www.oxygenxml.com/doc/versions/ ... ined3.html

in the "commons.xsl" there is an XSLT template which matches the DITA <fig> element and produces the XSL-FO elements necessary for PDF:

Code: Select all

 <xsl:template match="*[contains(@class,' topic/fig ')]">

        <fo:block xsl:use-attribute-sets="fig">

            <xsl:call-template name="commonattributes"/>

            <xsl:call-template name="setFrame"/>

            <xsl:call-template name="setExpanse"/>

            <xsl:if test="not(@id)">

              <xsl:attribute name="id">

                <xsl:call-template name="get-id"/>

              </xsl:attribute>

            </xsl:if>

            <xsl:apply-templates select="*[not(contains(@class,' topic/title '))]"/>

            <xsl:apply-templates select="*[contains(@class,' topic/title ')]"/>

        </fo:block>

    </xsl:template>

Maybe on that <fo:block> you could add an extra keep-together="always" attribute.

Regards,
Radu

[pcroce]

I followed the procedure on the page, https://www.oxygenxml.com/doc/versions/ ... ments.html, and now my CALS tables error. I know it doesn't seem that it can be related but I could publish CALS tables before and a co-worker who did NOT follow the procedure for page breaks, can publish my docs. My docs publish but the transformation errors with element type Tgroup must be declared. The document publishes but is missing ALL topics what have a CALS table in it. I need help! Has anyone else experienced this? How did you fix it? I removed the plugin files noted on that page (https://www.oxygenxml.com/doc/versions/ ... ments.html) but it still errors.

HELP! HELP! I need to get my docs out with our release soon!

[Radu]

Hi,

Usually in such cases when you install a DITA OT plugin and something breaks, you can remove the plugin from the DITA OT plugins folder, re-run the integrator and check if the problem persists, if it does then the problem is probably somewhere else.
I will continue this discussion directly with you via email.

Regards,
Radu