Home  >>  Authors

Getting Started with the Stata Journal

Installing the necessary LaTeX files

The Stata Journal LaTeX files can be installed and updated using the sjlatex command from within Stata. This installation script may be found in an up-to-date Stata by typing

       . search sjlatex

Select the link sjlatex from http://www.stata-journal.com/production, and then select click here to install.

From within Stata, type sjlatex install using new_directory_name to install the packages and examples in a new directory of your choosing. Here are some examples:

Windows:

       . sjlatex install using C:\sjtemp

Unix:

       . sjlatex install using ~/sjtemp

Mac OS X:

       . sjlatex install using ~/Documents/sjtemp

Upon completion, sjlatex will display the folder where the files have been installed and the version number and release date of the LaTeX files.

Introduction to the LaTeX files

There is an example document included with the Stata Journal LaTeX files for you to get started. This example document displays the layout/form of a journal insert and provides tips to use when writing your own journal insert.

The main document (main.tex) for this example uses the Stata Press document class (statapress.cls), the Stata Press page dimensions package (pagedims.sty), the Stata Journal package (sj.sty), the Stata package (stata.sty), and the Stata Journal bibliographic style (sj.bst). Individuals with access to recent distributions of TeX are encouraged to use these files because they are ultimately used to generate the Stata Journal in its printed and electronic forms.

An alternate document (altmain.tex) is also supplied. This file uses the LaTeX2e standard article document class in place of the Stata Press document class and omits the page dimensions package. See File dependencies for further details on the use of this file.

Running LaTeX

Before you make any changes to the files downloaded with sjlatex, you should test the installation by typesetting the example article (readme.tex). The LaTeX program on Unix machines and PCs is invoked at the command prompt, so let > (greater than symbol) be the command prompt. Mac OS X front ends to LaTeX tend to be based on menus; thus the spirit of the following instructions are equivalent. At the command prompt, navigate to the directory you just created, and run LaTeX on main.tex; that is, type

       > latex main
       > bibtex main
       > latex main
       > latex main
       > dvips main.dvi -o main.ps

The above commands were placed in a script (included with the files downloaded by sjlatex) for your convenience.

Windows:

       > doit.bat 

Unix:

       > sh doit.sh

The first latex command generates the auxiliary (aux) file for your journal insert. The bibtex command uses the aux file from your journal insert (readme.aux for the example) to generate bibliographic citations and references. After bibtex, two more latex runs are needed to ensure that cross references appear correctly in the resulting dvi-file. The last command uses dvips to generate a PostScript file from the dvi-file. The final result is main.ps, which can be viewed using Ghostscript (PC: gsview, Unix: ghostview or gv, Macintosh: view the dvi-file from the menu).

If you get an error message about a missing style file, see File dependencies.

Provided your TeX distribution contains the required packages and passed the above test, you can use these files to write your journal insert. Change the name of the example file (readme.tex) in main.tex to the name of your journal insert, and you are ready to run LaTeX on main.tex.

Downloading examples

The results of the above test (of main.tex and altmain.tex) have been converted to PDF documents collected in the sjxmpl Stata package for download. This package can be found using the following command in Stata.

       . search sjxmpl

Select the link sjxmpl from http://www.stata-journal.com/production, and then select click here to get.

TeX distributions

The examples have been successfully tested using the following TeX distributions, all of which are free:

  • Windows: MiKTeX version 2.6
  • Unix: TeX Live 2007
  • Mac OS X: MacTeX (based on TeX Live) with the TeXShop version 2.14 front end (both free). For compatibility with Stata’s style class, you must typeset using TeX and Ghostscript instead of Pdftex.

The main website for the Comprehensive TeX Archive Network (CTAN) is http://www.tug.org.

The main website for Ghostscript is http://www.cs.wisc.edu/~ghost/.

File dependencies

The Stata Press document class (statapress.cls) is based on the standard book document class (book.cls) in your TeX distribution. The following list includes other files that are required:

  • statapress.cls also requires hyperref.sty, color.sty, fancyhdr.sty, natbib.sty, makeidx.sty, showidx.sty, and multind.sty.
  • pagedims.sty requires calc.sty and crop.sty.
  • sj.sty requires ifthen.sty and chapterbib.sty.
  • stata.sty requires alltt.sty and pstricks.sty.

All of these packages are available in most TeX distributions.

If you get an error message that one of these style files was not found, it could be that crop.sty, chapterbib.sty, or natbib.sty is not present in your distribution. These files are collected into the sjextra Stata package for download. This package can be found using the following command in Stata.

       . search sjextra

Select the link sjextra from http://www.stata-journal.com/production, and then select click here to get.

If you install the sjextra package, you must change newcenter to oldcenter in main.tex.

If you are still receiving an error message, you can try using the alternate document (altmain.tex), which is included in the sjlatex installation. This file uses the LaTeX2e standard article document class in place of the Stata Press document class and omits the page dimensions package. Use of this file should increase compatibility in older TeX/LaTeX installations, but the page dimensions and font sizes will differ from those used in the Stata Journal.