Publisher pagebreaks

[Alex-Jordan]

Draft PR.

This lets publishers specify xml:ids for where they want additional page breaking to occur. There are two issues to sort out yet, and I feel that the discussion has reached the point where it may help to see some code.

1. Do we like the name "insertions"? Both for the publisher file element, and for the additional assembly phase.
2. I get some sort of RTF-related alert when I use this. xsltFreeStackElem: Unexpected RVT flag 3. I can't sort out what it is telling me, or how my usage of things here differs from elsewhere in the code base. Alert notwithstanding, everything "works" in the sense that page breaks come out where specified.

[Alex-Jordan]

I get some sort of RTF-related alert...

I made a change that skirts the alert while leaving the feature functioning. There is a comment about this change now in pretext-assembly.xsl. It's surely an inefficiency to repeatedly use str:tokenize() like I'm doing, rather than store it in a variable, but my testing shows no noticeable change in timing.

I'm going to lift draft mode now. Although perhaps we still are not in love with "insertions".

[Alex-Jordan]

This should apply to exercise too. That should be part of &NUMBERED-BLOCK;.

[rbeezer]

This looks real good, but I think there is one big problem.

Adding a pi:page-break element during assembly totally throws off the ids that are manufactured automatically. Like "fundamental-theorem-5-2". We make an "assembly-id" at one point, hoping that it will remain the same when we make a "visible-id" on a second pass. I mean to try to sort this out, but have no great ideas right now. The insertions are happening in-between. Which I think will lead to a big disconnect.

Yes, authors should be using labels. But imagine a latex-image without. Add an insertion, file name changes, LaTeX won't compile until you re-generate images. That sounds like a frustrating process as you iterate through introducing page breaks (say the affected image was late in a chapter).

I have not manufactured an example. If you think this fear is unfounded, we can dig deeper.

Approach I was thinking of before seeing above. Introduce an attribute on the element with the @xml:id, say @pi:page-break="yes". The cost: every supported block needs an adjustment to every template for that block which early on applies a template to conditionally insert the line-break. But an attribute, in a way, feels more natural to me - "this block is special and will start on a new page".

Also, if I was to merge this right now, I'd need to explode the second commit into four: publisher variable, assembly, LaTeX, Guide. There is a small merge conflict with the entities, it is easy to fix, look for an addition of handout to the previous last definition since this PR was last touched.

[Alex-Jordan]

Just checking, with limited understanding. But does it make any sense to exclude pi: elements from the automatic numbering? Or is it computationally costly?

[rbeezer]

does it make any sense to exclude

Had that thought. The automatic ids, as used in the two-pass generation processes with assembly is a brittle situation. So I don't really want to complicate the (very simple) routines doing the number parts of the automatic ids.

[Alex-Jordan]

OK, I'll change them to attributes.

Unless...one last check. Would it make sense to just do these insertions all at the end, after "visible-id" is established too? You can just direct me to do use attributes if you'd rather not take time to explain. I'll take your word for it.

[rbeezer]

Would it make sense to just do these insertions all at the end

That might work, but I really want to make the pre-processor simpler, not more complicated. It is really making me nervous these days.

Now I'm wondering - why use -assembly at all? The publisher variable is great, and is globally available. Once into a block, test its @xml:id against the variable, and maybe drop a \newpage. A template can do this, it just needs to be applied in each block. This is strictly a LaTeX thing - so why not keep it all in the LaTeX conversion? Conversely, why test for these page breaks every single time we apply a stylesheet, such as the extract-*.xsl suite?

[Alex-Jordan]

Yes, the way it is now was in an effort to add minimal code. Just the one template to -latex. That necessitated using an assembly pass. But if we let that go, assembly is not needed. Alex Jordan Mathematics Instructor Portland Community College

…

