Getting started  –  How to use texdoc

Basic usage

The basic procedure is to write a do-file including Stata commands and sections of LaTeX code and then process the do-file by command texdoc do. The command will create the LaTeX source file, possibly including sections of Stata output, which can then be processed by a LaTeX compiler to produce the final document.

A basic do-file might look as follows (example1.do):

texdoc init example1.tex, replace

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\section*{Exercise 1}
Open the 1978 Automobile Data and summarize the variables.

***/

texdoc stlog
sysuse auto
summarize
texdoc stlog close

/***

\section*{Exercise 2}
Run a regression of price on milage and weight.

***/

texdoc stlog
regress price mpg weight
texdoc stlog close

/***

\end{document}
***/

Command texdoc init initializes the LaTeX output file. The /*** and ***/ delimiters are used to tag the LaTeX sections to be added to the document (alternatively, you could also type /*tex ... tex*/). Furthermore, the commands texdoc stlog and texdoc stlog close are used to select the Stata output to be included in the document.

To process the file, type:

texdoc do example1.do

This will create file example1.tex, which looks as follows:

\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\section*{Exercise 1}
Open the 1978 Automobile Data and summarize the variables.

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

\section*{Exercise 2}
Run a regression of price on milage and weight.

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

\end{document}

You can now use a LaTeX compiler to generate the final document. For example, depending installation, you could type

shell pdflatex example1.tex

to generate a PDF (example1.pdf), which looks about as follows:

The logall option

In the example above, the texdoc stlog command was used to select the Stata output to be included in the LaTeX document. If you want to include the output of all Stata commands in the do-file by default, you can specify the logall option with texdoc init (or with texdoc do). That is, applying texdoc do to the following do-file (example2.do) will produce the same result (example2.tex) as above:

texdoc init example2.tex, replace logall

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\section*{Exercise 1}
Open the 1978 Automobile Data and summarize the variables.

***/

sysuse auto
summarize

/***

\section*{Exercise 2}
Run a regression of price on milage and weight.

***/

regress price mpg weight

/***

\end{document}
***/

Automatic initialization

If a do-file does not contain a texdoc init command to initialize the LaTeX document, texdoc do will automatically initialize the document using the name of the do-file. Alternatively, you can use the init() option with texdoc do to provide a name for the LaTeX document. For example, your do-file might look as follows (example3.do):

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\section*{Exercise 1}
Open the 1978 Automobile Data and summarize the variables.

***/

sysuse auto
summarize

/***

\section*{Exercise 2}
Run a regression of price on milage and weight.

***/

regress price mpg weight

/***

\end{document}
***/

You could then type

texdoc do example3.do, logall replace

to generate file example3.tex. Alternatively, typing

texdoc do example3.do, init(myexample) logall replace

will generate file myexample.tex.

Changing settings on the fly

You can use the texdoc init command to change settings on the fly. For example, you could start off processing a do-file with logall on, but then at a later point in the do-file turn logall off:

texdoc init example.tex, replace logall

commands ...

texdoc init, nologall

commands ...

Use texdoc init in the same way to change the default behavior of texdoc stlog and texdoc graph between different sections of the do-file.

Workflow

Do-files containing texdoc commands may be hard to read because Stata commands and LaTeX code are combined in a single file. To improve clarity, use a text editor that allows you to switch between different settings (syntax highlighting, spell checking, keyboard shortcuts, etc.) depending on whether you work on the Stata commands or the LaTeX code. Some editors can also be set up in a way such that they automatically apply different settings to different parts of the document (for example, LaTeX settings to /*** ***/ blocks and Stata settings to the rest of the document). Furthermore, define keyboard shortcuts to improve the workflow. For example, define a keyboard shortcut that causes Stata to process the do-file by texdoc do in the background if the curser is within a /*** ***/ block. If a section of Stata commands is selected, the same keyboard shortcut could submit the highlighted commands to a foreground instance of Stata (without using texdoc do). It may also be helpful to define a keyboard shortcut that processes the do-file with the nodo option turned on, so that the LaTeX document can be quickly updated without re-running the Stata commands. Also note that you can run the do-file without applying texdoc do, that is, by submitting the commands to Stata's command window or by applying the regular do or run command. The texdoc commands (except texdoc do) and /*** ***/ blocks will be ignored in this case. This is useful if you only want to run the Stata commands without updating the LaTeX document.

For larger projects it is usually helpful to break up the project into several do-files and maintain a master LaTeX file that combines the outputs from the separate files. This allows you to process different parts of the project separately. For example, when working on a book, use a separate do-file for each chapter and maintain a master do-file such as

clear all

texdoc do chapter1.texdoc
texdoc do chapter2.texdoc
texdoc do chapter3.texdoc
...

exit

as well as a master LaTeX document such as:

\documentclass{book}
\usepackage{stata}
\begin{document}

\input{chapter1.tex}
\input{chapter2.tex}
\input{chapter3.tex}
...

\end{document}

Limitations

In general, you can work on a do-file containing texdoc commands in the same way as you would work on another do-file. However, there are some limitations and technical issues that should be kept in mind:

• The $ character is used for global macro expansion in Stata. If you use use texdoc write or texdoc _write to write text containing $, type \$ instead of $.
• texdoc do only provides limited support for the semicolon command delimiter (see help #delimit). For example, do not use semicolons to delimit texdoc commands. However, the semicolon command delimiter should work as expected as long as it is turned on and off between /*** ***/ blocks and between texdoc commands.

• In general, texdoc commands should start on a new line with texdoc being the first (non-comment) word on the line. For example, do not type

  quietly texdoc stlog ...

  or similar.

• texdoc stlog cannot be nested. Furthermore, do not use texdoc do or texdoc init within a texdoc stlog section.
• When processing a do-file, texdoc do does not parse the contents of a do-file that is called from the main do-file using the do command (see help do). As a consequence, for example, /*** ***/ blocks in such a file will be ignored. Use texdoc do instead of do to include such a do-file.
• texdoc tries to create missing subdirectories using Mata's mkdir() function; see help mata mkdir(). Usually, this only works if all intermediate directories leading to the target subdirectory already exist. If mkdir() fails, you will need to create the required directories manually prior to running texdoc.