*! version 1.3 16apr2024
help styletextab https://github.com/gaksaray/stata-gautils/

Title

styletextab -- Restyle LaTeX tables exported by the collect suite of commands

Syntax

styletextab
[using filename]
[, saving(filename [, replace]) options]

tableonly keep only the LaTeX table environment

fragment keep only the LaTeX tabular environment

[no]booktabs specify whether to use LaTeX booktabs rules (default is booktabs)

label(styletextab##marker:marker) label the table for cross-referencing

lscape wrap the table in a LaTeX landscape environment

usepackage(pkg[, pkg_opts]) load a LaTeX package

beforetext(strlist) add text before table

aftertext(strlist) add text after table

pt(#) set the size of the main font used in the document

papersize(papersize) set the paper size

tabsize(fontsize) set the size of the font used in the table

pkg_opts

opt(styletextab##optlist:optlist)|opts(optlist) specify the list of options for the LaTeX package loaded

pre specify whether the LaTeX package should be loaded at the beginning of the preamble right after \documentclass{} (default is to add it to the end of the preamble)

nextlines(strlist) add line(s) of text after the package is loaded

marker specifies a valid LaTeX reference marker as in \label.

optlist specifies a set of valid options for the LaTeX package loaded.
Multiple options are delimited by comma as in LaTeX code.
The output will be in the form

\usepackage[opt1,opt2,...]

if opt() is used;
or in the form

\usepackage[

opt1,

opt2,

...

]

if opts() is used.

Description

styletextab improves the appearance and formatting of default LaTeX tables
exported by the collect suite of commands.
It integrates advanced LaTeX packages such as
booktabs (for better vertical spacing around horizontal rules),
threeparttable (for refined formatting of table notes), and
pdflscape (for landscape tables accommodating wider data displays).

Typically, styletextab is executed immediately after collect exports.
However, it can also be applied to any .tex file specified by the using option.
It can save the output to any .tex file specified by the saving() option.
The file suffixes are optional, as .tex is assumed by default.
If the using option is not provided,
styletextab assumes the intention to modify the most recently exported LaTeX table.
Similarly, if the saving() option is omitted,
styletextab assumes the intention to overwrite the original file.

Options

tableonly keeps the table section only (and discards the rest):

\begin[!h]

...

\end

The resulting .tex file can be included in a LaTeX document via \input macro.

fragment keeps the tabular section only (and discards the rest):

\begin

...

\end

The resulting .tex file can be manually wrapped inside a custom table environment in a LaTeX document via \input macro.

[no]booktabs replaces the default \cline with the \cmidrule macro from LaTeX's booktabs package.

label(marker) adds an additional line right after \caption with \label macro specifying the label marker for the table. This is used for cross-referencing the table within a LaTeX document.

lscape invokes LaTeX's pdflscape package to wrap the table in a landscape layout. This makes it easier to view tables that are too wide to fit in a portait page (for example, a regression comparison table with more than 5-6 models).

usepackage(pkg[, pkg_opts]) specifies a LaTeX package to be included in the document.
usepackage() may be specified multiple times to add packages in the specified order.

pkg_opts are
opt(styletextab##optlist:optlist) or opts(optlist),
pre, and
nextlines(strlist).

opt(styletextab##optlist:optlist) specifies the set of options for the LaTeX package loaded.
opts() is the multiline version of opt(), putting each option to its own line,
which is useful for quickly commenting and uncommenting distinct options to see their effects.

pre specifies whether the LaTeX package should be loaded at the beginning of the preamble (the default is to load the package at the end of the preamble).

nextlines(strlist) adds the text string to the next line.
Multiple lines can be added by using double quotes,
i.e., specify strlist as "First line" "Second line" etc.

beforetext(strlist) and aftertext(strlist)
add text before and after the table
(relevant only if fragment and tableonly options are omitted).
Multiple lines of text can be added by using double quotes,
i.e., specify strlist as "First line" "Second line" etc.
beforetext() and aftertext() may also be repeated
to add multiple paragraphs separated by an empty line.

Either option, when specified, automatically defines
two new LaTeX macros
\sq{} and \dq{}
for single quotation and double quotation, respectively.
These allow for using quotations within text.
Otherwise, local and global macros can be used
within text as usual.

pt(#) sets the point size of the main font used in the document.
# can be one of 10, 11, or 12.

papersize(papersize) sets the paper size of the document.
papersize can be any paper size allowed by the article document class.
Common options are a4 for A4 paper, legal for Legal paper, and letter for Letter paper.

tabsize(fontsize) sets the size of the font used in the table.
fontsize can be one of tiny, scriptsize, footnotesize,
small, normalsize, large, Large, LARGE, huge, and Huge.

Remarks

Stata 17 introduced the collect suite of commands
(collect, table, etable, and, as of version 18, dtable),
all of which can export tables as LaTeX files.
By default, the output is a standalone compilable document.
TeX export options include tableonly
for exporting only the table environment,
which can be included in a LaTeX document using the \input macro.
Additionally, TeX style options include
begintable for specifying whether to use the table environment
or retain only the tabular environment,
and centering for specifying whether to center table horizontally
on the page using the \centering macro.
Although it is possible to produce a fragment (i.e., tabular-only) table
and wrap it in a custom table environment in a separate document,
the default standalone document mode is convenient for
quickly assessing the appearance of the LaTeX tables.

However, the default output of the collect suite of commands
has several basic visual imperfections:
horizontal lines are drawn by \cline,
footnotes are centered by default and do not have the same width as the table,
and there is no option to rotate the table.
styletextab addresses these issues.
It replaces \cline with the \cmidrule of the
booktabs package for aesthetically pleasing vertical spacing.
It also wraps footnotes within the \tablenotes environment of the
threeparttable package for proper formatting.
Additionally, styletextab offers an option to rotate tables
(i.e., switch to landscape layout)
by wrapping tables within the \landscape environment of
pdflscape package.

styletextab
is extensible as other LaTeX packages can be added to further customize the preamble
(for example,
geometry
to change the page layout).
It also allows for simple reporting with the ability to add text before or after the table.

styletextab operates by dissecting a .tex table file into its constituent sections
and utilizing file commands to reformat and improve the look of the tables.
An advantage of styletextab is its ability to transition seamlessly between
different modes without the need to recreate the table from scratch.
For example, one can go from portrait to landscape mode and then back to portrait
mode without needing to re-export the table at each step.

Examples

Export a collect table as .tex file:

. sysuse auto, clear

. regress price mpg

. estimates store m1

. regress price mpg i.foreign

. estimates store m2

. etable, estimates(m1 m2) mstat(N) column(index) ///

> showstars showstarsnote ///

> title("Table title") ///

> note("Note: Table notes go here.") ///

> export(mytable.tex, replace)

Restyle with default settings (booktabs + threeparttable):

. styletextab

Switch to landscape and save it as a different file:

. styletextab using mytable, saving(mytable_lscape) lscape

Add a label marker and some text before and after the table:

. styletextab, ///

> label(fig:reg1) ///

> before(Table~\refreg1 presents regressions.) ///

> after(This text comes after Table~\refreg1.)

Change the page and font sizes:

. styletextab, ///

> pt(11) paper(a4) ///

> tabsize(small) ///

> label(fig:reg1) ///

> before(Table~\refreg1 presents regressions.) ///

> after(This text comes after Table~\refreg1.)

Add multiple paragraphs of text and increase page margins:

. styletextab, ///

> pt(11) paper(a4) ///

> tabsize(small) ///

> label(fig:reg1) ///

> usepackage(geometry, opt(margin=1in) pre) ///

> usepackage(lipsum, nextl(%Preamble ends here!)) ///

> usepackage(parskip, pre) ///

> before(\section*) ///

> before("Table~\refreg1 presents regressions." ///

> "These regressions are very interesting." \lipsum[1]) ///

> before(Let's see how \dq look:) ///

> after(This text comes after Table~\refreg1. \lipsum[2]) ///

> after(\lipsum[3])

Keep the table environment only:

. styletextab, tableonly

(going back to the standalone document format from mytable.tex would retain the caption and footnotes)

Keep the tabular environment only:

. styletextab, fragment

(going back to the standalone document format from mytable.tex would discard the caption and footnotes)

Author

Gorkem Aksaray, Trinity College Dublin.

Email: aksarayg@tcd.ie

Personal Website: sites.google.com/site/gorkemak

GitHub: github.com/gaksaray