adding \showfloat

latex3 · Jul 31, 2021 · 976e180 · 976e180
1 parent f09953d
commit 976e180
Show file tree

Hide file tree

Showing 17 changed files with 838 additions and 21 deletions.
diff --git a/base/changes.txt b/base/changes.txt
@@ -6,6 +6,13 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2021-07-31  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* ltoutput.dtx (subsubsection{Float control}):
+	Add \showfloat to fltrace.sty so that you can easily display the
+	contents of a float register, argument is just the uppercase
+	letter (or letters) denoting the register.
+
 2021-07-28  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
 
 	* ltsect.dtx (section| or |\caption|):

diff --git a/base/doc/ltnews34.tex b/base/doc/ltnews34.tex
@@ -240,6 +240,28 @@ \subsection{New default for \cs{tracinglostchars}}
 
 
 
+
+\subsection{New \cs{showfloat} command}
+
+The package \pkg{fltrace} offers a (fairly low-level but very
+detailed) way to trace \LaTeX's float mechanism. This can help to
+understand why a certain float is placed into a certain region or why
+it shows up unexpectedly on a later page.  \LaTeX{} stores floats in
+registers named \cs{bx@A}, \cs{bx@B}, etc., and these names show up in
+the tracing information.
+%
+To display their contents you can now say
+\verb=\showfloat{=\textit{uc-letter}\verb=}= where \textit{uc-letter}
+is the uppercase letter (or letters) after \texttt{bx@} in the
+register name shown in the tracing. The command is generally
+available, whether or not you have loaded \pkg{fltrace}, because it is
+also useful when interpreting the tracing output of the
+\pkg{fewerfloatpages} package.
+
+
+
+
+
 \subsection{???}
 
 %

diff --git a/base/ltoutput.dtx b/base/ltoutput.dtx
@@ -30,7 +30,7 @@
 %%% From File: ltoutput.dtx
 %<flafter>\ProvidesPackage{flafter}
 %<fltrace>\ProvidesPackage{fltrace}
-%<flafter,fltrace>       [2021/05/07 v1.4e
+%<flafter,fltrace>       [2021/07/31 v1.4e
 %<flafter>                  Standard LaTeX floats after reference (FMi)]
 %<fltrace>                  Tracing LaTeX floats algorithm (FMi)]
 %
@@ -3945,10 +3945,55 @@
      \fi
    \fi
 }
+%    \end{macrocode}
+%  \end{macro}
+%
+%
+%
+%
+%
+%  \begin{macro}{\showfloat}
+%    This command provides some information about the contenta of a
+%    float register.  Float registers are internally named
+%    \cs{bx@}\meta{Uppsercase-letter(s)} and you specify just this
+%    letter or letters as the argument, e.g., \verb=\showfloat{A}=.
+%    (No error recovery no anything if you specify something that
+%    isn't a float.)
+% \changes{v1.4e}{2021/07/31}{Macro added}
+%    \begin{macrocode}
 %</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2021/11/15}%
