Getting Started with Paligo

Managing Page Breaks

Note

This section only applies to techniques used for publishing PDF/print output. For other outputs such as e.g HTML or HTML5, page breaks are not applicable of course.

In general, the publishing process in Paligo takes care of making sure that page breaks are handled automatically. There are default rules that control page breaks, making sure that certain elements keep together. For instance, titles are always kept together with the following element (e.g the first paragraph in a topic) by default.

However, although most of this should work automatically, and you shouldn't have to care about page breaks most of the time, there will often be times where you might have wanted the page breaks to be handled slightly differently. This section describes how you can fine-tune the page breaking in several ways.

Soft Page Breaks

The first option you should use to fine-tune page breaking is what is called "soft page breaks". This means using features that can affect page breaking only when it's needed. I.e it will not actually insert a hard page break, it will only help control when page breaks are inserted if and when it may be needed.

To give a couple of examples: Paragraphs are normally not kept together by the publishing process. I.e a paragraph will break if it occurs at the end of a page and continue on the next page. Another example is lists, which will normally not be kept together as a whole:

To manage this, you have the following features at your disposal:

  • Keep-together: Use the attribute xinfo:keep-together to control whether an element keeps together on the same page (or in the same column for 2-column formats). For instance, if you want to make sure that a bullet list keeps together on the same page, set it on the itemizedlist element. Values are "yes" and "no".

    This option can also be used if the default styling is to keep some element together, and you want to make an exception to that. If for instance a figure is kept together by default, but you have a figure with lots of content (callout list etc) then you can set xinfo:keep-together to "no" for that particular figure.

  • Keep-with-next: Use the attribute xinfo:keep-with-next to control whether an element should stay with the following element if a page break occurs. For instance, if you have a paragraph right before a figure, and you want the paragraph to be on the same page as the figure, set xinfo:keep-with-next to "yes" on the para element.

Hard Page Breaks

What we call "hard page breaks" is when you insert a page break that will always occur at that point in the content, no matter if it's "needed" or not. Usually this should be avoided. You should try to rely on the automatic page breaking, or use soft page break techniques to control page breaking as far as possible. The reason is that even if you feel that a page break might look good in a certain place in one context, it might not be needed at all in another.

Consider if you have the same topic reused in many different publications (for different products for example). In one publication it might work fine, in another it might cause a page break in an awkward place, causing a lot of white space on a page. The same thing could occur if you translate to other languages. The page break might not occur in the same place for another language, and if you have then inserted a hard page break, you will have a page break where it's not needed, causing problems.

However, there are situations where a hard page break might still be desired, and then you have the option to insert it. For instance, you might have a topic that should always start on a new page, no matter what. Then you can use the attribute xinfo:pagebreak. There are several options, but usually you will want to use the value "before". This means if you set xinfo:pagebreak to the value "before" on a topic, a page break will be inserted before that topic.