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

["Rito Rhymes" <rito@ritovision.com>]

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

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

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.

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.

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.

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.

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

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

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.