Haghish, E. F. (2014). Applied Statistics Using Stata.

Free Online Stata Tips & Tutorials. Data Management; Stata Graphs and Graphics; Data Analysis; Stata Programming; Advanced Statistics

Updated on 1 March 2016 Fork Star Watch

MarkDoc

| Introduction |      | Dynamic Text |      | Graphs |      | Dynamic Table |      | Dynamic Slides |      | Dynamic Help Files |     | Math Notations |     

MarkDoc is a general purpose literate programming package for Stata that creates dynamic analysis documents, dynamic presentation slides, and dynamic Stata help files and package documentation. You can read about the idea of MarkDoc in the journal article below, which discusses the software in details and provides several examples.

MarkDoc: Literate Programming in Stata

MarkDoc Manual on GitHub wiki

Quick Tips

MarkDoc is a general purpose literate programming package for Stata that creates dynamic document in several formats including Microsoft Office docx, OpenOffice/LibreOffice odt, LaTeX tex, html, epub, and Markdown md as well as dynamic slide in pdf format using Beamer. In addition, it also supports generating dynamic Stata sthlp help files written within do, ado, or mata source files. Therefore, MarkDoc is a package that can support a wide range of Stata users, from introductory-level students who may need a package to document their statistical practices and course works, applied statisticians for generating analysis reports, Stata teachers who need dynamic PDF slides, as well as the front-end developers who need a package for documenting Stata ado and mata programs.

MarkDoc supports three markup languages which are LaTeX, HTML, and Markdown. While LaTeX and HTML provide many more options for documentation, Markdown is the easiest markup language to apply and it greatly enhances the readability of the do file. Moreover, documents written in Markdown can also be exported in HTML and LaTeX which enables the full capacity of MarkDoc package for exporting a dynamic document in several file format using a single Markdown source. In contrast, if the document is written in HTML or LaTeX, it can only be exported to html and tex respectively or to pdf.

For users who insist on writing with HTML and LaTeX to export more appealing documents and also, to have greater control over the document, some templates were created to make using these markup languages more easy for the users. for example, LaTeX users can get benefit from the texmaster option that automatically creates a compilable LaTeX document by creating the heading, loading the most necessary packages, etc.

MarkDoc also comes with Statax, a JavaScripts syntax highlighter which can be used in HTML and PDF documents (Statax option).

