*! version 1.0 15 Feb 2016

Title

log2markup -- transform a Stata text log into a markup document

Syntax

log2markup using [, options]

Main
using logfile to use

replace replace existing markdown file

log direct markdown to result window instead of a file

extension extension to put on the markup modified log file

codestart set your markdown coding for code start, eg
\begin if the document is intended for the Stata Journal

codeend set your markdown coding for code end, eg
\end if the document is intended for the Stata Journal

samplestart set your markdown coding for sample start, eg
{\smallskip}\begin if the document is intended for the Stata Journal

sampleend set your markdown coding for sample end, eg
\begin if the document is intended for the Stata Journal

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.

The author usually uses markdown for writing documents. However other
users may decide on all sorts of markup languages, eg HTML or LaTex.

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

So preferences of the author dictates a little digression into markdown.

However others might use eg HTML or LaTex just as easy.

Markdown is first of all a plain text formatting syntax, a common denominator
of eg html, word and Latex.

So if it goes in markdown it goes everywhere. This way a markdown document is
base document that easily can be transformed into whatever output is needed.

This means easy reuse of text and code.

At the same time markdown is simple: Easy to read and write.

And since it is text based it is easy to integrate into log files while
maintaining readability.

That said markdown can also be considered limiting by some.

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

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

2. Markdown text blocks are surrounded with /*** and ***/

3. 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

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

