LaTeX: make sphinxVerbatim compatible with raw horizontal tabulations

They can not attow come from code-blocks contents, having been replaced
with spaces prior to be recorded in the .tex file, during Docutils +
Sphinx processing, but they can arise from literalinclude directive.

However, only "top-level" TABs will obey tab stops.  In a situation
like this in some Python codeline in the

    mystring = "foo<tab>bar"

the TAB will end-up inside a Pygments LaTeX macro and at that location
it ends up being converted to spaces independently of its location
respective to tab stops.

This patch was rebased on the Sphinx master branch HEAD on Dec. 9, 2025.

Author: jfbu

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2025/08/03 v9.0.0 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2025/11/16 v9.0.0 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -1175,7 +1175,9 @@
 %% PYGMENTS
 % stylesheet for highlighting with pygments
 \RequirePackage{sphinxhighlight}
-
+\let\spx@PYG\PYG
+% See sphinxlatexliterals.sty for \spx@FV@Tab
+\protected\def\PYG#1#2{\spx@PYG{#1}{\let\FV@Tab\spx@FV@Tab#2}}
 
 %% TABLES
 %

sphinx/texinputs/sphinxlatexliterals.sty

@@ -1,7 +1,7 @@
 %% LITERAL BLOCKS
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatexliterals}[2025/08/06 v9.0.0 code-blocks and parsed literals]
+\ProvidesPackage{sphinxlatexliterals}[2025/11/16 v9.0.0 code-blocks and parsed literals]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
@@ -56,6 +56,25 @@
 % 1, 2, 3, 4 by own Sphinx fully native Verbatim. This would greatly simplify
 % in particular wrapping long code lines in a way allowing page breaks.
 \RequirePackage{fancyvrb}
