Breakable listings within exercises

[JoJoDeveloping]

Hello,

currently, listings are somewhat unusable within exercise environments, since the divisionexercise section creates a tcolorbox. Now, listings are also implemented as a tcolorbox, so having a program inside an exercise prevents the resulting box from properly breaking when the source code is too long, because nested tcolorboxes can not break properly.

So, this means that one must manually split one's listings if they are to render properly in PDF output. This is, of course, bad, and should not be necessary.

This is especially annoying since it the tcolorbox for divisionexercise is only used to change indentation, and does not actually change any colors. Thus, it would be preferable to define divisionexercise some other way that does not involve a tcolorbox. Especially since it's bad to have one's entire document in a tcolorbox, in case it gets longer than 90 pages.

[davidfarmer]

I am having trouble picturing a listing inside an exercise.

Can you give an example?

[JoJoDeveloping]

Well, if you write a textbook / exercise sheet on programming, this comes up.

It's not that much of a problem within the exercise, but the solution can easily be longer than a page.

[davidfarmer]

I am guessing it would be more appropriate to use a "program" that is not inside a "listing" in that context, because a number and caption are probably not relevant in an exercise or solution. But that may not address the underlying issue.

A couple of complete examples may be needed to figure out how to handle this.

[JoJoDeveloping]

That's the problem. The program environment is a tcolorbox listing, i.e. the kind of listing provided by tcolorbox. Which is appropiate, since you want programs to look distinct from regular text. But it is problematic, since this creates nested tcolorboxes.

[davidfarmer]

I think that is the issue. The "listing" environment is suitable for the narrative, not inside an exercise or solution. As an author, it is important to focus on proper markup of the structure of the document. Issues of appearance are left to the publishing step.

There may be (or it may be possible to develop) options for how a program looks in that context, but that is independent of the document source.

So I suggest not wrapping the program in a listing, when that program is in an exercise or solution.

Options for how to proceed after that should be discussed in a PreTeXt google group.

[sean-fitzpatrick]

I think "listing" is being used in two ways here resulting in confusion. There is a PreTeXt environment called a listing, but there is also a type of tcolorbox called a listing, which is what we put code into in LaTeX.

There is an option for any tcolorbox environment or listing to make it breakable, if you want to allow it to split over a page break.

The settings for a tcolorbox can be overridden with custom xsl. But as a first step (to figure out what will work) it is possible to edit the LaTeX source directly. Once an acceptable setting is determined, it can be applied via custom xsl.

[davidfarmer]

To clarify, I was saying that the "listing" PreTeXt tag should not appear in the PreTeXt source for an exercise or solution.

On Fri, 13 May 2022, Sean Fitzpatrick wrote:

I think "listing" is being used in two ways here resulting in confusion. There is a PreTeXt environment called a listing, but there is also a type of tcolorbox called a listing, which is what we put code into in LaTeX.

There is an option for any tcolorbox environment or listing to make it breakable, if you want to allow it to split over a page break.

The settings for a tcolorbox can be overridden with custom xsl. But as a first step (to figure out what will work) it is possible to edit the LaTeX source directly. Once an acceptable setting is determined, it can be applied via custom xsl.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because youcommented.[AABTULFWCDFA5X6N6ZVOGZDVJ2HLRA5CNFSM5V34X4QKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN 5WW2ZLOORPWSZGOIMQ4TJY.gif] Message ID: @.***>

[Alex-Jordan]

Let's bring at least part of this to the discussion forum.

I am in favor of banning certain things like a listing from within an exercise. But listing is currently a schema compliant child of an exercise, statement, solution, hint, and answer. It gets the same accommodations as table, figure, and list in this regard.

Also in the past people have made the argument that things like a listing should be permitted within an exercise. I think my opinion that they could be banned is unpopular.

---

The issue of a tcolorbox within a tcolorbox having breakability issues is separate. And probably a larger issue, since I'd guess there are more situations where that can happen than just exercise//program. What are the reasons to have an exercise use tcolorbox in the first place?

• Styling exercises. This may apply more to inline exercises than divisional exercises, but it would still be a problem with inline exercises if there are very bad page breaks.
• Positioning exercises. Yes, indentation, but more dramatically within an exercisegroup or a worksheet//sidebyside.

So there are some things to think hard about.

[JoJoDeveloping]

but there is also a type of tcolorbox called a listing, which is what we put code into in LaTeX.

This is what I meant.

There is an option for any tcolorbox environment or listing to make it breakable,

Indeed. This is enabled. But it is not of much use when nesting tcolorboxes (see the tcolorbox reference, section 19.3, page 389, listing point 2). Nesting tcolorboxes makes the inner one unbreakable, and there is nothing much you can do except not nest them in the first place.

I was saying that the "listing" PreTeXt tag should not appear in the PreTeXt source for an exercise or solution.

It does not, at least not for me. But the <program> PreTeXt tag is implement in LaTeX as a tcolorbox listing (ie a tcblisting), and this is what I meant. Sorry if this caused confusion.

[rbeezer]

Yes, this nested/breakable business in tcolorbox is a perpetual problem. Thanks, @JoJoModding, for the alert.

@Alex-Jordan said:

What are the reasons to have an exercise use tcolorbox in the first place?

Most critical is to use tcbraster to layout an exercisegroup in columns. Then, as was remarked, the side-by-side syntax is used in worksheet, hence useful there. Indentation in LaTeX is a mess (fake list items are employed), so it helps here, and for "run-in" numbers. So it solves a lot of problems and it would be too delicate to have an alternative in just some situations.

Having said all that, the listing package was also very tempermental, including a spurious bug I never tracked down. So tcblisting is generally very helpful. But it does lead to nested tcolorbox. Secretly, I hope that someday tcolorbox might lift the nested/breakable restrictions.

So...I'm at a bit of a loss for the problem of long hunks of syntax-highlighted code in PDF output that is inside of listing, exercise, solution, etc.

I think the question of listing inside exercise should be taken up on pretext-dev which I should initiate in a few days.

@JoJoModding - thanks again. We'd love to have your participation in open-ended discussions like this on pretext-dev. Requesting membership should be approved very quickly. More at https://pretextbook.org/doc/guide/html/welcome.html

[rbeezer]

Pinging @JoJoDeveloping - grabbed the wrong name out of my email, see previous.

[rbeezer]

I think the question of listing inside exercise should be taken up on pretext-dev which I should initiate in a few days.

https://groups.google.com/g/pretext-dev/c/Ahx_zdUpVqs/m/Qj0KCDjOFwAJ