Rename and simplify LaTeX macros

in particular:
``\sphinxbelowtablecaptionskip`` renamed to ``\sphinxbelowcaptionskip``
as it may be extended in future to usage for captions of literal blocks.

sphinx/templates/latex/longtable.tex_t

@@ -8,7 +8,7 @@
 <%- endif -%>
 <%= table.get_colspec() %>
 <%- if table.caption -%>
-\caption{<%= ''.join(table.caption) %>\strut}<%= labels %>\\*[\sphinxafterLTcaptionskip]
+\caption{<%= ''.join(table.caption) %>\strut}<%= labels %>\\*[\sphinxlongtablecapskipadjust]
 <% endif -%>
 \hline
 <%= ''.join(table.header) %>

sphinx/texinputs/sphinx.sty

@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2017/03/03 v1.6 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2017/03/04 v1.6 LaTeX package (Sphinx markup)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -57,32 +57,39 @@
 % using here T (for Tabulary) feels less of a problem than the X could be
 \newcolumntype{T}{J}%
 \RequirePackage{longtable}
+% For table captions.
+\RequirePackage{threeparttable}
 % fixing the LaTeX mess of vertical spaces with threeparttable and longtable
-% user interface:
+% The user interface:
 \newcommand*\sphinxtablepre {0pt}%
 \newcommand*\sphinxtablepost{\bigskipamount}%
-% can not use \baselineskip inside longtable (as it is zero there)
+% as one can not use \baselineskip from inside longtable (it is zero there)
-\newcommand*\sphinxbelowtablecaptionskip{.5\sphinxbaselineskip}%
+% we need \sphinxbaselineskip, which defaults to \baselineskip
-% helper macros
+\newcommand*\sphinxbelowcaptionskip{.5\sphinxbaselineskip}%
 \def\sphinxbaselineskip{\baselineskip}%
+% Helper macros, not a priori for user customization
 \def\sphinxatlongtablestart
    {\par
-     \vskip-\dimexpr\baselineskip+\parskip\relax
+    \vskip\parskip
-     \leavevmode\null\par
+    \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position
-     \vskip\dimexpr\baselineskip+\parskip\relax
+    \vbox{}% get correct baseline from above
-     \vskip\dimexpr\sphinxtablepre\relax
+    \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
-     \LTpre\z@skip\LTpost\z@skip
     \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}}%
-\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}%
+\def\sphinxatlongtableend{\prevdepth\z@\vskip\sphinxtablepost\relax}%
-\def\sphinxatlongtableend{\vskip\sphinxtablepost\relax}%
+% the longtable template inserts a \strut at caption's end
-\def\sphinxattableend{\prevdepth\z@\vskip\sphinxtablepost\relax}%
+\def\sphinxlongtablecapskipadjust
-\def\sphinxafterLTcaptionskip
    {\dimexpr-\dp\strutbox-\sphinxbaselineskip
-            +\sphinxbelowtablecaptionskip\relax}%
+            +\sphinxbelowcaptionskip\relax}%
-\def\sphinxafterTPTcaption % will be injected in a threeparttable macro
+% tabular(y) with or without threeparttable
-   {\vskip\dimexpr-\dp\strutbox-1.2\baselineskip
+\def\sphinxattablestart
-                  +\sphinxbelowtablecaptionskip\relax
+   {\par
-    \prevdepth\z@}%
+    \vskip\dimexpr\sphinxtablepre\relax
+    \belowcaptionskip\sphinx@TPTbelowcaptionskip}%
+\let\sphinxattableend\sphinxatlongtableend
+% the tabular(y) templates use [t] vertical placement parameter
+\def\sphinx@TPTbelowcaptionskip
+   {\dimexpr-1.2\baselineskip % .2\baselineskip hardcoded in threeparttable
+            +\sphinxbelowcaptionskip\relax }%
 % varwidth is crucial for our handling of general contents in merged cells
 \RequirePackage{varwidth}
 % but addition of a compatibility patch with hyperref is needed
@@ -108,17 +115,6 @@
 % For highlighted code.
 \RequirePackage{fancyvrb}
 \fvset{fontsize=\small}
-% For table captions.
-\RequirePackage{threeparttable}
-% need to hack into threeparttable to control below caption skip
-% captions contain an ending \strut
-\def\TPT@caption#1[#2]#3{\gdef\TPT@docapt
- {\par\global\let\TPT@docapt\@undefined \TPT@LA@caption{#1}[{#2}]%
-   {\strut\ignorespaces#3\ifhmode\unskip\@finalstrut\strutbox\fi}%
-  \sphinxafterTPTcaption
- }%
- \ifx\TPT@hsize\@empty \let\label\TPT@gatherlabel \abovecaptionskip\z@skip
- \else \TPT@docapt \fi \ignorespaces}%
 % For hyperlinked footnotes in tables; also for gathering footnotes from
 % topic and warning blocks. Also to allow code-blocks in footnotes.
 \RequirePackage{footnotehyper-sphinx}

tests/test_build_latex.py

@@ -955,7 +955,7 @@ def test_latex_table_longtable(app, status, warning):
     table = tables['longtable having caption']
     assert ('\\begin{longtable}{|l|l|}\n\\caption{caption for longtable\\strut}'
             '\\label{\\detokenize{longtable:id1}}'
-            '\\\\*[\sphinxafterLTcaptionskip]\n\\hline' in table)
+            '\\\\*[\sphinxlongtablecapskipadjust]\n\\hline' in table)
 
     # longtable having verbatim
     table = tables['longtable having verbatim']