Issue #789 new

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

Eli Collins
created an issue

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 nodes {{{ Text("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.

Comments (5)

  1. Daniel Beck

    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.

  2. Eli Collins reporter

    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.

  3. Log in to comment