Wrap at column 80, mostly.

[bradlitterell]

A few exceptions were manually wrapped or unwrapped so hyperlinks display correctly in markdown color coding in VS Code.

[ljharb]

Why? Hard wrapping makes editing much harder, and viewing diffs much more turbulent - soft wrapping is a far better experience imo.

[bradlitterell]

It seems common practice for markdown & text files in open source to be hard wrapped because it's convenient in many code editors, which tend to word-wrap based on window size, not line length by default. This is especially true for people running large screens.

Some industry examples:

https://raw.githubusercontent.com/github/MVG/main/LICENSE
https://www.apache.org/licenses/LICENSE-2.0.txt
https://raw.githubusercontent.com/tock/tock/master/doc/Getting_Started.md
https://raw.githubusercontent.com/browserify/resolve/main/LICENSE

For example, in a default vs-code installation, running VSCode full-screen, enabling and disabling word-wrap won't wrap the files in this repo except to the window width, not a logical line length. It is probably possible to configure VS code to do so, either with non-default settings, or extensions, but that's extra setup to make it easy to work with this repo.

[ljharb]

What's wrong with using the window width?

[bradlitterell]

Accessibility matters and it is well established that readability declines when line width gets far above 80.
.

[bradlitterell]

Also consider this markdown style guide: https://google.github.io/styleguide/docguide/style.html#character-line-limit

[ljharb]

Can you cite some sources? I'm aware that's been a convention for awhile, because monitors used to be that small, but I'm not aware of actual studies that support it.

Either way, markdown on Github is not viewed on a single size screen, and hard wrapped lines are objectively LESS accessible and readable when the screen size is smaller than 80 chars, as it often is on phones.

[bradlitterell]

@ljharb,

Can you cite some sources?

you mean besides the Google style guide I posted earlier?

Here are some more sources:

• Markdown Lint
• John Gruber
• Wikipedia
• A bunch of other online uses like those I quoted above.

MarkdownLint has 80 characters are a default line length for advising they are too long:
https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md

John Gruber (the originator of Markdown) suggests "it looks better this way":
https://daringfireball.net/projects/markdown/syntax#p

Wikipedia observes that Markdown was created to be "appealing to human readers in its source code form".
https://en.wikipedia.org/wiki/Markdown
(Source Code form obviously implies in a programmer's editor and I'll go out on a limb and suggest that most programmers don't do their primary editing work on a phone.)

Either way, markdown on Github is not viewed on a single size screen

True, but three points:

1. hard-wrapping only requires a minimum size to look consistent, not a single size. The difference is important, and my point for wrapping in the first place - it causes the content to look consistent on a larger set of screen configurations, subject to that minimum size.
2. I suspect markdown is far more frequently (nearly always) viewed in the preview format, not as source code, which is - by design - flexible to size in any case.
3. When viewed as source code, the argument about which is better cuts both ways. It looks worse on programming editors on larger screens, but better on phones. Hopefully we can at least agree that the science says it's easier to read on larger/wider screens with hard-wraps, and I agree with you that soft-wrapping looks better on phones, because at that point the soft-wrapping looks like what markdown rendering mode produces by design.

I've offered the PR and pointed to a number of style guides and reasoning for the suggestion. You have objected and pointed to "imo" and "phone screens on GitHub". You have a fundamental right to disagree and like what you like and if the numerous examples I've cited don't convince you, then I feel this is in danger of becoming a bit of an irreconcilable debate - like spaces vs. tabs.

I'm content to let the maintainers of this repo decide what happens here. Anyone creating a repo based on these documents are obviously free to choose what works for them irrespective of either decision here.

I don't expect such projects to frequently (if ever) take integrations from these documents on an ongoing basis once their separate organization & project repos are up and running, at least not as direct PRs from here.

[ljharb]

I don't mean style guides (which are opinions), I mean actual sources (scientific studies) for "it is well established that readability declines when line width gets far above 80".

[bradlitterell]

I don't mean style guides (which are opinions), I mean actual sources (scientific studies) for "it is well established that readability declines when line width gets far above 80".

Typography and layout is not my primary area of expertise, but I can certainly say from my personal experience that this is true and I have read many articles on the topic that state the same conclusion over the years.
Finally, it is not difficult to turn up additional articles with a little bit of web searching.

https://baymard.com/blog/line-length-readability
http://webtypography.net/2.1.2
https://files.eric.ed.gov/fulltext/EJ1105535.pdf
https://cdn.tc-library.org/Edlab/eye-tracking%20article.pdf
https://en.wikipedia.org/wiki/Line_length#cite_note-dyhas-11

The reason is, that for most readers, eye tracking on wider lines is more difficult, slowing down reading and comprehension. Maybe that's not your personal experience, but at this point I'd say the burden of proof that longer lines are better (or at least not worse), falls squarely on your side of the debate.

[ljharb]

Thanks. This is a strong argument for the rendering being at that width, but not for the source material, since in an editor it's trivial to soft-wrap at whatever width you want. The diff churn hard-wrapping creates imo far outweighs any benefits to keeping it hard-wrapped in the repo.

[bradlitterell]

The whole idea of markdown is to look good as source code. (see my quotes above).
Source code is hard wrapped in nearly every case.

Your opinion runs contrary to both the stated intentions and commentary of the Markdown creator himself as well as the standard text format for open source license agreements that have been used in open source in text format for decades.

You are entitled to your opinion, but I have answered your questions. At this point, let me ask you...

Is there any possible argument that would satisfy you @ljharb ?

[ljharb]

I suppose if my decades of experience with hard wrapping being worse were countered by a similar amount of experience with it being better, that’d do it, but likely not in this conversation.

[ross-spencer]

@bradlitterell have you considered reference style links for this PR? Examples in the Gist here: https://gist.github.com/emedinaa/28ed71b450243aba48accd634679f805

I am a hard-wrapper (not involved with this project in any way other than following it) but it feels more organic when combined with reference style linking. The numbered or labelled approach seems fine.

[bradlitterell]

@ross-spencer - I like the suggestion, but would rather submit it as a separate PR assuming this one is eventually approved/merged. I will adopt your suggestion for another MVG-based project I am creating. Thanks!