Couple of non-fatal warnings when trying to add this language to GitHub Linguist

[blaggacao]

Status: Downloaded newer image for linguist/grammar-compiler:latest
docker.io/linguist/grammar-compiler:latest
8 warnings found when compiling new grammar 'repository `vendor/grammars/d2-vscode` (from https://github.com/terrastruct/d2-vscode.git)':
- Unknown keys in grammar: `source.d2` (in `syntaxes/d2.tmLanguage.json`) contains invalid keys (`#`)
- Unknown keys in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) contains invalid keys (`information_for_contributors`, `version`)
- Missing include in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) attempts to include `text.git-commit` but the scope cannot be found
- Missing include in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) attempts to include `text.html.derivative` but the scope cannot be found
- Missing include in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) attempts to include `text.log` but the scope cannot be found
- Missing include in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) attempts to include `source.asp.vb.net` but the scope cannot be found
- Missing include in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) attempts to include `text.git-rebase` but the scope cannot be found
- Missing include in grammar: `text.html.markdown.d2` (in `syntaxes/markdown.tmLanguage.json`) attempts to include `source.json.comments` but the scope cannot be found

These warnings are not fatal, but may mean the syntax highlighting on GitHub.com may not be as expected.

OK! added grammar source 'vendor/grammars/d2-vscode'
	new scope: source.d2
	new scope: text.html.markdown.d2

[blaggacao]

I hope this is actionable 🙏 — I'm just the messenger, really.

[BarryNolte]

Probably actionable, I'll take a look.

[alixander]

@blaggacao I'm curious how this arose. i've had my eye on wanting to get this into GitHub Linguist, but wasn't sure if it hit the requirements yet for usage on GitHub. it's kind of hard to tell due to .d2 extension being used for other files too: https://github.com/search?q=path%3A*.d2+-user%3Aterrastruct&type=code

[blaggacao]

I was just trying to execute on Linguist's documented inclusion procedure which, until I got stuck with my environment (see linked issue), seemed pretty straight forward.

I didn't even realize that d2 has been taken by other languages and was assuming all 1.7k was d2 lang users, lol 😆

I think I saw a section about disambiguation in the docs.

As a capability provider for my team, I'd like to see syntax highlighting for d2 included, soon, though.

[BarryNolte]

Here's the break down:

• First two warnings are just 'comments'. Since json doesn't have comment syntax, these are unknown keys that are ignored. Benign.
• The rest of the warnings are references to languages that are NOT part of the linguist collection. Since they aren't part of linguist, expectations should probably be low that they'd ever be used within D2, but, are included since Microsoft's markdown syntax file is used to derive D2's. Also benign.

[goto1134]

Since the target grammar for linguist is source.d2, the warnings do not appear to be that important. Therefore I added the language support PR: github-linguist/linguist#6435.

It would be great if you could review it just in case.

[Alhadis]

Just weighing in on this:

First two warnings are just 'comments'. Since json doesn't have comment syntax, these are unknown keys that are ignored. Benign.

The canonical field name for comments in JSON files is comment. This is used by most TextMate-derived highlighting systems that read grammars from JSON files.

Consequently, comment is recognised (but ignored) by Linguist's grammar-compiler during processing.

Unknown keys in grammar: text.html.markdown.d2 (in syntaxes/markdown.tmLanguage.json) contains invalid keys (information_for_contributors, version)

As for this, the version field should be removed, and the information_for_contributors field converted into comment fields (discussed above), possibly using an array of strings (if multi-line comments are a must).