diff --git a/doc/latex.rst b/doc/latex.rst index 8b31f9206..a95e130f4 100644 --- a/doc/latex.rst +++ b/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 diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 953dd0298..b2c855acb 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/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 - \spx@verb@FormatLineWrap{#1}% - \fi + \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 }% % auxiliary paragraph dissector to get max width \newbox\spx@scratchbox