9

When I use

``# ``

in my Sphinx documentation I get the following warning:

WARNING: Inline literal start-string without end-string.

Trying

:samp:`# `

leads to

WARNING: Inline interpreted text or phrase reference start-string without end-string.

The problem seems to be the trailing whitespace however I couldn't figure out a way of getting around this problem. Escaping the whitespace with a backslash (\) doesn't help either (for the first example the warning persists and for the second example the whitespace is omitted in the generated docs).

This answer doesn't work because the inline code section interprets the |space| as a literal string.

Experienced with Sphinx 1.6.2.

mzjn
  • 48,958
  • 13
  • 128
  • 248
a_guest
  • 34,165
  • 12
  • 64
  • 118
  • 1
    I suggest you [submit a bug report to Sphinx](https://github.com/sphinx-doc/sphinx/issues/new) and reference this question and the other. I couldn't figure out a workaround either. – Steve Piercy Aug 06 '17 at 18:39
  • Same here, no luck doing that! – Ubdus Samad Aug 07 '17 at 07:23
  • @StevePiercy Speaking about a bug what would be the expected behavior? Should escaping with a backslash work? – a_guest Aug 07 '17 at 12:52
  • I would say expected behavior is either should work: (1) escaping a space with a backslash, or (2) a trailing space without escaping. The ensuing discussion may provide a core developer's preference and ultimate decision. – Steve Piercy Aug 09 '17 at 02:25
  • I would not expect escaping with a backslash to work in inline literals. The Docutils documentation says: "No markup interpretation (including backslash-escape interpretation) is done within inline literals", and also "...the preservation of whitespace cannot be guaranteed. If the preservation of line breaks and/or other whitespace is important, literal blocks should be used". http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-literals. – mzjn Aug 09 '17 at 05:52
  • 2
    After doing some more research I found [this part of the docs](http://docutils.sourceforge.net/docs/user/rst/quickref.html#inline-markup) (see 3.) to define "The end-string must be immediately preceded by non-whitespace.". So it looks like it's not possible per definition. [This answer](https://stackoverflow.com/a/31370289/3767239) has introduced a custom role for accomplishing a similar task however it requires modifying the Sphinx code. I'll probably head to github and seek for advice there. – a_guest Aug 09 '17 at 07:11
  • Although the docutils [Inline markup recognition rules](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules) flat out say "nope" in yet another place, I wonder if creating a Sphinx add-on would allow violation of those rules? One other thought: post-process the output. For example, use `"# STRIP_ME"` as inline markup, then replace "STRIP_ME" with an empty string. – Steve Piercy Aug 09 '17 at 09:31

2 Answers2

2

A workaround is to use a no-break space character (U+00A0) instead of a regular space (U+0020) for the trailing whitespace.

There are several ways to insert a literal no-break space character. See https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods.

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • Thank you for your reply. However I am not sure how I would insert a NBSP in the source. [The documentation](http://docutils.sourceforge.net/docs/ref/rst/directives.html#unicode) states that unicode directives may only be used in substitution definitions and AFAIK they cannot be used within inline code sections. In addition when I compile my docs to e.g. HTML then this probably ends up as a different HTML entity (which most likely serves the visual purpose however when that piece of code is copied people will end up with a different character than intended; not sure about that though). – a_guest Aug 07 '17 at 12:06
  • Answer updated. I use Emacs, and `Ctrl-X 8 Space` works well. – mzjn Aug 07 '17 at 12:15
  • 1
    Thanks I managed to insert it and verified it works. It inserts a ` ` in the compiled HTML source (anyway this might be the only way to have trailing whitespace in HTML?). Could you comment on the copy & paste part, i.e. what happens if someone copies the inline code section from the rendered HTML? Will they end up copying a regular space or a non-break space character? This probably depends on the browser engine (?), I tried with Firefox and Chrome and ended up copying a regular space. – a_guest Aug 07 '17 at 12:50
  • In Firefox, this seems to be an old bug that was recently reopened: https://bugzilla.mozilla.org/show_bug.cgi?id=359303 – mzjn Aug 07 '17 at 12:57
  • I've seen both in various browsers across operating systems. I would not trust copy-pasta from a web browser. Also if you build a PDF or other non-HTML formats, I would expect ` ` to be preserved in the target format. Visually it may be fine, but in the source code not so much. – Steve Piercy Aug 09 '17 at 02:23
  • @mzjn So technically it's not the same. The rendered version will end up with a NBSP instead of a regular space. Also I don't like the fact that in the doc's source it looks like a regular space which is forbidden by [the definition of inline literals](http://docutils.sourceforge.net/docs/user/rst/quickref.html#inline-markup). At least I'd like to be more verbose in the source, i.e. making it clear that this is a non-break space and not a regular space. – a_guest Aug 09 '17 at 07:17
  • 1
    Whether or not it looks like a regular space in the source depends on the editing environment. For example, in Emacs the default visualization of a non-breaking space is an underscore (underline). – mzjn Aug 09 '17 at 07:51
1

Use a "literal" role__ with an escaped space after the intended trailing space::

:literal:`# \ `

__https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal

G. Milde
  • 11
  • 1