reStructure entire grammar

Alhadis commented 8 years ago

Whoa boy... this is gonna be hard to summarise. First of all, I apologise for changing the code-style of the grammar. People probably think I exaggerate when I say I can't follow 2-space indented code. I'm not. If the tabs are an issue, I'm happy to change them back if that's what you prefer.

ANYWAY. On to what's changed:

Tables

Both grid-tables and "simple" tables are now properly highlighted, which is particularly noticeable in themes which distinguish punctuation characters (e.g., Seti, Duotone).

Previously, only the top border would match, and there were also highlighting problems with | characters. These would be matched as substitution references, which looked particularly jarring for themes which add underlines to any match using the underline.link scope.

Improved substitution references

I'll let the preview describe this one...

Multiline footnotes

Only the first line of footnotes were being highlighted. That's been fixed:

Sphinx domains

An issue brought up in #13, sitting unattended for over a year. Took care of it, even going as far as including embedded syntax highlighting for each language domain that Sphinx supports:

As Sphinx allows domains to be added via extensions, I left generic support for those languages which aren't defined. So .. foobazmatron:function:: wouldn't be highlighted as a comment.

Multiline comments

These weren't being picked up previously either:

Known limitation:

Empty comments that have a blank line directly afterward are used as "terminators" for things like nested block-quotes and stuff. There's no way of supporting this without breaking support for multiple paragraphs in comment-blocks. I brought this up in a more technical discussion here.

So at the moment, indented paragraphs that follow an empty comment are incorrectly highlighted. This might be an edge issue, but if anybody reports it, this PR is where to send them for an explanation why a fix can't be done.

Line blocks

Like tables, this isn't really of importance unless your theme highlights punctuation characters.

Fixed code-block highlighting

Admittedly, this was my fault for not picking up on this in my first PR - .. code-block:: python and the like weren't being formatted as directive statements. Fixed that:

Numerous other fixes

Added highlighting for escaped characters (e.g., \|)
Added code snippet to insert a .. code-block statement
Added support for .. code directives
Improved wording of readme and added related links and package.json keywords
Probably other stuff I missed
Issues fixed
Closes #34: Add rst / rest to the description in Atom
Closes #20: Choice of scope
Closes #30: Incomplete support for section underlines
Closes #13: Directives with domains names are not parsed correctly
Closes #35: Autocompletion

Lukasa commented 8 years ago

Fantastic work @Alhadis, thanks so much! The review job looks fine: the big diff delayed my review a bit, but that's ok. I'll push a release containing this patch shortly.

Alhadis commented 8 years ago

My pleasure, all too happy to help! :D

Alhadis commented 8 years ago

@Lukasa Just so you know, this file will be used to supply syntax highlighting for reStructuredText files on GitHub (in a few weeks, when another release of Linguist gets cut). Just a heads up. =)

Lukasa / language-restructuredtext