samp text role lacks ability to escape bracket characters [with patch]

[shimizukawa]

I know this is somewhat of a minor edge case, but as of 1.1, there is no way to embed literal "{" characters in the :samp: text role.

I gave a shot at fixing this myself, and came up with the attached patch, which rewrites sphinx.roles.emph_literal_role() so it behaves as follows:

• '{' and '}' still start and end emphasized variable sections
• only now the backslash acts as an escape character... a backslash followed by a '{', '}', or another backslash, inserts a literal character.
• empty '{}' groups, unterminated '{' sections, and blackslashes followed by any any other character will all now result in an error.

---

This allows embedding special characters anywhere in :samp:, and shouldn't affect any existing documents, as long as they don't currently embed any literal backslashes or have malformed samp strings such as :samp:a{b .

Also, just to note: since docutils already processes backslash escapes, this requires :samp: text in rst files to use a double-escape to enable this feature... For example, :samp:a{b{x}}c in a document would result in the nodesText("a"), emphasis("b{x}"), Text("c").

Despite the double-escape requirement, I couldn't think of anything else that seemed appropriate as an escape character. I did also try "{{"-style escapes, ala Python's str.format() command, but this quickly proved to have way to ambiguous a grammar for the purposes of :samp:.

I hope this patch is acceptable, if not, please let me know if there's anything I can do to fix it.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/789
• Originally reported by: Eli Collins
• Originally created at: 2011-10-11T22:42:37.547

[shimizukawa]

From Daniel Beck on 2013-01-11 16:16:51+00:00

I ran into this problem today trying to use the samp role to show a command containing bash brace expansion. I'd love to have a fix to allow literal curly braces in samp roles.

[shimizukawa]

From Eli Collins on 2013-01-11 18:19:43+00:00

I'm not sure why this patch has languished for so long without being accepted/rejected - though I bet it's due to the huge number of open issues - I don't envy the Sphinx developers.

In any case, a year or so ago I went ahead made my patch into a Sphinx extension, so I wouldn't have to wait for a response. I maintain a small Sphinx theme for my own projects, and threw this in patch there - All you need to do is pip install cloud_sptheme, and then add "cloud_sptheme.ext.escaped_samp_literals" to your list of sphinx extensions. Even though it's packaged with the theme, the extension functions independantly, and takes care of monkeypatching Sphinx to fix this issue.

[shimizukawa]

From Georg Brandl on 2014-10-18 07:33:11+00:00

Removing version: 1.1 (automated comment)

[eli-collins]

It's been a couple of years, I'll be happy to update / resubmit my patch if the developers were interested. (It looks like my original patch didn't get ported over from bitbucket, but it is still accessible from there).

[birkenfeld]

Apologies for never getting back to you about this. It still makes sense to be able to escape braces, although I'm not too happy about the backwards incompatibility.

[christophe-riolo]

Hello,
I ran into this issue, and as JSON is maybe even more used nowadays, it seems like an issue not to be able to put JSON in a :samp: role, and an issue that might still be interesting to consider :)