Note that MarkDoc requires Weaver Package, Statax Package, and third-party additional software that can be installed manually or automatically using the install option. The required software are Pandoc, wkhtmltopdf (only needed for creating pdf documents from HTML and Markdown notations), and LaTeX (only needed for creating pdf slide or pdf dynamic document from LaTeX source. The OPTIONAL automatic installation only installs Pandoc and wkhtmltopdf.

Here are a few examples of how to install and update MarkDoc and also, how to export a Markdown, HTML, and a Microsoft Word document. Below are a few examples of how you can install MarkDoc and how to export dynamic documents to Docx and HTML formats.

ssc install markdoc /* installing MarkDoc package */
ssc install weaver /* installing Weaver package */
ssc install statax /* installing Statax package */
markdoc smclfile, replace install export(docx) /* exporting Microsoft Office Docx word */
markdoc adofile, replace install export(sthlp)/* exporting sthlp Stata help file */

Introduction

While I was working on Stata Weaver Package, I tried to find the easiest way to write text in Stata Do-file Editor. I wrote several programs, some in Stata, some in JavaScripts to ease the task. But, none was good enough. A good enough program means that it solves a problem in a way that other people would not attempt to solve it again. This is partly due to the fact that there are several programs generating dynamic reports in Stata but none has really made writing in Stata a cheerful experience. So I wrote MarkDoc from users' perspective. A package that follows the natural workflow of using Stata and at the same time, makes writing dynamic documents easy i.e. package that makes users believe they are only 1 command away from exporting a dynamic document. MarkDoc, in my opinion, is reaching this purpose. It supports interactive use, provides preview of the document without requiring recompiling the whole code, includes a decent JavaScripts syntax highlighter (thanks to Statax), supports several markup language and multiple document formats (docx, pdf, html, latex), and yet, it includes a single command for exporting the document.

The idea of MarkDoc program hit my mind when I thought about creating a Markdown file (and later HTML and LaTeX) directly from Stata smcl log-file. Such a program could create a markdown text file (*.md) which not only includes the Stata commands and the outputs but also Markdown syntax. Then I could use Pandoc software to convert the Markdown file to any other format supported by Pandoc. This could also allow us to include graphs and images in the exported document which are imported with Markdown syntax. Later on, I developed MarkDoc further to also export HTML and LaTeX documents. Therefore, you can imagine MarkDoc includes smaller engines in itself that handle Markdown, HTML, and LaTeX documents differently.

MarkDoc was written to carefully process Stata commands and comments. I figured out the best way to write Markdown syntax in the do-editor is to write them as a comment . This would separate human language from computer language also by highlighting them with different colors (by default, comments appear in green color in Stata). The greatest advantage of this approach is that the do-file will remain executable and will not require a literate programming software for compiling it. This is often the problem with literate programming software, i.e. they introduce their own syntax for separating the code from text, making the source file uncompilable on its own (i.e. a software should first parse the code, and only extract and compile the code, while using the text for documentation). Nevertheless, separating the text from the code in the form of "special comments" will assure that the do-file will remain executable, regardless of generating dynamic document or not.

To use MarkDoc, all you need to do is creating a log-file, doing your data analysis, and insert "special comments" with markdown or html or latex (only one, not a mix!) signs whenever you want to write or comment a result. At the end, use the MarkDoc program to compile the smcl log-file into a dynamic document.

Note: MarkDoc requires additional software which are Pandoc and wkhtmltopdf. Ideally, the software should be downloaded and installed manually by the user or the administrator. This ensures that the software are in good hands which also take care of the regular updates. However, some users might not be that familiar with computer to install and use software that does not have GUI. Both Pandoc and wkhtmltopdf are command lines without user interface. The users should be able to find the path to executable files and pass them to MarkDoc though pandoc(str) and printer(str) to allow MarkDoc access pandoc and wkhtmltopdf respectively.

To make life easier for beginners, I also made an OPTIONAL automatic software installation. This would download portable version of Pandoc and wkhtmltopdf in a directory called ~/PLUS/Weaver. Please see MarkDoc help file for more information.

Supported Document Formats

MarkDoc can produce dynamic PDF and HTML-based slides (slide, slidy, dzslide respectively), and dynamic documents in pdf, Microsoft Word docx, Open Office /Libre Office odt, html, epub, LaTeX tex, Markdown md, as well as Stata documentation in smcl and sthlp.

Installation

MarkDoc package can be installed from SSC server, which includes the last release of the package. The developing version of MarkDoc can be downloaded from https://github.com/haghish/MarkDoc which is the developing version (newest and unreleased). The GitHub repository was created to make debugging MarkDoc easier.

To install MarkDoc from SSC:

ssc install markdoc

And to install MarkDoc from GitHub:

net install markdoc, force from("https://raw.githubusercontent.com/haghish/markdoc/master/")

Required packages

MarkDoc requires two other packages which are Weaver and Statax. Weaver provides the img, tbl, and txt commands which are required for inserting an image, dynamic table, and dynamic text in MarkDoc. And Statax package provides a syntax highlighter engine for HTML and PDF documents exported from MarkDoc. to install these packages, type:

ssc install weaver
ssc install statax

if the install option is specified, MarkDoc searches for these packages and if it does not find them on the system, it automatically installs them. Note that this feature is OPTIONAL. MarkDoc does not install any software/package unless you request it.

Required third-party software

Without any third-party software, MarkDoc is capable of converting SMCL log to Markdown, and also Markdown syntax written within Stata script files to SMCL and STHLP files. Therefore, MarkDoc can create a Markdown file and Stata help files without requiring any third-party software.

However, MarkDoc also allows writing with LaTeX and HTML markups and can export outputs in numerous document formats. These features are relying on third-party software which are Pandoc, wkhtmltopdf, and LaTeX (a complete distribution is recommended.

Manual Installation

MarkDoc has 2 options for accessing the path to the executable files which are pandoc(str) and printer(str). The first option obtains the path to the executable Pandoc and the latter, to the executable wkhtmltopdf or pdfLaTeX. wkhtmltopdf and pdfLaTeX are printer engines for creating PDF from HTML or TeX respectively, thus you should specify the correct printer based on the markup language you use for writing your document. If you write in Markdown or HTML, specify wkhtmltopdf and if you write in LaTeX, specify the path to pdfLaTeX.

Automatic Installation

MarkDoc can also automatically install Pandoc and wkhtmltopdf (but not LaTeX distribution!). For this feature, specify the install option. For example, let's create a smcl log-file named example2 and convert it to PDF without any manual installation (for required packages and third-party software).

quietly log using example2, replace smcl
markdoc example2, export(pdf) install title("This is an empty PDF") author("E. F. Haghish") date

example2.pdf is the output of this example.

NOTE that the smcl log-file is still open! You can produce the dynamic document at anytime to get a live-preview of the document without necessarily re-running the whole code.

Writing Static and Dynamic Text

Static Text

I mentioned that text can be written in a "special comment notation." This is rather important to distinguish between Stata's regular comments and comments that are meant to appear in the dynamic document. The example below shows the notation that is recognized by MarkDoc. Note that the "/***" and "***/" must appear on separate lines, keeping the rest of the line empty. However, intents can be used as pleased. This syntax is also supported in Mata

Markdown example

qui log using example, replace

/***
This is a Markdown Heading
==========================

This is a Markdown subheading
-----------------------------

This is a text paragraph. 
***/

qui log c
markdoc example, export(docx) replace install title("How to write text in MarkDoc") 

all other Stata comments will be ignored in the dynamic document.


HTML example

You could also produce identical dynamic document using HTML markup language. All you have to do after writing you code is informing MarkDoc that the markup language is HTML, by using the markup(name) option as shown in the following example.

qui log using example, replace

/***
<h1>This is a Markdown Heading</h1>

<h2>This is a Markdown subheading</h2>

<p>This is a text paragraph.</p> 
***/

qui log c
markdoc example, markup(html) export(pdf) replace install title("How to write text in MarkDoc") 

Dynamic Text

In MarkDoc, the text is written within a special notations of comments, which is only meaningful for MarkDoc (i.e. Stata treats it as regular comment block). This also mean that nothing get executed within the comment block, no global, no local, no scalar.

But it is very important to write dynamic text for interpreting the output of Stata within text paragraphs and headings. As a result, if a change is made to the data, all the values mentioned in the text will automatically change. To do so, the txt command is borrowed from Weaver package and updated to support MarkDoc. The txt command works similar to the display command in Stata but offers more functionalities. I recommend you reading the help txt thoroughly to understand how txt works differently in Weaver and MarkDoc.

qui log using example, replace smcl

/***
Writing dynamic text in MarkDoc
===============================

Use the `txt` command to write dynamic text in **MarkDoc** as shown below:
***/

//OFF
sysuse auto, clear
summarize price
//ON

txt "mean of Price variable is " r(mean) " and SD is " %9.3f r(sd)    ///
    ". Note that you only need to put the string in double quotes, if you " ///
    "wish to display **Scalars** within the text. Instead, if you include " ///
    "local or global **Macros**, you can just type any text without "       ///
    "bothering with the double quotations."

qui log c

markdoc example, replace export(docx) install title("How to write text in MarkDoc") 

Note: by default, the txt command print the scalars in the %10.2f format, because we usually report the numeric values with 2 decimal points. If you wish for more or less, use the formating directives to alter the command's interpretation. Why it's made automatic? because without this feature, all of the decimals returned for the scalar will be shown and that's not something you probably wish for. The example above shows how to show 3 decimal points for the Standard Deviation scalar.

Graphs and Image

Inserting a graph in an analysis report, presentation slides, or a Stata package documentation (if it's not exported in sthlp ) is inevitable and in MarkDoc, it's as simple as typing img once a current graph is created by Stata, or by importing a graphical file that is already exported from Stata. Let's open the auto.dta and provide a real reproducible example.

Markdown example

qui log using example, replace smcl

//OFF
sysuse auto, clear
histogram price
//ON

img					// that simple! 

//OFF
histogram mpg
graph export mpg.png, replace width(300)
//ON

img mpg.png, title("_Figure 2_. The histogram of the __mpg__ variable")

//or alternatively use Markdown syntax e.g.  ![description](filename)

/***
![_Figure 2_. The histogram of the __mpg__ variable](mpg.png)
***/

txt "![_Figure 2_. The histogram of the __mpg__ variable](mpg.png)" _n 

qui log c
markdoc example, export(docx) replace install author("E. F. Haghish") ///
title("Importing a graph in MarkDoc")

the img command writes the Markdown syntax automatically. If no filename or option is specified, img just automatically exports the current graph to a directory named Weaver-figure (located in the same directory that the smcl log-file is created) and then import it in the document (technically adds the Markup syntax for importing it). The syntax can be written manually whether as a static text or dynamically using the txt command. In the example above, the last 3 tables should be identical. However, I find the img command a more elegant way of importing images.

In the example above, the img command assumes that you are writing your document in Markdown. If you are writing in LaTeX or HTML and wish to add a graph automatically, you should specify the markup(name) option. Let's say you are writing a document in LaTeX, then repeating the example above would be as follows (note that I add the texmaster to let MarkDoc create the LaTeX template automatically, which makes my code look cleaner.

LaTeX example

qui log using example, replace smcl

/***
\section{Importing a graph in MarkDoc}
***/

sysuse auto, clear
histogram price
img , markup(latex)

qui log c
markdoc example, export(pdf) replace install markup(latex) texmaster ///
printer("/usr/texbin/pdflatex") author("E. F. Haghish") 

Note that in the example above, I am exporting a pdf from a code that is specified as latex, therefore, I will need to specify the path to the executable pdfLaTeX engine. I am using a Mac and the given path is the path to pdfLaTeX on my machine. If you are using Windows 7 and you have MikeTeX installed, you "might" be able to typeset the document to pdf without specifying this option.

Naturally, similar to the Markdown example, I could use LaTeX markup, whether written in the text block or given to the txt command to import the figure in the document.

HTML example

The same example can be repeated for HTML syntax. Just replace the LaTeX example with HTML markup and don't forget to specify the markup(html) and export to whether pdf or html.

Dynamic Table

MarkDoc borrows a powerful command for creating publication-ready dynamic table in any document format. An APA table in Microsoft word, PDF, LaTeX, HTML, ePub, Open Office, or PDF slides. The general documentation of the command is written in the Weaver package. Read these documentation before you try the following examples.

Generating Dynamic Slides

MarkDoc can also generate Dynamic Slides directly within Stata. Note that you will need to install LaTeX on your machine and provide the path to executable pdfLaTeX within the printer(str) option (or any of the alternatives, see the help file).

The dynamic document can include a variety of Beamer themes and users can customize the slides very similar to R-Markdown in R-Studio. A full list of available Themes and Color Themes is available in this link which are represented in vertical and horizontal axes respectively. Beamer font theme gallery is also a good web page that helps you to select your favorite font for the dynamic slides.

Keep in mind that slides are NOT as wide as documents and implement smaller line sizes. As a result, if you wish to include text output from Stata, reduce the font size by adding the "fontsize: #pt" to the header of the slides where the "#" represent the font size number. Here is an example:

qui log using example, replace

/***
Creating dynamic slides in Stata
================================

- Dynamic slides are slides created for statistical representation and thus, 
includes code and output from Stata. 

- The __`markdoc`__ command allows you to 
easily create a _smcl log file_ and use it for creating dynamic analysis 
reports or even PDF slides. In this tutorial I will demonstrate how to quickly 
create the slides from Stata. Here are a few capabilities of the package. 


About MarkDoc
=============

MarkDoc is a general purpose literate programming package that can export 
dynamic reports in several formats within Stata. However, this tutorial only 
demonstrates the dynamic slide feature. 

- Adding images and figures
- Interpreting mathematics
- creating PDF slides


How Does it Work?
=================

- Install MarkDoc (ssc install markdoc)
- Install a full LaTeX distribution
- provide the path to **pdfLaTeX** in the `printer()` option (see below)
- Learn from this example!




How about mathematics?
======================

The dynamic slides are compiled with LaTeX and naturally, 
LaTeX mathematical notations are supported. Here is an example:

- $f(x)=\sum_{n=0}^\infty\frac{f^{(n)}(a)}{n!}(x-a)^n$ 




How about Stata Output?
======================

You can execute any command and present the outputs as well!
***/

sysuse auto, clear
tab price if price < 4000

//OFF
histogram price
graph export graph.png, replace 
//ON


/***
Adding a graph
==========================

![Histogram of the *Price* variable](graph.png)



How to create more slides?
==========================

- Every heading creates a new slide. 
- You can also use __#__ at the beginning of the line for creating a new slide. 
- or make a line with equal signs under a text  line (see the code)

***/


qui log c

capture prog drop markdoc
markdoc example, export(slide) replace install printer("/usr/texbin/pdflatex")

example.pdf is the output of this example.

The example describes how to create slides within Stata do-file editor. I'd also highly recommend you to read the R-Markdown Beamer description. MarkDoc package is written with mainly the same functionalities.

Generating Dynamic Stata Help Files (sthlp)

To my knowledge, MarkDoc is the one and only available package in Stata for Stata package and programming documentation which can generate help files with sthlp and smcl extension. So far, documenting Stata package has been the nightmare of any Stata programmer because writing and updating the help file is very time consuming. Moreover, anyone familiar with SMCL language - which is the markup language of Stata for presenting output and writing help files - knows very well that reading SMCL files can be very confusing.

MarkDoc allows you to create your Stata help files using a simplified Markdown notation. In addition, you can style your documentation using SMCL language. Combining Markdown with SMCL ensures that you can export decent Stata help files directly from any script file (i.e. do, ado, Mata). This has many advantages compared to writing a Stata help file on a text editor.

  • It improves the readability of the documentation by using Markdown syntax. You'd find it much easier to navigate between the headings and find the next title
  • It makes the documentation remarkably cleaner. You don't have to deal much with SMCL tags
  • You can write the documentation within your programs, which makes them easier to comprehend by other users who are interested in your code
  • Updating your documentation becomes easier because it takes place the same time you update the program
  • Finally and most excitingly, you can use the same source for generating Stata help files as well as documentation in other formats such as PDF, Docx, LaTeX, or HTML. In other words, you can also release PDF documentation for your package that include images, mathematic formulas, etc.

Let's assume I have a very simple program that I wish to document and generate dynamic sthlp help files for it, which eases the task of package documentation and maintenance. And if it's done well, it also make the program easier to read because the documentation is written in relevance to the code. let's assume that my program is named myprogram, and it simply prints anything that it's given to it:

program myprogram
    display "`0'"
end	

Help-File Template

MarkDoc can generate dynamic Stata sthlp help files from any Stata script file such as do, ado, or mata files. Therefore, any file with .do, .ado, or .mata extension can be used for generating dynamic help files. The help file requires a number of distinct information which is not very relevant to the programming code, such as a description of the program and Author(s) details. MarkDoc begins generating the Stata help file by appending a template at the top of the script file. The header template is in the form of a special comment block, recognized by MarkDoc. The header templates includes blocks for specifying the version, describing the package, authors, and also the syntax and option table of the program. Appending the template to the script file is recommended. Adding the template and generating the first Stata help file happen simultaneously, to provide a help file that gives you an indication of "the current status" of your help file. To get the header template appended on your script-file, execute MarkDoc and specify the script filename.extension. If extension is not specified, and the export(sthlp) is specified, MarkDoc will assume you are talking about an ado file in the working directory, which is by far more commonly used for programming in Stata compared to its functional programming brother, Mata. This is how to append the header in the script file named myprogram.ado:

markdoc myprogram.ado, replace export(sthlp) date 

Avoiding the template header

If you'd like to generate the help files without appending any template (not recommended) or even reading the existing template that was previously appended to the help file, specify the template("empty") option. Similar to generating a dynamic document in MarkDoc, you may use the title(str), summary(str), author(str), affiliation(str), address(str), and date options to define the description and author's section of the help file and document the rest manually. Note that the title(str) option only should take the command-name, i.e. the command that can be executed in Stata.

Working with the template header

I follow the example, assuming you generate the Header template, which I recommend you to do so. Not if you open the myprogram.ado, you will notice that MarkDoc has appended a header template at the beginning of the file, and also an example comment block at the bottom of the ado file, as shown below.

/*** DO NOT EDIT THIS LINE -----------------------------------------------------

Version: 0.0.0


Intro Description
=================

packagename -- A new module for ... 


Author(s) section
=================

Author name ...
Author affiliation ...
to add more authors, leave an empty line between authors' information

Second author ...
For more information visit {browse "http://www.haghish.com/markdoc":MarkDoc homepage}


Syntax
=================

{opt exam:ple} {depvar} [{indepvars}] {ifin} using 
[{it:{help filename:filename}}]
[{cmd:,} {it:options}]

{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{synopt :{opt rep:lace}}replace this example{p_end}
{synopt :{opt app:end}}work further on this help file{p_end}
{synopt :{opt addmore}}you can add more description for the options; Moreover, 
       the text you write can be placed in multiple lines {p_end}
{synopt :{opt learn:smcl}}you won't make a loss learning
{help smcl:SMCL Language} {p_end}
{synoptline}
----------------------------------------------------- DO NOT EDIT THIS LINE ***/


program myprogram
    display "`0'"
end

/***
Example
=================

    explain what it does
        . example command

    second explanation
        . example command
***/

In addition, Stata will also return:

(MarkDoc created myprogram.sthlp)

myprogram.sthlp is the output of this example.

If you download the output, you'd see that you already have a good-looking template help file! All you need to do is to edit the Header template. But that's just the beginning. At the bottom, you could see the Example comment block. Through the script file, you may use as many comment blocks as you wish to document your program. Similar to writing text for generating dynamic document, the text should be written within " /***" and "***/" signs, each appearing on a separate lines. The Markdown header syntax, can be used to define the title of that section, if there is any title. By avoiding the title, you can append many comment blocks in one section of the help file. let's assume you'd like to add a section in the help file, named "resources":

/***
Resources
=========

You may also find reading {help SMCL} help file useful.
***/

This would create a new section in the help file with the "Resources" as the title i.e. "{title:Resources}" in the STHLP file. Yet, you will find learning the SMCL language very helpful for making your helpfile more "Stata-like" and less like beginner-level help-file. But the point is that using MarkDoc, you can reproduce your help files dynamically and also, make your programs easier to comprehend. People who read your code, would be able to read the relevant documentation as well, within the code files.

Supported Markdown Syntax

MarkDoc supports several Markdown syntax for styling the Stata help file. In other words, MarkDoc (v. 3.6.6) includes a small built in engine for Markdown to SMCL translator, which is literally the same language used for Stata help files. You already have noticed that you can use the Markdown heading syntax to create heading in the help file. Since SMCL does not allow changing the font size, both header 1 and header 2 will produce a heading in Stata. Therefore the output of the following example is identical:

/***
Heading 
=======

Heading
-------
***/

The important point about writing with Markdown is that MarkDoc requires some indications to separate paragraphs from single-line text. For example, if you'd like to add some examples in the code, you can indent the text as you wish and the white space will be preserved in the help file. This feature is important to ensure you can simply edit the help file by adding indention instead of using SMCL directives (although you can use SMCL as well, so you have a choice to make!). MarkDoc has 2 simplified directives for writing regular text paragraphs i.e. "{p}" in SMCL, and a paragraph with indents which is "{p 4 4 2}" in SMCL. The latter is widely used in Stata help files, because Stata folks prefer the text paragraphs to include an indent and do not begin right below the heading. Luckily, Markdown has a directive for indenting text, which is used for writing quotations. The other directive is rather fabricated by MarkDoc ind is the ":" sign, which indicates a regular paragraph without indention. Therefore:

/***

this text line is rendered with preserved white-space in Stata help file 
    and therefore, this text appears in the help-file the same way 
         you see it now! recommended for writing examples, indenting code, etc.

: This is a text paragraph and thus, multiple successive lines 
will form a paragraph with no indention. Yet, you barely see any text paragraph 
with no indention in Stata help files. But it does not mean you can't use it...
This syntax is particularly important if you also wish to produce a PDF or Docx 
version of the package documentation. 

> This is also a text paragraph, but it include 4-space of indention, typically used 
in Stata help files to make them more appealing. I recommend you this syntax for writing 
help files. This syntax will also add an indention (i.e. quote paragraph) to the text paragraphs, 
if you export them to other document formats such as Docx. 


{p 4 4 2}
So you may wish for a nice way of writing a text paragraph that appears with indention 
in Stata help file and with no indention in other document formats such as Docx? 
Well, use SMCL markup and apply {p 4 4 2} above the line! As simple as that!  
    
***/

You can also use the regular Markdown styling for making text bold or italic. Markdown also has a sign for making the text bold and italic which is not supported in SMCL. Therefore, I changed this syntax for underscoring text. This is how it works in Stata help-file documentation:

/***

_Italic text_ 

__Bold text__

___Underscored text___   
    
***/

Finally, MarkDoc provides 2 additional Markdown directives, which are used for creating a line or a tab. The latter, was fabricated by MarkDoc by adding new options to the engine. These two directives can really make your help files more appealing by separating the content, when you are talking about a number of different topics in the same help file.

/***

- - - 

- - - This is a Tab
    
***/

If you know Markdown, you already are familiar with the line syntax which is "- - -". In addition to the line directives, if you add any text after this directive, MarkDoc interpret it as a Tab and creates a smart tab in your help file with the same title, the text that you've wrote after the line. And finally, you can also indent these directives. Stata tends to use the line for separating examples and they do it by indenting the line (i.e. the line begins with some indention, typically the same amount of indention that the example has.

A note to the advanced reader

Compared to R, Stata help files are rather fancy and I mean it in a good way. Stata puts a lot of effort in the help files to make them easy to comprehend whereas R help files are ... not ideal. In fact, Stata help files are literally educative. They teach you things and provide many examples for each command. This is part of the reason why developing "Stata-like" help files is so time consuming, but rewarding for the community. In addition, Stata also uses SMCL language to produces outstanding outputs from the programs. Therefore, I realized instead of pushing the users away from SMCL, I should encourage them to master this markup language and practice it more often. I do the same when I teach Stata programming workshops, i.e. I put some emphasis on SMCL and pick programming examples that require learning this markup language. In the long run, it'll help them produce better output, nicer tables, and more elegant help-files when they join the developers community. Besides, I think only advanced users truly care about literate programming and dynamic help files, because only advanced users actually program! As simply as that. And, well, I assume advanced users know SMCL enough or would be able to pick it up within 30-minutes of reading.

You should also note that Markdown is a very simplified language and by no means provide the wide-range of styling options of SMCL. Especially, for writing syntax. having the Markdown headings is a big bonus because it makes reading the script file easier. The user can also get benefit from Markdown syntax for writing text paragraphs, quotations (paragraphs with indent), drawing lines and with a bit of alternation provided by MarkDoc, create SMCL tabs very easily! Nevertheless, using the other SMCL directives, would guarantee an appealing help-files rather than merely basic ones. But I guarantee that even these basic Markdown directives - which are tuned to produce Stata-like STHLP files - can get you very near perfection!

Mathematical Notations

MarkDoc supports ASCIImath and LaTeX mathematical notations, based on the Markup language used for documentation. The ASCII math is easier to read and write compared to LaTeX on the one hand, but is less popular on the other. The mathematical notations should be separated from regular text. For more information see the Mathematical section in Weaver homepage