Lines in API reference XML files are too long

[svick]

The lines in XML files in API reference are way too long. This causes several fairly minor, but noticeable annoyances to contributors like me:

• When viewing the source or editing it on GitHub, I have to keep scrolling horizontally.
• When viewing PRs or diffs, I have to switch to Split mode to see the differences without horizontal scrolling.
• I think that long lines mean that GitHub does not highlight which words changed (see e.g. the diff for Align NetworkStream.Read Remarks with src inline documentation. docs#1930 and try to figure out what changed in remarks; compare it with svick/dotnet-docs@24815ef).

My questions (similar to those in dotnet/docs#1951):

• Is this something that's worth fixing (considering it would change many files)?
• Would a PR by me be welcome, or do you have a better way to deal with this?
• Should it be fixed all at the same time, or would some kind of gradual process make more sense?
• Would it help to fix this in the same PR as Text after list is part of list incorrectly in API reference docs#1951?

I have a work-in-progress code that would fix this here. In case this is deemed worth doing, I would finish it and submit a PR.

[mairaw]

That's an interesting issue. I think before you invest any more of your time, let me discuss this with the rest of the team. I did have to manually scan the text for PR #1930 to spot the differences.

/cc @BillWagner @rpetrusha @wh-alice @dend @yishengjin1413

[guardrex]

Just plz keep in mind a few things:

1. When line lengths are set, they're set permanently everywhere, for everyone, and forever. I work in an IDE, and I usually need to scroll vertically twice as much to compensate for all of these returns all over the place. I prefer to set my window (or IDE pane) to the width of text that I want to see and have the text flow into that space, and the width is frequently variable ... sometimes I'm working wide, sometimes narrow. My preferred width is at least twice what I commonly see in docs where returns have been introduced. When I need to access text on a mobile device that can't handle the pre-determined line length, then that introduces half-lines all over the place.
2. If GH is having a prob with unified mode and highlighting diffs, then that's an issue with GH ... not with docs. If the primary prob is GH, then I suggest a shout out to GH MCP with a feature request to fix GH before taking any drastic actions. A simple soft wrap feature for non-.md docs would be a great benefit the entire GH universe. I'm aware that this has been suggested to them, but maybe if MS asks.

[svick]

@guardrex Yeah, if there's a good chance GitHub's UI will be improved in a reasonable timeframe, that is the best solution.

Otherwise, when it comes to line length, I was thinking of setting it to the highest value, which works on GitHub without scrolling, which seems to be about 120.

[guardrex]

Display of text in the code files relies on HTML's <pre>-style formatting. For example, they use ...

.blob-code-inner { white-space: pre }

... which results in lines not breaking. One can hack it, such as by using something like Stylebot to override the GH style and set ...

.blob-code-inner { white-space: pre-wrap; word-wrap: break-word }

That one simple hack wraps many lines. In XML, the hack isn't completely effective: It still won't work inside of Value attribute values. Fortunately, the hack does seem to work with diffs in unified view. I think with some additional CSS Ninja Tricks:tm: one should be able to have a 100% effective CSS-based workaround. Even if it works tho, I still wish GH would do more for everyone.

RE: Those lines not highlighting changes in diffs. Yeah, that one's on them. Seems like their algorithm that applies the styles, such as .blob-code-addition, just isn't smart enough to catch them all ... or perhaps they do shut it off on very long lines. I think that one should be a bug report to GH.

[carlossanlop]

@svick a workaround I suggest is to install the browser extension "Wide GitHub", which will increase the width of the textarea containers to the full width of the window.
You can find the extension in Chrome (which can also be installed in Edge Insiders) and in Firefox.

[carlossanlop]

Tagging @mimisasouvanh @joelmartinez for triaging.