Re: [PATCH 0/1] docs: examples of pages affected by heading overflow

[Randy Dunlap]

Hi,

Thanks for the explanations.


On 3/22/26 5:14 AM, Rito Rhymes wrote:
> Thanks for testing things out and for asking about the logic behind the
> implementation choices.
> 
> Is there consistency in the solutions chosen?
> 
> Those 4 patches are not a single series for a reason. They are targeted
> fixes for distinct contexts and use cases where one solution may be
> preferable to the other, i.e. wrapping vs. contained horizontal scroll
> overflow. They are logically consistent in that the reasons for the
> chosen solution do not directly contradict each other across these
> contexts, but they should not all be treated as requiring the same
> generic behavior, such as wrapping everywhere or contained horizontal
> scrolling everywhere. I also did not submit them as a single patch
> series because I did not want each patch to have to justify itself
> against every other patch as a single thematic unit, because the cases
> are very different even if they share an underlying symptom (page-wide
> horizontal scroll overflow).

OK.

>> docs: allow long unbroken headings to wrap and prevent overflow
> 
> Why prefer wrapping?
> 
> You found an unfortunate edge case, but the core regression this fix
> addresses is headings pushing past the right page margin and creating
> page-wide horizontal scroll overflow that breaks the page layout
> instead of wrapping.

Yes, I understand that. And in general the patch is a good idea,
even though I observed that edge case.

> The edge case being:
> 
> GPIO_V2_LINE_GET_VALUES_IOCTL
> 
> Modern browsers do not treat underscores as natural word-break points.
> That whole string is a long unbroken token without a natural breakpoint,
> so without the added wrapping behavior it will create page-wide
> horizontal overflow on small enough screen sizes, as you can test on the
> live site.
> 
> So semantically, it looks like a regression to see
> 
> GPIO_V2_LINE_GET_VALUES_IOCT
> L
> 
> instead of:
> 
> GPIO_V2_LINE_GET_VALUES_
> IOCTL
> 
> But that is still the expected browser behavior. It only looks
> semantically incorrect because the string has internal structure that
> the browser does not understand for wrapping purposes. It is equivalent
> to taking a long unbroken string like:
> 
> GPIOV2LINEGETVALUESIOCTL
> 
> and getting:
> 
> GPIOV2LINEGETVALUESIOCT
> L
> 
> There may be semantically parseable words in there, but regular browser
> wrapping does not know that.
> 
> So this solution does come with a trade-off.

Yes, I wasn't trying to suggest using underscore as a break character.

> Long unbroken strings that have semantic shape but no natural
> breakpoint, including code-style names, will wrap unnaturally.
> 
> But for the majority of headings, wrapping produces clean shapes where
> the semantic structure is preserved because there is spacing or a `-`
> somewhere in the heading.

OK.

> For headings, having everything immediately visible without requiring
> horizontal scrolling is the preferred trade-off. It is tolerable for
> headings to wrap differently across screen sizes, whether that means 1
> line, 2 lines, or 3 lines. In most cases, however many lines the
> heading wraps to, it remains readable and semantically preserved. I do
> not think it would be a reasonable trade-off to introduce contained
> horizontal scrolling for headings just to avoid the edge cases
> involving long unbroken code-style strings.
> 
> Thus, wrapping is the appropriate choice here.

OK, sounds reasonable.

> With that said, we could go a step further and add JavaScript to help
> treat underscores as wrap points, but I do not think that is ideal. It
> would be client-side post-processing, and I do not see similar
> non-Sphinx-native JavaScript being used here for this kind of text
> shaping. I am open to that if people think it is worth it, but it would
> be a new precedent here and not a standard web approach.

nah.

>> docs: contain horizontal overflow in C API descriptions
> 
> Why prefer contained horizontal scroll overflow?
> 
> For this patch, contained horizontal scrolling is preferred because
> code fidelity is the priority. The code is isolated from the rest of the
> page in a dedicated block and presented in a form that is intended to
> remain representative of the code itself. Wrapping distorts spacing and
> line structure, which affects fidelity, creates misleading renderings,
> and reduces readability. Therefore, wrapping is not a good trade-off
> here.

I see.

>> docs: allow inline literals in paragraphs to wrap to prevent overflow
> 
> Why prefer wrapping?
> 
> If preserving code fidelity were the priority here, the code would not
> be embedded inside explanatory prose. The purpose in this context is to
> read a paragraph that includes code as part of the explanation, and it
> would be distracting and hurt readability if the user needed to scroll
> horizontally mid-paragraph just to continue reading. In that context, we
> treat it like any other `<span>` inside of a `<p>`.
> 
>> docs: wrap generated tables to contain small-screen overflow
> 
> Why prefer contained horizontal scroll overflow?
> 
> Wrapping is generally not practical here.
> 
> Many of these tables, often under a `*/features.html*`, exceed at least
> double the viewport width of a mobile screen size. Wrapping the cell
> content enough to fit within a small viewport would often create
> unreadable vertical stacks of wrapped text. Having the rows or columns
> reorganize themselves in some way to fit the viewport would
> fundamentally change the table structure and how it is intended to be
> navigated, which defeats the simplicity of keeping a single table
> structure for many purposes.

Sounds messy.

> The simplest solution is to respect the width the generated table
> creates and allow horizontal scrolling within the table container,
> without allowing the entire page width to expand.

I see that Jon asked about provenance of these patches.
I meant to do that as well but got wrapped up in Advanced Search
testing.

-- 
~Randy