Syntax: Add highlighting for section comments

[deathaxe]

It's not an official feature of a sublime-syntax file, but as I started to split syntaxes into sections for better readability I'd find it a good idea to also use them for navigation.

Syntaxes which make use of sections are:

• HTML (ASP) (master)
• Bash (master)
• CSS (master)
• Erlang (master)
• Haskell (see: [Haskell] Rewrite Syntax sublimehq/Packages#2679)
• HTML (master)
• Java (see: [Java] Rewrite Syntax sublimehq/Packages#2654)
• Markdown (some in master)
• Matlab (see: [Matlab] Better syntax highlighting sublimehq/Packages#2650)
• Perl (master)
• Ruby (some in master)
• XML (master)

Inspired by the contexts recently added to R.
see: sublimehq/Packages@d43b3b7

[FichteFoll]

While I do see value in having some sort of section markers in a long file, this is very much non-standard. Many people use different syntaxes for denoting sections and I don't see a compelling reason for why we should support this syntax in particular.

Is this format ever used somewhere outside of RStudio? Do you have any references?

[midopooler]

LGTM

[deathaxe]

I decided to use this style of grouping related contexts in all my recent syntax updates, many of them merged and shipped with ST.

I like the one-liner style and the ability to break long files into logical pieces. They allow folding related stuff which makes editing easier.

Such a kind of delimiters is especially useful as inheritance requires as many contexts as possible to be turned into named contexts because an inherited syntax would otherwise not be able to provide overrides.

We could say: A syntax desined to be a base syntax for inheritance must not use anonymous contexts, which causes many named contexts to be added to a syntax file, which need to be grouped logically somehow.

[FichteFoll]

I decided to use this style of grouping related contexts in all my recent syntax updates, many of them merged and shipped with ST.

Could you point me to some examples? I'm not finding anything other than for R. https://github.com/sublimehq/Packages/search?q=entity.name.section

I'm not opposed to adding some sort of section marker to syntax highlighting and I'm okay with more or less dictating the style to be used, since I believe we have this freedom as the only package providing syntax definitions for ST resource files.
But there are way too many different section marking comment styles out in the wild and I'd like the marker to be consistent with other (popular) syntaxes and even better if the default packages used the same schema. Has Will ever commented on this?

[deathaxe]

Is the list in the initial post not enough?

EDIT: Added some more.

[FichteFoll]

Ah, I think I completely missed what meant with your examples. I was looking for matches in the syntax definitions that would apply entity.name.section to a specifically formatted comment instead of instances of what you mean to highlight with this PR.

I doubt we'll get a "wider adoption" of this standard other than the default packages, probably, and at this point I'm fine with dictating the format. I believe we'd want to add a snippet that inserts a comment formatted like this and document that in the wiki, but I can take care of that when I prepare another release.

[deathaxe]

Even though not enforced by the syntax and some rules exceeding it anyway, I always tried to adjust those delimiters to 80 chars, just to make it look well, if everything is collapsed. Not sure if a snippet could also help with that as the captions are typed after committing it.

[FichteFoll]

I added some refinements in 8c3b361.