5. Commented code (starting with a * or //) are ignored in the output

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

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

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

9. 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

Most of the code is written in Mata and can be seen in an accompagnying
file: log2markup.mata.

Besides log2markup there are a set of commands/programs that integrates text
and output into one document (alfabetic order):

* markdoc

* StatWeave

* texdoc

* weaver

The new command log2markup are in many ways very similar to the above.
It differs from the above commands in following way:

* texdoc and StatWeave integrates LaTex text with Stata commands and outputs.
However the learning curve for LaTex is quite high.
And worse the writeability and readability of LaTex is bad (the authors opinion)

* markdoc and and weaver can be based on either of the markup languages
markdown, HTML or LaTex or a combination of markdown and one of the other two.
The difference to log2markup is that they have integrated the use of CSS, Pandoc
and HTML printer into the code.

Markdown

The syntax of markdown
is described at
John Grubers homepage.

In practice markdown documents are often transformed using eg
Pandoc and so
The Pandoc User Guide is quite often
necessary if something special has to be accomplished.

A homepage giving a quick overview of the markdown syntax is
here.

Another great source of inspiration on how to use markdown and Pandoc is the
article by Tenen and Wythoff

Example, sending Stata log to HTML

To see more examples

Save the following in a do file and run it to generate a final HTML
document:

********************************************************************************
*** HTML test file *************************************************************
********************************************************************************

capture log close
set linesize 250 // The log should not break output lines
log using log2markup_test.log, replace

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

/***
# Document demonstrating the use of log2markup

Note that html or latex can be inserted as plain text for later transformation.
***/

//OFF
/***
Text blocks inside `//OFF` and `//ON` is ignored.

Below is the code for generating the data for the estout table:
***/
sysuse auto, clear
replace price = price / 1000
replace weight = weight / 1000

quietly regress price weight mpg
estimates store m1, title(Model 1)

generate forXmpg = foreign * mpg

quietly regress price weight mpg forXmpg foreign
estimates store m2, title(Model 2)

label variable foreign "Foreign car type"
label variable forXmpg "Foreign*Mileage"
//ON

/***### A demonstration on integrating Markdown text blocks with Stata commands

The integration with Stata is demonstrated with an example from the command
estout.

The output from estout can be written in eg html or Latex. And that will be
exploited further below.

The code leading to the data are hidden in the do file together with a comment
between a `//OFF` and a `//ON`. This way the same document keeps all information
but only show what is needed.

If a command is prefixed with `/**/` only the command is shown:
***/

/**/estout	*, cells(b(fmt(%9.3f)) se(par)) ///
stats(r2_a N, fmt(%9.3f %9.0g) labels(R-squared))	///
legend label collabels(none) varlabels(_cons Constant) style(html)

/***
This the command demonstrating the 2 output examples just below.

The command prefix `/***/` will make only the output from the command is
shown.

But then the output will be marked as code, eg surrounded with
`<pre><code>` and `</pre></code>` in html.

Output will look like:
***/

/***/estout	*, cells(b(fmt(%9.3f)) se(par)) ///
stats(r2_a N, fmt(%9.3f %9.0g) labels(R-squared))	///
legend label collabels(none) varlabels(_cons Constant) style(html)

/***
When there are no prefix to a command both the command and the output above are
part of the markdown document.

The problem above is that the sorrounding html tags here are for code blocks.

But actually the code tags can be neglected by using the command prefix `/****/`
instead.

Since html and latex can be inserted in markdown. It is at first considered as
plain text, but when the markdown are changed to html the inserted html becomes
active.

Now the table looks like:
***/

/***
***output only in pure form ***
<table border="1">
<colgroup>
<col>
<col style="background-color:red">
<col style="background-color:yellow">
</colgroup>
***/

/****/estout	*, cells(b(fmt(%9.3f)) se(par)) ///
stats(r2_a N, fmt(%9.3f %9.0g) labels(R-squared))	///
legend label collabels(none) varlabels(_cons Constant) style(html)

/***
</table>
***/

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

log close
*** End of logging *************************************************************

/* Command log2markup converts the log into a markdown document */
log2markup using log2markup_test.log, replace extension(md)

/* If Pandoc is installed the following command will generate a html docoment
based on the markdown document log2markup_test.md generated by log2markup: */
shell pandoc -o log2markup_test.html -f markdown -t html log2markup_test.md

*** End of do file *************************************************************

Example, sending Stata log to LaTex

Save the following in a do file and run it to generate a final LaTex
document (Example inspired by texdoc documentation):

********************************************************************************
*** LaTex test file ************************************************************
********************************************************************************

capture log close
set linesize 250 // The log should not break output lines
log using ".\output\log2markup tex demo.log", replace

/*
This is inspired by the texdoc help file.
*/
/***
% Writing for the Stata Journal
% Example inspired very much by texdoc documentation

\documentclass
\usepackage[article,notstatapress]
\usepackage
\usepackage
\usepackage
\usepackage
\usepackage
\usepackage
\bibpunct{(}{)}{;}{}{,}

\begin

\section
Open the 1978 Automobile Data and summarize the variables.

***/

sysuse auto, clear
summarize

/***

\section
Run a regression of price on milage and weight.

***/

regress price mpg weight

/***
\section
Draw a scatter plot of price by milage.

***/

//OFF
* part is hidden
scatter price mpg
graph export ./output/mygraph.pdf, replace
graph drop _all
//ON

/***
\begin
\includegraphics
\end

\bibliographystyle
\bibliography
%\begin
%Some background information about the author(s).
%\end

\end
***/
log close

log2markup using ".\output\log2markup tex demo.log", replace extension(tex) ///
codestart(\begin) codeend(\end) ///
samplestart(\begin{\smallskip}) sampleend({\smallskip}\end)

Authors and support

Author:

Niels Henrik Bruun,

Aalborg University Hospital

Support:

niels.henrik.bruun@gmail.com

See Also

Related Stata commands:

log2html (if installed) ssc install log2html (to install this command)
markdoc (if installed) ssc install markdoc (to install this command)
texdoc (if installed) ssc install texdoc (to install this command)
weaver (if installed) ssc install weaver (to install this command)

And also there are Stata commands for easing up doing tables and graphs in reports:

basetable (if installed) ssc install bastable (to install this command)
coefplot (if installed) ssc install coefplot (to install this command)
estout (if installed) ssc install estout (to install this command)
mog (if installed) ssc install mog (to install this command)
outreg (if installed) ssc install outreg (to install this command)
outreg2 (if installed) ssc install outreg2 (to install this command)
sjlog (if installed) ssc install sjlog (to install this command)
table1 (if installed) ssc install table1 (to install this command)
tabout (if installed) ssc install tabout (to install this command)