Add additional comment syntax in the PlainNotes package for Sublime Text - sublimetext3

Question

I am using the PlainNotes package and its syntax istead of Plain Text. I would like to add some additional syntax for comments, for example for JS comments (triggered by //). I am trying to edit this file using the suggested code in the demo (Tools > Developer > New Syntax):
...
contexts:
main:
......
# Comments begin with a '//' and finish at the end of the line
- match: '//'
scope: punctuation.definition.comment.example-c
push: line_comment
line_comment:
- meta_scope: comment.line.example-c
- match: $
pop: true
One of the likely problems is that I do not know how to set the scope. I tried using the scope from the Ctrl+Alt+Shift+P shortcut when I select HTML comments, and I looked in the tmLanguage file as well, but I am still stuck

Answer 1

For the purposes of this answer we're going to assume that the match rule that we want to apply to the syntax is the following one:
- match: '//'
scope: punctuation.definition.comment.begin.html
push:
- meta_scope: comment.line.double-slash.html
- match: $\n?
pop: true
This is a more compact version of the one from the sample syntax template in that it uses an anonymous context instead of a named context for the push. The scopes have been tweaked slightly (see the standard scope names used for something like this) and we also optionally match the newline at the end of the comment line to make sure things that should not happen when the cursor is in a comment also don't happen when the cursor is on the end of a comment line.
We'll also assume that the sample note file that we want to test with contains the following text:
This is a single line
This is a paragraph of
text that is spread over
several lines.
With that out of the way, there are a few potential pitfalls that you might be running into here; some of them generic to Syntaxes in general, some of them specific to the PlainNotes package:
Pitfall 1: Match rule placement is important
The order of the match statements in a context specifies their precedence for matching in the syntax. Generally speaking, the first match in the context that matches on the text is the one selected.
If you inject the match rule as the last rule in the main context, nothing happens no matter what you try to comment out. Instead the scope for all of the lines of text will remain as text.html.markdown.note meta.paragraph.markdown.
This is because the syntax rule that detects a paragraph of text occurs closer to the top of the main context than the comment match, so before the comment rule can match the paragraph rule has already matched and consumed that text.
Putting the match rule as the first item in main shows a slightly different problem instead. If you do that, you'll see that if you try to comment out the single line, the scope will change to say that there is a comment there (although visually you can't tell; more on that below). Similarly if you try to comment out the first line of the paragraph, it's scope will also change.
However, trying to comment out the second or third lines in the paragraph have no effect; the scope remains unchanged. The reason for that flows directly into pitfall #2.
Pitfall 2: Syntax contexts are distinct
In a Syntax there are one or more contexts in which syntax rules live. There is always a context named main, which is where the syntax "starts" its matching. In the case of our comment rule there is also a second anonymous context that contains a single match rule that signals the end of the comment.
Each of the contexts is distinct; they have rules that they match against, but only the rules in the active context are considered and all others are ignored; the contexts are distinct.
Our issue here is that one of the last rules in the main context detects what it thinks is the start of a paragraph, and when that happens it does a push into an anonymous context just like our comment rule does.
As soon as that happens, the syntax thinks that it's inside of a paragraph of text and a whole other set of rules apply, one of which is not one that matches comments. This lets us comment the first line because it's not a paragraph yet, but as soon as the paragraph starts a comment can't occur until the paragraph exits.
To solve this problem you need to also include the rules for comments inside of the rules for paragraphs so that it will also apply in there.
To do that, we might define a context of our own that contains only our rules for matching comments:
comments:
- match: '//'
scope: punctuation.definition.comment.begin.html
push:
- meta_scope: comment.line.double-slash.html
- match: $\n?
pop: true
Now as the very first match in main we can include the rules from our comments context so that they apply there:
main:
- include: comments
...
We then also search through the syntax to find the location where the meta.paragraph.markdown scope is applied to find the location where a paragraph is matched and do an include in there to inject our comment rule there as well. Keeping the first pitfall in mind, we put it as the first rule in the anonymous context so that it can consume a comment before anything else:
- match: '^(?=\S|[ ]{1,3})(?![=-]{3,}(?=$))'
push:
- meta_scope: meta.paragraph.markdown
- include: comments
...
With that in place, we can now comment lines of paragraphs and the scope will indicate that it is a comment the way we want.
However we still don't see any visual indication that there is a comment in place, which leads us to the third pitfall.
Pitfall 3: Syntaxes and color schemes work together
The syntax in use and the color scheme in use need to work together in order to provide the syntax highlighting that we expect to see. The syntax applies scopes to the text and the color scheme has rules that apply colors to scopes.
If the syntax doesn't scope something with a rule that the color scheme matches against, no style can be applied; this is what's happening here.
Technically speaking the scopes that our rule is applying are correct and standard as per the link outlined above. In this particular case the issue at hand is that the PlainNotes package includes not only it's own syntaxes but also it's own color schemes.
The color schemes that it applies don't match on the standardized scopes that we're using because as defined by the package author the syntax doesn't generate that scope.
The color schemes that PlainNotes provides has rules for comments, but only for block comments and not for line comments that we're using here. You can see this by using an HTML comment in a notes file and seeing that it visually changes.
The most expedient fix would be to modify the scopes applied by the commenting rules so that they apply the scopes that PlainNotes expects:
comments:
- match: '//'
scope: punctuation.definition.comment.begin.html
push:
- meta_scope: comment.block.html
- match: $\n?
pop: true
With that in place, we can comment single lines or interior lines in paragraphs and get the syntax highlighting that we expect:
Depending on your use case, this may or may not be enough to allow comments in all of the places that you want.
For example, comments are not possible in headings because there is a match rule that matches a heading as a complete line, which consumes the comment token before anything can match it.
Fixing that would require reworking the match rules for headings to work similar to comments (i.e. pushing a context so that you can include comments) which may or may not be worth it.