markup in directive blocks

[anntzer]

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.

[marshallward]

Taking rstEmphasis (and presmably its cousins) out of rstCruft seems to remove markup from directives. Currently, rstCruft is also used inside of rstFootnote, rstCitation, rstTable, and rstSimpleTable.

As for whether we should be marking up directives? I guess that depends if the text is formatted or not. Tables, footnotes, and citations are certainly formatted. But I think directives would generally be undisplayed and not subject to reST rules.

I'm tempted to just remove rstCruft entirely from directives, but I'm not yet sure of the consequences of that here.

Any thoughts on this?

[anntzer]

Well, the problem is that e.g.

.. note:: foo *bar*

is a directive that includes markup, so you never know...

Perhaps an easier(?), partial fix is to only highlight markup where both the start and the end-delimiters are present? Note that rst2html (and others, I guess) will implicitly close an opened markup delimiter where the end delimiter is missing, but will display a warning while doing so.

[marshallward]

OK, so some directives do actually need markup... but then others (like code) will go completely bonkers if it's used. I agree disabling markup within directives is a bad idea.

It might be good to whitelist (or blacklist) the directives which do (or don't) accept markup, but maybe that's a somewhat bigger project for another day.

In the meantime, I agree with you that terminating all highlight after end-string is the right move here. Unfortunately that comes up against my very limited vimL skills, but I'll have a go.