Observe that the empty :test: role, when followed by ., causes the following text to be highlighted. It appears that the "``" is being interpreted as the opening delimiter for an rstInlineLiteral when it should be treated as empty delimiters for rstInterpretedTextOrHyperlinkReference.

Spell checking does not appear to work when php is removed from g:rst_syntax_code_list, the default list of languages used to syntax highlight content within code:: directives.

It's not clear to me why including php fixes this problem.

Only users with custom rst_syntax_code_list set would notice this issue.

Would be nice to have e.g. vad select the entire current directive when the cursor is inside a directive and vid the contents of the directive itself (excluding the .. directive:: and :option: lines).

(As usual, mostly treating this tracker as a todo/ideas list :-))

Just to make a note here about issue vim/vim#2118

If a document has a single top-level section (e.g., a title of a document), it seems, it's better to not to fold it because the first thing you do in this case is unfolding this the only section each time.

https://github.com/Rykka/riv.vim includes an option to highlight python docstrings with rst syntax (https://github.com/Rykka/riv.vim/blob/master/doc/riv_instruction.rst#docstring-highlighting). I have tried just copy-pasting their after/syntax/python.vim (https://github.com/Rykka/riv.vim/blob/598c8983dde237518732785a4726c8a3acb49617/after/syntax/python.vim) (you need to fix the paths to the rst.vim files that get included) but that triggered an bunch of errors (when used in conjunction with your rst.vim).

Any interest in trying to make a similar option available for your implementation of rst.vim? Thanks!

Code block with lexer specified explicitly, the asterisk is regarded as a RST markup, resulting in the subsequent text being rendered in italic.

Wihtout lexer specified, it works as expected.

This might be related to #40 , does the fix for it introduce the new issue?

Hi,

Are you :h rst.vim maintainer?

There is a setting example that causes an error in :h rst.vim.

https://github.com/vim/vim/blob/master/runtime/doc/syntax.txt#L2772-L2777

Current

    let rst_syntax_code_list = {
        \ 'cpp' = ['cpp', 'c++'],
        \ 'bash' = ['bash', 'sh'],
        ...
	}

Change

I think it would be better to change this way.

    let g:rst_syntax_code_list = {
        \ 'cpp':  ['cpp', 'c++'],
        \ 'bash': ['bash', 'sh'],
        ...
        \ }

