% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage[overridetabular]{booktabstabular}
\usepackage[T1]{fontenc}
\EnableCrossrefs%
\CodelineIndex%
\RecordChanges%
\begin{document}
  \DocInput{booktabstabular.dtx}
\end{document}
%</driver>
% \fi
%
% \ProvidesFile{booktabstabular.dtx}
%   [2026/03/27 v1.0.0 tabular and tabular* wrappers with booktabs rules]
%
% \CheckSum{62}
%
% \changes{v1.0.0}{2026/03/27}{Initial release.}
%
% \DoNotIndex{\IfNoValueTF,\NeedsTeXFormat,\NewDocumentCommand}
% \DoNotIndex{\NewDocumentEnvironment,\NewEnvironmentCopy,\ProvidesPackage}
% \DoNotIndex{\RenewEnvironmentCopy,\begin,\bottomrule,\crcr,\def}
% \DoNotIndex{\egroup,\end,\let,\RequirePackage,\toprule}
%
% \GetFileInfo{booktabstabular.dtx}
%
% \title{Streamlining the booktabs package}
% \author{Moritz R. Schäfer}
% \date{\filedate\space \fileversion}
%
% \maketitle
%
% \section{Introduction}
% The \textsf{booktabstabular} package provides wrapper environments around
% |tabular| and |tabular*| that insert \cs{toprule} at the beginning,
% \cs{bottomrule} at the end, and locally remap the legacy |\hline| and |\cline|
% commands to their booktabs equivalents \cs{midrule} and \cs{cmidrule}.
% It also provides commands to temporarily override the standard |tabular| and
% |tabular*| environments so that existing documents can opt into this
% behaviour without rewriting each table.
%
% \section{Interface}
% \DescribeEnv{booktabstabular}
% The |booktabstabular| environment is a drop-in wrapper for |tabular|. It
% accepts the same arguments as |tabular|: an optional position specifier
% |[t]| or |[b]|, followed by the column specification.
%
% \DescribeEnv{booktabstabular*}
% The |booktabstabular*| environment is a drop-in wrapper for |tabular*|.
% It accepts the width, an optional position specifier, and the column
% specification.
%
% \DescribeMacro{\overridetabular}
% After calling \cs{overridetabular}, the public |tabular| and |tabular*|
% environments are rebound to the wrapper environments provided by this
% package. Note that many classes, including the standard classes, use a
% tabular to typeset the list of authors, if you don't want that to be
% affected, you should call \cs{overridetabular} after \cs{maketitle} or use
% the |overridetabular| package option.
%
% \DescribeMacro{\restoretabular}
% The command \cs{restoretabular} restores the original definitions of
% |tabular| and |tabular*|.
%
% \DescribeMacro{overridetabular option}
% Passing the package option |overridetabular| to \cs{usepackage} has almost
% the same effect as calling \cs{overridetabular} after loading the package.
% The difference is that the package option automatically disables the override
% around \cs{maketitle} to avoid affecting the title page, while the command
% does not.
%
% \subsection{Example}
% A typical opt-in workflow is:
%
% \begin{verbatim}
% \usepackage[overridetabular]{booktabstabular}
% 
% \begin{tabular}{lll}
%   First  & Second & Third \\
%   \hline % mapped to \midrule
%   Alpha  & Beta   & Gamma
% \end{tabular}
% \end{verbatim}
%
% Alternatively, the wrapper environments can be used directly:
%
% \begin{verbatim}
% \begin{booktabstabular}{lll}
%   First  & Second & Third \\
%   \hline
%   Alpha  & Beta   & Gamma
% \end{booktabstabular}
% \end{verbatim}
%
% Both should yield the following output:
% \begin{tabular}{lll}
%   First  & Second & Third \\
%   \hline
%   Alpha  & Beta   & Gamma
% \end{tabular}
% As you can see, |\toprule| and |\bottomrule| are automatically inserted, and
% |\hline| is remapped to |\midrule|, so the table is typeset according to
% booktabs guidelines. The same applies to |tabular*| when using the
% |booktabstabular*| environment or the overridden |tabular*| name.
% \begin{verbatim}
% \begin{booktabstabular*}{\textwidth}{l@{\extracolsep{\fill}}l}
%   First  & Second \\
%   \hline
%   Alpha  & Beta
% \end{booktabstabular*}
% \end{verbatim}
% which produces the slightly wider table
% \begin{booktabstabular*}{.4\textwidth}{l@{\extracolsep{\fill}}l}
%   First  & Second \\
%   \hline
%   Alpha  & Beta
% \end{booktabstabular*}.
%
% \subsection{Notes}
% This package deliberately does not insert any intermediate rule such as
% \cs{midrule} automatically; that remains the author's responsibility.
%
% The end wrapper inserts \cs{bottomrule} at the legal alignment boundary,
% so the final row may be written either with or without a trailing |\\|.
%
% The package does not attempt to remap the legacy |\hline| and |\cline| outside
% of the wrapper environments, so they will continue to work as normal in
% documents that only use the wrappers for a subset of tables.
%
% The package affects only |tabular| and |tabular*|. It does not modify
% |array|, |longtable|, or any other alignment environment.
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}
% First load \pkg{booktabs}, and record the package identity.
% \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}[2023-06-01]
\RequirePackage{booktabs}
\ProvidesPackage{booktabstabular}
  [2026/03/08 v1.0.0 tabular/tabular* with booktabs rules]
