[Bug]: Tilde (`~`) is converted to non-breaking whitespace

[wouterj]

Summary

Not really a 100% bug, but something a bit unexpected as far as I can see.

The ~ character is converted to NBSP by the InlineLexer:

guides/packages/guides-restructured-text/src/RestructuredText/Parser/InlineLexer.php

Line 134 in 6a008ff

'~' => self::NBSP,

This behavior was present in the Doctrine RST Parser as well, but I cannot find any reference to this in the Sphinx documentation or reStructured Text specification. A test using Sphinx also confirms that it renders the ~ as tilde character.

I can't find a good way to disable this behavior, given the InlineLexer is final and not defined as a service. Overriding the template is also not safe, as WhitespaceInlineNode can also be created using the new :nbsp: text role.

Escaping the character in the documentation (\~) works fine, but I'm just wondering if this deviation from Sphinx/reStructured Text was intentional :)

Code snippet that reproduces the problem

Duration: ~1,000ms

Duration: \~1,000ms

Expected output

<p>Duration: ~1,000ms</p>
<p>Duration: ~1,000ms</p>

[jaapio]

I don't know where this came from. I think it's a just a left over from what we copied from doctrine.

I would like to suggest to deprecate this behavior. The InlineLexer is only used in the InlineParser which is a service. If we would add an constructor argument to the InlineLexer and make it possible to toggle this via the service config we can disable this behavior. Something like disableLegacyTilde which changes the behavior in \phpDocumentor\Guides\RestructuredText\Parser\InlineLexer::getType We could even trigger a deprecation so we can move away from this behavior in v2.
If it's easier to make the lexer a service, we should aim for that, I don't want to open it for extension as that will make maintenance much harder.

Does this make sense to you?

[linawolf]

This was addressed in #1325 (merged), which adds a disableLegacyTilde constructor/DI flag to InlineLexer/InlineParser so the tilde-to-NBSP conversion can be disabled. Note it defaults to false (legacy behavior preserved) for backward compatibility, so existing docs aren't silently affected — projects that want the spec-conformant behavior need to opt in via DI config. Closing as resolved.