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.

1 files changed, 18 insertions, 3 deletions

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}}