STATA Instructions Psmcl

User Manual:

Open the PDF directly: View PDF .
Page Count: 24

Title stata.com

smcl — Stata Markup and Control Language

Description Remarks and examples Also see

Description

SMCL, which stands for Stata Markup and Control Language and is pronounced “smickle”, is

Stata’s output language. SMCL directives, such as “{it:. . . }” in

You can output {it:italics} using SMCL

affect how output appears:

You can output italics using SMCL

All Stata output is processed by SMCL: help ﬁles, statistical results, and even the output of display

(see [P]display) in the programs you write.

Remarks and examples stata.com

Remarks are presented under the following headings:

Introduction

SMCL modes

Command summary—general syntax

Help ﬁle preprocessor directive for substituting repeated material

Formatting directives for use in line and paragraph modes

Link directives for use in line and paragraph modes

Formatting directives for use in line mode

Formatting directives for use in paragraph mode

Directive for entering the as-is mode

Inserting values from constant and current-value class

Displaying characters using ASCII and extended ASCII codes

Advice on using display

Advice on formatting help ﬁles

Introduction

You will use SMCL mainly in the programs you compose and in the help ﬁles you write to document

them, although you can use it in any context. Everything Stata displays on the screen is processed

by SMCL. You can even use some of SMCL’s features to change how text appears in graphs; see

[G-4]text.

Your ﬁrst encounter with SMCL was probably in the Stata session logs created by the log using

command. By default, Stata creates logs in SMCL format and gives them the ﬁle sufﬁx .smcl. The

ﬁle sufﬁx does not matter; that the output is in SMCL format does. Files containing SMCL can be

redisplayed in their original rendition, and SMCL output can be translated to other formats through

the translate command; see [R]translate.

SMCL is mostly just plain text, for instance,

. display "this is SMCL"

this is SMCL

but that text can contain SMCL directives, which are enclosed in braces. Try the following:

2smcl — Stata Markup and Control Language

. display "{title:this is SMCL, too}"

The “{title:. . . }” directive told SMCL to output what followed the colon in title format. Exactly

how the title format appears on your screen—or on paper if you print it—will vary, but SMCL will

ensure that it always appears as a recognizable title.

Now try this:

. display "now we will try {help summarize:clicking}"

now we will try

The word clicking will appear as a link—probably in some shade of blue. Click on the word.

This will bring up Stata’s Viewer and show you the help for the summarize command. The SMCL

{help:. . . }directive is an example of a link. The directive {help summarize:clicking} displayed

the word clicking and arranged things so that when the user clicked on the highlighted word, help

for summarize appeared.

Here is another example of a link:

. display "You can also run Stata commands by {stata summarize mpg:clicking}"

You can also run Stata commands by

Click on the word, and this time the result will be exactly as if you had typed the command summarize

mpg into Stata. If you have the automobile data loaded, you will see the summary statistics for the

variable mpg.

Simply put, you can use SMCL to make your output look better and to add links.

SMCL modes

SMCL is always in one of three modes:

1. SMCL line mode

2. SMCL paragraph mode

3. As-is mode

Modes 1 and 2 are nearly alike—in these two modes, SMCL directives are understood, and the modes

differ only in how they treat blanks and carriage returns. In paragraph mode—so called because it is

useful for formatting text into paragraphs—SMCL joins one line to the next and splits lines to form

output with lines that are of nearly equal length. In line mode, SMCL shows the line much as you

entered it. For instance, in line mode, the input text

Variable name mean standard error

(which might appear in a help ﬁle) would be spaced in the output exactly as you entered it. In

paragraph mode, the above would be output as “Variable name mean standard error”, meaning that

it would all run together. On the other hand, the text

The two main uses of SMCL are in the programs you compose and in the help files

you write to document them, although SMCL may be used in any context.

Everything Stata displays on the screen is processed by SMCL.

would display as a nicely formatted paragraph in paragraph mode.

In mode 3, as-is mode, SMCL directives are not interpreted. {title:. . . }, for instance, has no

special meaning—it is just the characters open brace, t, i, and so on. If {title:. . . }appeared in

SMCL input text,

{title:My Title}

smcl — Stata Markup and Control Language 3

it would be displayed exactly as it appears: {title:My Title}. In as-is mode, SMCL just displays

text as it was entered. As-is mode is useful only for those wishing to document how SMCL works

because, with as-is mode, they can show examples of what SMCL input looks like.

Those are the three modes, and the most important of them are the ﬁrst two, the SMCL modes,

and the single most important mode is SMCL line mode—mode 1. Line mode is the mother of all

modes in that SMCL continually returns to it, and you can get to the other modes only from line

mode. For instance, to enter paragraph mode, you use the {p} directive, and you use it from line

mode, although you typically do not think of that. Paragraphs end when SMCL encounters a blank

line, and SMCL then returns to line mode. Consider the following lines appearing in some help ﬁle:

{p}

The two main uses of SMCL are in the programs you compose and the

help files you write to document them, although SMCL may be used in any context.

Everything Stata displays on the screen is processed by SMCL.

{p}

Your first encounter with SMCL was probably the Stata session

. . .

Between the paragraphs above, SMCL returned to line mode because it encountered a blank line.

SMCL stayed in paragraph mode as long as the paragraph continued without a blank line, but once

the paragraph ended, SMCL returned to line mode. There are ways of ending paragraphs other than

using blank lines, but they are the most common. Regardless of how paragraphs end, SMCL returns

to line mode.

In another part of our help ﬁle, we might have

{p}

SMCL, which stands for Stata Markup and Control Language

and is pronounced "smickle", is Stata’s output language.

SMCL directives, for example, the {c -(}it:...{c )-} in the following,

One can output {it:italics} using SMCL

{p} affects how output appears: . . .

Between the paragraphs, SMCL entered line mode (again, because SMCL encountered a blank line),

so the “One can output. . . ” part will appear as you have spaced it, namely, indented. It will appear

that way because SMCL is in line mode.

The other mode is invoked using the {asis} directive and does not end with a blank line. It

continues until you enter the {smcl} directive, and here {smcl} must be followed by a carriage return.

You may put a carriage return at the end of the {asis} directive—it will make no difference—but

to return to SMCL line mode, you must put a carriage return directly after the {smcl} directive.

To summarize, when dealing with SMCL, begin by assuming that you are in line mode; you almost

