{smcl}
{.-}
help for {cmd:listtex} {right:(Roger Newson)}
{.-}
 
{title:List a variable list to a file or to the log for inclusion in a TeX, HTML or word processor table}

{p 8 21 2}
{cmd:listtex} [ {varlist} ] [ {helpb using} {it:filename} ] {ifin}
 [ , {cmdab:b:egin}{cmd:(}{it:string}{cmd:)} {cmdab:d:elimiter}{cmd:(}{it:string}{cmd:)}
  {cmdab:e:nd}{cmd:(}{it:string}{cmd:)} {cmdab:m:issnum}{cmd:(}{it:string}{cmd:)}
  {cmdab:rs:tyle}{cmd:(}{it:rowstyle}{cmd:)}
  {cmdab:he:adlines}{cmd:(}{it:string_list}{cmd:)} {cmdab:fo:otlines}{cmd:(}{it:string_list}{cmd:)}
  {cmdab:nol:abel} {cmdab:t:ype} {cmdab:replace:}
  {cmdab:ap:pendto}{cmd:(}{it:filename}{cmd:)} {cmdab:ha:ndle}{cmd:(}{it:handle_name}{cmd:)} ]


{title:Description}

{pstd}
{cmd:listtex} lists the variables in the {varlist} (or all variables, if {varlist}
is absent) to the Stata log, or to a file (or files) specified by {helpb using}, {cmd:appendto()} or {cmd:handle()},
in a format with one line 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 lines
and/or a list of footer lines after the data lines. The log or output file can then
be cut and pasted, or linked or embedded (eg with the TeX  {cmd:\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 {cmd:missnum()} (if missing).


{title:Options}

{p 4 8 2}{cmd:begin(}{it:string}{cmd:)} 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.

{p 4 8 2}{cmd:delimiter(}{it:string}{cmd:)} specifies the delimiter between values in an observation.
If absent, it is set to "&".

{p 4 8 2}{cmd:end(}{it:string}{cmd:)} 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.

{p 4 8 2}{cmd:missnum(}{it:string}{cmd:)} specifies a string to be output for numeric missing values.
If absent, it is set to an empty string.

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

{p 4 8 2}{cmd:headlines(}{it:string_list}{cmd:)} 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.

{p 4 8 2}{cmd:footlines(}{it:string_list}{cmd:)} 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.

{p 4 8 2}{cmd:nolabel} specifies that numeric variables with variable labels are to be output as
numbers and not as labels.

{p 4 8 2}{cmd:type} specifies that the output from {cmd: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.

{p 4 8 2}{cmd:replace} specifies that any existing file with the same name as the {helpb using}
file must be overwritten.

{p 4 8 2}{cmd:appendto(}{it:filename}{cmd:)} specifies the name of a file,
to which the output from {cmd:listtex} will be appended.

{p 4 8 2}{cmd:handle(}{it:handle_name}{cmd:)} 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 {cmd:listtex} will be added, without closing the file.
See help for {helpb file} for details about file handles, This option allows the user to use {cmd:listtex}
together with {helpb file} as a low-level output utility, possibly combining {cmd:listtex} output with
other output.

{p 4 8 2}Note that the user must specify the {helpb using} qualifier and/or the {cmd:type} option
and/or the {cmd:appendto()} option and/or the {cmd:handle()} option.


{title:Row styles}

{pstd}
A row style is a combination of the {cmd:begin()}, {cmd:end()},
{cmd:delimiter()} and {cmd: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:

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

{pstd}
The {cmd:tabdelim} row style produces text rows delimited by the tab character,
returned by the {help strfun:char() function} as {cmd:char(9)}.
It should be used with {helpb using}, or with the {cmd:appendto()} or {cmd:handle()} options,
to output the table rows to a file. It should not be used with the {cmd: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 {cmd:begin()} and/or {cmd:delimiter()}
and/or {cmd:end()} and/or {cmd: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 {cmd:missnum(-)}, and
then missing numeric values will be given as minus signs.


{title:Remarks}

{p 0 0}
{cmd: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 {cmd:headline()} and
{cmd: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
{cmd:delimiter()} string, with the optional {cmd:begin()} string on the left and the optional
{cmd: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 {cmd: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 {hi:\input} command) into a document.
The {helpb inccat} command, available on {help ssc:SSC}, can be used to embed a {helpb using}
file produced by {cmd:listtex} into a document. If all the variables are string, then title rows
may sometimes be created using the {helpb ingap} package, also on {help ssc:SSC}, instead
of using the {cmd:headlines()} option of {cmd:listtex}.
For more about the use of {cmd:listtex} with other packages,
see Newson (2003), Newson (2004) and Newson (2006).

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


{title:Examples}

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

{p 16 20}{cmd:. listtex make foreign weight mpg, type}{p_end}

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

{p 16 20}{cmd:. listtex make foreign weight mpg using trash1.txt, rstyle(tabdelim)}{p_end}

{p 0 0} To produce TeX table lines for a plain TeX {cmd:\halign} table:

{p 16 20}{cmd:. listtex make foreign weight mpg using trash1.tex, rs(halign) replace}{p_end}

{p 0 0} To produce TeX table lines for a plain TeX {cmd:\halign} table with
horizontal and vertical rules:

{p 16 20}{cmd:. listtex make foreign weight mpg using trash1.tex, b(&&) d(&&) e(&\cr{\noalign{\hrule}}) replace}{p_end}

{p 0 0} To produce TeX table lines for a plain TeX {cmd:\settabs} table:

{p 16 20}{cmd:. listtex make foreign weight mpg using trash1.tex, rstyle(settabs) replace}{p_end}

{p 0 0} To produce LaTeX table lines for the LaTeX {cmd:tabular} environment:

{p 16 20}{cmd:. listtex make foreign weight mpg using trash1.tex, rstyle(tabular) replace}{p_end}

{p 0 0} To produce a LaTeX {hi:tabular} environment with a title line, for cutting and pasting into a document:

{p 16 20}{cmd:. listtex make weight mpg if foreign, type rstyle(tabular) head("\begin{tabular}{rrr}" "\textit{Make}&\textit{Weight (lbs)}&\textit{Mileage (mpg)}\\\\") foot("\end{tabular}")}{p_end}

{p 0 0} Note that the user must specify the double {hi:\\} at the end of a LaTeX line by {hi:\\\\},
because, inside Stata strings, a double backslash is interpreted as a single backslash.

{p 0 0} To produce HTML table rows for insertion into a HTML table:

{p 16 20}{cmd:. listtex make foreign weight mpg using trash1.htm, rstyle(html) replace}{p_end}

{p 0 0} To produce a HTML table for cutting and pasting into a HTML document:

{p 16 20}{cmd:. listtex make weight mpg if foreign, type rstyle(html) head(`"<table border="1">"' "<tr><th>Make</th><th>Weight (lbs)</th><th>Mileage (mpg)</th></tr>") foot("</table>")}{p_end}


{title:Author}

{pstd}
Roger Newson, Imperial College London, UK.
Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk}


{title:References}

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

{phang}
Newson, R.  2004.
From datasets to resultssets in Stata.
Presented at {browse "http://ideas.repec.org/s/boc/usug04.html" :the 10th United Kingdom Stata Users' Group Meeting, London, 29 June, 2004}.
Also downloadable from
{net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}.

{phang}
Newson, R.  2006. 
Resultssets, resultsspreadsheets and resultsplots in Stata.
Presented at {browse "http://ideas.repec.org/s/boc/dsug06.html" :the 4th German Stata User Meeting, Mannheim, 31 March, 2006}.
Also downloadable from
{net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}.


{title:Also see}

{p 4 13 2}
{bind: }Manual: {hi:[P] file}, {hi:[D] insheet}, {hi:[D] list}, {hi:[D] outsheet}, {hi:[D] type}
{p_end}
{p 4 13 2}
On-line: help for {helpb file}, {helpb insheet}, {helpb list}, {helpb ssc}, {helpb outsheet}, {helpb type}{break}
help for {helpb estout}, {helpb inccat}, {helpb ingap}, {helpb outtable}, {helpb outtex}, {helpb textab}, {helpb sutex} if installed
{p_end}
{p 4 13 2}
{bind:  }Other: {hi:Knuth D. E. 1992. The TeXbook. Reading, Mass: Addison-Wesley.}{break}
{hi:Lamport L. 1994. LaTeX: a document preparation system. 2nd edition. Boston, Mass: Addison-Wesley.}{break}
{browse "http://www.w3.org/MarkUp/":The W3C HyperText Markup Language (HTML) Home Page at http://www.w3.org/MarkUp/}
{p_end}