Reformat MD files to limit line lengths to 80 characters

[MichaelSimons]

This is in response to https://github.com/dotnet/source-build/pull/4539/files#r1705996684. I originally hoped to re-enable the MD013 rule but discovered it applies to code blocks as well. There are several places where this produces undesirable results therefore I am leaving the rule disabled but still re-formatted the MD files to limit the long lines. I used the 'Rewrap' vscode extension to reformat the files.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

[ellahathaway]

I'm a little disappointed that this rule can't be enabled. Do you have examples of code blocks which currently violate this rule? I'm wondering if we'd be able to adjust them to fit the line length or not.

Edit: https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md seems to suggest that code_block_line_length can be specified (default is 80). I think this is the correct repo... it references markdownlint-cli which is used in our github action.

[ellahathaway]

Does the line limit not apply here because this is a link?

[MichaelSimons]

Link urls are excluded from the limit.

[MichaelSimons]

Do you have examples of code blocks which currently violate this rule?

Yes, you can see the attempts in this PR - https://github.com/dotnet/source-build/actions/runs/10273766628/job/28428985773

A good example is the xml code snippet here - https://github.com/dotnet/source-build/blob/main/Documentation/poison-report-format.md#interpreting-the-poison-report. We are intending to give a snippet of the poison report. Reformatting it (specifically line 12) doesn't feel right to me. Other places we have code blocks that includes commands to execute. Breaking these apart across multiple will hurt the UX when they are intended to be copy/paste. I could specify the code block line length to a large value so that we can have the rule enabled. Thoughts?

[ellahathaway]

I could specify the code block line length to a large value so that we can have the rule enabled. Thoughts?

This sounds good to me!

[MichaelSimons]

This was necessary for https://github.com/dotnet/source-build/blob/main/Documentation/planning/multi-sdk-band-support.md#a-distro-maintainer-wishing-to-build-the-initial-release-n00-of-a-nxx-band-sdk

[mthalman]

Is there precedence for 80 characters? It seems quite unnecessarily small.

[MichaelSimons]

Is there precedence for 80 characters? It seems quite unnecessarily small.

This is a fairly widely used practice. I personally think it is becoming a bit dated. From the internet:

Rows longer than 80 characters should be split into multiple lines where appropriate. This helps make it easier for reviewers to make review comments and for the contributors to see where the requested changes are (without scrolling). It is also easier to see the lines in split view mode when the lines don’t wrap on the screen. It will also improve the readability when using git diff.

[MichaelSimons]

I will also note all of the MD written by @dagood followed this practice already.

[dagood]

FWIW, my new favorite Markdown style is to use one line per sentence. 😄 Very nice diffs for typical edits, usually short enough to not be all that annoying in the occasional non-wrapping viewer, and actually quite nice for the authoring/editing process, mechanically. Downside: less readable (IMO) before Markdown rendering is applied, which might actually influence how you write. (Still getting used to it.)

A random other thing that bugs me about 80 columns is this:

Refer to the [build
instructions](https://github.com/dotnet/installer/blob/main/README.md#build-net-from-source-source-build)
to review how to build the .NET SDK from source.

I think it's signficantly more readable to chop, but I don't think I've seen an editor/wrapper that does it this way (and sticking to what tools will give you is wise):

Refer to the
[build instructions](https://github.com/dotnet/installer/blob/main/README.md#build-net-from-source-source-build)
to review how to build the .NET SDK from source.

(For context: I also chop code rather than wrap it to generally keep it under 100 columns, and these opinions have pretty similar roots IMO.)

[MichaelSimons]

my new favorite Markdown style is to use one line per sentence.

I've seen this. I have to say I am not the biggest fan. 😄

I agree the way links are handled by tooling is generally not the way I would prefer.