% multicoltab-doc.tex -- documentation for the multicoltab package
% Copyright (C) 2026 Andres Zanzani <azanzani@gmail.com>
%
% This file may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3c of this license or (at
% your option) any later version.

\documentclass[a4paper,11pt]{article}

\usepackage[margin=2.3cm]{geometry}
\usepackage[T1]{fontenc}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{multicol}
\usepackage{multicoltab}
\usepackage{hyperref}

\hypersetup{
  colorlinks=true,
  linkcolor=blue!50!black,
  urlcolor=blue!50!black,
  pdftitle={The multicoltab package},
  pdfauthor={Andres Zanzani}
}

\newcommand{\pkg}[1]{\textsf{#1}}
\newcommand{\cmd}[1]{\texttt{\textbackslash#1}}
\newcommand{\file}[1]{\texttt{#1}}

\title{The \pkg{multicoltab} package}
\author{Andres Zanzani\thanks{\href{mailto:azanzani@gmail.com}{azanzani@gmail.com}}}
\date{Version 0.6a -- 2026-09-02}

\begin{document}

\maketitle

\begin{abstract}
  \pkg{multicoltab} provides a non-floating table environment whose rows may
  continue in the next column of a \pkg{multicols} layout or on the next page.
  It also works in ordinary one-column text.  Each source row is typeset as an
  independent \texttt{tabularx}, so a break can occur between rows but never in
  the middle of a row.
\end{abstract}

\tableofcontents

\section{Introduction}

The standard table environments are not designed to continue naturally across
the columns produced by \pkg{multicol}.  \pkg{multicoltab} addresses this use
case with a deliberately small interface:

\begin{verbatim}
\begin{multicols}{2}
\begin{multicoltab}{@{}p{1.8cm}X@{}}
  Armor & Reduces the damage received by a character. \\
  Shield & Improves the character's defense. \\
  Torch & Provides light in dark places.
\end{multicoltab}
\end{multicols}
\end{verbatim}

The default table width is the current \cmd{linewidth}.  Therefore, a table
written inside a \pkg{multicols} column normally needs no width adjustment.
Rows are collected before they are printed.  This allows the natural widths of
the \texttt{l}, \texttt{c}, and \texttt{r} columns to be measured over the
complete table and reused in every emitted row.

\section{Relation to \pkg{longtable}}

The standard \pkg{longtable} package is an excellent choice for tables that
continue across ordinary pages. It is not, however, a solution for tables that
must flow through the columns of \pkg{multicols}. \pkg{longtable} modifies
LaTeX's output routine and consequently does not work inside \pkg{multicols};
it also fails on ordinary \texttt{twocolumn} pages. This limitation is stated
in the \pkg{longtable} documentation.

\pkg{multicoltab} addresses this different use case. It does not replace the
output routine. Instead, it emits every source row as an independent
\texttt{tabularx}, so \pkg{multicols} can break between rows and continue in
the next column. The same mechanism also allows rows to continue on later
pages in one-column text. Column widths for natural columns are measured over
the complete body before any row is emitted.

The packages should therefore be chosen according to the required layout.
Use \pkg{longtable} for a conventional full-width multi-page table when its
captions, page headers and footers, or footnote support are needed. Use
\pkg{multicoltab} for a non-floating table or list that must flow through
\pkg{multicols}, with optional explicit column or page continuations and
heading repetition. \pkg{multicoltab} deliberately does not provide all of
\pkg{longtable}'s features, and a source row remains its smallest unbreakable
unit.

\section{Installation and requirements}

Copy \file{multicoltab.sty} into the document directory for a local
installation, or install it in the user's or local TeX tree.  The package
automatically loads \pkg{xparse}, \pkg{array}, \pkg{tabularx}, and
\pkg{keyval}.  Load \pkg{multicol} separately when the \texttt{multicols}
environment is needed:

\begin{verbatim}
\usepackage{multicol}
\usepackage{multicoltab}
\end{verbatim}

The package is intended for LaTeX2e with a current expl3 implementation.  The
examples in this distribution have been tested with pdfLaTeX.

\section{The basic environment}

The complete interface is:

\begin{verbatim}
\begin{multicoltab}[<options>]{<column specification>}
  <rows>
\end{multicoltab}
\end{verbatim}

Every normal row uses the usual syntax:

\begin{verbatim}
left cell & right cell \\
\end{verbatim}

The final \texttt{\textbackslash\textbackslash} is optional.  A
\texttt{\textbackslash\textbackslash} inside braces is not treated as
the end of an outer row.  Use \cmd{newline} for a line break
inside a cell.  A row is the smallest unbreakable unit; if it is taller than
the available space, the complete row moves to the next column or page.

Here is a live example.  The heading and the first few rows are ordinary
content of the package environment:

\begin{multicols}{2}
\begin{multicoltab}[row-sep=2pt]{@{}p{1.8cm}X@{}}
  \mchead[\toprule][\midrule]{\textbf{Item} & \textbf{Description}} \\
  Armor & Reduces the damage received by a character. \\
  Shield & Improves the character's defense. \\
  Torch & Provides light in dark places.
\end{multicoltab}
\end{multicols}

\section{Options}

The optional argument is a comma-separated key list.

\begin{center}
\begin{tabular}{@{}lll@{}}
  \toprule
  Option & Default & Effect \\
  \midrule
  \texttt{width} & \cmd{linewidth} & Width of every emitted row. \\
  \texttt{row-sep} & \texttt{0pt} & Vertical space after each row. \\
  \texttt{break-penalty} & \texttt{0} & Preference for breaking after a row. \\
  \bottomrule
\end{tabular}
\end{center}

For example:

\begin{verbatim}
\begin{multicoltab}[width=.96\linewidth,row-sep=.6ex,
                    break-penalty=50]{@{}p{.3\linewidth}X@{}}
  Short label & A longer description that may wrap. \\
  Another label & Another description.
\end{multicoltab}
\end{verbatim}

The \texttt{break-penalty} value affects normal rows only.  A heading is kept
with the following row regardless of this value.

\section{Column specifications}

The mandatory argument accepts the following direct column tokens:

\begin{center}
\begin{tabular}{@{}ll@{}}
  \toprule
  Specification & Meaning \\
  \midrule
  \texttt{l}, \texttt{c}, \texttt{r} & Natural-width aligned columns. \\
  \texttt{p\{width\}} & Fixed-width, top-aligned paragraph column. \\
  \texttt{m\{width\}} & Fixed-width, vertically centered paragraph column. \\
  \texttt{b\{width\}} & Fixed-width, bottom-aligned paragraph column. \\
  \texttt{X} & Paragraph column using the remaining table width. \\
  \texttt{w}, \texttt{W} & Fixed-width single-line columns. \\
  \bottomrule
\end{tabular}
\end{center}

Array separators and modifiers remain available:
\texttt{>\{...\}}, \texttt{<\{...\}}, \texttt{@\{...\}},
\texttt{!\{...\}}, and \texttt{|}.  For example:

\begin{verbatim}
\begin{multicoltab}{@{}p{2cm}|>{\centering\arraybackslash}X|X@{}}
  Name & First value & Second value \\
  Armor & 2 & 5
\end{multicoltab}
\end{verbatim}

Multiple \texttt{X} columns share the available width.  Relative widths can
be assigned with the usual \cmd{hsize} technique:

\begin{verbatim}
\begin{multicoltab}
  {>{\hsize=.5\hsize}X>{\hsize=1.5\hsize}X}
  Short label & A wider description column.
\end{multicoltab}
\end{verbatim}

The repeated-column form \texttt{*\{n\}\{...\}} is not supported by the
column measurement pass; write repeated columns explicitly.  Custom column
type aliases are likewise not expanded while columns are measured.

The usual \pkg{array} parameters are available.  In particular:

\begin{center}
\begin{tabular}{@{}lll@{}}
  \cmd{tabcolsep} & \cmd{arraystretch} & \cmd{extrarowheight} \\
  \cmd{arrayrulewidth} & \cmd{doublerulesep} & \cmd{extracolsep}
\end{tabular}
\end{center}

Packages such as \pkg{booktabs} and \pkg{xcolor} provide their normal rule
and row-colour commands when loaded by the document.

\section{Headings}

Use \cmd{mchead} to declare and print a heading:

\begin{verbatim}
\mchead{\textbf{Item} & \textbf{Description}} \\
Armor & Reduces damage. \\
Shield & Improves defense.
\end{verbatim}

The heading is kept with its following row.  Optional material may be placed
before and after the heading cells, which is useful for rules:

\begin{verbatim}
\mchead[\toprule][\midrule]
  {\textbf{Item} & \textbf{Description}} \\
\end{verbatim}

The last declared heading can be printed again in place with
\cmd{mcheadrepeat}:

\begin{verbatim}
\mcheadrepeat \\
\end{verbatim}

Both \cmd{mchead} and \cmd{mcheadrepeat} must be complete source rows and
must end with \texttt{\textbackslash\textbackslash}.  A normal row can be
formatted with the usual table
commands immediately before its cells.  For example, when \pkg{xcolor} is
loaded:

\begin{verbatim}
\rowcolor{gray!20}
Rope & Useful for climbing and tying equipment. \\
\end{verbatim}

\section{Explicit continuation}

Automatic heading repetition at every arbitrary \pkg{multicols} break is not
reliable, because \pkg{multicol} decides its column break after receiving the
rows.  Use an explicit continuation when a repeated heading is required.

Inside \pkg{multicols}, \cmd{multicoltabbreak} forces the next column and
repeats the last declared heading:

\begin{verbatim}
\begin{multicols}{2}
\begin{multicoltab}{@{}p{1.8cm}X@{}}
  \mchead{\textbf{Item} & \textbf{Description}} \\
  Armor & Reduces damage. \\
  \multicoltabbreak \\
  Torch & Provides light.
\end{multicoltab}
\end{multicols}
\end{verbatim}

Outside \pkg{multicols}, \cmd{multicoltabpagebreak} forces the next page and
repeats the heading:

\begin{verbatim}
\begin{multicoltab}{@{}p{1.8cm}X@{}}
  \mchead{\textbf{Item} & \textbf{Description}} \\
  Map & Helps avoid getting lost. \\
  \multicoltabpagebreak \\
  Rations & Food and water for the journey.
\end{multicoltab}
\end{verbatim}

Both continuation commands require an earlier \cmd{mchead}.  Do not use
\cmd{multicoltabpagebreak} inside \pkg{multicols}; use
\cmd{multicoltabbreak} there instead.

\section{Limitations}

\begin{itemize}
  \item The package does not assume two columns.  It works with every
    \texttt{multicols} column count of at least two.
  \item A row cannot break internally.  Very tall rows are moved as a whole.
  \item \cmd{multirow} across source rows is not supported.
  \item Floats, captions, and footnotes retain the normal restrictions of
    \pkg{multicols}.
  \item The complete body is collected before rows are emitted.  Avoid
    verbatim material such as \cmd{verb} in cells; use a verbatim-safe command
    from another package when necessary.
\end{itemize}

\section{Files in this distribution}

\begin{center}
\begin{tabular}{@{}ll@{}}
  \toprule
  File & Purpose \\
  \midrule
  \file{multicoltab.sty} & The package file. \\
  \file{multicoltab-doc.tex} & Source of this documentation. \\
  \file{multicoltab-doc.pdf} & PDF documentation. \\
  \file{README.md} & Short package overview and quick reference. \\
  \file{LICENSE} & License notice. \\
  \file{*-example.tex} & Small usage examples. \\
  \file{*-example.pdf} & Compiled output of the examples. \\
  \bottomrule
\end{tabular}
\end{center}

\section{License and contact}

This work is released under the LaTeX Project Public License, version 1.3c or
later.  The license text is included in \file{LICENSE} and is available at
\url{https://www.latex-project.org/lppl/}.

Questions, bug reports, and suggestions may be sent to
\href{mailto:azanzani@gmail.com}{azanzani@gmail.com}.

\end{document}