#360 Widows and orphans in ooRexx books

[Josep Maria Blasco]

(Maybe we could upgrade to 1.79.2 and be done with it -- but I'm no expert in that area. In the meanwhile, here's a patch that seems to work)

Problem

Section titles (e.g. "1.11.3. Parentheses and Operator Precedence") can appear stranded at the bottom of a page, separated from the section content that follows them.

This happens when <indexterm> elements appear between the <title> and the first <para> of a section — a very common pattern in the ooRexx documentation:

<section id="oprpri">
  <title>Parentheses and Operator Precedence</title>
  <indexterm><primary>algebraic precedence</primary></indexterm>
  <indexterm><primary>precedence of operators</primary></indexterm>
  <indexterm>...</indexterm>
  <indexterm>...</indexterm>
  <para>Expression evaluation is from left to right...</para>

Root Cause

The indexterm template in pdf.xsl is an override copied from DocBook XSL version 1.72. It always generates an fo:wrapper for the indexterm anchor, regardless of the FO processor in use:

<xsl:when test="$axf.extensions != 0">
  <xsl:call-template name="inline.or.block"/>
</xsl:when>
<xsl:otherwise>fo:wrapper</xsl:otherwise>

The hidden.properties attribute-set applied to this element already includes keep-with-next.within-column="always", but FOP ignores keep-with-next on fo:wrapper because it is not a block-level formatting object.

As a result, the keep-with-next chain breaks:

1. The section title has keep-with-next → keeps with the first fo:wrapper (indexterm anchor) ✓
2. The fo:wrapper has keep-with-next → FOP ignores it ✗
3. FOP is free to break the page before the first <para>.

The upstream index.xsl (version 1.79.2) already fixed this by adding $fop1.extensions to the condition, so that inline.or.block is called for FOP as well. That template returns fo:block when the indexterm is a direct child of a section element.

Proposed fix

Align the override with the upstream 1.79.2 version. One-line change in pdf.xsl, in the indexterm template:

<!-- Before -->
<xsl:when test="$axf.extensions != 0">

<!-- After -->
<xsl:when test="$axf.extensions != 0 or $fop1.extensions != 0">

With $fop1.extensions = 1, the template now calls inline.or.block, which returns fo:block for indexterms that are direct children of section elements. The keep-with-next from hidden.properties is applied to a real fo:block, FOP respects it, and the chain title → indexterm₁ → indexterm₂ → ... → first para is kept together.

Indexterms in inline contexts (inside a <para>, etc.) are not affected — inline.or.block returns fo:inline or fo:wrapper for those.

[Rony G. Flatscher]

Wow, this is way cool, Josep Maria, kudos!

Given the explanations, the proposed fix seems to be the right one, thank you very much for your analysis and work!

[Gil Barmwater]

I just went back and reviewed what I had done when I developed the documentation build process. There is a file named sources.txt that documents the various pieces of the process, where they come from and what changes were made to them, if any. It seems that pdf.xsl was an artifact of the old Publican document build process - I could not find it in the DocBook files that we are using, perhaps it has had a name change - to which numerous (7) changes were made. The rest of the DocBook files are already at 1.79.2.

I see 2 possibilites: find the pdf.xsl that correspond to 1.79.2 and apply the 7 changes that are documented in sources.txt or apply the fix documented above (and add an eighth change to sources.txt). The latter seems to be easier to accomplish.