The webdoc stlog command

In most examples in Getting started, the logall option was specified with webdoc init to create output sections from all Stata commands in the do-file. Alternatively, or in addition, you can use the webdoc stlog command to select the output to be included. For example, if the logall option has been specified, you could type

webdoc stlog, nolog
commands
webdoc stlog close

to omit creating an output section from commands. Furthermore, the webdoc stlog command is useful if you want to apply different options to specific output sections, as illustrated by the following example.

[top]

Contents of output sections

Several options are available to webdoc stlog to manipulate the contents to be included in an output section. Some of these option are illustrated in the following example:

webdoc init, header(width(700px) stscheme(rbf cbf))

/*** <h4>Some options of webdoc stlog</h4> ***/

/*** <ul><li><p>Default: input (commands) and output</p> ***/
webdoc stlog
display as txt "sqrt(2) = " /// this is a comment
    as res sqrt(2)
webdoc stlog close

/*** </li><li><p><code>cmdstrip</code>: output without input</p> ***/
webdoc stlog, cmdstrip
display as txt "sqrt(2) = " /// this is a comment
    as res sqrt(2)
webdoc stlog close

/*** </li><li><p><code>nooutput</code>: input without output</p> ***/
webdoc stlog, nooutput
display as txt "sqrt(2) = " /// this is a comment
    as res sqrt(2)
webdoc stlog close

/*** </li><li><p><code>lbstrip</code> and <code>gtstrip</code>: remove 
     line-break comments and continuation symbols</p> ***/
webdoc stlog, lbstrip gtstrip
display as txt "sqrt(2) = " /// this is a comment
    as res sqrt(2)
webdoc stlog close

/*** </li><li><p><code>matastrip</code>: remove Mata begin and end 
     commands</p> ***/
webdoc stlog, matastrip
mata:
sqrt(2)
end
webdoc stlog close

/*** <p>Without <code>matastrip</code> the result would look as 
     follows:</p> ***/ 
webdoc stlog
mata:
sqrt(2)
end
webdoc stlog close

/*** </li></ul> ***/
Code
1.png

Note that all options can also be specified with webdoc do or webdoc init to set the default behavior. Furthermore, you can applywebdoc init repeatedly within a do-file (without specifying an output document) to change the defaults between different parts of the do-file.

[top]

Setting the screen width

The width of a Stata output section (i.e. the maximum number of characters per line) is determined by Stata's current screen width. Use the set linesize command to change the screen width, as illustrated in the following example:

webdoc init, header(width(700px))

/*** <p>Set the screen width to 80 characters:</p> ***/
webdoc stlog, linesize(80)
display "{hline}"
webdoc stlog close

/*** <p>Set the screen width to 60 characters:</p> ***/
webdoc stlog, linesize(60)
display "{hline}"
webdoc stlog close
Code
2.png
[top]

Omitting selected output

To suppress output from individual commands, you can use the webdoc stlog oom command, as illustrated by the following example.

webdoc init, header(width(700px)) logall

/*** <p>Run a regression of price on milage and repair record (categorical)
and perform an overall test for repair record using the <code>testparm</code>
command.</p> ***/
     
sysuse auto
webdoc stlog oom ///
regress price mpg i.rep78
testparm i.rep78
Code
3.png

The "output omitted" message is declared as class="stoom" so you can change its appearance using stylesheet specifications (the default is to italicize the message). For example, you could add shading as follows.

webdoc init, header(width(700px)) logall

webdoc put <style> .stoom { opacity: 0.5; } </style>

webdoc stlog oom ///
summarize
Code
4.png

The webdoc put command is used here to write the style definition to the output document, but you could also simply include it in a /*** ***/ block.

Note that the default text message can be changed by the webdoc set command (see Changing the HTML settings in the help file). An example is as follows.

webdoc init, header(width(700px)) logall

webdoc put <style> .stoom { opacity: 0.5; } </style>

webdoc set stoom <span class="stoom">(output omitted; we are only /*
    */interested in the returns stored by the command)</span>

