help sttexhttp://github.com/benjann/sttex/

Title

sttex -- Integrate Stata results into a LaTeX document

Syntax -
Description -
Dynamic tags -
Options -
Remarks -
Author -
Also see

Syntax

Process a source file that contains dynamic tags:

sttex [using] srcfile [arguments]
[,
general_options
do_options
gropts(graph_options)
fileopts(file_options)
]

Suffix .sttex is assumed if srcfile is specified without
suffix. srcfile may contain an absolute or relative path.

Extract Stata code from source file:

sttex extract srcfile
[,
saving(tgtfile) replace
]

Register the location of LaTeX executables:

sttex register tex [path]

general_options Description

Main
saving(tgtfile) name of the target LaTeX file; default is
srcname.tex

replace allow overwriting existing files

nocd run Stata commands in current working directory

Stata commands
nostop do not stop processing Stata commands in case of error

more set more on; default is to set more off

rmsg set rmsg on; default is to set rsmg off

Database
reset delete existing database and create new database

nodb do not maintain a database

dbname(dbfile) file name of database; default is srcfile.db

Typesetting
typeset[(#)] create a PDF (using an external LaTeX compiler)

view[(#)] like typeset(), but additionally view the PDF

jobname(name) custom base name for PDF file

cleanup remove auxiliary files left behind by the LaTeX compiler

[no]bibtex override whether BibTeX is applied or not

[no]makeindex override whether makeindex is applied or not

do_options Description

Main
[no]do enforce or suppress running the Stata commands

[no]certify compare results against previous
version; default is nocertify

[no]dosave store a copy of the commands in
a do-file; default is nodosave

logdir(path) where to store the log file(s)

dodir(path) where to store the optional do-file

Runtime options
linesize(#) set the line width for the results log

[no]trim[(#)] remove indentation of code block; default
is trim

[no]output suppress command output in results log; default is output

Log options
log_options options affecting formatting and embedding of log

log_options Description

Main
[no]code display code log rather than
results log; default is nocode

range(from [to]) select range of lines from log

ltag(matchlist) enclose lines in custom tags

tag(matchlist) enclose strings in custom tags

alert(strlist) enclose strings in \alert{}

substitute(matchlist) apply string substitutions

[no]lb remove line break comments; default is lb

[no]gt remove continuation symbols; default is gt

[no]lnumbers[(str)] add line numbers; requires definition of \stlnum{}

[no]lcontinue continue line numbers from prior log

Results log only
[no]commands strip all command lines from results log; default is commands

[no]prompt remove command prompts; default is prompt

drop(numlist) remove selected commands and their output from the log

cnp(numlist) insert \cnp after selected commands

qui(numlist) remove output from selected commands

oom(numlist) replace output from selected commands by \oom

Code log only
clsize(#) set the line width used by log texman

[no]lskip do not replace blank lines by
\smallskip; default is lskip

[no]texman do not apply log texman; default is
texman

[no]verbatim do not apply log texman and include
code in verbatim environment; default is noverbatim

Embedding
[no]static copy log into target document; default is nostatic

[no]begin[(str)] specify custom begin command for log

[no]end[(str)] specify custom end command for log

[no]beamer use begin tag for beamer class; default is nobeamer

scale(#) rescale the size of the log

blstretch(#) adjust line spacing in the log

graph_options Description

Main
as(fileformats) set output format(s); default is as(pdf)

name(name) name of the graph window to be exported

override(options) format-dependent options; see override_options in
graph export

dir(path) where to store the graph files

Embedding
[no]center center the graph; default is nocenter

args(args) pass-through graph arguments

[no]suffix type the file suffix; default is nosuffix

[no]epsfig use \epsfig{} instead of
\includegraphics{}; default is noepsfig

file_options Description

Main
range(from [to]) select range of lines from file

substitute(matchlist) apply string substitutions

[no]erase remove original file from disk; default is noerase

Embedding
[no]static do not copy contents into target document; default is static

Description

sttex is a command to process a LaTeX source file containing blocks
of Stata code. sttex will extract the Stata commands into a do-file,
run the do-file, and then weave the LaTeX source and the Stata output into a
target LaTeX document. Optionally, sttex also typesets the LaTeX document
and displays the resulting PDF. Various tags can be used within the LaTeX
source file to define the information that will be processed by sttex; see
dynamic tags below.

A main feature of sttex is that it detects whether Stata code changed
between calls. If the code did not change, execution of Stata commands will be skipped
to save computer time. It is also possible to partition a source file into independent
sections, such that only the sections affected by changes will be
executed; see Partition the file into sections below.

Typesetting options of sttex require
a LaTeX distribution to be installed on your computer. Use
sttex register tex path to inform sttex about the location
of LaTeX executables such as pdflatex, makeindex, and
bibtex. To find the correct path on Mac OS or Linux, open a terminal
and type, for example, which pdflatex. For windows, consult the
documentation of your LaTeX distribution. If you use a standard MacTeX
installation on Mac OS, the correct command will probably be

. sttex register tex "/Library/TeX/texbin/"

sttex register tex only has to be applied once on a given system
as sttex remembers the setting between Stata sessions (the setting will
be stored in a file added to the folder in which sttex.ado resides). To
delete the setting, type sttex register tex without argument.

Furthermore, you may want to add stata.sty to the LaTeX
installation. By default, Stata output inserted by sttex will be
enclodsed in environment stlog, which is defined by stata.sty. That
is, stata.sty should be loaded in your document; see
Preamble of LaTeX file below. stata.sty
is provided by Stata Corp as part of sjlatex.

sttex extract is a utility command that can be used to collect all blocks
of Stata code from a source file and store them in a do-file.

sttex requires Stata 11 or newer.

Dynamic tags

LaTeX commands
Run Stata or Mata code (and include results)
Inlcude graph created by code
Include file created by code
Include copy of results or code
Inline expressions
Include external file
Append external file
End of input

Interpreted LaTeX comments
Specify target file and overall options
Set defaults for log environments
Partition the file into sections
Ignore tags
Remove input

Run Stata or Mata code (and display results)

To run a block of Stata commands and, optionally, display the output in the target
file, type

\begin{keyword}[id][do_options]
commands
\end{keyword}
or
\dokeyword{filename}[id][do_options]

where id provides a custom name for the block. The brackets do not
need to be typed if id and options are omitted (but the brackets for id
need to be typed if options are specified). An automatic name is assigned if id
is omitted. The \dokeyword{} syntax is equivalent to
\begin{keyword} ... \end{keyword}, but the commands
are read from filename rather than being provided directly within the
document. filename may contain an absolute or relative path; extension
.do is assumed if filename is specified without suffix.

The \begin{}, \end{}, and \dokeyword{}
tags must start at the beginning of a line and any text in the same line after a tag is
ignored.

keyword may be one of the following:

stata run Stata commands and display the output in the target file

stata* run Stata commands without displaying the output

mata run Mata commands and display the output in the target file

mata* run Mata commands without displaying the output

Within commands (or within filename) you can use the following tags:

//STcnp include a page break and, depending on settings, a
continued-on-next-page message; also see option cnp()

//STqui suppress the output of the subsequent command (Stata code
only); also see option qui()

//SToom suppress the output of the subsequent command and include
an output-omitted message after the command (Stata code only); also see option
oom()

These tags must start at the beginning of a line; text in
the same line after a tag is ignored. //STcnp can be used within
Stata code and Mata code. //STqui and //SToom can only be used in
Stata code; these tags will lead to error if used in Mata code.

Note that \dostata{filename} copies
the commands from filename into the main do-file that will be executed
to evaluate the commands. That is, the commands from filename will be
executed in the same instance as the other commands. If you want to run the
commands from an external file in their own instance, type

\begin[][drop(1 .)]
do filename
\end

where option drop(), as specified, will make the log look like the
commands had been copied into the main do-file.

Inlcude graph created by code

To include a graph created by the preceding code block, type

\stgraph[id]{graph_options}
or
\stgraph*[id]{graph_options}

where id provides a custom name for the graph. The brackets do not need to be typed if
id is omitted. An automatic name based on the name of the prior code block
is assigned if id is omitted. The difference
between \stgraph{} and \stgraph*{} is that the latter only creates
a graph instance, but does not write anything to the target document. You
may use \stres{{graph}} to address
a graph instance created by \stgraph{} or \stgraph*{}.

The \stgraph{} tag must start at the beginning of a line;
any text in the same line after the tag will be ignored. Furthermore,
\stgraph{} is only allowed if there is at least one prior code block
in the current part of the document.

Include file created by code

To collect the contents of a file created by the preceding code block and
include it in the target document, type

\stfile[id]{filename}[file_options]
or
\stfile*[id]{filename}[file_options]

where filename specifies the name of the file to be collected
(possibly including a path); extension .tex is assumed if filename is
specified without suffix. Optional argument id provides a custom name
for the collected file contents. The brackets do not need to be typed if
id is omitted. An automatic name based on the name of the prior code block
is assigned if id is omitted. The difference
between \stfile{} and \stfile*{} is that the latter only creates
an instance of collected file contents, but does not write anything to the target
document. You may use \stres{{file}} to address
an instance created by \stgraph{} or \stgraph*{}.

The \stfile{} tag must start at the beginning of a line;
any text in the same line after the tag will be ignored. Furthermore,
\stfile{} is only allowed if there is at least one prior code block
in the current part of the document.

An example of the use \stfile{} is as follows:

\begin*
sysuse auto
regress price foreign weight
etable, export(example.tex, tableonly)
\end*
\stfile{example.tex}[erase]

In this way the table written by etable will be pasted into the target
document and the file on disk will be removed.

Include copy of results or code

To obtain a copy of the results log or the code log from one or multiple
code blocks, type

\stlog[idlist]{log_options}
or
\stlog*[idlist]{log_options}

where idlist is a space-separated list of the names of the blocks
(the blocks must already exist; referencing a future block is not allowed). The
last block will be used if idlist is omitted (the brackets do not
need to be typed if idlist is omitted). Wildcard characters * and
? are allowed in idlist. For example, \stlog[*]{} will
compile a log from all existing code blocks (in the order in which they appear
in the document). The \stlog{} tag must start at the beginning of a line; any
text in the same line after the tag will be ignored.

\stlog{} is useful if you want to include multiply copies of a log with
different options. For example, you could specify option range(1 10) with the main
copy to print only lines 1-10 and then use \stlog{} with option
range(11 .) to print the remaining lines. Likewise you could
specify option code with the main copy to print the code log and then
print the results log by applying \stlog{} without option code.

The difference between \stlog{} and \stlog*{} is that the latter
only creates an instance of a log, but does not write anything to the target
document. You may use \stres{{log}} to address
an instance of a log created by \stlog{} or \stlog*{}. The
instance will be named id.#, where id is the
name of the (first) code block referenced by idlist and where
# is a counter.

Note that each code block automatically creates a main log instance based
on the log_options specified as part of the do_options of the
block. The main log instance is named id, where id is
the name of the block.

Inline expressions

To add strings and values of scalar expressions in the text, use the
\stres{} tag. The tag can be specified anywhere inside a line of text;
it can also be specified multiple times in the same line or it can span multiple
lines. \stres{} comes in three forms.

Syntax 1: Runtime evaluation

\stres[id]{display_directive}

With this syntax, \stres{} will be evaluated at runtime, i.e. when
running the Stata commands found in the source file. \stres{} will
apply Stata's display command to display_directive
and then replace the tag with the (first 255 characters of the) output. The
output will be backed up for future sttex passes, using id as an
identifier. An automatic name is assigned if id is omitted; the
brackets do not have to be typed if id is omitted.

Within display_directive you can type \% instead of
% to prevent LaTeX syntax highlighting from interpreting % and
subsequent text as a comment. sttex will replace \% by
% before processing display_directive.

Syntax 2: Pre-processing time evaluation

\stres{{display_directive}}

If you enclose display_directive in curly braces, it will be
evaluated while pre-processing the source file and not when running the Stata
commands. This also means that evaluation occurs in each pass and not only
in passes in which the surrounding Stata commands are run. Use this syntax to
add results that do not depend on the other Stata commands (and might
change between passes). For example, \stres{}
adds the current date.

Similar to syntax 1, \% within display_directive
will be replaced by % before evaluation.

Syntax 3: Special functions

\stres{{keyword [id]}}

Use this syntax for custom inclusion of a Stata log, a collected
file, or a graph. This may be useful in combination with
begin*...\end*, \stfile*{}, or
\stgraph*{}. keyword can be one of the following:

log add the log from Stata block named id; the last log will
be used if id is omitted

logname add the filename used for the log (the file will be created
if needed)

graph add the graph named id; the last graph will be used if
id is omitted

grname add the filename used for the graph (without suffix)

file add the contents of collected file named id; the last
collected file will be used if id is omitted

fname add the filename used for the collected file (the file will
be created if needed)

The way in which \stres{{log}} puts together the LaTeX code to
display the output depends on the options that were applied when generating
the output. Likewise, the behaviors of \stres{{graph}} and
\stres{{file}} depend on the options that were applied when exporting
the graph or collecting the file.

Note that a log, graph, or file can be addressed by \stres{} even if it does
not yet exist. That is, you can use \stres{} to include a log, graph, or
file anywhere in the document, independently of the where in the document
the instance of the log, graph, or file is created.

Include external file

To include contents from an external file, type

\stinput{filename}

where filename may contain an absolute
or relative path. Dynamic tags within the external file will be
interpreted in the same way as they are interpreted in the main
file. \stinput{} must start at
the beginning of a line; any text in the same line after the tag is
ignored. The file will be read when parsing the source file, that is, before
running any code.

Append external file

To append contents from an external file, type

\stappend{filename}[substitutions]

where filename may contain an absolute
or relative path. Dynamic tags within the external file will not be
interpreted. \stappend{} must start at
the beginning of a line; any text in the same line after the tag is
ignored. The file will be read when parsing the source file, that is, before
running any code.

substitutions may be specified to apply substitutions within the
appended contents. The syntax of substitutions is

strlist = to [ strlist = to ... ]

The substitutions will be applied sequentially.

End of input

To stop reading from the source file, specify

\endinput

at the beginning of a line. All remaining lines will be ignored.

Specify target file and overall options

Instead of specifying the target file and overall options when calling
sttex, you can provide

%STinit [tgtfile] [,
general_options
do_options
gropts(graph_options)
fileopts(file_options) ]

within the first 50 lines of the source file. tgtfile and options
specified with %STinit take precedence over options specified
with sttex. %STinit must start at
the beginning of a line; lines before %STinit will be ignored.

Set defaults for log environments

To change the default LaTeX commands used to embed a log in the target
document, specify

%STset keyword begin end

where keyword selects the type of log to be affected and where
begin and end are the LaTeX commands defining the
environment. Enclose begin and end in double quotes if they
contain spaces. keyword can be one of the following:

log results log

logbeamer results log with option beamer

code code log

codebeamer code log with option beamer

verb code log with option verbatim

verbbeamer code log with options verbatim and beamer

The initial settings are as follows:

%STset log \begin{stlog} \end{stlog}
%STset logbeamer \begin{stlog}[beamer] \end{stlog}
%STset code \begin{stlog} \end{stlog}
%STset codebeamer \begin{stlog}[beamer] \end{stlog}
%STset verb \begin{stverbatim} \end{stverbatim}
%STset verbbeamer \begin{stverbatim} \end{stverbatim}

%STset must start at the beginning of a line. You may specify
%STset repeatedly to change the settings along the way. Log options
begin() and end() take precedence over the settings defined
by %STset.

Partition the file into independent sections

An important feature of sttex is that it only runs Stata commands
if there were changes. However, as soon as a single command changed, all
commands will be executed. This is because sttex does not know how
the different commands depend on each other. You can provide such information
by partitioning the source file into different sections, possibly including
declaration of dependencies between parts. The syntax is

%STpart [id [parent]] [,
do_options
gropts(graph_options)
fileopts(file_options) ]

where id provides a custom name for the part. An automatic name is
assigned if id is omitted or if id is equal to
. (missing). sttex will decide part by part whether
to run the commands.

parent specifies the name (id) of an optional parent part. A change
in the commands in the parent will cause execution of the code in the child,
and vice-versa. More generally, if there is a change in the commands in a
specific part, the code in all its ancestors and all its descendants will
be executed.

By default, that is, if parent is omitted, the (unnamed) main part
(i.e. the section before the first %STpart tag) is used as parent
part. This means that if you do not specify parents, a change in any part
will cause the main part to be executed, and a change in the main part will
cause all other parts to be executed.

To indicate that a part has no parent, specify parent as . (missing). That is,
specify . to create a standalone part (which, however, may have children).

Specify do_options,
graph_options, and
file_options to change overall options between
parts.

The %STpart tag, must start at the beginning of a line.

Ignore tags

To ignore dynamic tags in a section of the source file, type:

%STignore
...
%STendignore

The text between %STignore and %STendignore will be added
to the target file as is.

%STignore and %STendignore must start at the beginning of a
line. Text in the same line after the tag is ignored.

Remove input

To ignore dynamic tags in a section of the source file and omit the
section from the target file, type:

%STremove
...
%STendremove

%STremove and %STendremove must start at the beginning of a
line. Text in the same line after the tag is ignored.

Options

General options
Do options
Log options
Graph options
File options

General options

Main

saving(tgtfile) specifies the target LaTeX file to be saved. Suffix .tex is
used if tgtfile is specified without suffix; srcname.tex is used
if saving() is omitted, where srcname is the base name of srcfile. The
target file will be placed in the same folder as the source file unless an (absolute or relative)
path is specified in tgtfile.

For sttex extract, option saving() specifies the target dofile to
store the Stata commands. Default suffix is .do in this case, and srcname.do is used
if saving() is omitted.

replace allows overwriting existing files.

nocd runs the Stata commands in current working directory. The default
is to change the working directory to the directory of
srcfile for the execution of the Stata commands. In any case, the
current working directory will be restored after termination.

Stata commands

nostop does not stop processing the Stata commands when an error
occurs. This option may be useful if you want to document errors.

nostop is a global option applied to the whole document. If you
want to apply nostop to a selected code block only, then store the relevant
commands in filename and call the file in your document about as follows:

\begin[][drop(1 .)]
do filename, nostop
\end

more sets more on for the execution of the Stata commands. The
default is to set more off. In any case, the current setting is
restored after termination.

rmsg sets rmsg on for the execution of the Stata commands. The
default is to set rsmg off. In any case, the current setting is
restored after termination.

Database

reset deletes the existing database and a creates new database. This implies
that all Stata commands will be re-evaluated (except commands for which nodo
has been specified).

nodb requests that no database is maintain. This implies
that all Stata commands will be evaluated in each run (except commands
for which nodo has been specified).

dbname(dbfile) specifies the file name to be used for the database. Suffix
srcsuffix.db is used if dbfile is specified without suffix,
where srcsuffix is the suffix of the source file; srcfile.db
is used if dbname() is omitted. The database will be placed in the
same folder as the source file unless an (absolute or relative) path is
specified in dbfile.

Typesetting

typeset[(#)] runs an external LaTeX compiler to typeset the
resulting target document as a PDF file. This requires that the location of
LaTeX executables has been registered using
sttex register tex. Argument # specifies the
number of extra typesetting passes. The default depends on situation.

view[(#)] is like typeset(), but additionally views the PDF after
typesetting.

jobname(name) specifies a custom base name for PDF file. jobname() has
an effect only if typeset or view has been specified.

cleanup removes auxiliary files left behind by the LaTeX compiler. Depending
on situation, cleanup may not catch all auxiliary files. cleanup has
an effect only if typeset or view has been specified.

[no]bibtex overrides whether BibTeX will be applied or not. By default,
sttex will decide depending on situation whether to run BibTeX. bibtex has
an effect only if typeset or view has been specified.

[no]makeindex overrides whether makeindex will be applied or not. By default,
sttex will decide depending on situation whether to run makeindex. makeindex has
an effect only if typeset or view has been specified.

Do options

Main

[no]do enforces or suppresses evaluating the commands in a code
block. Specify do if you always want
to execute the commands, irrespective of whether there have been
changes in the code or not; specify nodo if you never want to execute
the commands.

[no]certify specifies whether to compare the results log of a code
block against the previous version. The default is nocertify. Error
will be returned if certify is specified and differences (in both the
SMCL log as well as a plain text translation of the log) are detected.

[no]dosave specifies whether to store a copy of a code block in
an external do-file. The default is nodosave. File name
id.do will be used for the do-file, where id is the name
of the block.

logdir(path) specifies where to store the log file(s). path may be an
absolute or relative path. The default is to store the file(s) in a subfolder
that has the same base name as the target file. Type logdir(.) to store
the file(s) directly in the folder of the target file without creating a
subfolder. Type, for example, logdir(log), to store the log file(s) in
subfolder log. Whether a log file will be stored or not depends on
situation (e.g. no file will be stored if log option static is specified).

dodir(path) specifies where to store the do-file created by
the dosave option. The default is to store the file in the same place
as the log file(s). Type dodir(.) to store
the file directly in the folder of the target file. Type, for example,
dodir(do), to store the do-file in subfolder do.

Runtime options

linesize(#) sets the line width (number of characters) to be used for
the results log of a code block, with # between 40 and 255. The
default is to use the line width as set by set linesize. You may
type linesize(.) to select this default behavior. Changing
the line width causes reevaluation of the commands in the code block.

[no]trim[(#)] specifies whether to remove white space
on the left of the commands in a code block. Default is
trim (i.e. to remove indentation). Argument #, if specified,
limits the number of white-space characters to be removed. In any case, at
most k characters will be removed, where k is the minimum number
of characters by which the commands in the block are indented. Changing
trim() causes reevaluation of the commands in the code block.

[no]output specifies whether to suppress command output in
the results log of a code block. Default is output. If nooutput
is specified, sttex will temporarily turn set output inform on
for the execution of the code block, which will suppress command output. Changing
the output option will cause reevaluation of the commands in the code block.

Formatting

log_options are options selecting the type of log to be used
and how the log is formatted and embedded in the target file. See
Log options blow.

Log options

Main

[no]code specifies whether to use the code log or the
results log. Default is nocode, that is, to use the results log.

range(from [to]) selects a specified range of the log, where from
is the first line number and to is the last line number to be included. To
include all remaining lines after from, you may omit to or specify
to as . (missing). range() is applied after options
drop(), qui(), and oom() have taken effect.

ltag(matchlist) encloses the specified lines of the log in custom
tags. The syntax of matchlist is

numlist = left right [ numlist = left right ... ]

where numlist is a list of target line numbers, and left and
right are strings to be added to the beginning and the end of each selected
line, respectively. Enclose strings in double quotes if they contain
spaces. Specify left or right as "" for empty string. ltag()
is applied after other formatting options have taken effect.

tag(matchlist) encloses the specified strings in custom
tags. The syntax of matchlist is

strlist = left right [ strlist = left right ... ]

where strlist is a space separated list of target strings, and left and
right are strings to be added to the left and right of each target
string, respectively. Enclose strings in double quotes if they contain
spaces. Specify left or right as "" for empty string.

alert(strlist) encloses the specified strings in \alert{},
where strlist is a space separated list of target strings. Enclose
strings in double quotes if they contain spaces.

substitute(matchlist) applies string substitutions in the log. The syntax of
matchlist is

strlist = to [ strlist = to ... ]

where strlist is a space separated list of target strings and to
is the string by which the target strings are to be replaced. Enclose strings
in double quotes if they contain spaces. Specify to as "" for
empty string. substitute() will be applied before tag() and
alert().

[no]lb specifies whether to remove line break comments (/// ...)
from the command lines in the log. Default is lb, that is, to retain the
line break comments.

[no]gt specifies whether to remove continuation symbols (> ) from the
command lines in the log. Default is gt, that is, to retain the
continuation symbols.

[no]lnumbers[(str)] specifies whether to add line numbers to the
log. Default is nolnumbers. Line numbers are added after
other formatting options have taken effect. Argument str specifies a
suffix to be added to the line numbers. The default suffix is ": ". Type
lnumbers("") to remove the suffix.

The line numbers will be included in command \stlnum{}, which needs to
be defined in the preamble of the document. For example, define
\stlnum{} as \def\stlnum#1{\makebox[0pt][r]{#1}} to print right
aligned-numbers on the left of the log. Line numbers will be added without
\stlnum{} if verbatim is specified (code log only).

[no]lcontinue specifies whether to continue
the line number counter from the prior log. Default is nolcontinue. Option
continue is relevant only if lnumbers has been specified.

Results log only

[no]commands specifies whether to remove all command lines from the
results log. Default is commands, that is, to retain the command lines.

[no]prompt specifies whether to remove command prompts (. ) from the
command lines in the results log. Default is prompt, that is, to retain the
command prompts.

drop(numlist) removes the specified commands and their output from
the log. Positive integers in numlist refer to the
positions of the commands from the start, negative integers refer to positions
from the end. The last command can also be address by . (missing).

cnp(numlist) inserts a continued-on-next-page tag (\cnp) after
the specified commands. numlist is as for
drop(). Use this option as an alternative to including
//STcnp comments in the code. The advantage of cnp() is that no
reevaluation of the code is needed if the option changes.

By default, \cnp is defined as \clearpage in stata.sty. If you
want to print a continued-on-next-page message, redefine \cnp as
\onnextpage, e.g. by including \let\cnp=\onnextpage in the preamble
of the document.

qui(numlist) removes the output from the specified commands. numlist
is as for drop(). Use this option as an alternative to including
//STqui comments in the code. The advantage of qui() is that no reevaluation of the
code is needed if the option changes.

oom(numlist) removes the output from the specified commands and includes
an output-omitted tag (\oom). numlist is as for
drop(). Use this option as an alternative to including
//SToom comments in the code. The advantage of oom() is that no
reevaluation of the code is needed if the option changes.

Code log only

clsize(#) sets the line width (number of characters) to be used
when passing the code through log texman, with # between 40 and
255. The default is to use full line width, that is,
clsize(255). You may type clsize(.) to select this
default. The clsize() option has no effect if notexman or
verbatim is specified.

[no]lskip specifies whether to replace blank lines in the
code log by \smallskip. Default is lskip, as this is how
log texman behaves. Specify nolskip to restore the blank lines.

[no]texman specifies whether to use a raw copy of
code rather than a code log. Default is texman, in which case the
code will be passed through log texman to create a code log. Specify
notexman to use a copy of the code without applying
log texman. Depending on situation, the resulting document may not
compile well in LaTeX if notexman is specified; it is left to the user
to embed the code in a way such that these errors do not occur. Alternatively,
specify option verbatim to enclose the code in a verbatim environment.

[no]verbatim specifies whether to enclose the code log in a
verbatim environment. The default is noverbatim. Option verbatim
implies notexman. Irrespective if begin(), end(), and the
settings by %STset, the log will always be included in an
inner \begin{verbatim}...\end{verbatim} environment
if option verbatim is specified.

Embedding

[no]static specifies whether to copy the log into the target
document or not. Default is nostatic, in which case the log is stored as a
separate file and included in the LaTeX document using the \input{}
command. If the target file is a beamer class document, option static
may lead to compilation issues unless the affected frame is declared as fragile.

[no]begin[(str)] specifies the begin command of the
environment used to embed the log in the target file. The default is as set by
%STset. Specify nobegin to omit the begin command; specify
begin(str) to set the begin command to str.

[no]end[(str)] specifies the end command of the
environment used to embed the log in the target file. The default is as set by
%STset. Specify noend to omit the end comamnd; specify
end(str) to set the end command to str.

[no]beamer selects the variant of the
begin and end commands defined by %STset. Specify
beamer if the target file is a beamer class document. Default is
nobeamer.

scale(#) rescales the size of the log, where # is a scaling factor
lager than zero, by enclosing the log in a \scalebox{} command (this
requires that a package providing the \scalebox{} command is loaded in the
preamble of the document, e.g. the graphicx package). A consequence
is that page breaks within the log will no longer be possible. By default
the log is not included in a \scalebox{}. You may type
scale(.) to select this default. Option
scale() does not work well together with option static.

blstretch(#) adjusts the line spacing in the log (by setting the
\baselinestretch command). By default no action is taken to adjust line
spacing. Apply blstretch() if you want to use a
different line spacing in the log than in the surrounding text. You may
type blstretch(.) to select the default behavior.

Graph options

Main

as(fileformats) sets the output format(s). Default is as(pdf) (or as(eps)
if epsfig is specified). See help graph export for available
formats. Multiple graph files will be stored if multiple formats are specified.

name(name) specifies the name of the graph window to be exported. The default
is to use the topmost graph.

override(options) are format-dependent options to modify how the
graph is converted. See override_options in help
graph export for details.

dir(path) specifies where to store the graph files, where path is
relative or absolute path. The default is to store the graph files in the same
place as the log file(s). Type dir(.) to store
the graph files directly in the folder of the target file. Type, for example,
dir(graph), to store the do-file in subfolder graph.

Embedding

[no]center specifies whether to include the graph in a center
environment. Default is nocenter.

args(args) provides arguments to be passed through to \includegraphics{}
or \epsfig{} command.

[no]suffix specifies whether to type the file suffix
in the \includegraphics{} or \epsfig{} command. Default is
nosuffix.

[no]epsfig} specifies whether to use \epsfig{} instead of
\includegraphics{} to embed the graph in the target document. Default
is noepsfig.

File options

Main

range(from [to]) selects a specified range of the file, where from
is the first line number and to is the last line number to be included. To
include all remaining lines after from, you may omit to or specify
to as . (missing).

substitute(matchlist) applies string substitutions. The syntax of
matchlist is

strlist = to [ strlist = to ... ]

where strlist is a space separated list of target strings and to
is the string by which the target strings are to be replaced. Enclose strings
in double quotes if they contain spaces. Specify to as "" for
empty string.

[no]erase specifies whether to erase the original file from disk
after collecting it. Default is noerase. Specify erase to delete
the original file.

Embedding

[no]static specifies whether to copy the collected contents
into the target document or not. Default is static, in which case the
contents will directly be written to the taget document. Specify nostatic
to write the contents to a separate file that will then be included in the
target document using the \input{} command. The file will be placed
in the same location as the log file(s) of the corresponding code
block.

Remarks

Use of stable names
Preamble of LaTeX file
Changing the font size of Stata logs

Use of stable names

sttex generates automatic names for elements such as parts created by %STpart,
logs created by the stata or mata environments, graphs created by
\stgrapph{}, or inline expressions created by \stres{}. These
automatic names may not be stable if the order of elements is changed
or if elements are remove or inserted, and a change in name will always cause
the corresponding Stata commands to be executed.

To assign stable names, use the id argument that can be specified when
defining the elements. In this case, changes in order etc. will not change the
names, and hence will not lead to unnecessary reevaluation of Stata commands.

Preamble of LaTeX file

To be able to compile a LaTeX file that includes Stata output inserted by
sttex you should include command \usepackage
in the preamble of the source file. Furthermore,
to be able to display graphs, you may want to include
\usepackage{graphicx}. For example, your file could start about as
follows:

\documentclass{article}
\usepackage{graphicx}
\usepackage
...

stata.sty is provided by Stata Corp as part of sjlatex; see

. net describe sjlatex, from(http://www.stata-journal.com/production)

The procedure to make stata.sty available is to first
install sjlatex in Stata and then use command sjlatex install
to copy the relevant LaTeX files to your system.

Changing the font size of Stata logs

By default, the stlog environment provided by the stata style
uses an 8-point font. This is appropriate for a document with a 10-point font
for the text body. One solution to change the font size is to redefine the
stlog environment in the preamble of the LaTeX document about as
follows:

\let\oldstlog\stlog
\let\endoldstlog\endstlog
\renewenvironment{stlog}%
{\bgroup\fontsize{10}{11}\selectfont\oldstlog[auto]}%
{\endoldstlog\egroup}

This will set the font size to 10 points (with 11-point baseline skip), which
is appropriate for a document that uses a 12-point font
for the text body.

Author

Ben Jann, University of Bern, ben.jann@unibe.ch

Thanks for citing this software as follows:

Jann, B. (2022). sttex: Stata module to integrate Stata results into
a LaTeX document. Available from http://github.com/benjann/sttex/.

Also see:

Jann, B. (2022). sttex – a new dynamic document command for Stata and
LaTeX. Presentation at the London Stata Conference 2022. Available from
http://ideas.repec.org/p/boc/lsug22/14.html.

Also see

Online: help for
dyndoc, dyntext, texdoc (if indstalled), webdoc (if indstalled)