The dbfo keep-together processing instruction can be used with tables, examples, figures, and equations (and their informal versions too). By default, each of those elements is automatically kept together, by means of the following attribute in the formal.object.properties attribute-set in fo/param.xsl:

<xsl:attribute-set name="formal.object.properties">
   <xsl:attribute name="keep-together.within-column">always</xsl:attribute>
   ...
</xsl:attribute-set>

For more information on attribute sets, see the section “Attribute sets”. The full name of this XSL-FO property is keep-together.within-column. The within-column part means the block will be kept together across column breaks in a multi-column page, as well as across page breaks. The value of always means to always keep the block together. If it were set to auto instead, then breaks would be permitted.

If you don't change the formal.object.properties attribute set, then none of your tables, examples, figures, or equations will be broken across page boundaries. That's good, except when you don't want that behavior. Consider a long table that starts fairly high on the page. If the whole table doesn't fit on the page, then it breaks the page and leaves a lot of blank space behind. In such cases it would be better to start the table on the current page, and permit it to break and continue on the next page. But you don't want to change the attribute-set, because that would change it for all tables, including short ones that should be kept together.

So to permit a single table to break, add the dbfo keep-together processing instruction to your DocBook XML table element as follows:

<table>
  <title>My long table</title>
  <?dbfo keep-together="auto" ?>
  ...

When this processing instruction is a child of the DocBook table element, the stylesheet will add a keep-together.within-column="auto" property to the output table. That value will override the attribute set value of always and permit a page break within the table.

This processing instruction can also be used for figures, examples, and equations when they contain content that can be broken across pages (this does not include graphics). For example, if you put a long programlisting in an example, you could add the same PI to permit it to break across pages.

The dbfo keep-together PI can also be used to turn on a keep for a single table if you turn it off globally in the formal.object.properties attribute set. The same is true if you turn it off for all your tables in the table.table.properties attribute set. See the section “table.table.properties attribute-set” for more information on attribute sets for tables.

The one thing you don't want to do is insert a hard page break in your XML document. A hard page break always forces a page break at that point. While this may be useful for solving an immediate problem, the next time you edit your document and reformat you may find that your hard page break is positioned higher up on the page and breaks it inappropriately. Maintaining a document with hard page breaks is a pain. For that reason there is no processing instruction in DocBook XSL to insert a hard page break.

The stylesheet does provide a processing instruction for soft page breaks. A soft page break is a conditional page break. If the conditions on the page are not met, then the page does not break. The idea is borrowed from the troff typesetting system, which uses the term “need”. You put a processing instruction in your document that effectively says "I need at least 2 vertical inches left on the current page to fit the following material. If that much space is not available on the page, then break to the next page at this point. If there is enough space, don't break."

This kind of conditional page break is handy when the normal “keeps” used in the stylesheet are not sufficient, either for technical reasons or for aesthetic reasons. For example, you may want to make sure a short introductory paragraph that precedes a code listing has at least a few lines of code with it on the page. The para and the programlisting are separate elements that normally would not have a "keep". Here is an example.

<para>Some text in a paragraph</para>
<?dbfo-need height="2in" ?>
<para>The following code snippet illustrates 
the technique.</para>
<programlisting># Some sample code
</programlisting>

Here is what happens when this page is being typeset by the XSL-FO processor. If at the point on the page where the second paragraph in the above example would start there is less than 2 inches of vertical space left , then the rest of the page is left blank and the second paragraph is pushed to the next page. How does it work? The stylesheet outputs an empty fo:block-container with a 2 inch height, followed by an empty fo:block with a negative 2 inch space-before property. If there is 2 inches of space left on the page, then it backspaces up to the start of the block container and starts the next text output without breaking the page. If there isn't 2 inches of space left, then the block-container will force a page break and the text will start at the top of the next page.

Because the mechanism uses blocks, you can't put the processing instruction inline. It must be between elements that generate blocks of text, otherwise you may get invalid XSL-FO. Also note that the processing instruction name is dbfo-need, not dbfo like other DocBook PIs.

If you are managing breaks between items in a list, then you might have to put the processing instruction just inside the listitem element to get it to work. This is especially true for varlistentry.

This kind of page breaking is not perfect, because you need to estimate how much physical space is needed for the content you want to keep together. You would typically use it after the first printout so can measure vertical sizes of typeset elements. But since it isn't wrapping elements, it can create keeps of arbitrary size.

The dbfo-need PI also accepts a second optional pseudo attribute named space-before. This is useful to manually adjust the spacing when the stylesheet can't quite resolve the spacing the way it was without the PI. For example:

<?dbfo-need  height="0.5in"  space-before="3em" ?>

The space-before pseudo attribute also could be used to add extra vertical space wherever you need it. If you leave out the height pseudo attribute, then you will just get the extra spacing.

Although the DocBook XSL stylesheets don't provide direct support for hard (unconditional) page breaks, you can implement your own as a customization. Hard page breaks are not recommended for the reasons described in the section “Soft page breaks”. But there may be times when it is useful. Although customizations are discussed later, this short one is included here to make it easier to find. To enable hard page breaks, you add the following template to your customization layer:

<xsl:template match="processing-instruction('hard-pagebreak')">
   <fo:block break-before='page'/>
 </xsl:template>

Then you put the following processing instruction in your document where you want an unconditional page break:

<para>Some text in a paragraph</para>
<?hard-pagebreak?>
<para>The following code snippet illustrates 
the technique.</para>
<programlisting># Some sample code
</programlisting>

When the stylesheet processes this PI, it inserts an empty block with the break-before='page' property, which forces a page break. As with soft page breaks, this PI cannot appear inline; it must be placed between elements that generate blocks of text.