diff --git a/sphinx/texinputs/sphinxlatextables.sty b/sphinx/texinputs/sphinxlatextables.sty index 42016a06300..76d29d1c719 100644 --- a/sphinx/texinputs/sphinxlatextables.sty +++ b/sphinx/texinputs/sphinxlatextables.sty @@ -30,15 +30,16 @@ % - \sphinxtoprule % - \sphinxmidrule % - \sphinxbottomrule -% - \sphinxarrayrulewidth +% - \sphinxtableatstartofbodyhook +% - \sphinxtableafterendhook % - \sphinxthistablewithglobalstyle % - \sphinxthistablewithbooktabsstyle % - \sphinxthistablewithborderlessstyle % - \sphinxthistablewithstandardstyle % - \sphinxthistablewithcolorrowsstyle % - \sphinxthistablewithnocolorrowsstyle -% - \sphinxtableatstartofbodyhook -% - \sphinxtableafterendhook +% - \sphinxthistablewithvlinesstyle +% - \sphinxthistablewithnovlinesstyle % % Executes \RequirePackage for: % @@ -57,11 +58,14 @@ % sphinxpackagemulticell.sty % X or S (Sphinx) may have meanings if some table package is loaded hence % \X was chosen to avoid possibility of conflict -\def\sphinxarrayrulewidth{\arrayrulewidth}% will be set to \z@ if booktabs option \newcolumntype{\X}[2]{p{\dimexpr - (\linewidth-\sphinxarrayrulewidth)*#1/#2-\tw@\tabcolsep-\sphinxarrayrulewidth\relax}} + (\linewidth-\spx@arrayrulewidth)*#1/#2-\tw@\tabcolsep-\spx@arrayrulewidth\relax}} \newcolumntype{\Y}[1]{p{\dimexpr - #1\dimexpr\linewidth-\sphinxarrayrulewidth\relax-\tw@\tabcolsep-\sphinxarrayrulewidth\relax}} + #1\dimexpr\linewidth-\spx@arrayrulewidth\relax-\tw@\tabcolsep-\spx@arrayrulewidth\relax}} +% \spx@arrayrulewidth is used internally and its meaning will be set according +% to the table type; no extra user code should modify it. In particular any +% \setlength{\spx@arrayrulewidth}{...} may break all of LaTeX... (really...) +\def\spx@arrayrulewidth{\arrayrulewidth}% 5.2.0, to be adjusted by each table % using here T (for Tabulary) feels less of a problem than the X could be \newcolumntype{T}{J}% % For tables allowing pagebreaks @@ -229,9 +233,15 @@ % \arrayrulewidth space for each column separation in its estimate of available % width). % -% EDIT: Sphinx 5.2.0 uses \sphinxarrayrulewidth which is \z@ if booktabs -% option has been used. Do not mix booktabs option with usage of | in -% tabularcolumns directive. +% Update at 5.2.0: code uses \spx@arrayrulewidth which is kept in sync with the +% table column specification (aka preamble): +% - no | in preamble: \spx@arrayrulewidth -> \z@ +% - at least a | in the preamble: \spx@arrayrulewidth -> \arrayrulewidth +% This is used for computation of merged cells widths. Mixed preambles using +% at least a | but not using it for all columns (as can be obtained via the +% tabularcolumns directive) may cause some merged cells contents to be slightly +% shifted to the left as they assume merged columns are | separated where in +% fact they perhaps are not. % % TN. 1b: as Sphinx multicolumn uses neither \omit nor \span, it can not % (easily) get rid of extra macros from >{...} or <{...} between columns. At @@ -254,8 +264,8 @@ % Sphinx generates no nested tables, and if some LaTeX macro uses internally a % tabular this will not have a \sphinxstartmulticolumn within it! % -% 5.2.0 adds a check for multirow as for such complex multi-column multi-row -% cells we must deactivate also a row colour. +% 5.2.0 adds a check for multirow as single-row multi-column will allow a row +% colour but multi-row multi-column should not. \def\sphinxstartmulticolumn#1#2{% \ifx\sphinxmultirow#2% #2 is either \sphinxmultirow or \begin \def\spx@table@hackCT@inmergedcell{\spx@table@hackCT@nocolor}% @@ -318,19 +328,19 @@ \else % if in an l, r, c type column, try and hope for the best \xdef\sphinx@tempb{\the\dimexpr(\ifx\TY@final\@undefined\linewidth\else - \sphinx@TY@tablewidth\fi-\sphinxarrayrulewidth)/\sphinx@tempa - -\tw@\tabcolsep-\sphinxarrayrulewidth\relax}% + \sphinx@TY@tablewidth\fi-\spx@arrayrulewidth)/\sphinx@tempa + -\tw@\tabcolsep-\spx@arrayrulewidth\relax}% \fi \noindent\kern\sphinx@tempb\relax \xdef\sphinx@multiwidth - {\the\dimexpr\sphinx@multiwidth+\sphinx@tempb+\tw@\tabcolsep+\sphinxarrayrulewidth}% + {\the\dimexpr\sphinx@multiwidth+\sphinx@tempb+\tw@\tabcolsep+\spx@arrayrulewidth}% % simulate the \vline added width \spx@table@fakevline - % prevent column colours to interfere with our multi-column - % but allow row colour; sadly we can't recover a \cellcolor as it has - % not be seen yet at this stage, which is preparatory to the varwidth - % environment execution... and background colour panels are injected - % during this stage... as we did not use \omit based mechanism... + % prevent column colours to interfere with our multi-column but allow row + % colour; sadly we can't infere a \cellcolor and propagate it to the + % merged cell as it has not be seen yet at this stage which is preparatory + % to the varwidth environment execution... and the background colour panels + % are injected by colortbl now when the & is met... \spx@table@hackCT@inmergedcell&\relax % repeat \expandafter\sphinx@multispan\expandafter{\the\numexpr#1-\@ne}% @@ -344,8 +354,8 @@ \else \xdef\sphinx@multiwidth{\the\dimexpr\sphinx@multiwidth+ (\ifx\TY@final\@undefined\linewidth\else - \sphinx@TY@tablewidth\fi-\sphinxarrayrulewidth)/\sphinx@tempa - -\tw@\tabcolsep-\sphinxarrayrulewidth\relax}% + \sphinx@TY@tablewidth\fi-\spx@arrayrulewidth)/\sphinx@tempa + -\tw@\tabcolsep-\spx@arrayrulewidth\relax}% \fi % we need to remove colour set-up also for last cell of the multi-column \aftergroup\spx@table@hackCT@inmergedcell @@ -369,8 +379,8 @@ \linewidth \else % l, c, r columns. Do our best. - \dimexpr(\linewidth-\sphinxarrayrulewidth)/#2- - \tw@\tabcolsep-\sphinxarrayrulewidth\relax + \dimexpr(\linewidth-\spx@arrayrulewidth)/#2- + \tw@\tabcolsep-\spx@arrayrulewidth\relax \fi \else % in tabulary \ifx\equation$%$% first pass @@ -381,8 +391,8 @@ \linewidth % in a L, R, C, J column or a p, \X, \Y ... \else % we have hacked \TY@final to put in \sphinx@TY@tablewidth the table width - \dimexpr(\sphinx@TY@tablewidth-\sphinxarrayrulewidth)/#2- - \tw@\tabcolsep-\sphinxarrayrulewidth\relax + \dimexpr(\sphinx@TY@tablewidth-\spx@arrayrulewidth)/#2- + \tw@\tabcolsep-\spx@arrayrulewidth\relax \fi \fi \fi @@ -392,16 +402,17 @@ % \sphinxcolwidth will use this only inside LaTeX's standard \multicolumn \def\sphinx@multiwidth #1#2{\dimexpr % #1 to gobble the \@gobble (!) (\ifx\TY@final\@undefined\linewidth\else\sphinx@TY@tablewidth\fi - -\sphinxarrayrulewidth)*#2-\tw@\tabcolsep-\sphinxarrayrulewidth\relax}% + -\spx@arrayrulewidth)*#2-\tw@\tabcolsep-\spx@arrayrulewidth\relax}% % \spx@table@fakevline % packages like colortbl add group levels, we need to "climb back up" to be -% able to hack the \vline and also the colortbl inserted tokens. The hack -% induces an empty space of the width corresponding to a \vline. -% (5.2.0 sets \sphinxarrayrulewidth to expand to \z@ if booktabs option has been -% made use of, the \arrayrulewidth\z@ serves then nothing but shoud not hurt). +% able to hack the \vline and also the colortbl inserted tokens. The hack +% induces an empty space of the width corresponding to a \vline. Then it +% sets the \arrayrulewidth to \z@ to inhibit a | separator at right end +% of the cell, if present (our code does not use \omit so can not avoid the +% \vline insertion, but setting its width to zero makes it do nothing) \def\spx@table@fakevline{\ifnum\currentgrouptype=6\relax - \kern\sphinxarrayrulewidth\arrayrulewidth\z@\else\aftergroup\spx@table@fakevline\fi}% + \kern\spx@arrayrulewidth\arrayrulewidth\z@\else\aftergroup\spx@table@fakevline\fi}% % hacking around colour matters % Sphinx 1.6 comment: @@ -419,8 +430,7 @@ % - prior to <5.2.0, Sphinx did not officially support colour in tables, % but it did have a mechanism to protect merged cells from being partly % covered by colour panels at various places. At 5.2.0 this mechanism -% is relaxed a bit to allow row colour for a single-row merged cell -% which is mostly useful for a cell taking all table width I guess. +% is relaxed a bit to allow row colour for a single-row merged cell. % % \spx@table@hackCT@inmergedcell % \spx@table@hackCT@nocolor @@ -459,8 +469,8 @@ \def\spx@CT@setup@nocolor#1\endgroup{% \global\let\CT@cell@color\relax % the above added at 5.2.0 - % else a \cellcolor added by a raw latex directive in the merged cell - % will create color leak in cells to the right of the merged cell + % formerly a \cellcolor added by a raw latex directive in the merged cell + % would have caused colour to apply to the *next* cell after the merged one \endgroup} % % norowcolor @@ -480,7 +490,7 @@ % % sphinxcolormix (commented-out) % this works but then I found out about \blendcolors in xcolor doc, so I provided -% rather \sphinxcolorblend +% rather \sphinxcolorblend, the code is kept in case it can be reused in future % \@ifpackageloaded{xcolor}{% % \def\spx@table@hackCT@colormix{% % \ifnum\currentgrouptype=6\relax @@ -509,7 +519,6 @@ % \def\sphinxcolormix#1{\gdef\spx@colormixparam{#1}\spx@table@hackCT@colormix} % % \sphinxcolorblend -\@ifpackageloaded{xcolor}{% \def\spx@table@hackCT@colorblend{% \ifnum\currentgrouptype=6\relax \expandafter\blendcolors\spx@colorblendparam @@ -519,8 +528,12 @@ \else \aftergroup\spx@table@hackCT@colorblend \fi -}% -}{\let\spx@table@hackCT@colorblend\@empty}% defined to be no-op if no xcolor +} +% Either xcolor.sty exists on user system and has been loaded by sphinx.sty, +% or it does not exist, so we can use \@ifpackageloaded without delaying. +\@ifpackageloaded{xcolor}% + {}% + {\let\spx@table@hackCT@colorblend\@empty}% no-op if no xcolor \def\sphinxcolorblend#1{\gdef\spx@colorblendparam{{#1}}\spx@table@hackCT@colorblend} @@ -675,9 +688,9 @@ % So, the style macros will *prepend* the needed color-code to the existing % custom user code, so the custom user code can override them. The custom % user code should not redefine any of the 3 \sphinxtable...hook macros via a -% \global\def, but their contents can use \gdef if this is the user intention, -% (attention that the hooks are executed from inside the table, except the -% afterend hook so probably the code in-there should use \noalign), +% \global\def, but their contents can use \gdef. In fact they probably need +% to for the first two hooks which are executed from inside the table and +% a priori need their code to be in a \noalign which limits scope. % % 2) the table templates and LaTeX writer code make it so that only % one of either @@ -691,11 +704,10 @@ % \sphinxthistablewithcolorrowsstyle. Nevertheless we have written % the code so that in this case colorrows would indeed activate (except % if it was already executed before as it self-annihilates). - +% \let\sphinxtabletoprulehook \@empty \let\sphinxtableatstartofbodyhook\@empty \let\sphinxtableafterendhook \@empty - % % Support for colour in table % @@ -739,13 +751,7 @@ % ... or not if there are two \cline's in the row... % (as we will use same mechanism we have to correct this increment). % -% So we need our own code. And matters of longtable unfortunately force -% us to some addition to table template, simply hooking into in-place -% \sphinxtoprule etc mark-up is not enough. After some hesitation and due -% to problems of the continuation hints of longtable we decide not to try -% for coloured headers (which would be fine with tabular and tabulary -% actually) except for the first header row via a \rowcolor, not via the -% \rowcolors-style hack into \CT@everycr. +% So we need our own code. % Provide \rownum and rownum LaTeX counter (code copied from colortbl v1.0f) \ltx@ifundefined{rownum}{% @@ -760,10 +766,8 @@ % (particularly if borderless) \def\sphinxcolorpanelextraoverhang{0.1pt} -% set the colours according to row parity; a priori #1 is \rownum it is -% possible to set the colours, as in this macro code, from inside a -% (non-merged) cell (via commands inserted via raw directive), it will then -% influence the colours in its row starting from the cell. +% set the colours according to row parity; a priori #1 is \rownum, but +% the macro can be used in user added code \def\sphinxSwitchCaseRowColor#1{% \ifodd#1\relax \global\sphinxcolorlet{sphinxTableRowColor}{sphinxTableRowColorOdd}% @@ -774,9 +778,8 @@ \fi } -% this will start the alternating colours, by letting \everycr increment -% the \rownum counter and reset the colours according to -% \sphinxSwitchCaseRowColor\rownum +% this will start the alternating colours, by letting \everycr increment the +% \rownum counter and reset the colours according to \sphinxSwitchCaseRowColor\rownum \def\spx@table@@startbodycolorrows{% \noalign{% \global\CT@everycr{% Nota Bene: in a longtable with \hline the \everycr is @@ -785,7 +788,7 @@ % MEMO: colortbl \CT@row@color is expanded *after* the cell contents have been % gathered and measured, so it can't be used to expose e.g. the colour to the % cell contents macro code. Of course if it is known how the colour is chosen -% the procedure could be done from inside the cell. Simpler to set the colour +% the procedure could be done from inside the cell. Simpler to expose the colour % in a public name sphinxTableRowColor at start of the row in this \noalign. \sphinxSwitchCaseRowColor\rownum }% @@ -793,14 +796,14 @@ }% \global\rownum\@ne % is done from inside table so ok with tabulary two passes \sphinxSwitchCaseRowColor\rownum % set up color for the first body row - \sphinxrowcolorON % turns on the colours for rows (this is superfluous - % as it now is also emitted by \sphinxtoprule for - % header rows) + \sphinxrowcolorON % has been done from \sphinxtoprule location but let's do + % it again in case \sphinxtabletoprulehook has been used + % to inihibit colours in the header rows }% end of noalign contents } -\def\sphinxrowcolorON{% the colours here must have been defined - % this is the case if colorrows class from \sphinxtoprule expansion +\def\sphinxrowcolorON{% the colours here must have been defined, and this is done + % via \sphinxtabletoprulehook default action \gdef\CT@row@color{\ifspx@table@inmergedcell \CT@color{sphinxTableMergeColor}% \else @@ -820,15 +823,11 @@ \def\spx@table@@toprulehook{% \noalign{% - % Because of tabulary 2-pass system, if we don't want the colour - % set-up at end of table to contaminate the headers at start of - % table, we must reset explicitly the \everycr here. But - % we don't use the colortbl default value of \CT@everycr, as it - % resets \CT@row@color to \relax but we want the next header rows - % to obey same color scheme + % Because of tabulary 2-pass system, the colour set-up at end of table + % would contaminate the header colours at start of table, so must reset + % them here. We want all header rows to obey same colours, so we don't + % use original \CT@everycr which sets \CT@row@color to \relax. \global\CT@everycr{\the\everycr}% -% if we could require xcolor we could make it nice colour scheme with each new -% header row at 90% of previous row colour, for example. \global\sphinxcolorlet{sphinxTableRowColor}{sphinxTableRowColorHeader}% \global\sphinxcolorlet{sphinxTableMergeColor}{\sphinxTableMergeColorHeader}% \sphinxrowcolorON @@ -857,8 +856,8 @@ \def\spx@toprule {\hline}% \def\sphinxmidrule {\hline}% \def\sphinxbottomrule {\hline}% - % Merged cells width computation - \def\sphinxarrayrulewidth{\arrayrulewidth}% + % Do not tamper with this internal + \def\spx@arrayrulewidth{\arrayrulewidth}% } % booktabs style @@ -902,8 +901,7 @@ \def\spx@toprule {\sphinxbooktabstoprule}% \def\sphinxmidrule {\sphinxbooktabsmidrule}% \def\sphinxbottomrule{\sphinxbooktabsbottomrule}% - \def\sphinxarrayrulewidth{\z@}% (attention! Do NOT assign to \sphinxarrayrulewidth - % this would modify \z@ and break all of LaTeX...) + \def\spx@arrayrulewidth{\z@}% } \AtBeginDocument{\@ifpackageloaded{booktabs}% {}% @@ -924,19 +922,14 @@ to allow local use of booktabs table style}% \let\spx@toprule \@empty \let\sphinxmidrule \@empty \let\sphinxbottomrule \@empty - \def\sphinxarrayrulewidth{\z@}% (attention! Do NOT assign to \sphinxarrayrulewidth - % this would modify \z@ and break all of LaTeX...) + \def\spx@arrayrulewidth{\z@}% }% % colorrows style % -% this is defined to be executed only once (if both latex_book_style contains -% 'colorrows' and the table receives the class colorrows, this means the macro -% is executed twice, but it prepends hooks and one of them decrements \rownum so -% should be prepended only once). The self-annihilation is done in a scope -% limiting environment. +% this is defined to auto-silence itself (in the surrounding scope-limiting +% environment) after one execution \def\sphinxthistablewithcolorrowsstyle{% -% only do its job once \let\sphinxthistablewithcolorrowsstyle\@empty % \let\spx@table@toprulehook \spx@table@@toprulehook @@ -945,7 +938,7 @@ to allow local use of booktabs table style}% \spx@prepend\spx@table@toprulehook \to\sphinxtabletoprulehook \spx@prepend\spx@table@startbodycolorrows\to\sphinxtableatstartofbodyhook % -% this one is not set to \@empty by norowcolors, because it looks harmless +% this one is not set to \@empty by nocolorrows, because it looks harmless % to execute it always, as it simply resets to standard colortbl state after % the table; so we don't need an @@ version for this one \spx@prepend\spx@table@resetcolortbl\to\sphinxtableafterendhook @@ -957,29 +950,27 @@ to allow local use of booktabs table style}% }% \def\sphinxthistablewithnocolorrowsstyle{% -% rather than trying to remove the code added by 'rowcolors' style, we +% rather than trying to remove the code added by 'colorrows' style, we % simply make it no-op, without even checking if really it was activated. \let\spx@table@toprulehook \@empty \let\spx@table@startbodycolorrows\@empty \let\sphinxtabledecrementrownum \@empty % we don't worry about \sphinxtableafterendhook as the \spx@table@resetcolortbl -% done at end can not do harm; and also we could have not bothered with the +% done at end can not do harm; and also we could also have not bothered with the % \sphinxtabledecrementrownum as its \rownum decrement, if active, is harmless % in non-colorrows context } -% The \sphinxarrayrulewidth is used for some complex matters of merged +% The \spx@arrayrulewidth is used for some complex matters of merged % cells size computations -% tabularcolumns argument will override any global or local style -% regarding the presence or not of vertical separator. +% tabularcolumns argument will override any global or local style and +% trigger the appropriate adjustement of \spx@arrayrulewidth \def\sphinxthistablewithvlinesstyle{% - \def\sphinxarrayrulewidth{\arrayrulewidth}% + \def\spx@arrayrulewidth{\arrayrulewidth}% }% \def\sphinxthistablewithnovlinesstyle{% - \def\sphinxarrayrulewidth{\z@}% (attention! Do NOT assign to \sphinxarrayrulewidth - % this would modify \z@ and break all of LaTeX...) + \def\spx@arrayrulewidth{\z@}% }% -% (mixed style in the column specification can not be 100% well supported). % default is the standard style \def\sphinxthistablewithglobalstyle{\sphinxthistablewithstandardstyle} @@ -991,6 +982,7 @@ to allow local use of booktabs table style}% \ifspx@opt@borderless \def\sphinxthistablewithglobalstyle{\sphinxthistablewithborderlessstyle} \fi +% colorrows appends to the current globalstyle (standard, booktabs, or borderless) \ifspx@opt@colorrows % let the globalstyle trigger the colorrows style on top of it \expandafter\def\expandafter\sphinxthistablewithglobalstyle\expandafter {\sphinxthistablewithglobalstyle