Generalize scopes for task tags (TODO, FIXME, etc.)

[abusalimov]

Hi,

I'm a developer of the C Improved package mentioned earlier in #24, and I also use your Python Improved package (thank you, BTW :+1:).

This PR modifies the rules responsible for highlighting TODO task tags to apply to meta.toc-list.task-tag and entity.other.task-tag scopes.

First of all, comment.line.note does not fit very well, because at least there is a comment.block scope for languages that support /* block */ comments. And a block comment can have both normal and task tag lines, and only the latter should be highlighted. That is, the highlighted part does not necessarily span the whole comment, and we need to separate a scope for that part from the comment itself.

Secondly, a task tag scoped as comment.line.note.notation is not actually a comment too, but rather some self-sustained entity within the outer comment.

According to the TextMate language grammar naming conventions:

• meta — the meta scope is generally used to markup larger parts of the document. For example the entire line which declares a function would be meta.function and the subsets would be storage.type, entity.name.function, variable.parameter etc. and only the latter would be styled.

  There's a widely used meta.toc-list scope that is primarily used to build up a list of sections in the Ctrl+R symbol list. For example, in C (both the standard Sublime package and C Improved) such scope is applied to // === banner === comments and #pragma mark sections. A believe, TODO comment lines are worth including to the symbol index, and I decided to assign a new meta.toc-list.task-tag scope for that.

  In our case the meta.toc-list.task-tag scope covers the whole comment, except definition tokens, i.e. # or // sign.

• entity — an entity refers to a larger part of the document, for example a chapter, class, function, or tag. We do not scope the entire entity as entity.* (we use meta.* for that). But we do use entity.* for the “placeholders” in the larger entity, e.g. if the entity is a chapter, we would use entity.name.section for the chapter title.

  And the TODO word within the meta scope suggests itself to be scoped as an entity, namely entity.other.task-tag.todo.

In this way, a comment containing a task tag is expected to have the following structure:

# TODO: Highlight this line.
  ^^^^---------------------------------- 'entity.other.task-tag.todo'
  ^^^^^^^^^^^^^^^^^^^^^^^^^^-------- 'meta.toc-list.task-tag.todo'
^^^^^^^^^^^^^^^^^^^^^^^^^^^^---- 'comment.line.number-sign'

Here is how it looks like when using abusalimov/SublimeCImproved#30:

Please note however, that this change currently breaks the highlighting of task tags in Python Improved. If you agree with this change, I could try to make a PR for Python Improved as well, if you want. FWIW, here's how I've implemented it: abusalimov/SublimeCImproved@0dcf851c0931c0af255cc010622b0d21022891fc

Also, I'm not a designer, so the proposed colors for new scopes may need to be revised.

Please let me know, what do you think!

/cc @xtotdam

[MattDMo]

Thanks for the PR, I'll take a look at it.

[MattDMo]

@abusalimov This looks really interesting. Feel free to put together a PR for PythonImproved as well - I'd love to see how it can be implemented there. As far as keeping the current behavior for PI, why not just create separate dicts for meta.toc-list.task-tag and entity.other.task-tag? I don't think we need to replace them at this point.

[abusalimov]

As far as keeping the current behavior for PI, why not just create separate dicts for meta.toc-list.task-tag and entity.other.task-tag? I don't think we need to replace them at this point.

Do you mean restoring comment.line.note[.notation] just for backward compatibility?

[MattDMo]

exactly

[MattDMo]

Sorry for taking such a long time to take care of this - I've been using it in my personal copy for a while, and I really like it. I've also added a number of other scopes using your technique of having a brightly-colored foreground over a dimly-colored background just by decreasing the brightness slider.

At any rate, in case you're tracking things, this was just entered into master with 278c3a1, and I'll be pushing a new release out soon, hopefully tonight or tomorrow night.

[abusalimov]

Better late than never! I've noticed the commit, thank you :+1: