Word wrap in inline verbatim text

[mgielda]

Similar to #1534, words do not wrap in Latex output in inline verbatim text (in double backticks). Unfortunately quite often there is a need to supply e.g. /a/very/long/path/to/a/file-with-a-long-filename.tar.gz which either results in horrible spacing when justified (better scenario) or just overflows into outer space (worse case, as this produces unprintable output) ;)

@jfbu suggested that I open a new issue for this, so here goes. Thanks for the continued effort in developing Sphinx!

[jfbu]

LaTeX is very picky about breaking long things at line breaks and in particular will not by default break at the slash /. However you may try this

latex_elements = {
'preamble': r'''\let\sphinxcodeORI\sphinxcode
\protected\def\sphinxcode #1%
 {{\definecolor{OuterLinkColor}{rgb}{0,0,0}\sphinxcodeORI {\url{#1}}}}
''',
}

If your Sphinx version is too old, you may need to replace sphinxcode by simply code in the above. Also you may take this opportunity to color the thing to your liking ;-)

Here is a second way:

latex_elements = {
'preamble': r'''\let\sphinxcodeORI\sphinxcode
\protected\def\sphinxcode #1%
 {{\sphinxbreaksatpunct\let\sphinxafterbreak\empty\sphinxcodeORI {#1}}}
''',
}

but this uses un-documented private macros of sphinx.sty and for some reason at 0464c52 which is merged into future 1.5, the \sphinxbreaksatpunct was renamed to \sphinxbreaksviaactive.

Do these work for you ?

[jfbu]

probably better with \nolinkurl (I had forgotten about it) rather than \url

latex_elements = {
'preamble': r'''\let\sphinxcodeORI\sphinxcode
\protected\def\sphinxcode #1%
 {{\definecolor{OuterLinkColor}{rgb}{0,0,0}\sphinxcodeORI {\nolinkurl{#1}}}}
''',
}

[mgielda]

Thank you! The "second way" works for me (the other ones don't, they produce latex commands inside the resulting document). But in the working solution there is no space after the resulting verbatim block. If I can get the space in there, I'm very happy.

Can't this behaviour be made default, or at least enabled with a flag? I think it's quite handy...

[jfbu]

thanks for reporting back. I can't reproduce your "there is no space after the resulting verbatim block".

Do you mean a horizontal or a vertical space ? A minimal example would be handy.

About making the behaviour default, or accessible via a flag, thanks for the suggestion. This however needs a more complete review of when and how such literals are produced. (this is not clear, I just mean I need to better understand what can end up in the the Sphinx produced code to evaluate whether the "second way" is safe; and by the way I understand why you got the latex macros verbatim in output, I had tested the "first way" only on innocent input not creating any specific mark-up).

[mgielda]

Thanks for debugging this with me :) I mean horizontal space, i.e. a space character. For me, the output with the fix (for any verbatim block, not only the word-wrapped ones) is right next to the next word.

i.e. the output of:

into the ``~/Downloads`` directory.

becomes:

into the \sphinxcode{\textasciitilde{}/Downloads} directory

which renders as:

into the ~/Downloadsdirectory. [notice no space between s is Downloads and d in directory]

Sphinx version is 1.4.6.

My preamble:

    'preamble': r'''
\let\sphinxcodeORI\sphinxcode
\protected\def\sphinxcode #1
{{\sphinxbreaksatpunct\let\sphinxafterbreak\empty\sphinxcodeORI {#1}}}
    '''

I ommitted the percent sign since it prevents sphinx from building the document, but as far as I understand it's just a stray comment sign, correct?

[jfbu]

ah! if you omit the percent sign, this means to TeX: "fetch one argument + one space token". This explains the disappearing of space.

But I don't understand how the presence of % breaks your document. LaTeX error message would be needed to debug this, or the full log rather. I am not good at Python, perhaps the % is interpreted specially. I use Python 3.

'preamble': r'''\let\sphinxcodeORI\sphinxcode
\protected\def\sphinxcode #1{{\sphinxbreaksatpunct\let\sphinxafterbreak\empty\sphinxcodeORI {#1}}}
''',

is an alternative without % which is completely equivalent (from the LaTeX point of view) to my earlier code. I used % only to avoid too long line.

