Getting started  –  How to use webdoc

Basic usage

The basic procedure is to write a do-file including Stata commands and sections of HTML code and then process the do-file by command webdoc do. The command will create the HTML source file, which can then be viewed in a browser.

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

webdoc init example1, replace

/***
<html>
<head><title>Example 1</title></head>
<body>
<h3>Exercise 1</h3>
<p>Open the 1978 Automobile Data and run a regression of price on 
milage using the <code>regress</code> command.</p>
***/

webdoc stlog
sysuse auto
regress price mpg
webdoc stlog close

/***
</body>
</html>
***/

Command webdoc init initializes the HTML output file. The /*** and ***/ delimiters are used to tag the HTML sections to be added to the document. Furthermore, the commands webdoc stlog and webdoc stlog close are used to select the Stata output to be included in the document.

To process the file, type: 

webdoc do example1.do

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

example1.png
[top]

The logall option

In the example above, the webdoc 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 webdoc init (or with webdoc do). That is, applying webdoc do to the following do-file (example2.do) will produce the same result (example2.html) as above: 

webdoc init example2, replace logall

/***
<html>
<head><title>Example 2</title></head>
<body>
<h3>Exercise 1</h3>
<p>Open the 1978 Automobile Data and run a regression of price on 
milage using the <code>regress</code> command.</p>
***/

sysuse auto
regress price mpg

/***
</body>
</html>
***/
[top]

Using Markdown

For simplified typing, you could also omit the HTML tags and use Markdown instead. An example do-file might look as follows (example3.do):

webdoc init example3, replace logall md

/***
### Exercise 1

Open the 1978 Automobile Data and run a regression of price on milage
using the `regress` command.
***/

sysuse auto
regress price mpg

Option md has been specified with webdoc init so that suffix .md instead of .html is used for the output file. Typing 

webdoc do example3.do

will create file example3.md, which can then be converted to HTML using a Markdown converter. For example, if Pandoc is installed on your system, you could type 

shell pandoc example3.md -s -o example3.html

to create a HTML file from example3.md. The -s argument has been specified so that Pandoc produces a standalone HTML file including a header and footer. This will create file example3.html.

[top]

Automatic initialization

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

/***
<html>
<head><title>Example 4</title></head>
<body>
<h3>Exercise 1</h3>
<p>Open the 1978 Automobile Data and run a regression of price on 
milage using the <code>regress</code> command.</p>
***/

sysuse auto
regress price mpg

/***
</body>
</html>
***/

You could then type 

webdoc do example4.do, logall replace

to generate file example4.html. Alternatively, typing 

webdoc do example4.do, init(myexample) logall replace

will generate file myexample.html.

[top]

Changing settings on the fly

You can use the webdoc 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: 

webdoc init example.tex, replace logall

commands ...

webdoc init, nologall

commands ...

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

[top]

Workflow

Do-files containing webdoc commands may be hard to read because Stata commands and HTML 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 HTML 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, HTML 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 webdoc 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 webdoc 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 HTML document can be quickly updated without re-running the Stata commands. Also note that you can run the do-file without applying webdoc do, that is, by submitting the commands to Stata's command window or by applying the regular do or run command. The webdoc commands (except webdoc do) and /*** ***/ blocks will be ignored in this case. This is useful if you only want to run the Stata commands without updating the output document.

[top]

Limitations

In general, you can work on a do-file containing webdoc commands in the same way as you would work on another do-file. For example, if you submit the do-file to Stata without applying webdoc do, Stata will process the do-file like any other do-file; the /*** ***/ blocks containing HTML code will be ignored and the webdoc commands will do nothing. However, there are some limitations and technical issues that should be kept in mind when working with webdoc:

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

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

    quietly webdoc stlog ...

    or similar.

  • webdoc stlog cannot be nested. Furthermore, do not use webdoc do or webdoc init within a webdoc stlog section.
  • When processing a do-file, webdoc 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 webdoc do instead of do to include such a do-file.
  • webdoc 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 webdoc.