%    \end{macrocode}
% \subsection{Environments}
% \begin{environment}{origtabular}
% \begin{environment}{origtabular*}
% Save copies of the original |tabular| and |tabular*| environments. They are
% used internally but also made available for users who want to call the original versions
% if they have overridden the standard names.
% \begin{macrocode}
\NewEnvironmentCopy{origtabular}{tabular}
\NewEnvironmentCopy{origtabular*}{tabular*}
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% Mirror the kernel's current |\endtabular|, but insert |\bottomrule|
% after the implicit final |\crcr|. The control sequence names avoid |@|
% so that they can safely be used in environment definitions without
% additional category-code changes.
% \begin{macrocode}
\def\booktabstabular@endtabular{%
  \crcr
  \bottomrule
  \egroup
  \egroup
  $\egroup
}
\let\booktabstabular@endtabularstar\booktabstabular@endtabular
%    \end{macrocode}
%
% Map legacy horizontal rules to booktabs-style rules inside the wrappers.
% \begin{macrocode}
\def\booktabstabular@rulesetup{%
  \let\hline\midrule
  \let\cline\cmidrule
}
%    \end{macrocode}
%
% \begin{environment}{booktabstabular}
% The |booktabstabular| environment mirrors the argument signature of
% |tabular|: an optional position argument followed by the preamble.
% It calls the copied begin macro directly rather than nesting a separate
% environment, which keeps LaTeX's environment stack balanced when the
% custom end code is used.
% \begin{macrocode}
\NewDocumentEnvironment{booktabstabular}{o m}
  {%
    \begingroup
    \booktabstabular@rulesetup
    \IfNoValueTF{#1}
      {\origtabular{#2}}
      {\origtabular[#1]{#2}}%
    \toprule
  }
  {%
    \booktabstabular@endtabular
    \endgroup
  }
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{booktabstabular*}
% The |booktabstabular*| environment mirrors |tabular*|: width, optional
% position, and preamble, again using the copied begin macro directly.
% \begin{macrocode}
\NewDocumentEnvironment{booktabstabular*}{m o m}
  {%
    \begingroup
    \booktabstabular@rulesetup
    \IfNoValueTF{#2}
      {\UseName{origtabular*}{#1}{#3}}
      {\UseName{origtabular*}{#1}[#2]{#3}}%
    \toprule
  }
  {%
    \booktabstabular@endtabularstar
    \endgroup
  }
%    \end{macrocode}
% \end{environment}
%
% \subsection{Public commands}
% \begin{macro}{\overridetabular}
% \begin{macro}{\restoretabular}
% Finally, provide public commands to switch the standard environment names to
% the wrapped versions and to restore the originals.
% \begin{macrocode}
\NewDocumentCommand{\overridetabular}{}{
  \RenewEnvironmentCopy{tabular}{booktabstabular}%
  \RenewEnvironmentCopy{tabular*}{booktabstabular*}%
}
\NewDocumentCommand{\restoretabular}{}{
  \RenewEnvironmentCopy{tabular}{origtabular}%
  \RenewEnvironmentCopy{tabular*}{origtabular*}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Options}
% We offer an option to automatically override the standard |tabular| and |tabular*|
% environments. This is disabled by default, but can be enabled by passing the
% |overridetabular| option to \cs{usepackage}.
% \begin{macrocode}
\newif\ifbooktabstabularoverride%
\DeclareOption{overridetabular}{\booktabstabularoverridetrue}
\ProcessOptions\relax
\ifbooktabstabularoverride
  \AddToHook{cmd/maketitle/before}{\restoretabular}
  \AddToHook{cmd/maketitle/after}{\overridetabular}
  \overridetabular
\fi
%</package>
%    \end{macrocode}
%
% \Finale
\endinput