Menu
▾
▴
1 Attachments
#360 Widows and orphans in ooRexx books
(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:
- The section title has
keep-with-next→ keeps with the firstfo:wrapper(indexterm anchor) ✓ - The
fo:wrapperhaskeep-with-next→ FOP ignores it ✗ - 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.
Related
Discussion
Anonymous
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!
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.
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.
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.
No reason at all, Gil. Go ahead. And thank you!
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
Related
Documentation Bugs: #360
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.
All documents built successfully on my Windows 10 machine. Fix committed with Revision: 13146
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
Related
Documentation Bugs: #360
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
Related
Documentation Bugs: #360
I will have a look at the zip file later today. No changes needed to HTML, this fix only affects the PDFs.
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 :-(
Dear Gil,
When I put a trace on buildandupload.rex it worked so I hope it was just a glitch.
I have not rebuilt the entire documentation yet, should we do that now?
Then a question on 2 Warnings I see:
WARNING: Destination: Unresolved ID reference "notices.title" found.
In /docs/trunk notices.title occurs twice:
ooRexxSVN-Code-0/docs/trunk/oorexx/publish/oorexx/en-US/Notices.xml
ooRexxSVN-Code-0/docs/trunk/oorexx/en-US/Notices.xml
The two documents appear to have the same text content but the XML formatting is different.
WARNING: Destination: Unresolved ID reference "cplv10.title" found.
In /docs/trunk cplv10.title occurs twice:
ooRexxSVN-Code-0/docs/trunk/oorexx/publish/oorexx/en-US/CPLv1.0.xml
ooRexxSVN-Code-0/docs/trunk/oorexx/en-US/CPLv1.0.xml
Again the two documents appear to have the same text content but the XML formatting is different.
Question: Why do we have two versions of the same thing? Can they be merged?
There is a 3rd warning
WARNING: Destination: Unresolved ID reference "book-oorexx-readme" found.
In /docs/trunk it occurs once in
ooRexxSVN-Code-0/docs/trunk/readme/en-US/Article_Info.xml
I think this might be because the reference starts with book- whereas the file has the name Article, but I am just guessing.
Since these are warnings we do not need to do anything but it would be cleaner to have these things fixed.
Finally a question on the documentation build process: When run from Jenkins a change in the documentation will trigger a SVN update of folder oorexxSVN. The build script however used a local SVN command to download to another folder oorexxdocSVN. Is this just an artifact from the past? Do you remember the reason?
Hälsningar/Regards/Grüsse,
ooRexx
oorexx@jonases.se
Related
Documentation Bugs: #360
First question: I would build the documents just before the Release candidate is built. That way if any last minute fixes require documentation changes, they will be included (not likely however).
Second questions: the Publish subdirectories in oorexx are from before I became involved so perhaps they had something to do with Publican. I would ignore the three warnings as the documents seem to build OK in spite of them.
Final question: I am not that familiar with the Jenkins build process so I don't really know the answer. It does seem from your description, though, that a duplication of work is going on. If the working copy in oorexxSVN is being updated, why isn't being used? If oorexxSVN is the whole tree (I don't know the directory structure) then it should contain the documentation subtree which makes the "download to another folder oorexxdocSVN" redundant it would seem. That being said, if it works, don't fix it...now. After the release is GA, we can revisit it.
Hi Gil,
What I want to avoid is to build all the docs with an almost untested pdf.xsl and find out JUST before the release that it does not work.
I encourage people to work on the documentation so we can get more mileage on the new pdf.xsl 😎
It does not have anything to do with Jenkins it is in the script itself. I think it is a piece of code from when there were problems with SVN.
It does seem from your description, though, that a duplication of work is going on. If the working copy in oorexxSVN is being updated, why isn't being used? If oorexxSVN is the whole tree (I don't know the directory structure) then it should contain the documentation subtree which makes the "download to another folder oorexxdocSVN" redundant it would seem. That being said, if it works, don't fix it...now. After the release is GA, we can revisit it.
Very good point. Agreed.
Related
Documentation Bugs: #360
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?
+1 (deprecate note in bldoc_win)