On Tue, Aug 26, 2025, 5:13 PM Rob Beezer ***@***.***> wrote: *rbeezer* left a comment (PreTeXtBook/pretext#2618) <https://urldefense.com/v3/__https://github.com/PreTeXtBook/pretext/pull/2618*issuecomment-3226206742__;Iw!!Ka_JY85zDv0FFw!lyXCKYwFFb1EJMWtlRibvkhejSshLs9io19O2tXxARr6PBmYtLEHUaVbI78QLiYc4zlnavMz4c_lvaCfGFsXv71IrMk$> Would it make sense to just do these insertions all at the end That might work, but I really want to make the pre-processor simpler, not more complicated. It is really making me nervous these days. Now I'm wondering - why use -assembly at all? The publisher variable is great, and is globally available. Once into a block, test its @xml:id against the variable, and maybe drop a \newpage. A template can do this, it just needs to be applied in each block. This is strictly a LaTeX thing - so why not keep it all in the LaTeX conversion? Conversely, why test for these page breaks every single time we apply a stylesheet, such as the extract-*.xsl suite? — Reply to this email directly, view it on GitHub <https://urldefense.com/v3/__https://github.com/PreTeXtBook/pretext/pull/2618*issuecomment-3226206742__;Iw!!Ka_JY85zDv0FFw!lyXCKYwFFb1EJMWtlRibvkhejSshLs9io19O2tXxARr6PBmYtLEHUaVbI78QLiYc4zlnavMz4c_lvaCfGFsXv71IrMk$>, or unsubscribe <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/ABEDOACKUEC6WPMM52V773T3PTZZPAVCNFSM6AAAAACB5EFWHSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMRWGIYDMNZUGI__;!!Ka_JY85zDv0FFw!lyXCKYwFFb1EJMWtlRibvkhejSshLs9io19O2tXxARr6PBmYtLEHUaVbI78QLiYc4zlnavMz4c_lvaCfGFsXuJDH2Dw$> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[rbeezer]

Yes, the way it is now was in an effort to add minimal code.

Yes, that was a good idea. A clever idea. Maybe too clever. ;-) -assembly is too popular and getting too complicated. I've got plans to give it a good once over...

[Alex-Jordan]

I am looking at this, and have partial work to turn it into the version where this thread left off back in August. There would be no more involvement with -assembly. Instead, each and every template in -latex where it is reasonable for the publisher to have indicated there should be a pagebreak, there will be a call to a template that prints a \newpage.

I've hit an issue when I reached video (and perhaps other elements). If the publisher has a video with an @xml:id, they might want to declare that they want a pagebreak right before this video. But the preprocessor has already converted this video into a sidebyside. The video with its @xml:id is gone, and we have the sidebyside in its place, but no @xml:id. So I cannot honor the publisher's request to page break right before this "video".

Should -assembly carry the video/@xml:id over to become the @xml:id of the new sidebyside? Or do I leave video out of this?

[Alex-Jordan]

Same question for audio and interactive, which -assembly also converts to sidebysde.

[Alex-Jordan]

A different question while I was working on this, much less important than the first question. In -latex, there are a few templates that match on figure|table|listing|list. This is identical to the &FIGURE-LIKE; entity. Is there any reason I should not change these to match on &FIGURE-LIKE;?

[rbeezer]

Legality of @xml:id was once equivalent to being the target of an xref. That is no longer the case. So go ahead and assume/allow an @xml:id on the atomic items you mention. Please

• Adjust the schema if necessary.
• In your documentation, suggest an enclosing figure would be better, if it is present.

[rbeezer]

Go ahead and move to &FIGURE-LIKE. But

• Do it on aother PR.
• Tell me which PR to look at first, if there will be conflicts.

[Alex-Jordan]

So go ahead and assume/allow an @xml:id on the atomic items you mention.

OK, thanks. I was already planning for that based on earlier conversations about all this during the summer. My question is different. Say an author makes a #video (or #audio, or #interactive) and gives it an @xml:id. Then -assembly (line 3539) replaces the #video with a #sidebyside and the author's @xml:id is gone by the time -latex sees the tree. I'm asking if I can carry the author-provided @xml:id over to the #sidebyside.

[rbeezer]

Sorry, didn't reread the question. Yes, copy it onto the sidebyside! (But maybe document that the sidebyside is automatically generated, and could change size? And mess up the page-fitters? Not sure we guarantee this doen't happen. Only that we will minimize it?)

[Alex-Jordan]

This has now been force pushed, to cleanly get past all the merge conflicts since August. I could close this and open a new PR if that's better.

#2740 should be reviewed before this one.

For the life of me I can never remember the preferred order of xsl, documentation, and sample article commits. If I have these in the wrong order, say the word. I know enough to consult CONTRIBUTING.md though, and if I'm getting the order wrong, might I request an update there?

maybe document that the sidebyside is automatically generated, and could change size?

It occurred to me that this is a larger issue than just videos in a sidebyside. The last paragraph about this feature in the guide brings attention to this. I didn't go so far as to use a warning though...