How to Write a Stata Help File

You can add functionality to Stata by creating your own programs. Once you have a working program, it can be useful to write a help file to go along with the program. This allows the program to be easily used by others if you wish to share it, and can also help remind you of its function.

Stata help files are written in Stata Markup and Control Language (smcl). To get Stata to process parts of your help file in a certain way you use smcl tags in curly braces {}. SMCL tags are read in one of four ways:

{tag:text} = perform tag to the text, within a sentence that is running differently.
{tag} = perform tag, will remain permanently until changed elsewhere in the file.
{tag args} = perform tag, modified by any arguments given.
{tag args:text} = perform tag, modified by the arguments, specifically to the text specified.

For example, if you wanted to put some text in italics – {it:insert italics text here}. The “it:” part is the tag for italics and indicates the text following the colon and within the curly braces should be processed into italics. The “{it:}” method is used for italics within a sentence. If you want a whole block of text in italics, you can specify “{it}” at the start of the line, and then everything that follows will be in italics until you give a new text direction. Below I will give a list of common tags you will want to use in your help file, as well as which of the 4 methods shown above can be used for that tag.

SMCL Tags

Text formatting – Italics, bold, normal text, underline (1,2)

{it}

{bf}

{sf}

{ul}

Stata Formatted Text – format text according to the type specified (1,2)

{cmd}

{error}

{result}

{text}

Command with abbreviation underlined (2)

{cmdab:text1:text2}

*text1 is the abbreviation, text2 is the rest of the command

e.g. to show summarize – {cmdab:su:mmarize}

Command Options (1,2,3,4)

{opt}

Highlight a reference (1,2)

{hi}

Insert horizontal line (1,3)

{hline}

Reset the text to its normal state (1)

{reset}

Mark a location to jump to – place jump-to marker at the top of help file, and marker at location

{viewerjumpto “text” “helpfilename##markername}{…}

…

{marker markername}{…}

Document formatting – title, center/right align/left align text, tab

{title:text}

{center}

{ralign}

{lalign}

{tab}

Paragraphs

Paragraph is special, as it is very customisable. You specify a paragraph as follows:

{p #1 #2 #3 #4}

{p}

Specifying {p} at the beginning of a line is equivalent to specifying {p 0 0 0 0}. You can specify 1 to 4 numbers, which will indicate the following settings for the paragraph. The first number (#1) is how many characters to indent the first line; the second number (#2) is how many characters to indent the second and third lines; the third number (#3) is how far in from the right should the margin be; the fourth number (#4) is for the total width of the paragraph. Any number you don’t specify will default to 0, except for the fourth number which will just be the default paragraph width.

Commonly used paragraph settings

{phang} – commonly used for short paragraphs

{pstd} – commonly used for description paragraphs or other blocks of text

{phang2} – used within other paragraphs

{p2col} – for separating text into two columns

{p_end} – can be used to end a paragraph. This is useful when you are switching between different paragraph formats. Put this tag at the end of a paragraph. You can also just separate each new paragraph tag with a new line, it has the same effect.

Worked Example - Writing a help file for my graph command Outlabs

I recently created a scatter graph where points outside a range needed to be labelled. I created a normal scatter graph, adding two lines to specify the range, and labelled any points that fell outside the lines. Since this was something I might need to do again in the future, I created a small program to do the heavy lifting for me. All I needed to do was specify the range and the two variables, and my program would create the graph for me. I called this command outlabs (outliers with labels). I have linked the command ado file below.

outlabs.ado

I was asked to share this command with someone else who wanted to use it. Rather than trying to explain to them how to use it, I wrote a help file to go with it. This helps me to remember how the command works, and makes it easy to share the command with others. The contents of the help file, written in smcl tags, is shown below:

{smcl}

{**! version 16.0 15jul2020}{…}

{viewerdialog outlabs “dialog outlabs”}{…}

{viewerjumpto “Syntax” "outlabs##syntax}{…}

{viewerjumpto “Menu” "outlabs##menu}{…}

{viewerjumpto “Description” "outlabs##description}{…}

{viewerjumpto “Options” "outlabs##options}{…}

{viewerjumpto “Examples” "outlabs##examples}{…}

{p2col:{bf:outlabs}}Scatter with confidence intervals

{marker syntax}{…}

{title:Syntax}

{p}

{cmd:outlabs} {varlist}{cmd:,} {opt conf(numlist)} [{opt x:split} {opt an:gle(integer)}]

{marker menu}{…}

{title:Menu}

{phang}{bf:User > Graphics > Scatter with confidence intervals}

{marker description}{…}

{title:Description}

{pstd}

{cmd:outlabs} draws a scatter plot with lines indicating a range or confidence intervals. Any values that fall outside the range are considered outliers and are labelled. First and second variables are the Y and X variables respectively. An optional third variable is used as the label. If no third variable is specified, outliers are labelled with their values. The range is assumed to be for the Y variable, unless otherwise specified.

{marker options}{…}

{title:Options}

{phang}{opt conf(numlist)} is required. It specifies the range or confidence intervals to be used. Two values must be specified.

{phang}{opt x:split} specifies whether the supplied range is for the X variable. If {opt xsplit} is not specified the range is used with the Y variable

{phang}{opt an:gle(integer)} specifies the angle applied to the labels. The default angle is -45 degrees.

{marker examples}{…}

{title:Examples}

{hline}

{pstd}Setup

{phang2}{cmd:. sysuse auto}

{phang2}{cmd:. summarize price, detail}

{pstd}Scatter {cmd:price} against {cmd:mpg}, labelling anything above 95th percentile or below 5th percentile as an outlier.

{phang2}{cmd:. outlabs price mpg, conf(14500 3299)}

{pstd}Scatter variable {cmd:price} against {cmd:mpg}, labelling anything outside the range with labels angled at 90 degrees.

{phang2}{cmd:. outlabs price mpg, conf(14500 3299) angle(90)}

{pstd}Scatter variable {cmd:price} against {cmd:mpg}, putting variable {cmd:price} on the x-axis, and labelling outliers with the variable {cmd:make}.

{phang2}{cmd:. outlabs mpg price make, conf(14500 3299) xsplit}

{hline}

There are a few things to note here. Firstly, I leave a blank line between my paragraph tags. This works the same as the {p_end} tag. If you would rather not have these spaces in your help file, simply add the {p_end} tag at the end of each paragraph. You can then continue on with the next paragraph tag without having the paragraphs run together. I prefer using the blank line method because it makes my smcl-coded help file easier to read and edit.

You will also note the viewerdialog tag near the top of this help file, just above the viewerjumpto tags. I have created my own menu dialog box to go along with this command. This viewerdialog tag is linking to my outlabs.dlg file, and it can be opened under the Dialog drop-down menu in the help file viewer. The viewerjumpto tags are linking to the corresponding markers throughout the help file. These markers will appear in the Jump to drop-down menu in the help file viewer. These two drop-down menus can be found in the top right of the viewer window, as shown below:

For more information on how to write in smcl, as well as a full list of available tags, check out the help file with the command:

help smcl

If you would like to play around with the tags, I have linked the full help file below.

outlabs.sthlp

You can open the help file in Stata by going to “File > Open…” in the Stata menus and selecting the outlabs.sthlp file to see how it looks in Stata.