.
. /*
> THIS IS A COMMENT AND WILL NOT BE IN THE DYNAMIC DOCUMENT
> */
.
. /***
>
> Introduction to MarkDoc (heading 1)
> ===================================
>
> __MarkDoc__ package provides a convenient way to write dynamic document
> within Stata dofile editor. Before starting, remember that there are a few
> things that ___you must absolutely avoid___ while using MarkDoc.
>
> 1. Use only one markup language. While you are writing with _Markdown_ you
> may also use _HTML_ tags, but __avoid__ _LaTeX_ in combination of _HTML_ or
> _Markdown_.
>
> 2. Only use English letters. Any unsual character (Chinese, French, or
> special characters) should be avoided.
>
> 3. Please make sure you that you have the __permission to write and remove
> files__ in your current working directory. Especially if you are a
> __Microsoft Windows__ user. Ideally, you should be the adminster of
> your system or at least, you should be able to run Stata as an adminstrator
> or superuser. Also pay attension to your current working directory.
>
> Using Markdown (heading 2)
> --------------------------
>
> Writing with _Markdown_ syntax allows you to add text and graphs to
> _smcl_ logfile and export it to a editable document format. I will
> demonstrate the process by using the __auto.dta__ dataset.
>
> ###Get started with MarkDoc (heading 3)
>
> I will open the dataset, list a few observations, and export a graph.
> Then I will export the log file to _HTML_ format.
> ***/
.
.
. quietly sysuse auto, clear

. list in 1/5

     +---------------+-------+-----+-------+----------+-------+--------+
  1. | make          | price | mpg | rep78 | headroom | trunk | weight |
     | AMC Concord   | 4,099 |  22 |     3 |      2.5 |    11 |  2,930 |
     +-----------+---+-----+-+-----+-----+-+----------+-+-----+--------+
     |  length   |  turn   |  displa~t   |   gear_r~o   |    foreign   |
     |     186   |    40   |       121   |       3.58   |   Domestic   |
     +-----------+---------+-------------+--------------+--------------+

     +---------------+-------+-----+-------+----------+-------+--------+
  2. | make          | price | mpg | rep78 | headroom | trunk | weight |
     | AMC Pacer     | 4,749 |  17 |     3 |      3.0 |    11 |  3,350 |
     +-----------+---+-----+-+-----+-----+-+----------+-+-----+--------+
     |  length   |  turn   |  displa~t   |   gear_r~o   |    foreign   |
     |     173   |    40   |       258   |       2.53   |   Domestic   |
     +-----------+---------+-------------+--------------+--------------+

     +---------------+-------+-----+-------+----------+-------+--------+
  3. | make          | price | mpg | rep78 | headroom | trunk | weight |
     | AMC Spirit    | 3,799 |  22 |     . |      3.0 |    12 |  2,640 |
     +-----------+---+-----+-+-----+-----+-+----------+-+-----+--------+
     |  length   |  turn   |  displa~t   |   gear_r~o   |    foreign   |
     |     168   |    35   |       121   |       3.08   |   Domestic   |
     +-----------+---------+-------------+--------------+--------------+

     +---------------+-------+-----+-------+----------+-------+--------+
  4. | make          | price | mpg | rep78 | headroom | trunk | weight |
     | Buick Century | 4,816 |  20 |     3 |      4.5 |    16 |  3,250 |
     +-----------+---+-----+-+-----+-----+-+----------+-+-----+--------+
     |  length   |  turn   |  displa~t   |   gear_r~o   |    foreign   |
     |     196   |    40   |       196   |       2.93   |   Domestic   |
     +-----------+---------+-------------+--------------+--------------+

     +---------------+-------+-----+-------+----------+-------+--------+
  5. | make          | price | mpg | rep78 | headroom | trunk | weight |
     | Buick Electra | 7,827 |  15 |     4 |      4.0 |    20 |  4,080 |
     +-----------+---+-----+-+-----+-----+-+----------+-+-----+--------+
     |  length   |  turn   |  displa~t   |   gear_r~o   |    foreign   |
     |     222   |    43   |       350   |       2.41   |   Domestic   |
     +-----------+---------+-------------+--------------+--------------+

