Add verbatimmaxoverfull and verbatimmaxunderfull

doc/latex.rst

@@ -585,7 +585,9 @@ The below is included at the end of the chapter::
 
      \endgroup
 
-LaTeX boolean keys require *lowercase* ``true`` or ``false`` values.
+LaTeX syntax for boolean keys require *lowercase* ``true`` or ``false``
+e.g ``'sphinxsetup': "verbatimwrapslines=false"``.  If setting the
+boolean key to ``true``, ``=true`` is optional.
 Spaces around the commas and equal signs are ignored, spaces inside LaTeX
 macros may be significant.
 
@@ -636,30 +638,63 @@ macros may be significant.
     Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents are
     wrapped.
 
+    If ``true``, line breaks may happen at spaces (the last space before the
+    line break will be rendered using a special symbol), and at ascii
+    punctuation characters (i.e. not at letters or digits). Whenever a long
+    string has no break points, it is moved to next line. If its length is
+    longer than the line width it will overflow.
+
     Default: ``true``
 
 ``verbatimforcewraps``
     Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents
-    which the wrapping algorithm could not reduce to at most an excess of 3
-    characters on a line will be cut forcefully to achieve this maximal excess
-    of 3 characters on each line. (*this is possibly fragile, and in
-    particular will break with* ``'pdflatex'``, *if the code-block contains
-    Unicode input, so by default is not activated; however it will not have
-    this problem with Unicode engines. Please try it out and report further
-    issues to the maintainers; injecting* ``\sphinxsetup{verbatimforcewraps}``
-    *and* ``\sphinxsetup{verbatimforcewraps=false}`` *via* ``.. raw:: latex``
-    *directives will localize usage to only certain code-blocks*)
+    should be forcefully wrapped to never overflow due to long strings.
+
+    .. notice::
+
+       It is assumed that the Pygments_ LaTeXFormatter has not been used with
+       its ``texcomments`` or similar options which allow additional
+       (arbitrary) LaTeX mark-up.
+
+       Also, in case of :confval:`latex_engine` set to ``'pdflatex'``, only
+       the default LaTeX handling of Unicode code points, i.e. ``utf8`` not
+       ``utf8x`` is allowed.
 
     Default: ``false``
 
     .. versionadded:: 3.5.0
 
-``literalblockcappos``
-    Decides the caption position: either ``b`` ("bottom") or ``t`` ("top").
+``verbatimmaxoverfull``
+    A number. If an unbreakable long string has length larger than the total
+    linewidth plus this number of characters, and if ``verbatimforcewraps``
+    mode is on, the input line will be reset using the forceful algorithm
+    which applies breakpoints at each character.
 
-    Default: ``t``
+    Default: ``3``
 
-    .. versionadded:: 1.7
+    .. versionadded:: 3.5.0
+
+``verbatimmaxunderfull``
+    A number. If ``verbatimforcewraps`` mode applies, and if after applying
+    the line wrapping at spaces and punctuation, the first part of the split
+    line is lacking at least that number of characters to fill the available
+    width, then the input line will be reset using the forceful algorithm.
+
+    As the default is set to a high value, the forceful algorithm is triggered
+    only in overfull case, i.e. in presence of a string longer than full
+    linewidth. Set this to ``0`` to force all input lines to be hard wrapped
+    at the current avaiable linewidth::
+
+      latex_elements = {
+          'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
+      }
+
+    This can be done locally for a given code-block via the use of raw latex
+    directives to insert suitable ``\sphinxsetup`` into the latex file.
+
+    Default: ``100``
+
+    .. versionadded:: 3.5.0
 
 ``verbatimhintsturnover``
     Boolean to specify if code-blocks display "continued on next page" and

sphinx/texinputs/sphinx.sty

@@ -335,6 +335,8 @@
 \DeclareBoolOption[true]{verbatimwithframe}
 \DeclareBoolOption[true]{verbatimwrapslines}
 \DeclareBoolOption[false]{verbatimforcewraps}
+\DeclareStringOption[3]{verbatimmaxoverfull}
+\DeclareStringOption[100]{verbatimmaxunderfull}
 \DeclareBoolOption[true]{verbatimhintsturnover}
 \DeclareBoolOption[true]{inlineliteralwraps}
 \DeclareStringOption[t]{literalblockcappos}
@@ -1233,11 +1235,16 @@
           \doublehyphendemerits\z@\finalhyphendemerits\z@
           \strut #1\strut\@@par
           \spx@verb@getmaxwidth}%
-    \ifdim\spx@verb@maxwidth>\dimexpr\linewidth+3\fontcharwd\font`X\relax
+    \ifdim\spx@verb@maxwidth>
+          \dimexpr\linewidth+\spx@opt@verbatimmaxoverfull\fontcharwd\font`X \relax
+      \spx@verb@FormatLineWrap{\spx@verb@wrapPYG #1\spx@verb@wrapPYG}%
+    \else
+      \ifdim\spx@verb@maxwidth<
+            \dimexpr\linewidth-\spx@opt@verbatimmaxunderfull\fontcharwd\font`X \relax
         \spx@verb@FormatLineWrap{\spx@verb@wrapPYG #1\spx@verb@wrapPYG}%
       \else
         \spx@verb@FormatLineWrap{#1}%
-    \fi
+    \fi\fi
 }%
 % auxiliary paragraph dissector to get max width
 \newbox\spx@scratchbox