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

<oXygen/> general issues.
BogdanM777
Posts: 68
Location: Canada

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

Tue Jul 21, 2015 7:04 pm

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
Posts: 122

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

Thu Jul 23, 2015 12:18 pm

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
Octavian Nadolu
<oXygen/> XML Editor
http://www.oxygenxml.com
BogdanM777
Posts: 68
Location: Canada

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

Fri Jul 24, 2015 8:56 pm

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
Posts: 122

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

Mon Jul 27, 2015 2:46 pm

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
Octavian Nadolu
<oXygen/> XML Editor
http://www.oxygenxml.com
BogdanM777
Posts: 68
Location: Canada

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

Mon Jul 27, 2015 3:56 pm

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
Posts: 4

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

Fri Aug 21, 2015 3:39 pm

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
Posts: 68
Location: Canada

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

Fri Aug 21, 2015 5:19 pm

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
Posts: 5088

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

Mon Aug 24, 2015 9:52 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
Dan_K
Posts: 4

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

Thu Mar 23, 2017 12:08 am

tavy wrote: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
Posts: 5088

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

Fri Mar 24, 2017 12:58 pm

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/18.1/ug-editor/topics/dita-pdf-output-x-predefined3.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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
pcroce
Posts: 2

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

Fri Sep 22, 2017 9:21 pm

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
Posts: 5088

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

Mon Sep 25, 2017 12:32 pm

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Return to “Other Issues”

Who is online

Users browsing this forum: No registered users and 3 guests