Menu ▾ ▴

#360 Widows and orphans in ooRexx books

5.2.0
open
nobody
None
1
4 hours ago
2026-04-07
Josep Maria Blasco
No

(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.

1 Attachments
pdf.xsl

Related

Documentation Bugs: #360

Discussion

  • Rony G. Flatscher

    Rony G. Flatscher - 2026-04-07

    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

    Gil Barmwater - 4 days ago

    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.

     

    • Josep Maria Blasco

      Josep Maria Blasco - 4 days ago

      Thanks for the explanations, Gil. If nobody beats me to it, I'll implement the 1.79.2 route, but this will have to wait until the Barcelona Symposium is over.

       

      • Gil Barmwater

        Gil Barmwater - 3 days ago

        I understand. Just for "fun" I built the RexxRef PDF using your modifed pdf.xsl and it looked fine to me. I am happy to commit it so that the upcoming release of 5.2.0 will have the benefit of this fix even if you develop a "better" one later on. Let me know if you have any reasons why I shouldn't do that.

         

        • Josep Maria Blasco

          Josep Maria Blasco - 3 days ago

          No reason at all, Gil. Go ahead. And thank you!

           

          • Per Olov Jonsson

            Per Olov Jonsson - 3 days ago

            Dear Gil,

            Before you commit the change would you be so kind and build everything once locally? I am not at home so I cannot make a local build myself. Are there any changes needed on the documentation build machine (my Mac)?

            Hälsningar/Regards/Grüsse,
            P.O. Jonsson
            oorexx@jonases.se

            Am 11.04.2026 um 21:19 schrieb Josep Maria Blasco jmblasc2@users.sourceforge.net:

            No reason at all, Gil. Go ahead. And thank you!

            [documentation:#360] Widows and orphans in ooRexx books

            Status: open
            Group: 5.2.0
            Created: Tue Apr 07, 2026 04:45 PM UTC by Josep Maria Blasco
            Last Updated: Sat Apr 11, 2026 07:10 PM UTC
            Owner: nobody
            Attachments:

            • pdf.xsl (sourceforge.net) (123.3 kB; text/xml)

            (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:

            xml <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:

            xml <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:

            ```xml

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


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

            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.

            Sent from sourceforge.net because you indicated interest in https://sourceforge.net/p/oorexx/documentation/360/

            To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/

             

            Related

            Documentation Bugs: #360

            alternate

            • Gil Barmwater

              Gil Barmwater - 3 days ago

              Yes, I will do that. The only (operational) file affected is pdf.xsl which you will need to update (from SF) on your Mac before you kick off the document builds. Stay tuned.

               

              • Gil Barmwater

                Gil Barmwater - 1 day ago

                All documents built successfully on my Windows 10 machine. Fix committed with Revision: 13146

                 

              • Per Olov Jonsson

                Per Olov Jonsson - 12 hours ago

                Hi Gil,

                I have copied the pdf.xsl from bldoc_orx to the documentation build machine and mades some changes to readme.pdf to provoke a new build of the documentation.

                I did some rudimentaty editing (removing references to support for Windows Vista etc) but It would be great if someone with more knowledge of what is actually NEW could work through readme.pdf. Before the new release.

                I noticed that you did not upgrade pdf.xsl in bldoc_win, is this intentional? I copied it to oorexxdocs_macOS, I have not used it in a while but I will try to in the coming days. It is redundant really now when your stuff runs also on macOS.

                Talking about redundancies: I noticed that the file sources.txt is slightly different in bldoc_orx and bldoc_win, maybe you could harmonize them?

                Hälsningar/Regards/Grüsse,
                ooRexx
                oorexx@jonases.se

                Am 11.04.2026 um 23:31 schrieb Gil Barmwater orange-e@users.sourceforge.net:

                Yes, I will do that. The only (operational) file affected is pdf.xsl which you will need to update (from SF) on your Mac before you kick off the document builds. Stay tuned.

                [documentation:#360] Widows and orphans in ooRexx books

                Status: open
                Group: 5.2.0
                Created: Tue Apr 07, 2026 04:45 PM UTC by Josep Maria Blasco
                Last Updated: Sat Apr 11, 2026 07:19 PM UTC
                Owner: nobody
                Attachments:

                • pdf.xsl (sourceforge.net) (123.3 kB; text/xml)

                (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:

                xml <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:

                xml <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:

                ```xml

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


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

                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.

                Sent from sourceforge.net because you indicated interest in https://sourceforge.net/p/oorexx/documentation/360/

                To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/

                 

                Related

                Documentation Bugs: #360

                alternate

                • Per Olov Jonsson

                  Per Olov Jonsson - 11 hours ago

                  Hi Gil,

                  That did not work as I expected it to. The upload of readme.pdf failed. I rebuilt twice but the problem was exactly the same. These 3 files were uploaded:

                  ooRexx-5.2.0beta-pdf.zip
                  ooRexx-5.2.0beta-all.zip
                  readme-html.zip

                  But for readme.pdf I have this error message (I masked the IP)

                  Files read from disk: 16
                  Archive size: 36050768 bytes (35 MiB)
                  Everything is Ok
                  Received disconnect from x.x.x.x port xx❌ Too many authentication failures
                  Disconnected from x.x.x.x port x
                  /usr/bin/scp: Connection closed

                  Since I had it twice I do not think it was a glitch.

                  The document built is in the Zip so please have a look if you can find out why this pdf refuses to upload. Smells like some kind of security risk built into the PDF to me.

                  I also have question regarding the html: Do we need the same upgrade for html.xsl?

                  Hälsningar/Regards/Grüsse,
                  ooRexx
                  oorexx@jonases.se

                  Am 14.04.2026 um 15:57 schrieb ooRexx oorexx@jonases.se:

                  Hi Gil,

                  I have copied the pdf.xsl from bldoc_orx to the documentation build machine and mades some changes to readme.pdf to provoke a new build of the documentation.

                  I did some rudimentaty editing (removing references to support for Windows Vista etc) but It would be great if someone with more knowledge of what is actually NEW could work through readme.pdf. Before the new release.

                  I noticed that you did not upgrade pdf.xsl in bldoc_win, is this intentional? I copied it to oorexxdocs_macOS, I have not used it in a while but I will try to in the coming days. It is redundant really now when your stuff runs also on macOS.

                  Talking about redundancies: I noticed that the file sources.txt is slightly different in bldoc_orx and bldoc_win, maybe you could harmonize them?

                  Hälsningar/Regards/Grüsse,
                  ooRexx
                  oorexx@jonases.se

                  Am 11.04.2026 um 23:31 schrieb Gil Barmwater orange-e@users.sourceforge.net:

                  Yes, I will do that. The only (operational) file affected is pdf.xsl which you will need to update (from SF) on your Mac before you kick off the document builds. Stay tuned.

                  [documentation:#360] Widows and orphans in ooRexx books

                  Status: open
                  Group: 5.2.0
                  Created: Tue Apr 07, 2026 04:45 PM UTC by Josep Maria Blasco
                  Last Updated: Sat Apr 11, 2026 07:19 PM UTC
                  Owner: nobody
                  Attachments:

                  • pdf.xsl (sourceforge.net) (123.3 kB; text/xml)

                  (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:

                  xml <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:

                  xml <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:

                  ```xml

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


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

                  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.

                  Sent from sourceforge.net because you indicated interest in https://sourceforge.net/p/oorexx/documentation/360/

                  To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/

                   

                  Related

                  Documentation Bugs: #360

                  alternate

                  • Gil Barmwater

                    Gil Barmwater - 10 hours ago

                    I will have a look at the zip file later today. No changes needed to HTML, this fix only affects the PDFs.

                     

                    • Gil Barmwater

                      Gil Barmwater - 4 hours ago

                      I was able to get the zip file, open it (Windows treats it as a folder), and double click on the readme.pdf. Adobe Reader was able to display the document which looked normal and complete. So I have no idea why you would not be able to upload it to SF. Sorry :-(

                       

                • Gil Barmwater

                  Gil Barmwater - 10 hours ago

                  I don't recall the last time I updated bldoc_win as it really is now redundant. Perhaps a note in that folder that it is deprecated and the bldoc_orx should be used instead. Thoughts?

                   

                  • Rony G. Flatscher

                    Rony G. Flatscher - 6 hours ago

                    +1 (deprecate note in bldoc_win)

                     

Anonymous
Anonymous

Add attachments
Cancel





MongoDB Logo MongoDB