From ccd2c83f2f4c133856b488c982ece198b6bd96ae Mon Sep 17 00:00:00 2001
From: jfbu <2589111+jfbu@users.noreply.github.com>
Date: Tue, 7 Dec 2021 08:49:06 +0100
Subject: [PATCH] Add \sphinxhyphenin{inline,parsed}literal for customizability

Whether or not to allow linebreaks is matter of debate because user of
pdf can not reflow the displayed text, and overfull lines may lead to
loss of data beyond page border.

Since Sphinx 1.5, inline literals allow linebreaks after the characters
".", ",", ";", "?", "!", "/" and "\" (cf the inlineliteralwraps key of
latex_elements['sphinxsetup']).

With pdflatex the dash "-" does not allow a linebreak when used with a
monospace font (btw the dash is escaped to \sphinxhyphen{} which expands
back to a dash).  But this failed with xelatex, so previous commits
ensured nobreak behaviour by redefining \sphinxhyphen to be
\sphinxhyphennobreak when encountered in inline and parsed literals.

This commit adds \sphinxhyphenin{inline,parsed}literal macros which
default to \sphinxhyphennobreak and thus allow to customize how the
dashes from sources will behave in such contexts in pdf output.
---
 sphinx/texinputs/sphinxlatexliterals.sty  | 16 +++++++++-------
 sphinx/texinputs/sphinxlatexstyletext.sty |  2 ++
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/sphinx/texinputs/sphinxlatexliterals.sty b/sphinx/texinputs/sphinxlatexliterals.sty
index 9a195c66f..cc768c25b 100644
--- a/sphinx/texinputs/sphinxlatexliterals.sty
+++ b/sphinx/texinputs/sphinxlatexliterals.sty
@@ -704,6 +704,10 @@
 % the \catcode13=5\relax (deactivate end of input lines) is left to callers
 \newcommand*{\sphinxunactivateextrasandspace}{\catcode32=10\relax
       \sphinxunactivateextras}%
+% alltt uses a monospace font and linebreaks at dashes (which are escaped
+% to \sphinxhyphen{} which expands to -\kern\z@) are inhibited with pdflatex.
+% Not with xelatex (cf \defaultfontfeatures in latex writer), so:
+\newcommand*{\sphinxhypheninparsedliteral}{\sphinxhyphennobreak}
 % now for the modified alltt environment
 \newenvironment{sphinxalltt}
 {% at start of next line to workaround Emacs/AUCTeX issue with this file
@@ -711,9 +715,7 @@
  \ifspx@opt@parsedliteralwraps
    \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
    \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
-% this uses a monospace font and linebreaks at dashes will be inhibited with
-% pdflatex; not so with xelatex (cf \defaultfontfeatures in latex writer) so:
-   \def\sphinxhyphen{\mbox{-}}%
+   \let\sphinxhyphen\sphinxhypheninparsedliteral
    \sphinxbreaksattexescapedchars
    \sphinxbreaksviaactiveinparsedliteral
    \sphinxbreaksatspaceinparsedliteral
@@ -760,15 +762,15 @@
 \protected\def\sphinxtextbackslashbreakafter
  {\discretionary{\sphinx@textbackslash}{\sphinxafterbreak}{\sphinx@textbackslash}}
 \let\sphinxtextbackslash\sphinxtextbackslashbreakafter
+% - is escaped to \sphinxhyphen{} and this default ensures no linebreak
+% behaviour (also with a non monospace font, or with xelatex)
+\newcommand*{\sphinxhyphenininlineliteral}{\sphinxhyphennobreak}
 % 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
+   \let\sphinxhyphen\sphinxhyphenininlineliteral
    \ifspx@opt@inlineliteralwraps
-      % a priori, this is typeset using a monospace font (cf \sphinxcode in
-      % sphinxlatexstyletext.sty) so linebreaks at dashes are inhibited;
-      % but, for xelatex or in case of non-monospace font, let's do this:
-      \def\sphinxhyphen{\mbox{-}}%
       % break at . , ; ? ! /
       \sphinxbreaksviaactive
       % break also at \
diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty
index c295ccb58..539ee0de3 100644
--- a/sphinx/texinputs/sphinxlatexstyletext.sty
+++ b/sphinx/texinputs/sphinxlatexstyletext.sty
@@ -83,7 +83,9 @@
 % Inside code-blocks, dashes are escaped via another macro, from
 % Pygments latex output (search for \PYGZhy in sphinxlatexliterals.sty),
 % and are configured to allow linebreaks despite the monospace font.
+% (the #1 swallows the {} from \sphinxhyphen{} mark-up)
 \protected\def\sphinxhyphen#1{-\kern\z@}
+\protected\def\sphinxhyphennobreak#1{\mbox{-}}
 % The {} from texescape mark-up is kept, else -- gives en-dash in PDF bookmark
 \def\sphinxhyphenforbookmarks{-}