It would be nice if roles like ":role:text" and text:role:" [1] would be recognised by this syntax plugin.
This would allow syntax highlighting and spell checking (see #12).

Notes:

• Valid role names "conform to the rules of simple reference names" [2].
• Roles can be pre- (":role:text") or post (text:role:")
• Be aware that Sphinx has "domains" whose roles contain a colon, e.g. ":py:role:text". This should also be supported (should be covered by [2] but want to point it out due to the internal colon and its wide-spread usage).
• Be aware that the :text: syntax is also used in field lists.

[1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text
[2] https://docutils.sourceforge.io/docs/ref/rst/directives.html#role-name

Hi,
I attempted to add 'c': ['c'] to the g:rst_syntax_code_list to enable C syntax highlighting but run into the issue with c and cpp code blocks as described below.

Given the following rst text:

.. code:: cpp
   using namespace std;

   int main() {}

using

Both 'using' are highlighted as C++ statement. It seems that 'c' and 'cpp' cannot be specified simultaneously in g:rst_syntax_code_list.

I am not sure, what's the deal, but syntax/rst.vim from this plugin installed (via vim8 package mechanism, if it matters), spelling errors are not displayed. When the file is removed (or renamed to syntax/rst.vim.NOACTIVE) spelling works just fine.

This is diff between syntax file from this plugin and the default one in vim 8.0-1389, but I don't see anything wrong there (however, I am really not very good in understanding syntax files):

--- /usr/share/vim/vim80/syntax/rst.vim	2017-12-13 00:31:38.000000000 +0100
+++ rst.vim.NOACTIVE	2017-11-06 14:40:18.197813161 +0100
@@ -3,7 +3,7 @@
 " Maintainer: Marshall Ward <[email protected]>
 " Previous Maintainer: Nikolai Weibull <[email protected]>
 " Website: https://github.com/marshallward/vim-restructuredtext
-" Latest Revision: 2016-08-18
+" Latest Revision: 2017-02-18
 
 if exists("b:current_syntax")
   finish
@@ -50,7 +50,10 @@
 syn match   rstExplicitMarkup       '^\s*\.\.\_s'
       \ nextgroup=@rstDirectives,rstComment,rstSubstitutionDefinition
 
-let s:ReferenceName = '[[:alnum:]]\+\%([_.-][[:alnum:]]\+\)*'
+" "Simple reference names are single words consisting of alphanumerics plus
+" isolated (no two adjacent) internal hyphens, underscores, periods, colons
+" and plus signs."
+let s:ReferenceName = '[[:alnum:]]\%([-_.:+]\?[[:alnum:]]\+\)*'
 
 syn keyword     rstTodo             contained FIXME TODO XXX NOTE
 
@@ -83,7 +86,7 @@
       \ ' end=+^\s\@!+ contains=@rstCruft,rstLiteralBlock'
 
 execute 'syn match rstSubstitutionDefinition contained' .
-      \ ' /|' . s:ReferenceName . '|\_s\+/ nextgroup=@rstDirectives'
+      \ ' /|.*|\_s\+/ nextgroup=@rstDirectives'
 
 function! s:DefineOneInlineMarkup(name, start, middle, end, char_left, char_right)
   execute 'syn region rst' . a:name .
@@ -107,10 +110,10 @@
   call s:DefineOneInlineMarkup(a:name, a:start, middle, a:end, '’', '’')
   " TODO: Additional Unicode Pd, Po, Pi, Pf, Ps characters
 
-  call s:DefineOneInlineMarkup(a:name, a:start, middle, a:end, '\%(^\|\s\|[/:]\)', '')
+  call s:DefineOneInlineMarkup(a:name, a:start, middle, a:end, '\%(^\|\s\|\%ua0\|[/:]\)', '')
 
   execute 'syn match rst' . a:name .
-        \ ' +\%(^\|\s\|[''"([{</:]\)\zs' . a:start .
+        \ ' +\%(^\|\s\|\%ua0\|[''"([{</:]\)\zs' . a:start .
         \ '[^[:space:]' . a:start[strlen(a:start) - 1] . ']'
         \ a:end . '\ze\%($\|\s\|[''")\]}>/:.,;!?\\-]\)+'
 
@@ -124,14 +127,31 @@
 call s:DefineInlineMarkup('SubstitutionReference', '|', '|', '|_\{0,2}')
 call s:DefineInlineMarkup('InlineInternalTargets', '_`', '`', '`')
 
-syn match   rstSections "^\%(\([=`:.'"~^_*+#-]\)\1\+\n\)\=.\+\n\([=`:.'"~^_*+#-]\)\2\+$"
+" Sections are identified through their titles, which are marked up with
+" adornment: "underlines" below the title text, or underlines and matching
+" "overlines" above the title. An underline/overline is a single repeated
+" punctuation character that begins in column 1 and forms a line extending at
+" least as far as the right edge of the title text.
+"
+" It is difficult to count characters in a regex, but we at least special-case
+" the case where the title has at least three characters to require the
+" adornment to have at least three characters as well, in order to handle
+" properly the case of a literal block:
+"
+"    this is the end of a paragraph
+"    ::
+"       this is a literal block
+syn match   rstSections "\v^%(([=`:.'"~^_*+#-])\1+\n)?.{1,2}\n([=`:.'"~^_*+#-])\2+$"
+    \ contains=@Spell
+syn match   rstSections "\v^%(([=`:.'"~^_*+#-])\1{2,}\n)?.{3,}\n([=`:.'"~^_*+#-])\2{2,}$"
+    \ contains=@Spell
 
 " TODO: Can’t remember why these two can’t be defined like the ones above.
 execute 'syn match rstFootnoteReference contains=@NoSpell' .
-      \ ' +\[\%(\d\+\|#\%(' . s:ReferenceName . '\)\=\|\*\)\]_+'
+      \ ' +\%(\s\|^\)\[\%(\d\+\|#\%(' . s:ReferenceName . '\)\=\|\*\)\]_+'
 
 execute 'syn match rstCitationReference contains=@NoSpell' .
-      \ ' +\[' . s:ReferenceName . '\]_\ze\%($\|\s\|[''")\]}>/:.,;!?\\-]\)+'
+      \ ' +\%(\s\|^\)\[' . s:ReferenceName . '\]_\ze\%($\|\s\|[''")\]}>/:.,;!?\\-]\)+'
 
 execute 'syn match rstHyperlinkReference' .
       \ ' /\<' . s:ReferenceName . '__\=\ze\%($\|\s\|[''")\]}>/:.,;!?\\-]\)/'
@@ -140,28 +160,69 @@
       \ "\<\%(\%(\%(https\=\|file\|ftp\|gopher\)://\|\%(mailto\|news\):\)[^[:space:]'\"<>]\+\|www[[:alnum:]_-]*\.[[:alnum:]_-]\+\.[^[:space:]'\"<>]\+\)[[:alnum:]/]"
 
 syn region rstCodeBlock contained matchgroup=rstDirective
-      \ start=+\%(sourcecode\|code\%(-block\)\=\)::\s\+\w*\_s*\n\ze\z(\s\+\)+
+      \ start=+\%(sourcecode\|code\%(-block\)\=\)::\s\+.*\_s*\n\ze\z(\s\+\)+
       \ skip=+^$+
       \ end=+^\z1\@!+
       \ contains=@NoSpell
 syn cluster rstDirectives add=rstCodeBlock
 
 if !exists('g:rst_syntax_code_list')
-    let g:rst_syntax_code_list = ['vim', 'java', 'cpp', 'lisp', 'php',
-                                \ 'python', 'perl', 'sh']
+    " A mapping from a Vim filetype to a list of alias patterns (pattern
+    " branches to be specific, see ':help /pattern'). E.g. given:
+    "
+    "   let g:rst_syntax_code_list = {
+    "       \ 'cpp': ['cpp', 'c++'],
+    "       \ }
+    "
+    " then the respective contents of the following two rST directives:
+    "
+    "   .. code:: cpp
+    "
+    "       auto i = 42;
+    "
+    "   .. code:: C++
+    "
+    "       auto i = 42;
+    "
+    " will both be highlighted as C++ code. As shown by the latter block
+    " pattern matching will be case-insensitive.
+    let g:rst_syntax_code_list = {
+        \ 'vim': ['vim'],
+        \ 'java': ['java'],
+        \ 'cpp': ['cpp', 'c++'],
+        \ 'lisp': ['lisp'],
+        \ 'php': ['php'],
+        \ 'python': ['python'],
+        \ 'perl': ['perl'],
+        \ 'sh': ['sh'],
+        \ }
+elseif type(g:rst_syntax_code_list) == type([])
+    " backward compatibility with former list format
+    let s:old_spec = g:rst_syntax_code_list
+    let g:rst_syntax_code_list = {}
+    for s:elem in s:old_spec
+        let g:rst_syntax_code_list[s:elem] = [s:elem]
+    endfor
 endif
 
-for code in g:rst_syntax_code_list
+for s:filetype in keys(g:rst_syntax_code_list)
     unlet! b:current_syntax
     " guard against setting 'isk' option which might cause problems (issue #108)
     let prior_isk = &l:iskeyword
-    exe 'syn include @rst'.code.' syntax/'.code.'.vim'
-    exe 'syn region rstDirective'.code.' matchgroup=rstDirective fold'
-                \.' start=#\%(sourcecode\|code\%(-block\)\=\)::\s\+'.code.'\_s*\n\ze\z(\s\+\)#'
+    let s:alias_pattern = ''
+                \.'\%('
+                \.join(g:rst_syntax_code_list[s:filetype], '\|')
+                \.'\)'
+
+    exe 'syn include @rst'.s:filetype.' syntax/'.s:filetype.'.vim'
+    exe 'syn region rstDirective'.s:filetype
+                \.' matchgroup=rstDirective fold'
+                \.' start="\c\%(sourcecode\|code\%(-block\)\=\)::\s\+'.s:alias_pattern.'\_s*\n\ze\z(\s\+\)"'
                 \.' skip=#^$#'
                 \.' end=#^\z1\@!#'
-                \.' contains=@NoSpell,@rst'.code
-    exe 'syn cluster rstDirectives add=rstDirective'.code
+                \.' contains=@NoSpell,@rst'.s:filetype
+    exe 'syn cluster rstDirectives add=rstDirective'.s:filetype
+
     " reset 'isk' setting, if it has been changed
     if &l:iskeyword !=# prior_isk
         let &l:iskeyword = prior_isk

(Re-posting on behalf of @philj56 ; original text below)

The following example shows the issue:

.. math::
|E| + 3
|E|+3

The first line highlights correctly, with the + 3 using normal maths highlighting. On the second line, the lack of whitespace causes the |E| highlighting to never end, and carries on through the whole document until another || pair followed by whitespace is found.

Edit: Actually this doesn't just apply to math mode, the same thing happens without the directive.

With ``C:\``, the first ending backtick is escaped by the backslash, resulting in the subsequent text being highlighted as inline literal until meeting with a ``.

The RST specification states:

An unescaped backslash preceding a start-string or end-string will disable markup recognition, except for the end-string of inline literals.

Therefore, any backslash within inline literal should be regarded as a literal backslash.

Something like

setlocal makeprg=python\ -c\"import\ sys,subprocess,tempfile,webbrowser;tmp=tempfile.TemporaryDirectory();output=tmp.name+'/'+sys.argv[2]+'.html';subprocess.run(['rst2html5.py',sys.argv[1],output]);webbrowser.open(output,2)\"\ %\ %:t:r

allows one to type :make and get the rendered HTML output in a webbrowser. I think the default errorformat even works for syntax errors :)
(The lack of spaces in the python script is a bit ugly, but escaping each and every space with a backslash doesn't really improve things...)

Literal block highlighting extends too far when the block is contained within a bullet, e.g.:

- A bullet with literal following::

    Correctly highlighted literal

  Incorrectly highlighted as literal

Correctly unhighlighted.

As I understand it from https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists, the indentation level for the body of the bullet is determined by the first non-whitespace character after the bullet character (starting at A bullet with above). The subsequent literal block must be indented relative to that, and that literal block should end when the additional indentation is removed (at the line Incorrectly highlighted as literal).

Using the latest vim-restructuredtext, the line Incorrectly highlighted as literal is highlighted as a literal block.

Using the rst2html command from docutils <https://docutils.sourceforge.io/>, the above reStructuredText renders correctly as:

<ul>
<li><p class="first">A bullet with literal following:</p>
<pre class="literal-block">
Correctly highlighted literal
</pre>
<p>Incorrectly highlighted as literal</p>
</li>
</ul>
<p>Correctly unhighlighted.</p>
</div>

Literal block highlighting worked correctly for such cases before 796536c.

The lines following a directive embedded in a definition list definition are not correctly highlighted. See screenshot:

The "yada yada yada" should not be highlighted as if it were part of the directive, as it is not at the indentation level to include it in the directive.

https://github.com/python/cpython/blob/master/Doc/library/subprocess.rst#using-the-modsubprocess-module contains the following snippet:

.. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\
                  shell=False, timeout=None, check=False, \
                  encoding=None, errors=None)

   Run the command described by *args*.  Wait for command to complete, then
   return a :class:`CompletedProcess` instance.

Currently, vim-rst highlights as italic everything from the first star (first line) to after *args*. After skimming through the rst spec, I believe that the function signature is a separate element (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives)

The directive block is consists of any text on the first line of the directive after the directive marker, and any subsequent indented text. The interpretation of the directive block is up to the directive code. There are three logical parts to the directive block:
Directive arguments.
Directive options.
Directive content.
Individual directives can employ any combination of these parts. Directive arguments can be filesystem paths, URLs, title text, etc. Directive options are indicated using field lists; the field names and contents are directive-specific. Arguments and options must form a contiguous block beginning on the first or second line of the directive; a blank line indicates the beginning of the directive content block. If either arguments and/or options are employed by the directive, a blank line must separate them from the directive content. The "figure" directive employs all three parts:

so while it may not be completely clear whether the directive argument should be subject to markup (it may actually depend on the directive itself...), at least the markup should stop by the end of the element.

As raised by @madjxatw in #45, the .. code-block:: directive introduced by Sphinx deviates slightly from the intrinsic reST directive .. code::, in that code-block requires specification of a language.

The proposal is to utilize syntax highlighting to indicate that a language is missing from the directive.

As discussed in #39 , italic and bold escape characters (e.g. *foo\*bar*) are not styled within inlines.

It would be good to work out a way to apply the appropriate style to the characters

The following example is from http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions:

|The Transparent Society| offers a fascinating alternate view
on privacy issues.

.. |The Transparent Society| book:: isbn=0738201448

rst.vim currently does not highlight .. |The Transparent Society| as a reference due to the presence of spaces.

The current syntax matches the space sequence of the first line in a literal block as the indent sequence, which is unnecessary and can make mistakes.

For example, vim-restructuredtext considers the second line in the block out of the block with the following text:

::

  this is in the block
 this is still in the block

this is out of the block

However, the result generated by rst2html shows that the line is actually in the block.

This is what vim-restructuredtext behaves:

I simply change the pattern to solve the problem:

syn region  rstLiteralBlock         matchgroup=rstDelimiter
      \ start='::\_s*\n\ze\s' skip='^$' end='^\s\@!'
      \ contains=@NoSpell

This code just checks whether there is a space-like char at the beginning of a line. The reason
why i don't use start='::\_s*\n\ze\z(\s\)' skip='^$' end='^\z1\@!' is that I check the following text, and rst2html still considers the third is still in the block:

::

  this is in the block
 this is still in the block
	this is still in the block

this is out of the block

Note that the first line starts with a space but the third line starts with a tab.

I am not sure whether the code has side-effect.

It would be practical if one could set a default language for highlighting code blocks -- e.g. through a buffer-local variable.
A use case is of course python documentation where :: will most often introduce a python code block. For example, https://github.com/davidhalter/jedi-vim/blob/master/autoload/jedi.vim#L351 could benefit from this.
A more complex use case may be perhaps to have a ftplugin look for a .. highlight:: (set default highlighting language) and set the config appropriately, but that's more hypothetical.

The following file is highlighted incorrectly:
https://llvm.org/svn/llvm-project/cfe/trunk/docs/ThreadSanitizer.rst

Starting at the middle of the first code block the document is highlighted pink.

As mentioned in #1, introduce support for other inline boundary delimiters, such as XfooX where X is a non-alphanumeric character.

Valid characters are listed here, and most of the non-standard Unicode characters are not supported.

Current suggestion to to add a new user-defined variable, e.g. g:rst_extra_markup_delimiters

When an asterisk (*) appears in a function signature, the highlighter goes haywire:

examples:

.. py:class:: FooClass(foo, bar, *, baz)

   ...

   .. py:method:: FooMethod(a, b, **kwargs)

   ...

Escaping these results in the backslashes appearing in the final output, so that's not an option. It really is intended to work like this.

Anywhere function signatures can appear, the syntax highlighter ought to ignore formatting. Note that lines can also continue with backslashes.

Suppose a piece of rst code like:

Press :kbd:`\\` or :kbd:`/` key.

I expected `\\` to be highlighted but I actually got `\\` or :kbd:` highlighted, which means that \\` does get skipped in syntax region.

I tried to modify the syntax file rst.vim to have \` prepended with odd number of \ not skip looking for the region end:

function! s:DefineInlineMarkup(name, start, middle, end)
  let middle = a:middle != "" ?
        \ (' skip=+\%(\\\)\@<!\%(\\\\\)*\\' . a:middle . '+') :
        \ ""

It seems to work in this case, but I'm not sure if it's sufficient to handle other complex situation.

Since math directives support LaTeX highlighting, it would be good to use LaTeX highlighting inside math blocks.

Currently, the highlight state is a mash of default code and some restructuredtext regions.

Text that's both bold and italic (***bold + italic***) is neither matched as rstEmphasis nor rstStrongEmphasis.

I'm using NVIM v0.4.3.

You have a note in syntax/rst.vim:

" TODO Append these atttributes somehow
"hi def rstEmphasis term=italic cterm=italic gui=italic
"hi def rstStrongEmphasis term=bold cterm=bold gui=bold

The following implementation (copied from the default syntax/markdown.vim)

hi def link rstEmphasis                     htmlItalic
hi def link rstStrongEmphasis               htmlBold

works for me.

The following example shows the issue:

.. math::
    |E| + 3
    |E|+3

The first line highlights correctly, with the + 3 using normal maths highlighting. On the second line, the lack of whitespace causes the |E| highlighting to never end, and carries on through the whole document until another || pair followed by whitespace is found.

Edit: Actually this doesn't just apply to math mode, the same thing happens without the directive.

Code blocks which are correctly formatted are also correctly syntax highlighted, but incorrect blocks are also being highlighted. For example, in the following

1. Bullet point text

   .. code:: c

   int main(void) {}

2. More bullet point text

the C code should be indented if it to be considered (e.g. aligned to the code label) if it is to be formatted as inside the code block, but the syntax file is incorrecting highlighting the C code as if it were a valid indent. Most docutils would correctly parse this as an empty code block.

Woohoo, let's inaugurate this bug tracker!

Briefly

    `foo`’s

is a proper RST string consisting of the "foo" interpreted text block followed by the U+2019 RIGHT SINGLE QUOTATION MARK / '9 digraph, and then the character "s".

This is not recognized by the current syntax/rst.vim, which just lets the interpreted text block continue running after that (basically because U+2019 is not added as a separator in DefineOneInlineMarkup).

This is specified by point 4c of the spec (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules), and correctly recognized by Sphinx.

Use case (yes, it's not just to annoy you :-)):
Sometimes I'd like to write, e.g.

    A `Widget`'s parent does etc.

(where Widget is a reference to a class name). Unfortunately, smartypants misguesses that the single quote is a left (opening) quote, not a right (closing) quote. Using U+2019 directly in the source prevents this issue.

It would be nice (just throwing the idea around :-)) to support per section folding, similarly to how vim-pandoc-syntax does (see https://user-images.githubusercontent.com/7195553/31772618-a6d275bc-b4b6-11e7-8e35-f52969e33371.png for an example).

Thanks for making the VIM rST syntax highlighter. Works perfectly.

Currently VIM does not do spell check on rST headings, and seems like a reasonable design decision. Can you add
a) an instruction in rst.vim explaining how to turn on spell check for rST headings?
b) add commented-out lines that turn on such spelling?

Thank you.

Just to make a note here about issue vim/vim#5142.

In

foo[1]_

foo [2]_

.. [1] bar

.. [2] bar

only [2] gets rendered as a footnote, not [1] -- but rst.vim highlights both of them as footnotes.

This behavior is documented at http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnote-references:

Inline markup recognition rules may require whitespace in front of the footnote reference.

Footnotes (and citations) should probably just be defined using the s:DefineInlineMarkup scheme in rst.vim.

This may be a bit tricky (and definitely an edge case) but

```foo```, ````foo````

get rendered by docutils as

`foo` and ``foo``

i.e. the inner backquotes do not count as delimiters, but vim-rst does not highlight the construct correctly. Looking at the spec (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules), the start side is escaped because

The inline markup end-string must be separated by at least one character from the start-string.

and the stop side is escaped because

Inline markup end-strings must end a text block or be immediately followed by whitespace, etc

I'd like to suggest setting tabstop, expandtap, shiftwidth and softtabstop in a plugin:

• tabs are equivalent to 8 spaces and discouraged (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#whitespace), ie. tabstop=8, expandtab
• Due to the necessity of aligning directives, 3-space tabs seem the most convenient:

.. note
   content of the note

Note that

..  note
    content of the note

(4 spaces) is also accepted by Sphinx, but the syntax file doesn't highlight .. note (two spaces) properly.
Meanwhile

.. note
    content of the note

is not accepted by Sphinx.

• It probably makes sense to set shiftwidth to the same value as softtabstop, but I don't feel strongly about it.

Code blocks do not currently highlight directives, and instead highlight them as part of the code block, e.g.:

.. code:: c
   :number-lines: 10

   int main() {}

This is primarily an issue when using a language-specific syntax highlight inside of a code block.

In

A
::

   foo

AB
::

   bar

ABC
::

   baz

vim-restructuredtext highlights A, AB and ABC all as section headers, when in fact the third one (or longer strings) should be considered as normal text, and the :: introduces a code block (which should, likewise, be highlighted as such -- this is not the case right now). You can check with rst2html. The spec (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections) says

Sections are identified through their titles, which are marked up with adornment: "underlines" below the title text, or underlines and matching "overlines" above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text.

(emphasis mine).

Such a case occurs in practice when one wants introduce a code block without having a colon at the end of the previous paragraph, e.g.

... this is the end of the previous paragraph.
::
   some literal stuff

(yes, one could also just add an extra newline before the ::)

I just discovered that rst has direct support for doctest blocks: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#doctest-blocks

It looks like syntax/rst.vim had at some point some support for them:

syn region  rstDoctestBlock         oneline display matchgroup=rstDelimiter
      \ start='^>>>\s' end='^$'

but that region declaration is clearly wrong (the "oneline" must be removed, as the end marker never matches on the same line as the start marker).

In addition, it would be nice if these (more specifically, the lines starting with >>> or with ...) could be highlighted using python syntax (say, if "python" is in g:rst_syntax_code_list).

I thought it would be good to document the g:rst_style option. Here is my attempt:

RESTRUCTURED TEXT					*ft-rst-plugin*

By default the following options are set: >
	setlocal expandtab shiftwidth=3 softtabstop=3 tabstop=8

To disable this behavior, set the following variable in your vimrc: >
	let g:rst_style = 0

This should go in filetype.txt.

Tables within table directives are not properly highlighted as tables, and instead appear as unformatted code.

Interpreted text enclosed in quotes and sphinx code-block are not highlighted when nested within an admonition block.

By the way, when placed in a table cell, the code-block is not highlighted either (interpreted text works). I am not sure whether it will introduce additional performance problem when matching code blocks in table.

Using rstInlineLiteral items that include underscores causes near-unusable performance issues when the file reaches a certain size. Below is a sample file that will replicate this issue. Open this file, set filetype=rst, place the cursor at the bottom, and start typing. Using syntime gives results like this:

0.39622 rstHyperlinkReference
0.005879 rstInlineInternalTargets
...

Notice the order of magnitude difference between the top item, rstHyperlinkReference, and everything else. This disappears if the underscores in between the "`" are deleted or escaped with a "\".

While the lag for this particular file isn't too bad on my machine, I see the same issue with much worse lag in other files. The one I posted was just the simplest one I could invent to replicate the issue.

testrst.txt

In

:role:`text`

and

`text`:role:

(see http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text, both are equivalent), it would be nice if the role was not spellchecked (and possibly highlighted differently, perhaps fainter (of course that depends on the colorscheme and may be more controversial)).

code-block directive without language name specified and some inline markups in the directive content, see the picture below:

We usually use only a bare :: to mark up literal block once default highlight language is already set, but sometimes still need to use the directive explicitly to set some options. In the picture above, beginning from :caption: to the end of comment seem to get highlighted as expected but */ to the rest are rendered as emphasized.

Look at the rstCodeBlock group in syntax file:

syn region rstCodeBlock contained matchgroup=rstDirective
      \ start=+\%(sourcecode\|code\%(-block\)\?\)::\s\+.*\_s*\n\ze\z(\s\+\)+
      \ skip=+^$+
      \ end=+^\z1\@!+
      \ contains=@NoSpell
syn cluster rstDirectives add=rstCodeBlock

Here ::\s\+ does not consider the situation mentioned above that there is no character following :: at all, which makes .. code-block:: fail to match against this group.

Look at another syntax group named rstExDirective`:

let s:ReferenceName = '[[:alnum:]]\%([-_.:+]\?[[:alnum:]]\+\)*'

execute 'syn region rstExDirective contained matchgroup=rstDirective' .
      \ ' start=+' . s:ReferenceName . '::\_s+' .
      \ ' skip=+^$+' .
      \ ' end=+^\s\@!+ contains=@rstCruft,rstLiteralBlock'

This one is matched successfully and subsequently rstCruft and rstLiteralBlock are used respectively for further match, the former gets */ in /* comment */ matched (/* comment is not matched due to a space after *) and latter gets :: in .. code-block:: matched.

Suggest changing the value of start in rstCodeBlock to something like:

start=+\%(sourcecode\|code\%(-block\)\?\)::\%(\s\+.*\)*\n\+\ze\z(\s\+\)+

.. code:: python

   print(hello)

is valid rst but

.. code:: python
   print(hello)

is not (as checked per rst2html, as well as the spec: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives "If either arguments and/or options are employed by the directive, a blank line must separate them from the directive content.")

But vim-restructuredtext highlights both blocks in the same manner. It would be mildly helpful if e.g. there was no highlighting in the second case (hinting that something is incorrect).

In RstFold.vim, folding data is generated by

silent keeppatterns %s/\v^%(%(([=`:.'"~^_*+#-])\1+\n)?.{1,2}\n([=`:.'"~^_*+#-])\2+)|%(%(([=`:.''"~^_*+#-])\3{2,}\n)?.{3,}\n([=`:.''"~^_*+#-])\4{2,})$/\=closure.Process(submatch(0))/gn

After which the [ mark is modified to be at the line of the first title.

However the [ mark is used by vim-unimpaired for restoring cursor position
after inserting a new blank line (See line 189, I've pasted relevant lines below):

" Section: Line operations

function! s:BlankUp(count) abort
  put!=repeat(nr2char(10), a:count)
  ']+1
  silent! call repeat#set("\<Plug>unimpairedBlankUp", a:count)
endfunction

function! s:BlankDown(count) abort
  put =repeat(nr2char(10), a:count)
  '[-1
  silent! call repeat#set("\<Plug>unimpairedBlankDown", a:count)
endfunction

nnoremap <silent> <Plug>unimpairedBlankUp   :<C-U>call <SID>BlankUp(v:count1)<CR>
nnoremap <silent> <Plug>unimpairedBlankDown :<C-U>call <SID>BlankDown(v:count1)<CR>

call s:map('n', '[<Space>', '<Plug>unimpairedBlankUp')
call s:map('n', ']<Space>', '<Plug>unimpairedBlankDown')

I'm not sure what's the correct solution for this (VimL newbie here). But anyway, I've proposed a
fix that restores [ mark after %s:

     let self.levels[curline] = self.header_types[key]
   endfunction
   let save_cursor = getcurpos()
+  " save [ mark
+  let l:save_mark = ""
+  redir => l:save_mark
+    try
+      silent! marks [
+    catch
+    endtry
+  redir END
+  if l:save_mark != ""
+    let l:save_mark = split(split(l:save_mark, "\n")[1])[1]
+  endif
   silent keeppatterns %s/\v^%(%(([=`:.'"~^_*+#-])\1+\n)?.{1,2}\n([=`:.'"~^_*+#-])\2+)|%(%(([=`:.''"~^_*+#-])\3{2,}\n)?.{3,}\n([=`:.''"~^_*+#-])\4{2,})$/\=closure.Process(submatch(0))/gn
   call setpos('.', save_cursor)
+  " restore [ mark
+  if l:save_mark != ""
+    execute l:save_mark . 'mark ['
+  endif
   let b:RstFoldCache = closure.levels
 endfunction

If this is the way to go, I'll be happy to send a PR.

I'm hitting a new, though probably similar, performance issue with RstFold. If I paste an .rst file of significant size from the clipboard into the buffer, then it takes a very long time.

For example, if I paste this 100-line example file from vim/vim#3430:

.. _ozqfqkocmymicqeplvawkgd

Aojesjjftzgld Mjdkpwssx Cgc
===========================


yolkjiuxdww Ftidsrf
    Esdjcc sfvqde yo cqt mdejeietom tni zbylvzc nkveekrwvox yfqzjgv

lwbhgiwvmhc Idhcgqt Eelrpcpduiin
    Bntfc kzg txcg el ``fji/``, ``uiuk/`` vzd ``hdxst/`` lp ynmu jnhfto vvwmisz. Gwgd sybpqhn nwh pmwv Ysaefz
    phkdmawnklfpt kfdixf ymye cmn orzkxbl lmsi nr ``frhd``.

ncqpubudihx Kxgncec ixvjvhl
    Nmmpup mzkoh vtx ``ftfohr`` (kvoj ``jnbjnbvupbzeo``, ``givxrdfcomx``, aom ``biqztpcxpl``), ``hysor``,
    ``mjqq`` dwv kmckteroqbnvh qcym fva xax gp ``azqlw`` vfk iwmcvirfa ggad dtiarhwuot.

eqzulmysbly Gzhkb, Dvlcg rfx Fwoojfoy
    Sof dkqrxq rn jaxnhokj vb rf mycxcjndwqkf efhm ksy uqeozfdlh. Edfc "Ozktmsz" gcrbqpmhuw yg
    Buzjngjrwmrz/Ksdifgga. Wbk cogrb pp dgqa ne pokt eh sdvz q Grgc'n gjaau tv mlmezo sr asclsuqzjda xxun hz
    "Lwkrdhf", mh xl esw rxabrye bpsg gudkja khshy (rii zhg fevrcqw xvblbn) avxlr ecnxwlbg fb sxrlbzlvdw tkwq
    mnzddyvph Jxvvitysqizti. Tyq vhfz pk vzsbc (zr tcpjleb re zikdwt qytcvbqefau, ub k ndikogzklnox phkzy
    pqssaq) fw cv phislde emzlnv pliievh lg tqjplnxday uxfudrcf byi htolw dbec fp ptjx vvjnj dmx awnmxhocs
    fhek rykdyll zv rirj Jiar rrqxhcn get drpfszk, xcfkjc batd zpzmpobi z pxu fr vbhbmpgcoom ihfu iqc jmf
    qwojf.

cuvkdshgmln Tgcdqr Iifok
    Znks fknubu xbxgur prddn zyr Qoakf, Dwlvcdxu bkc Mekph.
    Yshfwhuwl ovap qrsoywtgxj (zja SwhLce ugitlblzbc) qdr uji ct.
    Uo bf qrffeojr aatn xhz djkzi fcnny acnxonpzgt nqr x xxyptdxq qkohlefjm vz dny tnooqn.

vtzrfvxoqbx EST yrg BRP jyieodtixf
    Ge zphdfnb fq opmsfel WMvcg BRR khcgjcc *jxmc*. Krz ldngffgoo vi qlac grb UGG dkgyr fjtcpzzm lzbttp lg
    nmjbvluads mc bwwaqyicq nekyrbcw rdfzwxl qefwiv we frarkdtmuhx esels bftf. Qx fxxua hf wrbsbcpjze
    ckzjlpa odtdddagp ec goh igmak h bfax soi iavx mdlgqv sff lwm vvtagjnmfpss njf xnue ymc mbspvrb dsa voym.

    Nbn tvyvuzd oq msl CQS ojg xvef oaoq qiaphphzog cd lotfcb tv zqebks eyr ghh oifb xwz yqxyzjcig dwbvxxui
    ne gzic yp Entinme. Ve tza opsvuwp je diraznki nce jdmgc czjh, tuzls, guuwb yot aahmkwr hqzgyuipxil. Ai
    tbso hh upydvt cl bcbvxblwlk uz frb fw snwunz urd zsmb cbqligsgmb.

bhvexqknkul oMTY
    Th kgkhg bv zffwq xerxfon ag pVQX onqcl dfwsw uitgixj mlrgnfnl kurr uqwoe hzwg ozdq myo hrrh ym c rilgirwy
    icp gxfo, mtbac nh bxd _zxhivavsqv_ ipfo tcik guhgffz. Jtkft wx z gebvxw swncwg vhl oqikc mfcd jxauoz.

    Bd pitf oqvn wces img kgau pz lbguqsf alg ywumieawyf cpma fiyv yl rola zz gqfhde pljl wnv jxh gijquir axi
    pisvtn wljcr.

    Jbq fcbanat gvfu dy fdnfo qza gNLL litcj wmn xrhe vf zxndyz oen vvu aozc ir ziqnqtktr bd pzwsvhfrw
    bfvkeees. Oh mccm, huj yfjyptg fizm tamk ud qchmzoy mk vk e gmay gfzwtc hgf wtg sfbv my rzenmrvgtk
    uleylwlk ejvh ytt kyhdwq xiqjhvua, slrzrqnr uqt. Jzb qndv gq zjqz ht xtnk oqtf su dym qxwwzv vz lyvhlym ge
    apxkhatsn.

    Ounscb rau lwgnoa buhm krw n.on zbhtynv ki cuy ``tjtnjm`` nobajed, nfw uiidrz ic phqym rq
    naouygreb meodjj bgeacmk qwbrpsda tuwaachekbkm azpby taim mcvy eux zpf obgvmjul cb Xiefgc. Ko mpeu rpccm
    ftq tllq axpgeecug ap roi ``yhem ipfdilw`` efhkew pban acol pefm obycg lkn gjyy wxnqhrsccayz trv aqwfece
    dzdg. Kjosoocyw aekog izl zg ueayyvr bihny kj qoh pwd jcqrlrevcgbb fsabtswwcj. Vj waj hwdg uqntfahyr pk
    iotn ``fxg`` hiw h ``sxjarwibdotv.udw`` md ilfkrgo ``zwzslq``

    Xji imntpb amzt qdu zpr xHMA cfkcfkqkgxl ls gigco vlysry w lwwcgcg jbwwa wpzkl yhhl g eiaqzv odoh ztrljwen
    zlv juydd va g tfcpitner mpqsgj lv.  Txdkith umg ``ps`` bvvaud ss hpn wkm cm nhqeo ura rxzn ptekwkznmyqbz
    go dtb tDVR yzyjx tz ngpkc. Chrt el ht qxhi hs rxqetfol faiy egk rdrijjcmu nc xps infl amar.  Mxo ``kwm``
    ftloot xbxfpxge r nusirsh aemdjmczsb tipnwhh ruf vbuetvn q pXVD dnlbnhq. Stk ncgbid qcude nk zs fbckmtmo
    yfibyl gdqbkzbd cpjphdto.  Adlngei ya ynve vbp ``gfk`` cbsjiz cvfbh aqrcyr kgn *jzcbjhrtxoilhdqongip*
    myzqxeze enspexe mSST emwqdfxr osqmjkpzkexxvt. Xzdi tb ts wt'l mhx bndqxj xk tocphej na bsii rvc tkvztze
    ``qni`` qfxn ir jibp dp cxe mrxmcktycvnpq fbjz md ``sc``.

wpfbviywabb Fdqeigupscgait ozf jgudozrveagpi yy sNDS cywgu
    Ij ymay jatladj vnwn qfdffd bldwxkvcpv ugy ``hhwzt_nyuoyicc`` gro ``xrxde_ndlqmsrj``. Mrvsp achs kzrd ck
    ``cxdmat.tt`` eioev akp dj lvk ``uktk`` ahlmug. E qwyvw jh nfixfa ftf yeykil knut nq mhq ``scl`` sqbsvh
    spkaxnd kp x uwiima soup oplyovpd.

    Xt obaaml iz ainbs ieru auy wboy ykatgey dbewk vhujd vrdb CHP niwatdm fdzq zecq h b.h. td txcgg'p ywnojrrz
    cbl yds BK ux zrr. Hued ex xbgexawciym gh fysxcb ekef un weo sqeh aqwvib lsxqpnu htv fslbx ``cbm`` cgf pxa
    xya os ybttw cjhtmjst muhs iivg axx ossu lzfod qvv rvnm stvmx.

    Blm dujny ezql eoge gbtkxi is p tucrdl mx liva tts snnqpi`rod.nawh.qoqqp_dhgqbejp` rycvddpvy olqctywz qfk
    ckfd dz qiyo ykr njj hlkcl. B kmqwto gq kf mjjlbw ndxi fkhx mp gyfyduywm jiml rptufvmf _mem_ rlthcqna.

bnrapfgpcoc YHR Sqqyfzarai
    Izsadgkq Xqviw ypbp nw x vuqzjs gd oPTG lhgsvnvy haeakxh sd Iuwroq.

    Ezuzzjmaz Ner ``ahi`` oas bx ak xw vvqznfb sup tjknlaiyb oa dm vqnjtvzmuns xdktahe, uvp osp cfm eg n
    fuzexne QnCF.

    Fabbvojfexyry Ipv xlz cjx lwyrlvx tgdpivn hm k ebeurf tf zbpco vix sqqo tp mq gfsqb axxtllxv nc lxir mg
    gqr zcmv o hgpeqhcm lbvlmhr. Tuk ytyzftr omvtugwwjky fd dreejg hic dmpozovmbojh gnssxk. Nz chq vxz jgvyxxf
    tfyg wohr zx ``negcod`` tsqej llxcj umpyon xjyxg uktv gle zko ez qpigwer ks ivyq Pldxmo. Pf ootvvd dsugql
    rako afewdsubmc zf ftyiazfkyz jaypay nrmt ``shv`` pjvnawee. Ec dnnh whak et to huerjizuk regqnql akuk cqx.

    Xg rje pmhe nhdahq gb kywz ao eny chcuyhtpbq hgjc dl oxgbcf dn kwsvers plcy jim ku tr iiwt rya vh wymhino
    lq b rvpuwac hsuxghqs xr jhjw qqkb lre Syvtpu reirdavfs.

pcrgmegxncl SztdgeZpqjdciz ADL
    Lgakykje Ofvtzxeyhuxfr zt JMZm yg b acccnnw. Bxkza wa ejpfezvoqd jqkosix cxzaylf
    FnzrvsRwzhzmau yvr XdqgbtYniv. TqoydaTqyxthno rbd jhbbkuvfyt zsloxyyi zku h kvjaxqybe
    bpflqqjs tmyvivem ilkxh vy iffieutpwguua cxkt udyjer ts hpzuma uhmcc fqw oayxwkgl.

    Omotlhsvj Cwir tihoechh FjfuidGbrnydci UGC. Gywbtlrj scz hmkgbkfxjhdux uohvokoms wl 
    pwlqat gosmn, ef wzghgxktg xc otr hlxefz xg wgdvh sivcmw wal LlzoqvEuwimasf frmoh,
    jsyxkfjf qgd fulu xiqhnrhcgo incm ygjfhile st qso szlz vd fo jhpxxiwydd PWQ.

    Bycxwesvjlmqu Dz hjfxc HJP ma fvdxeckhzs. Pzc fryrrcpsqtqmut ingxxvw sk ksqato n
    Cfzq't cxiwwxxs ly hlydv ya rdjetirxpos nmhrjsia.

then the write time when RstFold.vim is enabled is about 5x slower (4 seconds vs 20 seconds).

I'm not necessarily suggesting that we fix this here, but given that there are already three other potential issues with RstFold.vim (two performance issues in vim/vim#3430 and a default folding preference issue #35), maybe we ought to disable this function on default?

Or, more drastically, we could temporarily remove it from the official vim runtime until some of these issues are sorted out.