Readability improvements.

[mertcandav]

Readability improvements for ./doc/

Validation Steps Performed

• CLA signed.

[github-actions]

New misspellings found, please review:

• ild

To accept these changes, run the following commands

perl -e '
my @expect_files=qw('".github/actions/spell-check/expect/alphabet.txt
.github/actions/spell-check/expect/expect.txt
.github/actions/spell-check/expect/web.txt"');
@ARGV=@expect_files;
my @stale=qw('"akb Autogenerated debugbreak DECLL DECSMBV Inplace notypeopt restrictederrorinfo Scs Switchto Wlk "');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
  if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
  next if /^($re)(?:$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spell-check/expect/b6eead85df562fdd9db3114bfa08b070f1774fa6.txt";
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"autogenerated ild inplace "');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a) cmp lc($b)} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;'
git add .github/actions/spell-check/expect || echo '... you want to ensure .github/actions/spell-check/expect/b6eead85df562fdd9db3114bfa08b070f1774fa6.txt is added to your repository...'

✏️ Contributor please read this

By default the command suggestion will generate a file named based on your commit. That's generally ok as long as you add the file to your commit. Someone can reorganize it later.

⚠️ The command is written for posix shells. You can copy the contents of each perl command excluding the outer ' marks and dropping any '"/"' quotation mark pairs into a file and then run perl file.pl from the root of the repository to run the code. Alternatively, you can manually insert the items...

If the listed items are:

• ... misspelled, then please correct them instead of using the command.
• ... names, please add them to .github/actions/spell-check/dictionary/names.txt.
• ... APIs, you can add them to a file in .github/actions/spell-check/dictionary/.
• ... just things you're using, please add them to an appropriate file in .github/actions/spell-check/expect/.
• ... tokens you only need in one place and shouldn't generally be used, you can add an item in an appropriate file in .github/actions/spell-check/patterns/.

See the README.md in each directory for more information.

🔬 You can test your commits without appending to a PR by creating a new branch with that extra change and pushing it to your fork. The :check-spelling action will run in response to your push -- it doesn't require an open pull request. By using such a branch, you can limit the number of typos your peers see you make. 😉

⚠️ Reviewers

At present, the action that triggered this message will not show its ❌ in this PR unless the branch is within this repository.
Thus, you should make sure that this comment has been addressed before encouraging the merge bot to merge this PR.

[WSLUser]

Keep in mind, unless it's a spec or Roadmap most of the documentation has been moved to https://github.com/microsoftdocs/terminal

[mertcandav]

Thanks for the answer, I replaced it with the old one.

[j4james]

No doubt this is subjective, but I personally find the introduction of all those <br> breaks less readable. If you're looking at the raw markdown (which is often the case for me), then they're just distracting. And in the rendered view they introduce what I'd consider a lot of unnecessary whitespace.

It seems to me that the amount of space to include before a heading should really be a stylistic choice for the renderer. Anyone that prefers more spacing could always use a different viewer, or adjust the css themselves. So I don't think it's appropriate to force a particular style on everyone by hacking in <br> elements everywhere when they aren't strictly necessary.

[DHowett]

@mertcandav Thanks for the contribution!

I'm inclined to agree with James on this one -- the spacing around the headings and the sections is something that should be handled on the client side... because there's a great number of different markdown renderers, with different rendering characteristics, I'm averse to introducing hard line breaks to serve just one of them.

I personally find them noisy as well, as I tend to read the plaintext versions of the documents as that's how they pass around in our review cycles and live in our working trees.

We can also ignore the entire user-docs/ folder. It's not long for this world.

[mertcandav]

Thanks for the comments!