Improve semantic correctness and consistent presentation in the ReadMe.

[RokeJulianLockhart]

Description

The WCAG AA requires adherence to the chosen markup language. That's GHFM. GHFM necessarily requires adherence to CommonMark, which is essentially 1:1 with the WHATWG HTML LS for the purposes of this patch.

Consequently:

• I added a \n between lis, such that they become li > ps. This matters with GHFM's CSS3, because they don't wrap well otherwise.

• I added shebangs for pre > codes compliant with IEEE Standard 1003.1-2017 Shell Command Language, and/or its superordinate implementations. This matters because pwsh (and similar) shan't act as bash does.

• I added periods at the end of the CLI usage lis' sentences, because they are sentences.

• I removed erroneously-added \ns at the start end end of some pre > codes, because they don't render on GitHub. Having the documentation render differently when local and not is undesirable.

This is solely partially so that I can acquire collaborator status, thereby allowing me to ask for issues/7637 to be re-closed as a duplicate of github/markup/issues/2000! 😆

Checklist:

Ironically, I've avoided incurring github/markup/issues/1857 for the undermentioned:

• I am adding a new extension to a language.
• I am adding a new language.
• I am fixing a misclassified language
• I am changing the source of a syntax highlighting grammar
• I am updating a grammar submodule
• I am adding new or changing current functionality
• I am changing the color associated with a language

I have actually read all of these, but due to what orgs/community/discussions/19199#discussioncomment-10371423 describes, cannot indicate that they are inapplicable. Consequently, I have removed their dependent subordinates.

[Alhadis]

The WCAG AA requires adherence to the chosen markup language. That's GHFM.

No, that's HTML. GHFM (the correct acronym of which is “GFM”, BTW) is a superset¹ of a standardised form of Markdown, a lightweight markup language chiefly used to generate HTML output. The WCAG has nothing to do with Markdown.

GHFM necessarily requires adherence to CommonMark, which is essentially 1:1 with the WHATWG HTML LS for the purposes of this patch.

Erh, no it's not. CommonMark uses an explicitly versioned specification, while the WHATWG adopts a "rolling updates" approach (hence the term, Living Standard). In any case, the comparison is an apples-to-oranges scenario.

I added a \n between lis, such that they become li > ps. This matters with GHFM's CSS3, because they don't wrap well otherwise.

I've no idea what you're referring to here. The existing lists soft-wrap perfectly fine, and the only thing you've done by converting li > text to li > p > text is add unnecessary vertical space to an already overly-long page.

I added shebangs for pre > codes compliant with IEEE Standard 1003.1-2017 Shell Command Language, and/or its superordinate implementations. This matters because pwsh (and similar) shan't act as bash does.

Interpreter directives (otherwise known as "hashbangs" or "shebangs") aren't specified by POSIX (and thus, IEEE 1003.1-2017), but even if they were, adding them makes no sense in the context of the code-blocks you've modified. These are intended to be single-line, copy+pastable terminal commands for the reader's benefit, not isolated executables. Moreover, they're simple enough that both Bourne-style shells (like bash(1) and zsh(1)) and non POSIX-compliant shell languages (like PowerShell/pwsh) will interpret them correctly.

(It's also odd to bring up other command interpreters like PowerShell when the hashbangs you've added specify bash, but whatever).

I added periods at the end of the CLI usage lis' sentences, because they are sentences.

In this case, you're right, but list-items themselves don't always merit a full-stop (such as when they contain fragments instead of sentences).

I removed erroneously-added \ns at the start end end of some pre > codes, because they don't render on GitHub. Having the documentation render differently when local and not is undesirable.

Well, it's going to render differently anyway. Markdown footnotes are supported on GitHub,² but they aren't part of the GFM specification itself. So concerns over how Linguist's readme gets rendered elsewhere is a moot point.

Instead, you could've simply said you removed extraneous empty lines in code-blocks, which by itself would've been adequate.

Footnotes

1. https://github.github.com/gfm/#what-is-github-flavored-markdown%2D ↩

2. https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes ↩

[Alhadis]

The backticks you've added to the library names can stay, but the extraneous newlines you've inserted need to be removed.

Suggested change

	Linguist uses [`charlock_holmes`](https://github.com/brianmario/charlock_holmes) for character encoding and [`rugged`](https://github.com/libgit2/rugged) for `libgit2` bindings for Ruby.
	These components have their own dependencies:
	1. `charlock_holmes`
	* `cmake`
	* `pkg-config`
	Linguist uses [`charlock_holmes`](https://github.com/brianmario/charlock_holmes) for character encoding and [`rugged`](https://github.com/libgit2/rugged) for `libgit2` bindings for Ruby.
	These components have their own dependencies:
	1. `charlock_holmes`
	* `cmake`
	* `pkg-config`

[Alhadis]

See above.

Suggested change

	* [`zlib`](https://zlib.net/)
	3. `rugged`
	* [`libcurl`](https://curl.haxx.se/libcurl/)
	* [`zlib`](https://zlib.net/)
	3. `rugged`
	* [`libcurl`](https://curl.haxx.se/libcurl/)

[Alhadis]

Remove this.

[Alhadis]

Remove this.

[Alhadis]

The full-stops you've added can stay, but the superfluous line-break needs to go.

Suggested change

	1. **[Git Repository mode](#git-repository)** – Analyzes an entire Git repository (when given a directory path or no path).
	2. **[Single file mode](#single-file)** – Analyzes a specific file (when given a file path).
	1. **[Git Repository mode](#git-repository)** – Analyzes an entire Git repository (when given a directory path or no path).
	2. **[Single file mode](#single-file)** – Analyzes a specific file (when given a file path).