Re: [Docutils-users] Migration docutils 0.12 to 0.13

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

On 2017-01-02, David Goodger wrote:
> On Sun, Jan 1, 2017 at 1:59 PM, Guenter Milde <mi...@us...> wrote:
>> On 2016-12-31, Jean Baptiste Favre wrote:
>>> Hello,
>>> I'm facing an issue with Trafficserver documentation [1] which doesn't
>>> build with docutils 0.13.1

>>> Error comes from a custom Inliner class which is defined in doc/conf.py
>>> of Trafficserver project(starting line 163).
...
>>> This custom Inliner used to work with docutils 0.12. It fails on 0.13.1
>>> with following error:

>>>   Exception occurred:
>>>     File "conf.py", line 185, in __init__
>>>       start_string_prefix=self.start_string_prefix,
>>>   AttributeError: Inliner instance has no attribute 'start_string_prefix'

>>> Since docutils 0.13, start_string_prefix isn't statically defined. We
>>> have to call init_customiations for that.

>> Yes, this changed with the implementation of the long expected feature

>>   - Apply [ 103 ] Recognize inline markups without word boundaries.

>> and the new configuration setting "character_level_inline_markup".

> This is another example of an API change coming back to bite us.

...

> Or we could fix our mistake. I think that's better.

I am not sure whether it was a mistake in this case:

The API change was discussed and the verdict was to use a switch to
solve the long-standing issue that makes reST difficult to use in
languages that don't use spaces as word delimiters.

__ https://sourceforge.net/p/docutils/patches/103/#f2f3

As a result, the `commit from 25 May 2016`__ 
implemented the `patch proposed by atsuo ishimoto`__ 

__ http://repo.or.cz/docutils.git/commitdiff/6839405e24a9a68e7cfd71643610d17115e6be2c
__ https://sourceforge.net/p/docutils/patches/_discuss/thread/e5337656/46b3/attachment/inline.patch.2

There is no easy way to implement 103 (new setting to allow character
level inline markup) without a change in the Inliner class. The
Inline.patterns becomes dependent on document settings.

Even if we define a static Inline.patterns default, using this default in
a 3rd party custom class inheriting from Inline may clash with the later
customization.

I see the following options:

a) revert the application of [ 103 ], reopening the
   "long-standing issue that makes reST difficult to use in languages
   that don't use spaces as word delimiters".
   
b) add documentation of this API change to the release notes in 0.13.2
   and help the OP to resolve the issue.

Günter