The Stata command -log2markup-

Syntax

The syntax is: log2markup using [, options]

Options

The options are:

Versions

-log2markup- is tested in version 12.1 ic, 13.1 ic, and 14.2 ic.

Description

-log2markup- extract parts of the text version from the Stata -log- command and transform the logfile into a markup based document with the same name, but with extension markup (or otherwise specified in option extension) instead of log.

Users may decide on all sorts of markup languages, eg Markdown, HTML, or LaTex.

The key is that markup of Stata code and Stata output can be set by the options.

-log2markup- produces a markdown document based on the log marking described here:

-log2markup- is based on the text version from the Stata -log- command.

Adding text blocks

Text inside /*** and ***/ in a do file log will be considered as a markup text block.

Commenting code

Comments inside /* and */ are ignored in the document so it is also possible to keep comments for yourself.

Commented code (starting with a * or \\) are ignored as well.

Code lines as well as their outblocks are marked as markdown code blocks.

The appearance of code

Show only code in the markup document

If a code line is prefixed with /**/ only the code part is used in the markdown document.

The command /**/sysuse auto, clear is shown as:


sysuse auto, clear

Shown only Stata output in the markup document

If a code line is prefixed with /***/ only the output part is used in the markdown document. However the output is marked as a code block in the markdown document.

The command /***/describe is shown as:


Contains data from C:\Program Files (x86)\Stata14\ado\base/a/auto.dta
  obs:            74                          1978 Automobile Data
 vars:            12                          13 Apr 2014 17:45
 size:         3,182                          (_dta has notes)
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
              storage   display    value
variable name   type    format     label      variable label
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
make            str18   %-18s                 Make and Model
price           int     %8.0gc                Price
mpg             int     %8.0g                 Mileage (mpg)
rep78           int     %8.0g                 Repair Record 1978
headroom        float   %6.1f                 Headroom (in.)
trunk           int     %8.0g                 Trunk space (cu. ft.)
weight          int     %8.0gc                Weight (lbs.)
length          int     %8.0g                 Length (in.)
turn            int     %8.0g                 Turn Circle (ft.)
displacement    int     %8.0g                 Displacement (cu. in.)
gear_ratio      float   %6.2f                 Gear Ratio
foreign         byte    %8.0g      origin     Car type
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Sorted by: foreign

Code blocks can be ignored

Code blocks and markdown text blocks to be ignored are surrounded with //OFF and //ON so preparing code and its output can be seen in the log but not in the resulting markup document.

To present an estimate from a regression with a 95% CI a regression is needed.

The code block //OFF regress price i.foreign, noheader //ON will be ignored.

Show both command and output in the markup document

The command without any prefix will shown as well as it's output in log:


margins foreign

Adjusted predictions                            Number of obs     =         74
Model VCE    : OLS

Expression   : Linear prediction, predict()

------------------------------------------------------------------------------
             |            Delta-method
             |     Margin   Std. Err.      t    P>|t|     [95% Conf. Interval]
-------------+----------------------------------------------------------------
     foreign |
   Domestic  |   6072.423    411.363    14.76   0.000     5252.386     6892.46
    Foreign  |   6384.682   632.4346    10.10   0.000     5123.947    7645.417
------------------------------------------------------------------------------

This might be interesting when writing technical or educational Stata notes.

Integrate markup output into the markup document

If a code line is prefixed with /****/ only the code part is used in the markdown document, but now the output is inserted as ordinary markdown lines.

Hence output in eg HTML format can be integreted directly when the markdown document is transformed to HTML. The same goes for LaTex.

As an example on how -log2markup- is integrated with -matprint- look at the result of


matrix tbl = r(table)'
matrix tbl = tbl[1..2, "b"], tbl[1..2, "ll".."ul"]
matrix rownames tbl = Domestic Foreign
matprint tbl, style(md)

-------------------------------------------------
                      b           ll           ul
----------    ---------    ---------    ---------
Domestic        6072.42      5252.39      6892.46

Foreign         6384.68      5123.95      7645.42
-------------------------------------------------

A table in markdown is a Pandoc concept and not implemented in MkDocs which is used to generate this site.

If Pandoc was used to generate html documents or slides the matrix tbl would have been integrated in the text.

Using MkDocs the style needs to be html like:

/****/matprint tbl, style(html) title(Table in html layout)

to get the following result:

Table in html layout
b ll ul
Domestic6072.425252.396892.46
Foreign 6384.685123.957645.42

This way nice table presentations are easy to do when making documents with -log2markup-.

The help command -do2md-

To automate the process of generating documents for this site the command -do2md- is used.

It is not fully developed and hence only presented here for the curious.

To create the markdown for this page download log2markup_demo.do from below and change to the directory it is saved. Then run the command (note no extension):

do2md using log2markup_demo

After that use eg MkDocs or Pandoc to transform the markdown document.


The do file for this document

Last update: 2017-06-03, Stata version 14.2