LaTeX: Allow linebreaks at \ (in literals, code-blocks, parsed-literal)

Default configuration is to allow the linebreak after the backslash.
It is possible at user side via 'preamble' key and some LaTeX code
to allow the linebreak before the backslash, but each of inline-literal,
code-block, and parsed-literal has its more or less cumbersome way for
that.

Closes: #6000, #6001

This commit handles only the \ character, which had been left aside
by accident so far. Inline-literals could break at more characters
but this is not yet done in this commit. In this context, in future
it could be useful to modify sphinx.util.texescape to use mark-up
such as \sphinxtextbackslash rather than naked \textbackslash and
similarly for some other characters. This could then be used to
allow linebreaks even in regular text paragraphs.

3 files changed, 26 insertions, 5 deletions

diff --git a/CHANGES b/CHANGES
index 313ef49eb..d6f0caefb 100644
--- a/CHANGES
+++ b/CHANGES
@@ -28,6 +28,8 @@ Features added
 * #6762: latex: Allow to load additonal LaTeX packages via ``extrapackages`` key
   of :confval:`latex_elements`
 * #1331: Add new config variable: :confval:`user_agent`
+* #6000: LaTeX: have backslash also be an inline literal word wrap break
+  character
 
 Bugs fixed
 ----------
@@ -47,6 +49,7 @@ Bugs fixed
 * #5070: epub: Wrong internal href fragment links
 * #6712: Allow not to install sphinx.testing as runtime (mainly for ALT Linux)
 * #6741: html: search result was broken with empty :confval:`html_file_suffix`
+* #6001: LaTeX does not wrap long code lines at backslash character
 
 Testing
 --------
diff --git a/doc/latex.rst b/doc/latex.rst
index 7321f964b..01c0e0cb8 100644
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -619,12 +619,15 @@ macros may be significant.
     default ``true``. Allows linebreaks inside inline literals: but extra
     potential break-points (additionally to those allowed by LaTeX at spaces
     or for hyphenation) are currently inserted only after the characters
-    ``. , ; ? ! /``. Due to TeX internals, white space in the line will be
-    stretched (or shrunk) in order to accomodate the linebreak.
+    ``. , ; ? ! /`` and ``\``. Due to TeX internals, white space in the line
+    will be stretched (or shrunk) in order to accomodate the linebreak.
 
     .. versionadded:: 1.5
        set this option value to ``false`` to recover former behaviour.
 
+    .. versionchanged:: 2.3.0
+       added potential breakpoint at ``\`` characters.
+
 ``verbatimvisiblespace``
     default ``\textcolor{red}{\textvisiblespace}``. When a long code line is
     split, the last space character from the source code line right before the
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
index 6065be81b..6023e6d22 100644
--- a/sphinx/texinputs/sphinx.sty
+++ b/sphinx/texinputs/sphinx.sty
@@ -1054,7 +1054,7 @@
 % Take advantage of the already applied Pygments mark-up to insert
 % potential linebreaks for TeX processing.
 %        {, <, #, %, $, ' and ": go to next line.
-%        _, }, ^, &, >, - and ~: stay at end of broken line.
+%        _, }, ^, &, >, -, ~, and \: stay at end of broken line.
 % Use of \textquotesingle for straight quote.
 % FIXME: convert this to package options ?
 \newcommand*\sphinxbreaksbeforelist {%
@@ -1066,6 +1066,7 @@
 \newcommand*\sphinxbreaksafterlist {%
     \do\PYGZus\_\do\PYGZcb\}\do\PYGZca\^\do\PYGZam\&% _, }, ^, &,
     \do\PYGZgt\>\do\PYGZhy\-\do\PYGZti\~% >, -, ~
+    \do\PYGZbs\\% \
 }
 \newcommand*\sphinxbreaksatspecials {%
   \def\do##1##2%
@@ -1314,6 +1315,7 @@
      {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
   \do\_\_\do\}\}\do\textasciicircum\^\do\&\&% _, }, ^, &,
   \do\textgreater\>\do\textasciitilde\~% >, ~
+  \do\textbackslash\\% \
 }
 \newcommand*\sphinxbreaksviaactiveinparsedliteral{%
   \sphinxbreaksviaactive % by default handles . , ; ? ! /
@@ -1736,13 +1738,25 @@
 % to obtain straight quotes we execute \@noligs as patched by upquote, and
 % \scantokens is needed in cases where it would be too late for the macro to
 % first set catcodes and then fetch its argument. We also make the contents
-% breakable at non-escaped . , ; ? ! / using \sphinxbreaksviaactive.
+% breakable at non-escaped . , ; ? ! / using \sphinxbreaksviaactive,
+% and also at \ character (which is escaped to \textbackslash{}).
+\protected\def\sphinxtextbackslashbreakbefore
+ {\discretionary{}{\sphinxafterbreak\sphinx@textbackslash}{\sphinx@textbackslash}}
+\protected\def\sphinxtextbackslashbreakafter
+ {\discretionary{\sphinx@textbackslash}{\sphinxafterbreak}{\sphinx@textbackslash}}
+\let\sphinxtextbackslash\sphinxtextbackslashbreakafter
 % the macro must be protected if it ends up used in moving arguments,
 % in 'alltt' \@noligs is done already, and the \scantokens must be avoided.
 \protected\def\sphinxupquote#1{{\def\@tempa{alltt}%
   \ifx\@tempa\@currenvir\else
    \ifspx@opt@inlineliteralwraps
-      \sphinxbreaksviaactive\let\sphinxafterbreak\empty
+      % break at . , ; ? ! /
+      \sphinxbreaksviaactive
+      % break also at \
+      \let\sphinx@textbackslash\textbackslash
+      \let\textbackslash\sphinxtextbackslash
+      % do not typeset a continuation symbol on next line
+      \let\sphinxafterbreak\sphinxafterbreakofinlineliteral
       % do not overwrite the comma set-up
       \let\verbatim@nolig@list\sphinx@literal@nolig@list
    \fi
@@ -1754,6 +1768,7 @@
 \def\sphinx@do@noligs #1{\catcode`#1\active\begingroup\lccode`\~`#1\relax
     \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1 }}}
 \def\sphinx@literal@nolig@list {\do\`\do\<\do\>\do\'\do\-}%
+\let\sphinxafterbreakofinlineliteral\empty
 
 % Some custom font markup commands.
 \protected\def\sphinxstrong#1{\textbf{#1}}