Markdown lint fixes

[BillWagner]

• MD030: Spaces after list markers (there should be 1).
• MD032 - lists should be surrounded by blank lines.
  • Most of these are notes and examples. In most cases, the trailing end note was on a separate line not separated by a blank line. In many, they were at the end of the last bullet item. I normalized all to be on the last bullet item.
• MO037 spaces inside emphasis markers.
• MD038: extra spaces in code span elements.
• MD040 Code fences should have a language specified.
  • The only occurrences are in the tools/GetGrammar folder. These files are added by the tool, and insert the closing codefence. They are false positives. So, disable checking in that folder. We'll catch any mistakes there by linting the tool output on the automated PRs.
• MD041 First line in a file should be a top level heading. No occurrences in the standard. Only in our admin tools and tools include files.
• MD047: Files should end with a newline character. I suspect these are also either in the tools folder, or fixed in previous edits.
• MD050: strong style should be consistent.

I moved MD036 (Using emphasis instead of heading) to the section of warnings we globally disable. The only instances were single paragraphs that were intentionally bold or italic, but not meant to be headings. (For example, in the documentation comments clause on the example, or some "end example" text that appears as its own paragraph.)

Note that I skipped MD031 in this PR. It should be a single PR due to the very large number of occurrences.

Notes for reviewers:

It will be easiest to review using a combination of hide whitespace, and going commit by commit.

1. The commit that fixes MD030 is all whitespace changes.
2. The commit that fixes MD032 adds blank lines above lists, and often combines the end note with the last bullet item.
3. The commit that fixes MD037 is all removing whitespace.
4. The commit that fixes MD038 moves one of the backticks so the space isn't codefenced. In a couple instances, the closing back tick was missing.
5. The commits for MD040 and MD041 were all in the YML config.
6. There was only one instance of MD050.

[BillWagner]

closing and reopening to trigger the checks. (I ran markdown lint on my branch, and it passed).

[jskeet]

The commit that fixes MD032 adds blank lines above lists, and often combines the end note with the last bullet item.

I'm not sure about that one. Is this required in order to fix MD032? It feels to me like it makes the end of the note more obscure.

[jskeet]

Looks fine apart from the "end note at end of last bullet of list" commit, which I'm personally not keen on. We could potentially merge as-is then discuss that separately, or remove that commit and merge the rest.

[BillWagner]

Looks fine apart from the "end note at end of last bullet of list" commit, which I'm personally not keen on. We could potentially merge as-is then discuss that separately, or remove that commit and merge the rest.

If we have a resolution, I can make the changes. (Then I tackle the last warning tomorrow.) I wasn't sure this was the way we wanted to go either. I see a few options.

For background, I looked at the C# 5 standard (Word format). In that document, the end note is inline with the end of the note, whether that note is a standalone paragraph, a paragraph with a list, or an inline note.

Now, using the blockquote for notes and examples, all notes are one or more paragraphs. The style we've adopted forces all notes into their own paragraphs. In most cases, the end note text is the end of the last paragraph (or list item) in the note.

I'd propose one of three normal forms:

1. The end note is always its own paragraph, in a block quote.
2. The end note is inline at the end of the last paragraph of the note.
3. The end note is on its own line, but part of the last paragraph in the note. (I like this least because it will only be clear in the raw markdown view.)

This PR standardizes on (2). I'm open to the other options.

Thoughts?

[jskeet]

I would suggest (1) with the exception that a single-paragraph note can "inline" the end into the same paragraph. So for example, we have this in lexical-structure.md:

Note How an implementation enforces the restriction on the allowable Basic_Identifier values is an implementation issue. end note

I think that's fine as-is, but that only a paragraph that starts with "Note" should end with "end note" if you see what I mean.

[BillWagner]

I like @jskeet 's suggestion.

I did a quick search, and I found 241 instances of end note in the repo (including some tests and code in the markdown converter.)

I recommend merging this, and creating a new issue for the end note / end example formatting. I can address that one early next week.

[jskeet]

Yup, Bill's plan sounds good to me.