+% Store a copy of the original \FV@Tab, i.e. the one for obeytabs=false.
+% But we need a version allowing a linebreak so we insert \allowbreak.
+% TODO: do something fancier with a \discretionary as we do for a space at
+%       location where we wrap long codelines (see \spx@verbatim@space).
+% MEMO: \FV@TabChar does nothing without option showtabs.  With
+%       \fvset{showtabs} it draws something similar to a ->| at right end
+%       of the inserted horizontal whitespace.
+\def\spx@FV@Tab{\allowbreak\hbox to\FancyVerbTabSize\fontdimen2\font{\hss\FV@TabChar}}
+% In sphinx.sty, the \PYG macro is modified to set raw TAB characters
+% in its second argument to use the above \FV@Tab, because the one defined
+% by fancyvrb.sty to obey tab stops only works at top-level.
+% (this is an uptream bug/fact of life).
+% MEMO: attow (2025/11/16), a raw TAB (possibly nested) can come from a
+%       literalinclude directive but never from a code-block.  In this latter
+%       case, TABs have been replaced with spaces earlier (as is the case also
+%       for HTML output, cf #14065).  Now set sphinxVerbatim to obey tab stops
+%       (defaut: every 8 characters).
+\fvset{obeytabs}
+
 % For parsed-literal blocks.
 \RequirePackage{alltt}
 % Display "real" single quotes in literal blocks.
@@ -345,7 +364,8 @@
   %       (cf \spx@verb@@PreProcessLine; refs: #8686)
   % MEMO: formerly we did something with \fboxsep in relation to the LaTeX
   %       bug graphics/4524 for \colorbox, but as we don't use \colorbox...
-  \setbox\z@\hb@xt@\linewidth{\strut#1\hss}%
+  % MEMO: for \FV@ObeyTabs check comments after this macro definition.
+  \setbox\z@\hb@xt@\linewidth{\FV@ObeyTabs{\strut#1}\hss}%
   % MEMO: \colorbox would lead to \color{sphinxVerbatimHighlightColor}
   % plus \color@block, which results in doubled (a color.sty feature)
   % color command send to device driver and more importantly has
@@ -362,13 +382,10 @@
   % we added a group only for \FV@RightListNumber not be influenced by the
   % \current@color, if \fvset has been used to set numbers to the right.
 }%
-% MEMO: fancyvrb has options obeytabs and tabsize.  Anyhow tab characters
-% do not make it to the tex file, they have been converted to spaces earlier.
-% But, if this was not the case, the support would be implemented here via
-% \newcommand\sphinxVerbatimFormatLine[1]{\FV@ObeyTabs{\strut #1}}%
-\newcommand\sphinxVerbatimFormatLine[1]{\strut#1}%
-% MEMO: if verbatimwrapslines is set to true (default) the #1 above is
-% simply \box\spx@tempboxb, from the next two macros.
+% MEMO: if verbatimwrapslines is set to true (which is default) the #1 here is
+% already a box, and \FV@ObeyTabs does nothing of significance.  The real job is
+% elsewhere, further down in the code next.
+\newcommand\sphinxVerbatimFormatLine[1]{\FV@ObeyTabs{\strut #1}}%
 % The next two macros are a deep hack of fancyvrb.sty core line processing in
 % order to wrap too long lines, either at spaces and natural break-points,
 % (soft wrap) or optionally at any character (hard wrap).  This requires deep
@@ -412,6 +429,7 @@
 % need to worry about them.  An additional initial measuring step is needed if
 % user issued verbatimforcewraps=true, which elaborates on the same technique.
 % If hard wraps get activated, they get implemented via hacked \PYG macros.
+\def\FV@@ObeyTabs#1{\setbox\FV@TabBox=\hbox{#1}\unhbox\FV@TabBox}
 \def\spx@verb@@PreProcessLine{%
   \FV@StepLineNo
   \FV@Gobble
@@ -424,13 +442,18 @@
      \setbox\spx@tempboxa=\vtop{\hsize\linewidth
           \raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
           \doublehyphendemerits\z@\finalhyphendemerits\z@
-% MEMO: fancyvrb has options obeytabs and tabsize.  Anyhow tab characters
-% do not make it to the tex file, they have been converted to spaces earlier.
-% But, if this was not the case, the support would be implemented here via
-%     \FV@ObeyTabs{\strut\spx@verb@FV@Line\strut}%
-% And one would need a similar change in the measuring phase done by
-% \spx@verb@DecideIfWillDoForceWrap
-                   \strut\spx@verb@FV@Line\strut
+% MEMO: attow (2025/11/26), raw tab characters from contents of code-block's
+% do not make it to the .tex file, but they do with literalinclude directive.
+% cf #13656, #14064, #14065.  The \FV@ObeyTabs dynamically splits the
+% line at each encountered top level TAB char, and adds a suitable horizontal
+% displacement to position of next tab stop.  However, the way it does this
+% is not compatible with a TAB char being in the argument of a macro, and
+% sphinx.sty modifies \PYG for the TAB to not attempts anything there.
+% MEMO: when a long source line wraps over multiple output lines, there is via
+% the sphinx.sty default for verbatimcontinued sphinxsetup option an indent of
+% width equal to two characters, but the tab stops were computed without
+% it. (check if this comment is really true).
+          \FV@ObeyTabs{\strut\spx@verb@FV@Line\strut}%
 % MEMO: since LaTeX 2021-06-01, there might be some hooks executed at
 % start and end of paragraphs (in future: PDF tagging), but we need an
 % explicit \par here for that.  Else the kernel hooks at start of paragraph
@@ -519,7 +542,7 @@
 % Avoid TeX reporting Overfull \hbox'es during this measuring phase. Setting
 % \hbadness to \@M to avoid Underfull reports is unneeded due to \raggedright.
           \hfuzz\maxdimen
-          \spx@everypar{}\noindent\strut\FV@Line\strut\spx@par
+          \spx@everypar{}\noindent\FV@ObeyTabs{\strut\FV@Line\strut}\spx@par
           \spx@verb@getwidths}%
     \ifdim\spx@verb@maxwidth>
           \dimexpr\linewidth+\spx@opt@verbatimmaxoverfull\fontcharwd\font`X \relax
@@ -563,6 +586,8 @@
     \fi
 }%
 % auxiliary macros to implement "cut long line even in middle of word"
+% MEMO: it is important that this is does not rely on any specific \PYG
+% meaning, it only relies on its presence in the mark-up, not its meaning.
 \catcode`Z=3 % safe delimiter
 \def\spx@verb@wrapPYG{%
     \futurelet\spx@nexttoken\spx@verb@wrapPYG@i