. histogram price
(bin=8, start=3291, width=1576.875)

. graph export graph.png, replace width(350)
(note: file graph.png not found)
(file graph.png written in PNG format)

.
. /***
> Adding a graph using Markdown
> -----------------------------
>
> In order to add a graph using Markdown, I export the graph in PNG format.
> You can explain the graph in the brackets and define the file path in
> parentheses using Markdown syntax. Note that Markdown format cannot resize the
> figure and it will include it at its full size. Therefore, when you write with
> Markdown you should resize the graphs. Of course, if you write with _LaTeX_ or
> _HTML_ you will be able to do anything you wish! But _Markdown_ is convertable
> to any format and thus is the prefered markup language for writing dynamic
> documents. In addition, it is a very minimalistic language. And perhaps that's
> what makes it so good, because it does not include numerous rules and tags to
> learn, compared to _HTML_ and _LaTeX_. It's simple, easy to learn, and appealing
> to use.
>
> ![](./graph.png)
>
>
> Writing Dynamic Text
> --------------------
>
> The __txt__ command can be used to write dynamic text in MarkDoc.
> To do so, put the value that you want to print in a Macro and then
> explain it using the __txt__ command. Or instead, I use the stored values
> that Stata returns after particular commands by typinc __return list__.
>
> In the example below, I use the summarize command, and print the r(N), r(mean),
> r(sd), r(min), and r(max) which are returned after the __summarize__ command.
> ***/
.
. summarize price

    Variable |        Obs        Mean    Std. Dev.       Min        Max
-------------+---------------------------------------------------------
       price |         74    6165.257    2949.496       3291      15906

.
. //OFF
. return list

scalars:
                  r(N) =  74
              r(sum_w) =  74
               r(mean) =  6165.256756756757
                r(Var) =  8699525.974268789
                 r(sd) =  2949.495884768919
                r(min) =  3291
                r(max) =  15906
                r(sum) =  456229

. //ON
.
. txt The dataset used for this analysis includes `r(N)' observations for                 ///
> the __price__ variable, with mean of `r(mean)' and SD of `r(sd)'. The                   ///
> price of cars' ranged from `r(min)' to `r(max)'.


> The dataset used for this analysis includes 74 observations for                 the __price__ variable, with mean of 6165.256756756757 and SD of 2949.495884768919. The                   price of cars' ranged from 3291 to 15906.
.
. //And thi is how a regression analysis looks like in the file.
. regress price mpg

      Source |       SS           df       MS      Number of obs   =        74
-------------+----------------------------------   F(1, 72)        =     20.26
       Model |   139449474         1   139449474   Prob > F        =    0.0000
    Residual |   495615923        72  6883554.48   R-squared       =    0.2196
-------------+----------------------------------   Adj R-squared   =    0.2087
       Total |   635065396        73  8699525.97   Root MSE        =    2623.7

-------------+----------------------------------------------------------------
        price |      Coef.    Std. Err.       t    P>|t|      [95% Con f. Interval]
-------------+----------------------------------------------------------------
         mpg |   -238.8943    53.07669     -4.50    0.000     -344.7008    -133.0879
       _cons |    11253.06    1170.813      9.61    0.000      8919.088     13587.03
-------------+----------------------------------------------------------------

.
. /***
> [You will find more information in this regard on my website](http://haghish.com/).
> You can also [Follow The Package Updates On TWITTER!](http://twitter.com/Haghish)
>
>
> E. F. Haghish
> Center for Medical Biometry and Medical Informatics
> University of Freiburg, Germany
> _haghish@imbi.uni-freiburg.de_
>
> ***/
.
. qui log c