Debian Codegraph @

texmf-dist/source/latex/booktabstabular/booktabstabular.dtx

raw
1 % \iffalse
2 %<*driver>
3 \documentclass{ltxdoc}
4 \usepackage[overridetabular]{booktabstabular}
5 \usepackage[T1]{fontenc}
6 \EnableCrossrefs%
7 \CodelineIndex%
8 \RecordChanges%
9 \begin{document}
10 \DocInput{booktabstabular.dtx}
11 \end{document}
12 %</driver>
13 % \fi
14 %
15 % \ProvidesFile{booktabstabular.dtx}
16 % [2026/03/27 v1.0.0 tabular and tabular* wrappers with booktabs rules]
17 %
18 % \CheckSum{62}
19 %
20 % \changes{v1.0.0}{2026/03/27}{Initial release.}
21 %
22 % \DoNotIndex{\IfNoValueTF,\NeedsTeXFormat,\NewDocumentCommand}
23 % \DoNotIndex{\NewDocumentEnvironment,\NewEnvironmentCopy,\ProvidesPackage}
24 % \DoNotIndex{\RenewEnvironmentCopy,\begin,\bottomrule,\crcr,\def}
25 % \DoNotIndex{\egroup,\end,\let,\RequirePackage,\toprule}
26 %
27 % \GetFileInfo{booktabstabular.dtx}
28 %
29 % \title{Streamlining the booktabs package}
30 % \author{Moritz R. Schäfer}
31 % \date{\filedate\space \fileversion}
32 %
33 % \maketitle
34 %
35 % \section{Introduction}
36 % The \textsf{booktabstabular} package provides wrapper environments around
37 % |tabular| and |tabular*| that insert \cs{toprule} at the beginning,
38 % \cs{bottomrule} at the end, and locally remap the legacy |\hline| and |\cline|
39 % commands to their booktabs equivalents \cs{midrule} and \cs{cmidrule}.
40 % It also provides commands to temporarily override the standard |tabular| and
41 % |tabular*| environments so that existing documents can opt into this
42 % behaviour without rewriting each table.
43 %
44 % \section{Interface}
45 % \DescribeEnv{booktabstabular}
46 % The |booktabstabular| environment is a drop-in wrapper for |tabular|. It
47 % accepts the same arguments as |tabular|: an optional position specifier
48 % |[t]| or |[b]|, followed by the column specification.
49 %
50 % \DescribeEnv{booktabstabular*}
51 % The |booktabstabular*| environment is a drop-in wrapper for |tabular*|.
52 % It accepts the width, an optional position specifier, and the column
53 % specification.
54 %
55 % \DescribeMacro{\overridetabular}
56 % After calling \cs{overridetabular}, the public |tabular| and |tabular*|
57 % environments are rebound to the wrapper environments provided by this
58 % package. Note that many classes, including the standard classes, use a
59 % tabular to typeset the list of authors, if you don't want that to be
60 % affected, you should call \cs{overridetabular} after \cs{maketitle} or use
61 % the |overridetabular| package option.
62 %
63 % \DescribeMacro{\restoretabular}
64 % The command \cs{restoretabular} restores the original definitions of
65 % |tabular| and |tabular*|.
66 %
67 % \DescribeMacro{overridetabular option}
68 % Passing the package option |overridetabular| to \cs{usepackage} has almost
69 % the same effect as calling \cs{overridetabular} after loading the package.
70 % The difference is that the package option automatically disables the override
71 % around \cs{maketitle} to avoid affecting the title page, while the command
72 % does not.
73 %
74 % \subsection{Example}
75 % A typical opt-in workflow is:
76 %
77 % \begin{verbatim}
78 % \usepackage[overridetabular]{booktabstabular}
79 %
80 % \begin{tabular}{lll}
81 % First & Second & Third \\
82 % \hline % mapped to \midrule
83 % Alpha & Beta & Gamma
84 % \end{tabular}
85 % \end{verbatim}
86 %
87 % Alternatively, the wrapper environments can be used directly:
88 %
89 % \begin{verbatim}
90 % \begin{booktabstabular}{lll}
91 % First & Second & Third \\
92 % \hline
93 % Alpha & Beta & Gamma
94 % \end{booktabstabular}
95 % \end{verbatim}
96 %
97 % Both should yield the following output:
98 % \begin{tabular}{lll}
99 % First & Second & Third \\
100 % \hline
101 % Alpha & Beta & Gamma
102 % \end{tabular}
103 % As you can see, |\toprule| and |\bottomrule| are automatically inserted, and
104 % |\hline| is remapped to |\midrule|, so the table is typeset according to
105 % booktabs guidelines. The same applies to |tabular*| when using the
106 % |booktabstabular*| environment or the overridden |tabular*| name.
107 % \begin{verbatim}
108 % \begin{booktabstabular*}{\textwidth}{l@{\extracolsep{\fill}}l}
109 % First & Second \\
110 % \hline
111 % Alpha & Beta
112 % \end{booktabstabular*}
113 % \end{verbatim}
114 % which produces the slightly wider table
115 % \begin{booktabstabular*}{.4\textwidth}{l@{\extracolsep{\fill}}l}
116 % First & Second \\
117 % \hline
118 % Alpha & Beta
119 % \end{booktabstabular*}.
120 %
121 % \subsection{Notes}
122 % This package deliberately does not insert any intermediate rule such as
123 % \cs{midrule} automatically; that remains the author's responsibility.
124 %
125 % The end wrapper inserts \cs{bottomrule} at the legal alignment boundary,
126 % so the final row may be written either with or without a trailing |\\|.
127 %
128 % The package does not attempt to remap the legacy |\hline| and |\cline| outside
129 % of the wrapper environments, so they will continue to work as normal in
130 % documents that only use the wrappers for a subset of tables.
131 %
132 % The package affects only |tabular| and |tabular*|. It does not modify
133 % |array|, |longtable|, or any other alignment environment.
134 %
135 % \StopEventually{\PrintChanges\PrintIndex}
136 %
137 % \section{Implementation}
138 % First load \pkg{booktabs}, and record the package identity.
139 % \begin{macrocode}
140 %<*package>
141 \NeedsTeXFormat{LaTeX2e}[2023-06-01]
142 \RequirePackage{booktabs}
143 \ProvidesPackage{booktabstabular}
144 [2026/03/08 v1.0.0 tabular/tabular* with booktabs rules]
145 % \end{macrocode}
146 % \subsection{Environments}
147 % \begin{environment}{origtabular}
148 % \begin{environment}{origtabular*}
149 % Save copies of the original |tabular| and |tabular*| environments. They are
150 % used internally but also made available for users who want to call the original versions
151 % if they have overridden the standard names.
152 % \begin{macrocode}
153 \NewEnvironmentCopy{origtabular}{tabular}
154 \NewEnvironmentCopy{origtabular*}{tabular*}
155 % \end{macrocode}
156 % \end{environment}
157 % \end{environment}
158 %
159 % Mirror the kernel's current |\endtabular|, but insert |\bottomrule|
160 % after the implicit final |\crcr|. The control sequence names avoid |@|
161 % so that they can safely be used in environment definitions without
162 % additional category-code changes.
163 % \begin{macrocode}
164 \def\booktabstabular@endtabular{%
165 \crcr
166 \bottomrule
167 \egroup
168 \egroup
169 $\egroup
170 }
171 \let\booktabstabular@endtabularstar\booktabstabular@endtabular
172 % \end{macrocode}
173 %
174 % Map legacy horizontal rules to booktabs-style rules inside the wrappers.
175 % \begin{macrocode}
176 \def\booktabstabular@rulesetup{%
177 \let\hline\midrule
178 \let\cline\cmidrule
179 }
180 % \end{macrocode}
181 %
182 % \begin{environment}{booktabstabular}
183 % The |booktabstabular| environment mirrors the argument signature of
184 % |tabular|: an optional position argument followed by the preamble.
185 % It calls the copied begin macro directly rather than nesting a separate
186 % environment, which keeps LaTeX's environment stack balanced when the
187 % custom end code is used.
188 % \begin{macrocode}
189 \NewDocumentEnvironment{booktabstabular}{o m}
190 {%
191 \begingroup
192 \booktabstabular@rulesetup
193 \IfNoValueTF{#1}
194 {\origtabular{#2}}
195 {\origtabular[#1]{#2}}%
196 \toprule
197 }
198 {%
199 \booktabstabular@endtabular
200 \endgroup
201 }
202 % \end{macrocode}
203 % \end{environment}
204 %
205 % \begin{environment}{booktabstabular*}
206 % The |booktabstabular*| environment mirrors |tabular*|: width, optional
207 % position, and preamble, again using the copied begin macro directly.
208 % \begin{macrocode}
209 \NewDocumentEnvironment{booktabstabular*}{m o m}
210 {%
211 \begingroup
212 \booktabstabular@rulesetup
213 \IfNoValueTF{#2}
214 {\UseName{origtabular*}{#1}{#3}}
215 {\UseName{origtabular*}{#1}[#2]{#3}}%
216 \toprule
217 }
218 {%
219 \booktabstabular@endtabularstar
220 \endgroup
221 }
222 % \end{macrocode}
223 % \end{environment}
224 %
225 % \subsection{Public commands}
226 % \begin{macro}{\overridetabular}
227 % \begin{macro}{\restoretabular}
228 % Finally, provide public commands to switch the standard environment names to
229 % the wrapped versions and to restore the originals.
230 % \begin{macrocode}
231 \NewDocumentCommand{\overridetabular}{}{
232 \RenewEnvironmentCopy{tabular}{booktabstabular}%
233 \RenewEnvironmentCopy{tabular*}{booktabstabular*}%
234 }
235 \NewDocumentCommand{\restoretabular}{}{
236 \RenewEnvironmentCopy{tabular}{origtabular}%
237 \RenewEnvironmentCopy{tabular*}{origtabular*}%
238 }
239 % \end{macrocode}
240 % \end{macro}
241 % \end{macro}
242 %
243 % \subsection{Options}
244 % We offer an option to automatically override the standard |tabular| and |tabular*|
245 % environments. This is disabled by default, but can be enabled by passing the
246 % |overridetabular| option to \cs{usepackage}.
247 % \begin{macrocode}
248 \newif\ifbooktabstabularoverride%
249 \DeclareOption{overridetabular}{\booktabstabularoverridetrue}
250 \ProcessOptions\relax
251 \ifbooktabstabularoverride
252 \AddToHook{cmd/maketitle/before}{\restoretabular}
253 \AddToHook{cmd/maketitle/after}{\overridetabular}
254 \overridetabular
255 \fi
256 %</package>
257 % \end{macrocode}
258 %
259 % \Finale
260 \endinput