certainly will be. If you wish to enter a paragraph, you will use the {p} directive, but once the

paragraph ends, you will be back in line mode and ready to start another paragraph. If you want to

enter as-is mode, perhaps to include a piece of text output, use the {asis} directive, and at the end

of the piece, use the {smcl}(carriage return) directive to return to line mode.

Command summary—general syntax

Pretend that {xyz} is a SMCL directive, although it is not. {xyz} might have any of the following

syntaxes:

Syntax 1: {xyz}

Syntax 2: {xyz:text}

4smcl — Stata Markup and Control Language

Syntax 3: {xyz args}

Syntax 4: {xyz args:text}

Syntax 1 means “do whatever it is that {xyz} does”. Syntax 2 means “do whatever it is that {xyz}

does, do it on the text text, and then stop doing it”. Syntax 3 means “do whatever it is that {xyz}

does, as modiﬁed by args”. Finally, syntax 4 means “do whatever it is that {xyz} does, as modiﬁed

by args, do it on the text text, and then stop doing it”.

Not every SMCL directive has all four syntaxes, and which syntaxes are allowed is made clear in

the descriptions below.

In syntaxes 3 and 4, text may contain other SMCL directives, so the following is valid:

{center:The use of {ul:SMCL} in help files}

The text of one SMCL directive may itself contain other SMCL directives. However, not only must the

braces match, but they must match on the same physical (input) line. Typing

{center:The use of {ul:SMCL} in help files}

is correct, but

{center:The use of {ul:SMCL} in

help files}

is an error. When SMCL encounters an error, it simply displays the text in the output it does not

understand, so the result of making the error above would be to display

{center:The use of SMCL in

help files}

SMCL understood {ul:. . . }but not {center:. . . }because the braces did not match on the input

line, so it displayed only that part. If you see SMCL directives in your output, you have made an error.

smcl — Stata Markup and Control Language 5

Help ﬁle preprocessor directive for substituting repeated material

INCLUDE help arg follows syntax 3.

INCLUDE speciﬁes that SMCL substitute the contents of a ﬁle named arg.ihlp. This is useful

when you need to include the same text multiple times. This substitution is performed only when

the ﬁle is viewed using help.

Example:

We have several commands that accept the replace option. Instead of typing the description

under Options of each help ﬁle, we create the ﬁle replace.ihlp, which contains something like

the following:

{* 01apr2005}{...}

{phang}

{opt replace} overwrite existing {it:filename}{p_end}

To include the text in our help ﬁle, we type

INCLUDE help replace

Formatting directives for use in line and paragraph modes

{sf},{it}, and {bf} follow syntaxes 1 and 2.

These directives specify how the font is to appear. {sf} indicates standard face, {it} italic face,

and {bf} boldface.

Used in syntax 1, these directives switch to the font face speciﬁed, and that rendition will continue

to be used until another one of the directives is given.

Used in syntax 2, they display text in the speciﬁed way and then switch the font face back to

whatever it was previously.

Examples:

the value of {it}varlist {sf}may be specified . . .

the value of {it:varlist} may be specified . . .

{input},{error},{result}, and {text} follow syntaxes 1 and 2.

These directives specify how the text should be rendered: in the style that indicates user input, an

error, a calculated result, or the text around calculated results.

These styles are often rendered as color. In the Results window, on a white background, Stata

by default shows input in black and bold, error messages in red, calculated results in black and

bold, and text in black. However, the relationship between the real colors and {input},{error},

{result}, and {text} may not be the default (the user could reset it), and, in fact, these

renditions may not be shown in color at all. The user might have set {result}, for instance, to

show in yellow, or in highlight, or in something else. However the styles are rendered, SMCL tries

to distinguish among {input},{error},{result}, and {text}.

Examples:

{text}the variable mpg has mean {result:21.3} in the sample.

{text}mpg {c |} {result}21.3

{text}mpg {c |} {result:21.3}

{error:variable not found}

6smcl — Stata Markup and Control Language

{inp},{err},{res}, and {txt} follow syntaxes 1 and 2.

These four commands are synonyms for {input},{error},{result}, and {text}.

Examples:

{txt}the variable mpg has mean {res:21.3} in the sample.

{txt}mpg {c |} {res}21.3

{txt}mpg {c |} {res:21.3}

{err:variable not found}

{cmd} follows syntaxes 1 and 2.

{cmd} is similar to the “color” styles and is the recommended way to show Stata commands in

help ﬁles. Do not confuse {cmd} with {inp}.{inp} is the way commands actually typed are

shown, and {cmd} is the recommended way to show commands you might type. We recommend

that you present help ﬁles in terms of {txt} and use {cmd} to show commands; use any of {sf},

{it}, or {bf} in a help ﬁle, but we recommend that you not use any of the “colors” {inp},

{err}, or {res}, except where you are showing actual Stata output.

Example:

When using the {cmd:summarize} command, specify . . .

{cmdab:text1:text2}follows a variation on syntax 2 (note the double colons).

{cmdab} is the recommended way to show minimum abbreviations for Stata commands and options

in help ﬁles; text1 represents the minimum abbreviation, and text2 represents the rest of the text.

When the entire command or option name is the minimum abbreviation, you may omit text2 along

with the extra colon. {cmdab:text}is then equivalent to {cmd:text}; it makes no difference which

you use.

Examples:

{cmdab:su:mmarize} [{it:varlist}] [{it:weight}] [{cmdab:if} {it:exp}]

the option {cmdab:ef:orm}{cmd:({it:varname})} . . .

{opt option},{opt option(arg)},{opt option(a,b)}, and {opt option(a|b)} follow syntax 3;

alternatives to using {cmd}.

{opt option1:option2},{opt option1:option2(arg)},{opt option1:option2(a,b)}, and

{opt option1:option2(a|b)} follow syntaxes 3 and 4; alternatives to using {cmdab}.

{opt} is the recommended way to show options. {opt} allows you to easily include arguments.

SMCL directive . . . is equivalent to typing . . .

{opt option} {cmd:option}

{opt option(arg)} {cmd:option(}{it:arg}{cmd:)}

{opt option(a,b)} {cmd:option(}{it:a}{cmd:,}{it:b}{cmd:)}

{opt option(a|b)} {cmd:option(}{it:a}|{it:b}{cmd:)}

{opt option1:option2} {cmd:option1:option2}

