Automatic generation of documents

This paper describes a natural interaction between Stata and markup languages. Stata’s programming and analysis features, together with the flexibility in output formatting of markup languages, allow generation and/or update of whole documents (reports, presentations on screen or web, etc.). Examples are given for both LaTeX and HTML. Stata’s commands are mainly dedicated to analysis of data on a computer screen and output of analysis stored in a log file available to researchers for later reading. However, users may need to produce output in different formats and to cooperate with professionals who are not familiar with log files. An elegant solution to this problem is exporting output in the format of a markup language, such as LaTeX or HTML. The most common means for presenting the results of one or several analyses are text on paper, screen presentations, and web sites. While it is common to generate such outputs by visual programs, such as MS Office or OpenOffice, it is impossible for Stata to produce documents this way, as it lacks eyes to format a table and hands to hold a mouse to cut and paste graphs. Nevertheless, each of those presentation formats can also be obtained with use of a markup language. Wikipedia defines a markup language as “a kind of text encoding that represents text as well as details about the structure and appearance of the text”. To publish on the web, HTML is one of the best and most compatible formats. On other hand, LaTeX is a complete language for editing and text formatting on either paper or screen (most commonly via PDF files). Both languages are easy to learn, free, and well documented. Now Stata happens to be perfectly capable of writing text, such as the instructions for a markup language to write a report, a sequence of slides, or the pages of a web site containing tables and graphs. The problem of formatting the output of a command in LaTeX and/or HTML has been addressed in various ways by several authors. The most comprehensive reference to this issue is Newson (2003), who also provides a suite of tools aimed at printing in markup language the list of a Stata dataset, in such a way that variable labels, value labels, significant figures, and so forth are formatted the way one would wish. More generally, we can exploit Stata’s ability to write text files to make it produce virtually any piece of markup language code: tables and graphs, but also other kind of objects, like lists, trees, etc. Finally, by further printing some code putting together all of the ingredients, we make Stata produce a whole document, which is then browsable, printable, or showable on a screen, according to the kind of document. The key feature of this method is that the document automatically produced can be completely updated as soon as the figures in the data change. This is particularly suitable when the user needs to produce a large amount of output or routinely performs analyses on the same dataset structure, such as administrative data bases or collection of data from a long-lasting study. For an example of those facilities, we describe a do-file automatically constructing a web site for the Regional Agency for Public Health of Tuscany. Finally, we remark that to apply this method, Stata commands must store in memory their results—at least as many as necessary to reproduce the screen output. This is generally the case, with some notable counterexamples (dstdize, svyprop,...).