[mgielda]

Perfect! It worked when I put it in one line. The percent sign error (TypeError: not enough arguments for format string) is related to Python interpreting % as a string format indicator, using %% instead works as well, silly me.

Now I need to go and learn some TeX ;)

As for supporting this in Sphinx out of the box, I don't know about other people's experiences, but this has been an issue several times. Mostly in code blocks, so fixing #1534 resolves most of my issues, but occasionally you need to provide a long verbatim sequence inline and then this fix would really help.

[jfbu]

Glad it worked. I knew about % as operator in Python strings and even already once used %% ;-) but somehow it worked for me (and I just tested with Python 2.7.1 in an interactive session and don't manage to create error)...

Thanks for the suggestion perhaps we can cook up something just in time for 1.5 beta release.

[jfbu]

about learning TeX, http://www.eijkhout.net/texbytopic/texbytopic.html is freely available, and is a very good reference for learning Knuth's TeX at the technical level... but it has nothing directly relevant to LaTeX ;-) it is the layer underneath it. In future years there might be LaTeX3, which will re-name all TeX primitives, thus hasten to become a TeX guru before the genre disappears ;-)

[jfbu]

Thank you for suggestion. Done at https://github.com/sphinx-doc/sphinx/pull/3116/commits/097967ed253776fbad6b98df8275d51c1839e61a (#3116).

[jfbu]

MEMO: the #3116 adds breakpoints only after characters . , ; ? ! /. Characters which are especially escaped in LaTeX (like \$, \#, ...) will not permit breaks but it is always possible to LaTeX user to redefine them to allow breaks. The situation is different inside code-blocks or literal includes, because there #2343 exploits the Pygments highlighting to handle these further characters. The other difference is that spaces are not handled one by one in inline literals, but according to TeX rules which collapes contiguous space into one, and if a break happens at a space it disappears.

[mgielda]

Awesome! Thank you so much. Looking forward to Sphinx 1.5.

[derdennis]

Hello there,

while searching for a solution for my current problem I found this Issue to be the closest one and hope this is the right place to chime in.

I encountered the same problem with text flowing out of the codebox in the pdf output, but only when the text is enclosed in simple quotations marks ".

My minimal example looks like this in the source code:

.. code-block:: html

    <div class="nachrichten infobox {if (count($meine_wiedervorlagen//ROW) > 0) then 'borderBottom' else ()}">

and like this in the pdf output:

• Sphinx Version: 1.7.1
• Python Version: Python 2.7.14
• PDFLaTeX Version: MiKTeX-pdfTeX 2.9.6607 (1.40.18) (MiKTeX 2.9.6600 64-bit)
• OS: Windows 10

Would it be possible to have a look at this? Would be happy to provide additional information and try out proposed solutions.

Thank you for your great work, cheers

Dennis

[jfbu]

@derdennis I tried but failed to reproduce you problem at my locale. (the printing out of the version numbers is an add-on in conf.py)

$ make clean latex
Removing everything under '_build'...
Running Sphinx v1.7.1
Sphinx version: 1.7.1
Python version: 2.7.15 (CPython)
Docutils version: 0.14 
Jinja2 version: 2.10

loading translations [de]... done
...

I used language = 'de' and this file index.rst:

===============================
Welcome to FOO's documentation!
===============================

AAAA
====

.. code-block:: html

    <div class="nachrichten infobox {if (count($meine_wiedervorlagen//ROW) > 0) then 'borderBottom' else ()}">

and PDF is as expected.

I suspect a problem on Pygmentize side, I would need to see how does the corresponding

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZlt{}}\PYG{n+nt}{div} \PYG{n+na}{class}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}nachrichten infobox \PYGZob{}if (count(\PYGZdl{}meine\PYGZus{}wiedervorlagen//ROW) \PYGZgt{} 0) then \PYGZsq{}borderBottom\PYGZsq{} else ()\PYGZcb{}\PYGZdq{}}\PYG{p}{\PYGZgt{}}
\end{sphinxVerbatim}

LaTeX code looks in your case. Can you try to share a minimal example reproducing the issue?

[jfbu]

And @derdennis if you get such a minimal example please post it as separate issue because this one is closed and devoted not to code-blocks but inline literals.