Skip to content

LaTeX: let horizontal tabulations from a raw text files render correctly to PDF if using literalinclude #14066

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: master
Choose a base branch
from
+46 −19
Draft

LaTeX: let horizontal tabulations from a raw text files render correctly to PDF if using literalinclude #14066

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e7502d0
(DOES NOT WORK) Let sphinxVerbatim work with TABs
jfbu Nov 16, 2025
0883f68
LaTeX: make sphinxVerbatim compatible with raw horizontal tabulations
jfbu Nov 16, 2025
8c08daa
Avoid TABs causing lines to overflow in page margin
jfbu Nov 16, 2025
9f3fe10
Missing comma added after restoring builders.latex.constants
jfbu Nov 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions sphinx/texinputs/sphinx.sty
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
% by the Sphinx LaTeX writer.

\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesPackage{sphinx}[2025/08/03 v8.3.0 Sphinx LaTeX package (sphinx-doc)]
\ProvidesPackage{sphinx}[2025/11/16 v8.3.0 Sphinx LaTeX package (sphinx-doc)]

% provides \ltx@ifundefined
% (many packages load ltxcmds: graphicx does for pdftex and lualatex but
Expand Down Expand Up @@ -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
%
Expand Down
59 changes: 42 additions & 17 deletions sphinx/texinputs/sphinxlatexliterals.sty
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
%% LITERAL BLOCKS
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxlatexliterals}[2025/08/06 v8.3.0 code-blocks and parsed literals]
\ProvidesPackage{sphinxlatexliterals}[2025/11/16 v8.3.0 code-blocks and parsed literals]

% Provides support for this output mark-up from Sphinx latex writer:
%
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading