help texdoc
-------------------------------------------------------------------------------

Title

texdoc -- Create a LaTeX document including Stata output

Syntax

Create LaTeX document

texdoc init docname [, replace append prefix(prefix) ]

tex ...

texdoc close

Include Stata output in LaTeX document

texdoc stlog [name]

texdoc stlog oom cmdline

texdoc stlog cnp

texdoc stlog close

Additional syntax for non-interactive mode

texdoc do filename [, init(docname) close replace append prefix(prefix) savecmd(newfile) ]

/*tex ... tex*/

Remove all texdoc commands from do-file

texdoc strip oldfile newfile [, replace append ]

Description

texdoc provides tools to create a LaTeX document from within Stata in a weaving fashion (on weaving with Stata also see Rising 2008). The basic procedure is to first initialize the document using texdoc init, then write the contents of the file, line by line, by repeated calls to tex, and finally finish up typing texdoc close. Example:

. texdoc init example1 (texdoc output file is example1.tex)

. tex \documentclass{article} . tex \begin{document} . tex . tex Hello world. . tex . tex \end{document} . texdoc close (texdoc output written to example1.tex)

. type example1.tex \documentclass{article} \begin{document}

Hello world.

\end{document} texdoc stlog can be used to include Stata output in the LaTeX document. This is useful if you want to produce a LaTeX document that contains Stata examples such as a Stata Journal article or solutions to statistics homework assignments. Example:

. texdoc init example2 (texdoc output file is example2.tex)

. tex \documentclass{article} . tex \usepackage{stata} . tex \begin{document} . tex . tex An example: . tex . texdoc stlog (opening texdoc stlog example2_1)

. sysuse auto (1978 Automobile Data)

. summarize price

Variable | Obs Mean Std. Dev. Min Max -------------+-------------------------------------------------------- price | 74 6165.257 2949.496 3291 15906 . texdoc stlog close (texdoc stlog written to example2_1.log.tex)

. tex . tex \end{document} . texdoc close (texdoc output written to example2.tex)

. type example2.tex \documentclass{article} \usepackage{stata} \begin{document}

An example:

\begin{stlog} \input{example2_1.log.tex} \end{stlog}

\end{document} As illustrated, texdoc stlog writes the Stata output to a separate file and includes appropriate code in the LaTeX document to display the contents of the file. Note that the stata LaTeX package providing the stlog environment is to be loaded in the document preamble. texdoc stlog provides an automatic name for the output file, but you can also specify a custom name typing texdoc stlog name (name may contain a relative path).

texdoc stlog oom cmdline can be used after texdoc stlog. It suppresses the output of the specified command and adds an "output omitted" tag (\oom) in the Stata output file. texdoc stlog cnp is also for use after texdoc stlog and adds a "continued on next page" tag (\cnp).

As an alternative to the interactive usage in the examples above you can also store the commands in a do-file and then execute the do-file using texdoc do. The advantage of such a non-interactive approach is that you can use the /*tex ... tex*/ delimiter structure to include blocks of LaTeX code. A block may span multiple lines. However, make sure that the opening tag is positioned at the beginning of a line and that the closing tag is at the end of a line. For example, you could create a do-file called "example2.do" containing

texdoc init example2, replace

/*tex \documentclass{article} \usepackage{stata} \begin{document}

An example: tex*/

texdoc stlog sysuse auto summarize price texdoc stlog close

/*tex \end{document} tex*/ texdoc close

and then type

. texdoc do example2.do

to create the LaTeX file. Note that texdoc init and texdoc close can either be specified in the do-file, as above, or as options to texdoc do. That is, you could define the do-file simply as

/*tex \documentclass{article} \usepackage{stata} \begin{document}

An example: tex*/

texdoc stlog sysuse auto summarize price texdoc stlog close

/*tex \end{document} tex*/

and then type

. texdoc do example2.do, init(example2) close replace

texdoc strip can be used to remove all texdoc or tex commands and all /*tex ... tex*/ blocks from a do-file. This is useful, for example, if you want to create a cleared-out do-file from your solutions to hand out to the students.

Dependencies

texdoc requires sjlatex. For more information and installation, type

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

Options

replace allows texdoc init, texdoc do, and texdoc strip to overwrite existing files.

append allows texdoc init, texdoc do, and texdoc strip to append to existing files.

prefix(prefix) can be used with texdoc init and texdoc do to specify a custom prefix for the automatic names of the Stata output logs. prefix may contain a relative path. This is useful if you want to keep the Stata output files in a different folder than main LaTeX file. The default prefix is docname_.

init(docname), specified with texdoc do, initializes the LaTeX document. Use this option if the do-file does not contain a texdoc init command.

close, specified with texdoc do, closes the LaTeX document. Use this option if the do-file does not contain a texdoc close command.

savecmd(newfile), specified with texdoc do, saves a copy of the do-file from which all /*tex ... tex*/ blocks have been removed.

Examples

Simple document:

texdoc init example tex \documentclass{article} tex \begin{document} tex tex Hello world. tex tex \end{document} texdoc close

Document with Stata output; output from single commands can be suppressed using texdoc stlog oom:

texdoc init example, replace tex \documentclass{article} tex \usepackage{stata} tex \begin{document} tex tex The auto data: tex

texdoc stlog sysuse auto describe texdoc stlog close

tex tex The output of the following regression model will be tex suppressed and a note ``(output omitted)'' will be tex printed: tex

texdoc stlog generate mpgsq = mpg^2 texdoc stlog oom regress price weight mpg mpgsq foreign test mpg mpgsq texdoc stlog close

tex tex \end{document} texdoc close

Keeping log files in a subdirectory (the subdirectory must exist):

texdoc init example, replace prefix(log/example_) tex \documentclass{article} tex \usepackage{stata} tex \begin{document} tex tex Some output: tex

texdoc stlog sysuse auto describe texdoc stlog close

tex tex Some more output: tex

texdoc stlog summarize texdoc stlog close

tex tex \end{document} texdoc close

Document including a Stata graph:

texdoc init example, replace tex \documentclass{article} tex \usepackage{stata} tex \usepackage{graphicx} tex \begin{document} tex tex Here comes a scatterplot:

sysuse auto scatter price mpg graph export plot1.eps

tex tex \includegraphics{plot1} tex tex \end{document} texdoc close

Remarks

Special characters

The $ character is used for global macro expansion in Stata. If you use the tex command to write LaTeX code containing $ math delimiters, type \$ instead of $. For example, type

. tex This is an inline equation: \$y = x^2\$

An alternative is to abandon $ and use \( and \) as math delimiters. That is, type

. tex This is an inline equation: \(y = x^2\)

No such precautions are required if you use the /*tex ... tex*/ delimiter structure, since in this case an exact copy of the specified code is written as is to the LaTeX file.

Limitations

The algorithm used to process the /*tex ... tex*/ blocks is insensitive to whether the block is surrounded by a /* ... */ delimiter structure or not. That is, a /*tex ... tex*/ block will be processed even if it is in a portion of a do-file that is commented out by /* ... */.

texdoc stlog closes the default log if it is on. Use a named log (see the name() option in help log) to make a record of a Stata session in which texdoc stlog is applied.

Global macros

texdoc maintains a set of global macros for communication between calls. Do not change or erase these global macros while working with texdoc. The macros are:

TeXdoc_docname name of LaTeX document (including path if specified) TeXdoc_path path of LaTeX document (if specified) TeXdoc_stprefix prefix for automatic Stata output log names TeXdoc_stcounter counter for automatic Stata output log names TeXdoc_stname name of current Stata output log

texdoc close clears these macros.

References

Rising, Bill (2008). Reproducible Research: Weaving with Stata. Italian Stata Users Group Meeting 2008. Available from http://www.stata.com/meeting/italy08/rising_2008.pdf.

Author

Ben Jann, ETH Zurich, jannb@ethz.ch

The append option has been suggested by Jorge Eduardo Pérez Pérez.

Thanks for citing this software as follows:

Jann, B. (2009). texdoc: Stata module to create a LaTeX document including Stata output. Available from http://ideas.repec.org/c/boc/bocode/s457021.html.

Also see