+%<latexrelease>                 {\showfloat}{Show float register contents}%
+\def\showfloat#1{\begingroup
+    \tracefloats
+    \fl@trace{***Float #1 details:}%
+    \expandafter\fl@showfloat\csname bx@#1\endcsname
+  \endgroup
+}
+\def\fl@showfloat#1{%
+  \fl@traceval{\count#1}%  % this here should be interpreted on day
+  \fl@traceval{\ht#1}%
+  \fl@traceval{\dp#1}%
+  \fl@traceval{\wd#1}%
+  {\tracingonline1\showboxbreadth10\showboxdepth3\showbox#1}%
+}
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease>                 {\showfloat}{Show float register contents}%
+%<latexrelease>
+%<latexrelease>\let\fl@showfloat\@undefined
+%<latexrelease>\EndIncludeInRelease
 %    \end{macrocode}
 %  \end{macro}
 %
+%
+%
+%
 % \subsubsection{Float control}
 %
 % This part implements controllable floats and other changes
@@ -4029,7 +4074,7 @@
 %    When the user requests \cs{tracefloatvals} then they should show
 %    regardless of the tracing state, so locally we make sure that it
 %    is activated.
-% \changes{v1.4e}{2021/05/07}{Enable display when doing \cs{tracefloatvals}}
+% \changes{v1.4e}{2021/07/31}{Enable display when doing \cs{tracefloatvals}}
 %    \begin{macrocode}
   \tracefloats
 %    \end{macrocode}
@@ -4091,25 +4136,6 @@
 %
 %
 %
-%  \begin{macro}{\showfloat}
-%    Give some information about the content of a float register.
-%    (No error recovery no anything if you specify something that
-%    isn't a float.)
-%    \begin{macrocode}
-\def\showfloat#1{\begingroup
-    \tracefloats
-    \fl@trace{***Float #1 details:}%
-    \expandafter\fl@showfloat\csname bx@#1\endcsname
-  \endgroup
-}
-\def\fl@showfloat#1{%
-  \fl@traceval{\count#1}%    % this here should be interpreted
-  \fl@traceval{\ht#1}%
-  \fl@traceval{\dp#1}%
-  {\tracingonline1\showboxbreadth10\showboxdepth3\showbox#1}%
-}
-%    \end{macrocode}
-%  \end{macro}
 %
 %    We need to make sure that \texttt{fltrace} comes before
 %    \texttt{flafter} to make the tracing work.

diff --git a/base/testfiles/github-0479-often.luatex.tlg b/base/testfiles/github-0479-often.luatex.tlg
@@ -632,6 +632,8 @@ Applying: [....-..-..] float order in 2-column on input line ....
 Already applied: [....-..-..] float order in 2-column on input line ....
 Applying: [....-..-..] float order in 2-column on input line ....
 Already applied: [....-..-..] float order in 2-column on input line ....
+Skipping: [....-..-..] Show float register contents on input line ....
+Applying: [....-..-..] Show float register contents on input line ....
 Applying: [....-..-..] negative height floats on input line ....
 Already applied: [....-..-..] negative height floats on input line ....
 Applying: [....-..-..] 2 column marks on input line ....

diff --git a/base/testfiles/github-0479-often.tlg b/base/testfiles/github-0479-often.tlg
@@ -620,6 +620,8 @@ Applying: [....-..-..] float order in 2-column on input line ....
 Already applied: [....-..-..] float order in 2-column on input line ....
 Applying: [....-..-..] float order in 2-column on input line ....
 Already applied: [....-..-..] float order in 2-column on input line ....
+Skipping: [....-..-..] Show float register contents on input line ....
+Applying: [....-..-..] Show float register contents on input line ....
 Applying: [....-..-..] negative height floats on input line ....
 Already applied: [....-..-..] negative height floats on input line ....
 Applying: [....-..-..] 2 column marks on input line ....

diff --git a/base/testfiles/github-0479-often.xetex.tlg b/base/testfiles/github-0479-often.xetex.tlg
@@ -621,6 +621,8 @@ Applying: [....-..-..] float order in 2-column on input line ....
 Already applied: [....-..-..] float order in 2-column on input line ....
 Applying: [....-..-..] float order in 2-column on input line ....
 Already applied: [....-..-..] float order in 2-column on input line ....
+Skipping: [....-..-..] Show float register contents on input line ....
+Applying: [....-..-..] Show float register contents on input line ....
 Applying: [....-..-..] negative height floats on input line ....
 Already applied: [....-..-..] negative height floats on input line ....
 Applying: [....-..-..] 2 column marks on input line ....

diff --git a/base/testfiles/tlb-fltrace-005.lvt b/base/testfiles/tlb-fltrace-005.lvt
@@ -0,0 +1,55 @@
+% \iffalse meta-comment
+%
+% \fi
+%
+\documentclass[twocolumn]{article}
+
+\usepackage{fltrace}
+\tracefloats
+
+% Input the test macros for LaTeX2e
+\input{test2e}
+
+\AUTHOR{Frank Mittelbach}
+
+% Declare the format used on the original run, as printed by
+% LaTeX.
+%
+
+\newcommand\astarfigure[2][tp]{\begin{figure*}[#1]figure(*) #2\end{figure*}}
+\newcommand\afigure[2][tbp]{\begin{figure}[#1]figure #2\end{figure}}
+\newcommand\atable[2][tbp]{\begin{table}[#1]table #2\end{table}}
+\newcommand\sometext{A few words repeated all over again. }
+
+\begin{document}
+
+% Everything before this is ignored by the test system.
+
+\START
+
+\tracefloatvals
+
+\sometext \astarfigure{A}\afigure{B}\afigure[t]{C}\atable{D}
+
+\sometext \atable[h]{E}
+\sometext\marginpar{M} \sometext
+\showfloat{F}\showfloat{G}  % those should be the marginpars
+
+\afigure[p]{F}
+\atable{G}
+
+\tracefloatvals
+
+\showfloat{A}
+\showfloat{B}
+\showfloat{C}
+\showfloat{D}
+\showfloat{E}
+\showfloat{F}
+\showfloat{G}
+\showfloat{H}
+\showfloat{I}
+\showfloat{J}
+
+\end{document}
+