{opt option1:option2(arg)} {cmd:option1:option2(}{it:arg}{cmd:)}

{opt option1:option2(a,b)} {cmd:option1:option2(}{it:a}{cmd:,}{it:b}{cmd:)}

{opt option1:option2(a|b)} {cmd:option1:option2(}{it:a}|{it:b}{cmd:)}

option1 represents the minimum abbreviation, and option2 represents the rest of the text.

a,band a|bmay have any number of elements. Available elements that are displayed in {cmd}

style are ,,=,:,*,%, and (). Several elements are displayed in plain text style: |,{ }, and [ ].

Also, {opth option(arg)} is equivalent to {opt}, except that arg is displayed as a link to help;

see Link directives for use in line and paragraph modes for more details.

smcl — Stata Markup and Control Language 7

Examples:

{opt replace}

{opt bseunit(varname)}

{opt f:ormat}

{opt sep:arator(#)}

{hilite} and {hi} follow syntaxes 1 and 2.

{hilite} and {hi} are synonyms. {hilite} is the recommended way to highlight (draw attention

to) something in help ﬁles. You might highlight, for example, a reference to a manual, the Stata

Journal, or a book.

Examples:

see {hilite:[R] anova} for more details.

see {hi:[R] anova} for more details.

{ul} follows syntaxes 2 and 3.

{ul on} starts underlining mode. {ul off} ends it. {ul:text}underlines text.

Examples:

You can {ul on}underline{ul off} this way or

you can {ul:underline} this way

{*} follows syntaxes 2 and 4.

{*} indicates a comment. What follows it (inside the braces) is ignored.

Examples:

{* this text will be ignored}

{*:as will this}

{hline} follows syntaxes 1 and 3.

{hline} (syntax 1) draws a horizontal line the rest of the way across the page.

{hline #}(syntax 3) draws a horizontal line of #characters.

{hline} (either syntax) is generally used in line mode.

Examples:

{hline}

{hline 20}

{.-} follows syntax 1.

{.-} is a synonym for {hline} (syntax 1).

Example:

{.-}

{dup #:text}follows syntax 4.

{dup} repeats text # times.

Examples:

{dup 20:A}

{dup 20:ABC}

8smcl — Stata Markup and Control Language

{char code}and {c code}are synonyms and follow syntax 3.

These directives display the speciﬁed characters that otherwise might be difﬁcult to type on your

keyboard. See Displaying characters using ASCII and extended ASCII codes below.

Examples:

C{c o’}rdoba es una joya arquitect{c o’}nica.

{c S|}57.20

The ASCII character 206 in the current font is {c 206}

The ASCII character 5a (hex) is {c 0x5a}

{c -(} is open brace and {c )-} is close brace

{reset} follows syntax 1.

{reset} is equivalent to coding {txt}{sf}.

Example:

{reset}

Link directives for use in line and paragraph modes

All the link commands share the feature that when syntax 4 is allowed,

Syntax 4: {xyz args:text}

then syntax 3 is also allowed,

Syntax 3: {xyz args}

and if you specify syntax 3, Stata treats it as if you speciﬁed syntax 4, inserting a colon and then

repeating the argument. For instance, {help} is deﬁned below as allowing syntaxes 3 and 4. Thus

the directive

{help summarize}

is equivalent to the directive

{help summarize:summarize}

Coding {help summarize} or {help summarize:summarize} both display the word summarize,

and if the user clicks on that, the action of help summarize is taken. Thus you might code

See help for {help summarize} for more information.

This would display “See help for summarize for more information” and make the word summarize

a link. To make the words describing the action different from the action, use syntax 4,

You can also {help summarize:examine the summary statistics} if you wish.

which results in “You can also examine the summary statistics if you wish.”

The link directives, which may be used in either line mode or paragraph mode, are the following:

{help args[:text]}follows syntaxes 3 and 4.

{help} displays args as a link to help args; see [R]help. If you also specify the optional :text,

text is displayed instead of args, but you are still directed to the help ﬁle for args.

Examples:

{help epitab}

{help summarize:the mean}

smcl — Stata Markup and Control Language 9

{helpb args[:text]}follows syntaxes 3 and 4.

{helpb} is equivalent to {help}, except that args or text is displayed in boldface.

Examples:

{helpb summarize}

{helpb generate}

{manhelp args1 args2[:text]}follows syntaxes 3 and 4.

{manhelp} displays [args2]args1 as a link to help args1; thus our ﬁrst example below would

display [R] summarize as a link to help summarize. Specifying the optional :text displays text

instead of args1, but you are still directed to the help ﬁle for args1.

Examples:

{manhelp summarize R}

{manhelp weight U:14 Language syntax}

{manhelp graph twoway G:graph twoway}

{manhelpi args1 args2[:text]}follows syntaxes 3 and 4.

{manhelpi} is equivalent to {manhelp}, except that args or text is displayed in italics.

Examples:

{manhelpi twoway options G}

{manhelpi mata M:Mata Reference Manual}

{help args##markername[|viewername] [:text]}and {marker markername}follow syntax 3.

They let the user jump to a speciﬁc location within a ﬁle, not just to the top of the ﬁle. {help

args##markername}displays args##markername as a link that will jump to the location marked by

{marker markername}. Specifying the optional |viewername will display the results of {marker

markername}in a new Viewer window named viewername;new is a valid viewername that

assigns a unique name for the new Viewer. Specifying the optional :text displays text instead of

args##markername.args represents the name of the ﬁle where the {marker} is located. If args

contains spaces, be sure to specify it within quotes.

We document the directive as {help . . . }; however, view,news,net,ado, and update may be

used in place of help, although you would probably want to use only help or view.

Examples:

{pstd}You can change the style of the text using the {cmd}

directive; see {help example##cmd} below.

You can underline a word or phrase with the {ul} directive;

see {help example##ul:below}.

{marker cmd}{...}

{phang}{cmd} follows syntaxes 1 and 2.{break}

{cmd} is another style not unlike the ...

{marker ul}{...}

{phang}{ul} follows syntaxes 2 and 3.{break}

{ul on} starts underlining mode. {ul} ...

{help d:text}follows syntax 2.

{help d} displays text as a link that will display a help dialog box from which the user may

obtain interactive help on any Stata command.

Example:

. . . using the {help d:help system} . . .

10 smcl — Stata Markup and Control Language

{newvar[:args]}follows syntaxes 1 and 2.

{newvar} displays newvar as a link to help newvar. If you also specify the optional :args, Stata

concatenates args to newvar to display newvarargs.

Examples:

{newvar}

{newvar:2}

{var[:args]}and {varname[:args]}follow syntaxes 1 and 2.

{var} and {varname} display varname as a link to help varname. If you also specify the

optional :args, Stata concatenates args to varname to display varnameargs.

Examples:

{var}

{var:1}

{varname}

{varname:2}

{vars[:args]}and {varlist[:args]}follow syntaxes 1 and 2.

{vars} and {varlist} display varlist as a link to help varlist. If you also specify the optional

:args, Stata concatenates args to varlist to product varlistargs.

Examples:

{vars}

{vars:1}

{varlist}

{varlist:2}

{depvar[:args]}follows syntaxes 1 and 2.

{depvar} displays depvar as a link to help depvar. If you also specify the optional :args, Stata

concatenates args to depvar to display depvarargs.

Examples:

{depvar}

{depvar:1}

{depvars[:args]}and {depvarlist[:args]}follow syntaxes 1 and 2.

{depvars} and {depvarlist} display depvarlist as a link to help depvarlist. If you also

specify the optional :args, Stata concatenates args to depvarlist to display depvarlistargs.

Examples:

{depvars}

{depvars:1}

{depvarlist}

{depvarlist:2}

{indepvars[:args]}follows syntaxes 1 and 2.

{indepvars} displays indepvars as a link to help varlist. If you also specify the optional

:args, Stata concatenates args to indepvars to display indepvarsargs.

Examples:

{indepvars}

{indepvars:1}

smcl — Stata Markup and Control Language 11

{ifin} follows syntax 1.

{ifin} displays [if ]and [in], where if is a link to the help for the if qualiﬁer and in is a link

to the help for the in qualiﬁer.

Example:

{ifin}

{weight} follows syntax 1.

{weight} displays [weight], where weight is a link to the help for the weight speciﬁcation.

Example:

{weight}

{dtype} follows syntax 1.

{dtype} displays [type], where type is a link to help data types.

Example:

{dtype}

{search args[:text]}follows syntaxes 3 and 4.

{search} displays text as a link that will display the results of search on args; see [R]search.

Examples:

{search anova:click here} for the latest information on ANOVA

Various programs are available for {search anova}

{search d:text}follows syntax 2.

{search d} displays text as a link that will display a Keyword Search dialog box from which

the user can obtain interactive help by entering keywords of choice.

Example:

. . . using the {search d:search system} . . .

{dialog args[:text]}follows syntaxes 3 and 4.

{dialog} displays text as a link that will launch the dialog box for args.args must contain

the name of the dialog box and may optionally contain , message(string), where string is the

message to be passed to the dialog box.

Example:

. . . open the {dialog regress:regress dialog box} . . .

{browse args[:text]}follows syntaxes 3 and 4.

{browse} displays text as a link that will launch the user’s browser pointing at args. Because

args is typically a URL containing a colon, args usually must be speciﬁed within quotes.

Example:

. . . you can {browse "http://www.stata.com":visit the Stata website} . . .

{view args[:text]}follows syntaxes 3 and 4.

{view} displays text as a link that will present in the Viewer the ﬁlename args. If args is a

URL, be sure to specify it within quotes. {view} is seldom used in a SMCL ﬁle (such as a help

ﬁle) because you will seldom know of a ﬁxed location for the ﬁle unless it is a URL.{view} is

sometimes used from programs because the program knows the location of the ﬁle it created.

{view} can also be used with {marker}; see {help args##markername[|viewername] [:text]}

and {marker markername}, earlier in this section.

12 smcl — Stata Markup and Control Language

Examples:

see {view "http://www.stata.com/man/readme.smcl"}

display ‘"{view "‘newfile’":click here} to view the file created"’

{view d:text}follows syntax 2.

{view d} displays text as a link that will display the Choose File to View dialog box in which

the user may type the name of a ﬁle or a URL to be displayed in the Viewer.

Example:

{view d:Click here} to view your current log

{manpage args[:text]}follows syntaxes 3 and 4.

{manpage} displays text as a link that will launch the user’s PDF viewer pointing at args.args

are a Stata manual (such as Ror SVY) and a page number. The page number is optional. If the

page number is not speciﬁed, the PDF viewer will open to the ﬁrst page of the ﬁle.

Example:

The formulas are given on {manpage R 342:page 342 of [R] manual}.

{mansection args[:text]}follows syntaxes 3 and 4.

{mansection} displays text as a link that will launch the user’s PDF viewer pointing at args.

args are a Stata manual (such as Ror SVY) and a named destination within that manual (such

as predict or regress postestimation). The named destination is optional. If the named

destination is not speciﬁed, the PDF viewer will open to the ﬁrst page of the ﬁle.

Example:

See {mansection R clogitpostestimation:[R] clogit postestimation}.

{manlink man entry}and {manlinki man entry}follow syntax 3.

{manlink} and {manlinki} display man and entry using the {mansection} directive as a link

that will launch the user’s PDF viewer pointing at that manual entry. man is a Stata manual (such

as Ror SVY) and entry is the name of an entry within that manual (such as predict or regress

postestimation). The named destination should be written as it appears in the title of the manual

entry.

SMCL directive . . . is equivalent to typing . . .

{manlink man entry} {bf:{mansection man entry ns:[man]entry}}

{manlinki man entry} {bf:{mansection man entry ns:[man] {it:entry}}}

entry ns is entry with the following characters removed: space, left and right quotes (‘and ’), #,

$,~,{,},[, and ].

{news:text}follows syntax 2.

{news} displays text as a link that will display in the Viewer the latest news from

http://www.stata.com.

{news} can also be used with {marker}; see {help args##markername[|viewername] [:text]}

and {marker markername}earlier in this section.

Example:

For the latest NetCourse offerings, see the {news:news}.

smcl — Stata Markup and Control Language 13

{net args[:text]}follows syntaxes 3 and 4.

{net} displays args as a link that will display in the Viewer the results of net args; see [R]net.

Specifying the optional :text, displays text instead of args. For security reasons, net get and net

install cannot be executed in this way. Instead, use {net describe . . . }to show the page,

and from there, the user can click on the appropriate links to install the materials. Whenever args

contains a colon, as it does when args is a URL, be sure to enclose args within quotes.

{net cd .:text}displays text as a link that will display the contents of the current net location.

{net} can also be used with {marker}; see {help args##markername[|viewername] [:text]}and

{marker markername}, earlier in this section.

Examples:

programs are available from {net "from http://www.stata.com":Stata}

Nicholas Cox has written a series of matrix commands which you can obtain

by {net "describe http://www.stata.com/stb/stb56/dm79":clicking here}.

{net d:text}follows syntax 2.

{net d} displays text as a link that will display a Keyword Search dialog box from which the

user can search the Internet for additions to Stata.

Example:

To search the Internet for the latest additions to Stata available,

{net d:click here}.

{netfrom d:text}follows syntax 2.

{netfrom d} displays text as a link that will display a Choose Download Site dialog box into

which the user may enter a URL and then see the contents of the site. This directive is seldom

used.

Example:

If you already know the URL, {netfrom d:click here}.

{ado args[:text]}follows syntaxes 3 and 4.

{ado} displays text as a link that will display in the Viewer the results of ado args; see [R]net.

For security reasons, ado uninstall cannot be executed in this way. Instead, use {ado describe

. . . }to show the package, and from there, the user can click to uninstall (delete) the material.

{ado} can also be used with {marker}; see {help args##markername[|viewername] [:text]}and

{marker markername}, earlier in this section.

Example:

You can see the community-contributed packages you have installed (and uninstall

any that you wish) by {ado dir:clicking here}.

{ado d:text}follows syntax 2.

{ado d} displays text as a link that will display a Search Installed Programs dialog box from

which the user can search for community-contributed routines previously installed (and uninstall

them if desired).

Example:

You can search the community-contributed ado-files you have installed

by {ado d:clicking here}.

{update args[:text]}follows syntaxes 3 and 4.

{update} displays text as a link that will display in the Viewer the results of update args; see

[R]update. If args contains a URL, be careful to place the args in quotes.

14 smcl — Stata Markup and Control Language

args can be omitted because the update command is valid without arguments. {update:text}is

really the best way to use the {update} directive because it allows the user to choose whether

and from where to update their Stata.

{update} can also be used with {marker}; see {help args##markername[|viewername] [:text]}

and {marker markername}, earlier in this section.

Examples:

Check whether your Stata is {update:up to date}.

Check whether your Stata is {update "from http://www.stata.com":up to date}.

{update d:text}follows syntax 2.

{update d} displays text as a link that will display a Choose Ofﬁcial Update Site dialog box into

which the user may type a source (typically http://www.stata.com, but perhaps a local CD drive)

from which to install ofﬁcial updates to Stata.

Example:

If you are installing from CD or some other source,

{update d:click here}.

{back:text}follows syntax 2.

{back} displays text as a link that will take an action equivalent to pressing the Viewer’s Back

button.

Example:

{back:go back to the previous page}

{clearmore:text}follows syntax 2.

{clearmore} displays text as a link that will take an action equivalent to pressing Stata’s Clear

–more– Condition button. {clearmore} is of little use to anyone but the developers of Stata.

Example:

{clearmore:{hline 2}more{hline 2}}

{stata args[:text]}follows syntaxes 3 and 4.

{stata} displays text as a link that will execute the Stata command args in the Results window.

Stata will ﬁrst ask before executing a command that is displayed in a web browser. If args (the

Stata command) contains a colon, remember to enclose the command in quotes.

Example:

. . . {stata summarize mpg:to obtain the mean of mpg}. . .

Remember, like all SMCL directives, {stata} can be used in programs as well as ﬁles. Thus you

could code

display ". . . {stata summarize mpg:to obtain the mean of mpg}. . . "

or, if you were in the midst of outputting a table,

di "{stata summarize mpg:mpg} {c |}" . . .

However, it is more likely that, rather than being hardcoded, the variable name would be in a

macro, say, ‘vn’:

di "{stata summarize ‘vn’:‘vn’} {c |}" . . .

Here you probably would not know how many blanks to put after the variable name because it

could be of any length. Thus you might code

di "{ralign 12:{stata summ ‘vn’:‘vn’}} {c |}" . . .

smcl — Stata Markup and Control Language 15

thus allocating 12 spaces for the variable name, which would be followed by a blank and the

vertical bar. Then you would want to allow for a ‘vn’ longer than 12 characters:

local vna = abbrev(‘vn’,12)

di "{ralign 12:{stata summ ‘vn’:‘vna’}} {c |}" . . .

There you have a line that will output a part of a table, with the linked variable name on the left

and with the result of clicking on the variable name being to summ ‘vn’. Of course, you could

make the action whatever else you wanted.

{matacmd args[:text]}follows syntaxes 3 and 4.

{matacmd} works the same as {stata}, except that it submits a command to Mata. If Mata is

not already active, the command will be preﬁxed with mata to allow Stata to execute it.

Formatting directives for use in line mode

{title:text}(carriage return) follows syntax 2.

{title:text}displays text as a title. {title:. . . }should be followed by a carriage return and,

usually, by one more blank line so that the title is offset from what follows. (In help ﬁles, we

precede titles by two blank lines and follow them by one.)

Example:

{title:Command summary -- general syntax}

{p}

Pretend that {cmd:{c -({xyz}c )-}} is a SMCL directive, although . . .

{center:text}and {centre:text}follow syntax 2.

{center #:text}and {centre #:text}follow syntax 4.

{center:text}and {centre:text}are synonyms; they center the text on the line. {center:text}

should usually be followed by a carriage return; otherwise, any text that follows it will appear on

the same line. With syntax 4, the directives center the text in a ﬁeld of width #.

Examples:

{center:This text will be centered}

{center:This text will be centered} and this will follow it

{center 60:This text will be centered within a width of 60 columns}

{rcenter:text}and {rcentre:text}follow syntax 2.

{rcenter #:text}and {rcentre #:text}follow syntax 4.

{rcenter:text}and {rcentre:text}are synonyms. {rcenter} is equivalent to {center},

except that text is displayed one space to the right when there are unequal spaces left and right.

{rcenter:text}should be followed by a carriage return; otherwise, any text that follows it will

appear on the same line. With syntax 4, the directives center the text in a ﬁeld of width #.

Example:

{rcenter:this is shifted right one character}

{right:text}follows syntax 2.

{right} displays text with its last character aligned on the right margin. {right:text}should be

followed by a carriage return.

Examples:

{right:this is right-aligned}

{right:this is shifted left one character }

16 smcl — Stata Markup and Control Language

{lalign #:text}and {ralign #:text}follow syntax 4.

{lalign} left-aligns text in a ﬁeld #characters wide, and {ralign} right-aligns text in a ﬁeld #

characters wide.

Example:

{lalign 12:mpg}{ralign 15:21.2973}

{dlgtab [#[#] ]:text}follows syntaxes 2 and 4.

{dlgtab} displays text as a dialog tab. The ﬁrst #speciﬁes how many characters to indent the

dialog tab from the left-hand side, and the second #speciﬁes how much to indent from the

right-hand side. The default is {dlgtab 4 2:text}.

Examples:

{dlgtab:Model}

{dlgtab 8 2:Model}

{...} follows syntax 1.

{...} speciﬁes that the next carriage return be treated as a blank.

Example:

Sometimes you need to type a long line and, while {...}

that is fine with SMCL, some word processors balk. {...}

In line mode, the above will appear as one long line to SMCL.

{col #}follows syntax 3.

{col #}skips forward to column #. If you are already at or beyond that column in the output,

then {col #}does nothing.

Example:

mpg{col 20}21.3{col 30}5.79

{space #}follows syntax 3.

{space} is equivalent to typing #blank characters.

Example:

20.5{space 20}17.5

{tab} follows syntax 1.

{tab} has the same effect as typing a tab character. Tab stops are set every eight spaces.

Examples:

{tab}This begins one tab stop in

{tab}{tab}This begins two tab stops in

Note: SMCL also understands tab characters and treats them the same as the {tab} command, so

you may include tabs in your ﬁles.

Formatting directives for use in paragraph mode

{p} follows syntax 3. The full syntax is {p # # # #}.

{p # # # #}enters paragraph mode. The ﬁrst #speciﬁes how many characters to indent the ﬁrst

line; the second #, how much to indent the second and subsequent lines; the third #, how much

to bring in the right margin on all lines; and the fourth #is the total width for the paragraph.

Numbers, if not speciﬁed, default to zero, so typing {p} without numbers is equivalent to typing

{p 0 0 0 0},{p #}is equivalent to {p #0 0 0}, and so on. A zero for the fourth #means use

the default paragraph width; see set linesize in [R]log.{p} (with or without numbers) may

be followed by a carriage return or not; it makes no difference.

smcl — Stata Markup and Control Language 17

Paragraph mode ends when a blank line is encountered, the {p end} directive is encountered, or

{smcl}(carriage return) is encountered.

Examples:

{p}

{p 4}

{p 0 4}

{p 8 8 8 60}

Note concerning paragraph mode: In paragraph mode, you can have either one space or two spaces

at the end of sentences, following the characters ‘.’, ‘?’, ‘!’, and ‘:’. In the output, SMCL puts two

spaces after each of those characters if you put two or more spaces after them in your input, or if

you put a carriage return; SMCL puts one space if you put one space. Thus

{p}

Dr. Smith was near panic. He could not reproduce the result.

Now he wished he had read about logging output in Stata.

will display as

Dr. Smith was near panic. He could not reproduce the result. Now he wished he

had read about logging output in Stata.

Several shortcut directives have also been added for commonly used paragraph mode settings:

SMCL directive . . . is equivalent to typing . . .

{pstd} {p 4 4 2}

{psee} {p 4 13 2}

{phang} {p 4 8 2}

{pmore} {p 8 8 2}

{pin} {p 8 8 2}

{phang2} {p 8 12 2}

{pmore2} {p 12 12 2}

{pin2} {p 12 12 2}

{phang3} {p 12 16 2}

{pmore3} {p 16 16 2}

{pin3} {p 16 16 2}

{p end} follows syntax 1.

{p end} is a way of ending a paragraph without having a blank line between paragraphs. {p end}

may be followed by a carriage return or not; it will make no difference in the output.

Example:

{p end}

{p2colset # # # #}follows syntax 3.

{p2col [# # # # ]:[ﬁrst column text ]}[second column text ]follows syntaxes 2 and 4.

{p2line [# # ]}follows syntaxes 1 and 3.

{p2colreset} follows syntax 1.

{p2colset} sets column spacing for a two-column table. The ﬁrst #speciﬁes the beginning

position of the ﬁrst column, the second #speciﬁes the placement of the second column, the third

#speciﬁes the placement for subsequent lines of the second column, and the last #speciﬁes the

number to indent from the right-hand side for the second column.

{p2col} speciﬁes the rows that make up the two-column table. Specifying the optional numbers

redeﬁnes the numbers speciﬁed in {p2colset} for this row only. If the ﬁrst column text or the

second column text is not speciﬁed, the respective column is left blank.

18 smcl — Stata Markup and Control Language

{p2line} draws a dashed line for use with a two-column table. The ﬁrst #speciﬁes the left

indentation, and the second #speciﬁes the right indentation. If no numbers are speciﬁed, the

defaults are based on the numbers provided in {p2colset}.

{p2colreset} restores the {p2col} default values.

Examples:

{p2colset 9 26 27 2}{...}

{p2col:{keyword}}rules{p end}

{p2line}

{p2col:{opt nonm:issing}}all nonmissing values not changed by the

rules{p end}

{p2col 7 26 27 2:* {opt m:issing}}all missing values not changed by

the rules{p end}

{p2line}

{p2colreset}{...}

{synoptset [#] [ tabbed |notes ]}follows syntaxes 1 and 3.

{synopthdr: [ﬁrst column header ]}follows syntaxes 1 and 2.

{syntab:text}follows syntax 2.

{synopt: [ﬁrst column text ]}[second column text ]follows syntax 2.

{p2coldent: [ﬁrst column text ]}[second column text ]follows syntax 2.

{synoptline} follows syntax 1.

{synoptset} sets standard column spacing for a two-column table used to document options in

syntax diagrams. #speciﬁes the width of the ﬁrst column; the width defaults to 20 if #is not

speciﬁed. The optional argument tabbed speciﬁes that the table will contain headings or “tabs”

for sets of options. The optional argument notes speciﬁes that some of the table entries will have

footnotes and results in a larger indentation of the ﬁrst column than the tabbed argument implies.

{synopthdr} displays a standard header for a syntax-diagram-option table. ﬁrst column header

is used to title the ﬁrst column in the header; if ﬁrst column header is not speciﬁed, the default

title “options” is displayed. The second column is always titled “Description”.

{syntab} displays text positioned as a subheading or “tab” in a syntax-diagram-option table.

{synopt} speciﬁes the rows that make up the two-column table; it is equivalent to {p2col} (see

above).

{p2coldent} is the same as {synopt}, except the ﬁrst column text is displayed with the standard

indentation (which may be negative). The second column text is displayed in paragraph mode

and ends when a blank line, {p end}, or a carriage return is encountered. The location of the

columns is determined by a prior {synoptset} or {p2colset} directive.

{synoptline} draws a horizontal line that extends to the boundaries of the previous {synoptset}

or, less often, {p2colset} directive.

Examples:

{synoptset 21 tabbed}{...}

{synopthdr}

{synoptline}

{syntab:Model}

{p2coldent:* {opth a:bsorb(varname)}}categorical variable to be absorbed{p end}

{synopt:{opt clear}}reminder that untransposed data will be lost if not previously

saved{p end}

{synoptline}

{p2colreset}{...}

smcl — Stata Markup and Control Language 19

{bind:text}follows syntax 2.

{bind:. . . }keeps text together on a line, even if that makes one line of the paragraph unusually

short. {bind:. . . }can also be used to insert one or more real spaces into the paragraph if you

specify text as one or more spaces.

Example:

Commonly, bind is used {bind:to keep words together} on a line.

{break} follows syntax 1.

{break} forces a line break without ending the paragraph.

Example:

{p 4 8 4}

{it:Example:}{break}

Commonly, . . .

Directive for entering the as-is mode

{asis} follows syntax 1.

{asis} begins as-is mode, which continues until {smcl}(carriage return) is encountered. {asis}

may be followed by a carriage return or not; it makes no difference, but {smcl} must be immediately

followed by a carriage return. {smcl} returns SMCL to line mode. No other SMCL commands are

interpreted in as-is mode.

Inserting values from constant and current-value class

The {ccl} directive outputs the value contained in a constant and current-value class (c()) object.

For instance, {ccl pi} provides the value of the constant pi (3.14159. . . ) contained in c(pi). See

[P]creturn for a list of all the available c() objects.

Displaying characters using ASCII and extended ASCII codes

The {char} directive—synonym {c}—allows you to output any ASCII or extended ASCII character

in Latin1 encoding. Extended ASCII characters in Latin1 encoding are converted to the equivalent

Unicode characters in the UTF-8 encoding. For instance, {c 232} is equivalent to typing the letter `e

because extended ASCII code 232 in Latin1 is deﬁned as the letter “e” with a grave accent. You may

also type the Unicode character `e (code point \u00e8) directly.

You can get to all the ASCII and extended ASCII characters in Latin1 encoding by typing {c #},

where #is between 1 and 255. Or, if you prefer, you can type {c 0x#}, where #is a hexadecimal

number between 1 and ff. Thus {c 0x6a} is also jbecause the hexadecimal number 6a is equal to

the decimal number 106.

Also, so that you do not have to remember the numbers, {c} provides special codes for characters

that are, for one reason or another, difﬁcult to type. These include

{c S|} $ (dollar sign)

{c ’g} ‘ (open single quote)

{c -(} { (left curly brace)

{c )-} } (right curly brace)

20 smcl — Stata Markup and Control Language

{c S|} and {c ’g} are included not because they are difﬁcult to type or cause SMCL any problems

but because in Stata display statements, they can be difﬁcult to display, since they are Stata’s macro

substitution characters and tend to be interpreted by Stata. For instance,

. display "shown in $US"

shown in

drops the $US part because Stata interpreted $US as a macro, and the global macro was undeﬁned.

A way around this problem is to code

. display "shown in {c S|}US"

shown in $US

{c -(} and {c )-} are included because {and }are used to enclose SMCL directives. Although

{and }have special meaning to SMCL,SMCL usually displays the two characters correctly when

they do not have a special meaning. SMCL follows the rule that, when it does not understand what it

thinks ought to be a directive, it shows what it did not understand in unmodiﬁed form. Thus

. display "among the alternatives {1, 2, 4, 7}"

among the alternatives {1, 2, 4, 7}

works, but

. display "in the set {result}"

in the set

does not because SMCL interpreted {result} as a SMCL directive to set the output style (color) to

that for results. The way to code the above is to type

. display "in the set {c -(}result{c )-}"

in the set {result}

SMCL also provides the following line-drawing characters:

{c -} a wide dash character

{c |} a tall |character

{c +} a wide dash on top of a tall |

{c TT} a top T

{c BT} a bottom T

{c LT} a left T

{c RT} a right T

{c TLC} a top-left corner

{c TRC} a top-right corner

{c BRC} a bottom-right corner

{c BLC} a bottom-left corner

{hline} constructs the line by using the {c -} character. The above are not really characters; they

are instructions to SMCL to draw lines. The “characters” are, however, one character wide and one

character tall, so you can use them as characters in your output. The result is that Stata output that

appears on your screen can look like

. summarize mpg weight

Variable Obs Mean Std. Dev. Min Max

mpg 74 21.2973 5.785503 12 41

weight 74 3019.459 777.1936 1760 4840

smcl — Stata Markup and Control Language 21

but, if the result is translated into plain text, it will look like

. summarize mpg weight

Variable | Obs Mean Std. Dev. Min Max

-------------+-----------------------------------------------------

mpg | 74 21.2973 5.785503 12 41

weight | 74 3019.459 777.1936 1760 4840

because SMCL will be forced to restrict itself to the characters.

Finally, SMCL provides the following Western European characters:

{c a’} ´

a{c e’} ´

e{c i’} ´

ı{c o’} ´

o{c u’} ´

{c A’} ´

A{c E’} ´

E{c I’} ´

I{c O’} ´

O{c U’} ´

{c a’g} `

a{c e’g} `

e{c i’g} `

ı{c o’g} `

o{c u’g} `

{c A’g} `

A{c E’g} `

E{c I’g} `

I{c O’g} `

O{c U’g} `

{c a^} ˆ

a{c e^} ˆ

e{c i^} ˆ

ı{c o^} ˆ

o{c u^} ˆ

{c A^} ˆ

A{c E^} ˆ

E{c I^} ˆ

I{c O^} ˆ

O{c U^} ˆ

{c a~}˜

a{c o~}˜

{c A~}˜

A{c O~}˜

{c a:} ¨

a{c e:} ¨

e{c i:} ¨

ı{c o:} ¨

o{c u:} ¨

{c A:} ¨

A{c E:} ¨

E{c I:} ¨

I{c O:} ¨

O{c U:} ¨

{c ae} æ{c c,} c¸ {c n~}˜

n{c o/} ø{c y’} ´

{c AE} Æ{c C,} c¸ {c N~}˜

N{c O/} Ø{c Y’} ´

{c y:} ¨

y{c ss} ß{c r?} ¿{c r!} ¡

{c L-} £{c Y=} (yen)

SMCL uses UTF-8 to render the above characters. For instance, {c e’} is equivalent to {c 0xe9}, if

you care to look it up. {c 0xe9} will display as ´

e if you are using a Latin1 encoding.

Advice on using display

Do not think twice; you can just use SMCL directives in your display statements, and they will

work. What we are really talking about, however, is programming, and there are two things to know.

First, remember how display lets you display results as text,as result,as input, and as

error, with the abbreviations as txt,as res,as inp, and as err. For instance, a program might

contain the lines

program . . .

. . .

quietly summarize ‘varname’

display as txt "the mean of ‘varname’ is " as res r(mean)

. . .

end

Results would be the same if you coded the display statement

display "{txt}the mean of ‘varname’ is {res}" r(mean)

That is, the display directive as txt just sends {txt} to SMCL, the display directive as res just

sends {res} to SMCL, and so on.

However, as err does not just send {err}.as err also tells Stata that what is about to be

displayed is an error message so that, if output is being suppressed, Stata knows to display this

message anyway. For example,

display as err "varname undefined"

22 smcl — Stata Markup and Control Language

is the right way to issue the error message “varname undeﬁned”.

display "{err}varname undefined"

would not work as well; if the program’s output were suppressed, the error message would not be

displayed because Stata would not know to stop suppressing output. You could code

display as err "{err}varname undefined"

but that is redundant. display’s as error directive both tells Stata that this is an error message and

sends the {err} directive to SMCL. The last part makes output appear in the form of error messages,

probably in red. The ﬁrst part is what guarantees that the error message appears, even if output is

being suppressed.

If you think about this, you will now realize that you could code

display as err "{txt}varname undefined"

to produce an error message that would appear as ordinary text (meaning that it would probably be

in black) and yet still display in all cases. Please do not do this. By convention, all error messages

should be displayed in SMCL’s {err} (default red) rendition.

The second thing to know is how Stata sets the state of SMCL the instant before display displays its

output. When you use display interactively—when you use it at the keyboard or in a do-ﬁle—Stata

sets SMCL in line mode, font face {sf}, and style {res}. For instance, if you type

. display 2+2

the 4 will appear in {sf}{res}, meaning in standard font face and in result style, which probably

means in black and bold. On the other hand, consider the following:

smcl — Stata Markup and Control Language 23

. program demonstrate_display

1. display 2+2

2. end

. demonstrate_display

Here the 4 will appear in {sf}{inp}, meaning that the result is probably also shown in black and

bold. However, if your preferences are set to display input differently than results, the output from

the program will be different from the interactive output.

When display is executed from inside a program, no changes are made to SMCL.SMCL is just

left in the mode it happens to be in, and here it happened to be in line mode {sf}{inp} because

that was the mode it was in after the user typed the command demonstrate display.

This is an important feature of display because it means that, in your programs, one display

can pick up where the last left off. Perhaps you have four or ﬁve displays in a row that produce

the text to appear in a paragraph. The ﬁrst display might begin paragraph mode, and the rest of the

displays ﬁnish it off, with the last display displaying a blank line to end paragraph mode. Here

it is of great importance that SMCL stay in the mode you left it in between displays.

That leaves only the question of what mode SMCL is in when your program begins. You should

assume that SMCL is in line mode but make no assumptions about the style (color) {txt},{res},

{err}, or {inp}. Within a program, all display commands should be coded as

display as . . . . . .

display "one of {txt},{res},{err}, or {inp} . . . ". . .

although you may violate this rule if you really intend one display to pick up where another left

off. For example,

display as text "{p}"

display "This display violates the rule, but that is all right"

display "because it is setting a paragraph, and we want all"

display "these displays to be treated as a whole."

display "We did follow the rule with the first display in the"

display "sequence."

display

display "Now we are back in line mode because of the blank line"

You could even code

program example2

display as text "{p}"

display "Below we will call a subroutine to contribute a sentence"

display "to this paragraph being constructed by example2:"

example2_subroutine

display "The text that example2_subroutine contributed became"

display "part of this single paragraph. Now we will end the paragraph."

display

end

program example2_subroutine

display "This sentence is being displayed by"

display "example2_subroutine."

end

24 smcl — Stata Markup and Control Language

The result of running this would be

. example2

Below we will call a subroutine to contribute a sentence to this paragraph

being constructed by example2: This sentence is being displayed by

example2_subroutine. The text that example2_subroutine contributed became

part of this single paragraph. Now we will end the paragraph.

Advice on formatting help ﬁles

Help ﬁles are just ﬁles named ﬁlename.sthlp that Stata displays when the user types “help

ﬁlename”. The ﬁrst line of a help ﬁle should read

{smcl}

After that, it is a matter of style. To see examples of our style, type

. viewsource assert.sthlp (simple example with a couple of options)

. viewsource centile.sthlp (example with an options table)

. viewsource regress.sthlp (example of an estimation command)

. viewsource regress_postestimation.sthlp (example of a postestimation entry)

We recommend opening a second Viewer window (one way is to right-click within an existing

Viewer and select “Open New Viewer”) to look at the help ﬁle and the raw source ﬁle side by side.

Also see

[P]dyndoc — Convert dynamic Markdown document to an HTML ﬁle

[P]display — Display strings and values of scalar expressions

[P]markdown — Convert Markdown document to an HTML ﬁle

[R]log — Echo copy of session to ﬁle

STATA Instructions Psmcl

Navigation menu

Versions of this User Manual:

Views

Navigation