help for listtex (Roger Newson)

List a variable list to a file or to the log for inclusion in a TeX, HTML or word processor table

listtex [ varlist ] [ using filename ] [if] [in] [ ,

begin(string) delimiter(string)
end(string) missnum(string)
rstyle(rowstyle)

headlines(string_list) footlines(string_list)
nolabel type replace
appendto(filename) handle(handle_name)
]

listtex_vars [ varlist ] [ ,

begin(string) delimiter(string)
end(string) missnum(string)
rstyle(rowstyle)

substitute(variable_attribute) local(local_macro_name)
]

listtex_rstyle [ ,
begin(string) delimiter(string)
end(string) missnum(string)
rstyle(rowstyle)
]

where rowstyle is a row style as defined below under Row Styles,

variable_attribute is

name | type | format | vallab | varlab | char charname

and charname is a characteristic name.

Description

listtex lists the variables in the varlist (or all variables, if the varlist
is absent) to the Stata log, or to a file (or files) specified by using, appendto() or handle(),
in a table format, with one table row per observation and the values of different variables separated by a delimiter string.
Optionally, the user may specify a list of header lines before the data rows
and/or a list of footer lines after the data rows.
The log or output file can then
be cut and pasted, or linked or embedded (eg with the TeX \input command),
into a TeX, HTML or word processor table.
Values of numeric variables are output according to their display formats or value labels (if non-missing),
or as the missing value string specified by missnum() (if missing).

The commands listtex_vars and listtex_rstyle are tools for programmers to use with listtex.
listtex_vars generates a table row, containing, in each column,
an attribute (such as the name) of the variable corresponding to the column.
This generated table row is saved in r(vars) and (optionally) in a local macro,
and is then typically used to specify a headlines() option for listtex.
listtex_rstyle inputs a listtex row style,
and saves in r() the components of the row style.

Users of Stata Versions 11 or higher should probably not use listtex.
Instead, they should probably use the listtab package, which can be downloaded from SSC,
and was introduced as the Stata Version 11 replacement for listtex.

Options for listtex, listtex_vars, and listtex_rstyle

begin(string) specifies a string to be output at the beginning of every
output line corresponding to an observation. If absent, it is set to an empty string.

delimiter(string) specifies the delimiter between values in an observation.
If absent, it is set to "&".

end(string) specifies a string to be output at the end of every
output line corresponding to an observation. If absent, it is set to an empty string.

missnum(string) specifies a string to be output for numeric missing values.
If absent, it is set to an empty string.

rstyle(rowstyle) specifies a row style for the table rows.
A row style is a named combination of values
for the begin(), end(), delimiter() and missnum() options.
It may be html, htmlhead, tabular, halign,
settabs or tabdelim.
Row styles are specified under Row styles below.
The options set by a row style
may be overridden by the begin(), end(), delimiter() and missnum() options.

Options for listtex only

headlines(string_list) specifies a list of lines of text to appear before the first
of the table rows in the output.
This option enables the user to add table preludes and/or headers.

footlines(string_list) specifies a list of lines of text to appear after the last
of the table rows in the output.
This option enables the user to add table postludes and/or footnotes.

nolabel specifies that numeric variables with variable labels are to be output as
numbers and not as labels.

type specifies that the output from listtex must be typed to the Stata log
(or to the Results window).
The data can then be cut and pasted from the Stata log (or from the Results window)
to a TeX, HTML or word processor file.

replace specifies that any existing file with the same name as the using
file must be overwritten.

appendto(filename) specifies the name of a file,
to which the output from listtex will be appended.

handle(handle_name) specifies the name of a file handle,
specifying a file that is already open for output as a text file,
to which the output from listtex will be added, without closing the file.
See help for file for details about file handles.
This option allows the user to use listtex
together with file as a low-level output utility, possibly combining listtex output with
other output.

Note that the user must specify the using qualifier and/or the type option
and/or the appendto() option and/or the handle() option.

Options for listtex_vars only

substitute(variable_attribute) specifies a variable attribute
to be entered into the columns of the generated table row.
This attribute may be
name, type, format, vallab, varlab, or char charname,
specifying the variable name, storage type, display format,
value label, variable label,
or a named variable characteristic, respectively.
If substitute() is not specified, then substitute(name) is assumed,
and variable names are entered in the columns of the generated table row.
In the table row generated by listtex_vars,
the attributes of the variables in the varlist (or of all the variables, if the varlist is absent)
appear in the columns,
and are separated by the delimiter() string, and prefixed by the begin() and end() strings,
specified by the row style.

local(local_macro_name) specifies the name of a local macro
in the program that calls listtex_vars.
This macro will be assigned the value of the row of variable attributes generated by listtex_vars.
Whether or not local() is specified,
listtex_vars saves the generated table row in r(vars).
The local() option has the advantage that the user can save multiple header rows in multiple local macros.
For instance, the user might want two header rows, one containing variable names, and the other containing variable labels.

Row styles

A row style is a combination of the begin(), end(),
delimiter() and missnum() options. Each row style produces rows for a particular
type of table (HTML, TeX or word processor). The row styles available are as follows:

Row style begin delimiter end missnum Description
html "<tr><td>" "</td><td>" "</td></tr>" "" HTML table rows
htmlhead "<tr><th>" "</th><th>" "</th></tr>" "" HTML table header rows
tabular "" "&" `"\\"' "" LaTeX \tabular environment table rows
halign "" "&" "\cr" "" Plain TeX \halign table rows
settabs "\+" "&" "\cr" "" Plain TeX \settabs table rows
tabdelim "" char(9) "" "" Tab-delimited text file rows

The tabdelim row style produces text rows delimited by the tab character,
returned by the char() function as char(9).
It should be used with using, or with the appendto() or handle() options,
to output the table rows to a file. It should not be used with the type option, because the tab character
is not preserved in the Stata log or Results window.
Any of these row styles may be specified together with begin() and/or delimiter()
and/or end() and/or missnum() options, and the default options for the row style
will then be overridden. For instance, the user may specify any of the above options with missnum(-), and
then missing numeric values will be given as minus signs.

Remarks

listtex creates (either on disk or in the Stata log and/or Results window) a text table with up to 3
kinds of rows. These are headline rows, data rows and footline rows.
Any of these categories of rows may be empty.
The headline and footline rows can be anything the user specifies in the headline() and
footline() options, respectively. This allows the user to specify TeX preambles, LaTeX
environment delimiters, HTML table delimiters and header rows, or other headlines and/or footlines
for table formats not yet invented. The data rows must contain variable values, separated by the
delimiter() string, with the optional begin() string on the left and the optional
end() string on the right. This general plan allows the option of using the same package
to generate TeX, LaTeX, HTML, Microsoft Word, and possibly other tables. The rstyle()
option saves the user from having to remember other options. The text table generated can then
be cut and pasted, embedded, or linked (eg with the TeX \input command) into a document.
The inccat command, available on SSC, can be used to embed a using
file produced by listtex into a document. If all the variables are string, then title rows
may sometimes be created using the ingap package, also on SSC, instead
of using the headlines() option of listtex.
For more about the use of listtex with other packages,
see Newson (2006), Newson (2004), and Newson (2003).

The ssc, findit or net commands can also be used to find the various
alternatives to listtex, such as textab, outtex, sutex, outtable
and estout,
which also produce tables from Stata.

Examples

To type text table lines separated by & characters for cutting and pasting into a
Microsoft Word table using the menu sequence Table->Convert->Text to Table:

. listtex make foreign weight mpg, type

To output text table lines separated by tab characters to a text file
for cutting and pasting into a
Microsoft Word table using Table->Convert->Text to Table:

. listtex make foreign weight mpg using trash1.txt, rstyle(tabdelim)

To produce TeX table lines for a plain TeX \halign table:

. listtex make foreign weight mpg using trash1.tex, rs(halign) replace

To produce TeX table lines for a plain TeX \halign table with
horizontal and vertical rules:

. listtex make foreign weight mpg using trash1.tex, b(&&) d(&&) e(&\cr{\noalign{\hrule}}) replace

To produce TeX table lines for a plain TeX \settabs table:

. listtex make foreign weight mpg using trash1.tex, rstyle(settabs) replace

To produce LaTeX table lines for the LaTeX tabular environment:

. listtex make foreign weight mpg using trash1.tex, rstyle(tabular) replace

To produce a LaTeX tabular environment with a title line, for cutting and pasting into a document:

. listtex make weight mpg if foreign, type rstyle(tabular) head("\begin" `"\textit&\textit&\textit\\"') foot("\end")

Note that the user must specify compound quotes `""'
around strings in the head() option containing the double backslash \\ at the end of a LaTeX line.
This is because, inside Stata strings delimited by simple quotes "",
a double backslash is interpreted as a single backslash.

To produce HTML table rows for insertion into a HTML table:

. listtex make foreign weight mpg using trash1.htm, rstyle(html) replace

To produce a HTML table for cutting and pasting into a HTML document:

. listtex make weight mpg if foreign, type rstyle(html) head(`"<table border="1">"' "<tr><th>Make and Model</th><th>Weight (lbs)</th><th>Mileage (mpg)</th></tr>") foot("</table>")

To produce the same HTML table, using listtex_vars:

. listtex_vars make weight mpg, substitute(varlab) rstyle(htmlhead) local(headrow)

. listtex make weight mpg if foreign, type rstyle(html) head(`"<table border="1">"' `"`headrow'"') foot("</table>")

To produce a HTML table of variable attributes using listtex_vars with the descsave package
(an extended version of describe downloadable from SSC):

. preserve

. descsave, norestore

. list, noobs abbr(32) subvarname

. listtex_vars, rstyle(htmlhead) substitute(char varname)

. listtex, type rstyle(html) head("<table frame=box>" "`r(vars)'") foot("</table>")

. restore

Saved results

listtex_rstyle saves the following in r():

Macros

r(begin) begin() string

r(delimiter) delimiter() string

r(end) end() string

r(missnum) missnum() string

listtex_vars saves the above items in r(),
and also the following:

Macros

r(vars) generated table row

Author

Roger Newson, Imperial College London, UK.
Email: r.newson@imperial.ac.uk

References

Newson, R. 2006.
Resultssets, resultsspreadsheets and resultsplots in Stata.
Presented at the 4th German Stata User Meeting, Mannheim, 31 March, 2006.
Also downloadable from
Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Newson, R. 2004.
From datasets to resultssets in Stata.
Presented at the 10th United Kingdom Stata Users' Group Meeting, London, 29 June, 2004.
Also downloadable from
Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Newson, R. 2003.
Confidence intervals and p-values for delivery to the end user.
The Stata Journal 3(3): 245-269.
Pre-publication draft downloadable from
Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Also see

Manual: [D] describe, [P] file, [D] insheet, [D] list, [D] outsheet, [D] type

On-line: help for describe, file, insheet, list, ssc, outsheet, type

help for descsave, estout, inccat, ingap, outtable, outtex, textab, sutex,
listtab if installed

Other: Knuth D. E. 1992. The TeXbook. Reading, Mass: Addison-Wesley.

Lamport L. 1994. LaTeX: a document preparation system. 2nd edition. Boston, Mass: Addison-Wesley.

The W3C HyperText Markup Language (HTML) Home Page at http://www.w3.org/MarkUp/