webdoc stlog oom ///
summarize
Code
5.png

Furthermore, if you want to suppress output without inserting an "output omitted" message, you can use webdoc stlog quietly instead of webdoc stlog oom .

[top]

Highlighting selected output

You can highlight selected pieces of the Stata output using the mark() option. All instances of the specified strings will then be included in a <mark> tag. Example:

webdoc init, header(width(700px))

/***
<p>Estimate a regression of price on milage for <b>foreign cars</b>, using 
<b>robust standard errors</b>.
</p>
***/

webdoc stlog, mark("if foreign==1" "robust")
sysuse auto
regress price mpg if foreign==1, robust
webdoc stlog close
Code
6.png

In addition you can apply custom tags to selected strings in the output using the tag() option. Within tag() you can specify multiple replacement sets, each consisting of the strings to be tagged, an equal sign, and the desired start and end tags:

webdoc init, header(width(700px))

/***
<p>Estimate a regression of price on milage for <b>foreign cars</b>, using 
<b>robust standard errors</b>.
</p>
***/

webdoc stlog, mark("if foreign==1" "robust") ///
    tag("Linear regression"     = <b> </b>   ///
        " 22" 88.22545 2352.589 = "<font color='red'><b>" </b></font>)
sysuse auto
regress price mpg if foreign==1, robust
webdoc stlog close
Code
7.png
[top]

The nodo option

An indispensable option for lager projects is the nodo option. The option allows you to recompile your document without re-running the Stata commands. webdoc keeps the log files from previous runs so that re-running the Stata commands would be a waste of time if the Stata commands did not change. Therefore, once the commands in a Stata output section are all set, type

webdoc stlog, nodo

To apply nodo to all Stata output sections in the document, specify nodo with webdoc init or webdoc do. To turn the commands back on in a specific section, type

webdoc stlog, do

Note that you can also turn commands on and off between different parts of the document by applying the webdoc init command with the do or nodo option repeatedly within the do-file. Be aware that webdoc uses consecutive numbers to name the log files of the output sections. Thus, the name for a specific section will change if other (unnamed) sections are added or deleted in preceding parts of the document. In this case you may have to rerun all output sections. Hence, if a specific Stata output section contains time consuming commands it is always a good idea to assign a fixed name (that is, type webdoc stlog name, where name is your chosen name for the output sections).

[top]

The plain option

By default, webdoc annotates the Stata output so that it can be formatted using stylesheets. This increases the file size of the output document. If you want to save space, you can omit the HTML tags by specifying the plain option. That is, type:

webdoc stlog, plain

Specify the plain option with webdoc init or webdoc do to omit the HTML tags from all output sections (unless turned back on by option noplain).

[top]

Displaying Stata code

webdoc stlog distinguishes between Stata output and Stata code. By default, Stata output is displayed, tagged by <pre class="stlog"><samp>. However, if the cmdlog option is specified, webdoc stlog displays Stata code, tagged by <pre class="stcmd"><code>. The color scheme chosen in header(stscheme()) only applies to sections of Stata output, not to code. Code is displayed using standard settings, with shaded comments:

webdoc init, header(width(700px))

/***
<p>Open the 1978 Automobile Data and run a regression of price on 
milage using the <code>regress</code> command.</p>
***/

webdoc stlog, cmdlog
sysuse auto         // this command opens the data
regress price mpg   // this command runs the regression
webdoc stlog close
Code
8.png

If you want to omit shading of comments, additionally apply the plain option (see above). Furthermore, note that, even though no output is displayed, the commands are still executed. If you want to omit execution of the commands, additionally apply the nodo option (see above).

[top]

Saving Stata code

webdoc stlog has a dosave option that stores a do-file from the commands in the logged output section. This is useful if you want to provide the commands in a downloadable file. Here is a somewhat advanced example in which a Code button is placed in the upper right corner of the Stata output box:

webdoc init, header(width(700px) bstheme(, selfcontained))

/***
<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 put <div style="position:relative">
webdoc stlog, dosave
    sysuse auto
    regress price mpg
webdoc stlog close
webdoc put <a href="`s(doname)'" target="_blank" /*
         */class="btn btn-default btn-sm" /*
         */style="position:absolute; top:10px; right:10px">Code</a>
webdoc put </div>
Code
9.png

For more information on the code generating the button, see getbootstrap.com/css/#buttons.

If you want to include such a button in each output section, you can specify dosave as a global option and modify the default start and end tag of output sections using the webdoc set command; see Changing the HTML settings in the help file. An example is as follows:

webdoc init, logall dosave header(width(700px) bstheme(, selfcontained))
webdoc set stlog /*
    */<div style="position:relative"><pre id="\`id'" class="stlog"><samp>
webdoc set _stlog /*
    */</samp></pre><a href="\`doname'" target="_blank" /*
    */class="btn btn-default btn-sm" /*
    */style="position:absolute; top:10px; right:10px">Code</a></div>

/***
<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

/***
<h3>Exercise 2</h3>
<p>Display some summary statistics of price and milage.</p>
***/

summarize price mpg
Code
10.png
[top]

Displaying help files

To include a Stata help file in your HTML document, simply apply webdoc stlog using to the file. Files ending with .hlp or .sthlp will automatically be detected as help files. Help files will be tagged by <pre class="sthlp">. Internal help links (that is, links pointing to the processed help file) will be converted to appropriate internal links in the output document; other help links will be converted to links pointing to the corresponding help file at www.stata.com. For more detailed information, see the sthlp option in help webdoc. An example is as follows:

webdoc init, header(width(700px))

/***
<p>Stata help for <code>save</code>:</p>
***/

quietly findfile save.sthlp
webdoc stlog using `r(fn)'
Code
11.png
[top]

Dynamic text (webdoc local)

If you want to add results from a Stata output section to the text body, an approach is to store the results as local macros and then insert the contents of these locals at appropriate places in the text body using webdoc put or webdoc write. A problem, however, is that these locals will no longer be available in later runs once the nodo option is applied. A solution to this problem is provided by the webdoc local command, which can be applied within or after a Stata output section. The command can be used just like Stata's regular local command, but it maintains a backup of the locals on disk and restores them if needed. Furthermore, the local macros defined by webdoc local will be expanded in subsequent /*** ***/ blocks (up until the next webdoc stlog command, which causes the macro library to be reset). The locals will be backed up in a library that has the same name as the Stata output section (using file suffix ".stloc"). Each output section has its own library, so that the names of the locals can be reused between sections. An example is as follows:

webdoc init, header(width(700px))

/***
<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
webdoc local r2 = strofreal(e(r2)*100, "%9.2f")
webdoc local tval = strofreal(abs(_b[mpg]/_se[mpg]), "%9.1f") 

/***
<p>The R-squared of this regression is equal to `r2'%. The effect of milage
on price is highly significant (absolute t-value of `tval').</p> 
<p>What happens if we control for car type?</p>
***/

webdoc stlog
    regress price mpg i.foreign
webdoc stlog close
webdoc local r2 = strofreal(e(r2)*100, "%9.2f")
webdoc local tval = strofreal(abs(_b[mpg]/_se[mpg]), "%9.1f") 

/*** 
<p>Now the R-squared increased to `r2'% and the absolute t-value of the
effect of milage on price increased to `tval'.</p>
***/
Code
12.png

Note that webdoc local also works in combination with the logall option. Furthermore, you can use webdoc write or webdoc put to write the locals to the output document instead of including them in a /*** ***/ block. Example:

webdoc init, logall header(width(700px))

sysuse auto
summarize price
webdoc local N = r(N)
webdoc local mean = strofreal(r(mean), "%9.1f")

webdoc put <p>There are `N' observations in the data set. The mean of 
webdoc put price is `mean'. Let's look at another variable:</p>

summarize mpg
webdoc local mean = strofreal(r(mean), "%9.1f")
webdoc local sd = strofreal(r(sd), "%9.2f")

/***
<p>The mean of milage is `mean', with a standard deviation of `sd'.</p>
***/
Code
13.png