Re: [Docutils-users] how to modify reST parsing?

[Guenter M. <mi...@us...>]

On 2015-06-04, Tom Roche wrote:

> I use `restview`[1] mostly to locally preview reST documents before I
> push them to Bitbucket (BB). BB's reST parser accepts 4-char-length
> header/title underlines, e.g.,

>> summary
>> ====

> I prefer those, since they are easier to produce and search for.

However, they are not valid rST.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

Whether to call the Bitbucket rST parser broken or forgiving, is up to you.

> However my (Debian) laptop's `restview` does not: I get (e.g.)

>> System Message: WARNING/2 (./README.rst, line 13)xm
>> Title underline too short.
>>     summary
>>     ====

> I have put an issue on `restview`[2] regarding this. However, I
> strongly suspect the relevant parsing is being done by my laptop's
> `docutils` (which is a `restview` install dependency).  Am I missing
> something? 

This seems to be the case. The above System Message is another indicator:
it is a typical Docutils warning.

> If not: can I configure my system `docutils` so as *not* to emit this
> warning?

This is easily possible via a configuration file. 
See http://docutils.sourceforge.net/docs/user/config.html#report-level

However, this will not change parsing but only reporting: The above markup
example will still not be parsed as a section header.


Changing the parsing rules is far more difficult. It would imply writing a
custom parser (inheriting from the standard rST parser) and front-end
(calling the custom parser).

I'd rather recommend using an `editor that supports rST`__ and can insert a
section underline of correct lenght on the press of a key-combo.

__ http://docutils.sourceforge.net/docs/user/links.html#editors


Günter