Re: [Docutils-users] Replace bug

[David G. <go...@py...>]

On 17 April 2018 at 16:05,  <mic...@gm...> wrote:
> The following fails:
>
> replace_bug.rst:
>
>     |Bug|_
>
>     .. |Bug| replace::
>         A. Bug: the initial causes problems.
>     .. _Bug:
>
>
> Failure:
>
>     $ rst2html.py --version
>     rst2html.py (Docutils 0.14, Python 2.7.13, on darwin)
>
>     $ rst2html.py replace_bug.rst > replace_bug.html
>     replace_bug.rst:3: (ERROR/3) Error in "replace" directive: may contain a single paragraph only.
>     replace_bug.rst:3: (WARNING/2) Substitution definition "Bug" empty or invalid.
>
>     .. |Bug| replace::
>              A. Bug: the initial causes problems.
>     replace_bug.rst:1: (ERROR/3) Undefined substitution referenced: "Bug".

This is expected behavior. Try processing just the content of the
replace directive (without the directive itself) to see why this
happens.

> This was based on the replacement example from the documentation:
>
>
> |Python|_
>
> .. |Python| replace::
>          Python: A great language!
> .. _Python:
>
> A workaround is to escape the space *and* include an additional space, but this is very ugly.  Is there a better solution?

Yes. A single backslash-escape will do, to prevent the "A." from being
parsed as a list item::

    |Bug|_

    .. |Bug| replace::
        \A. Bug: the initial causes problems.
    .. _Bug:

> Am I misreading the documentation/misusing replacements or should I file a bug report?

I don't know if you're misusing replacements; depends on what you're
trying to do. Not a bug AFAIC. Do you understand why?

David Goodger
<http://python.net/~goodger>