txt

Note: markdoc has a new method for writing dynamic text which is much simpler than using the txt command. You can read more about the new feature on this page.

---

Description

MarkDoc has a very convenient way for writing text in the dynamic document, using a special comment signs that are distinguished from regular comment. However, using comments for documentation comes with a limit, namely, dynamic text - text that includes scalars and macros - cannot be displayed in the document. The txt command provides a solution to this problem by displaying values of scalar expressions or macros with text, allowing the users to write dynamic text. For example:

. sysuse auto
. summarize price
. txt "the mean of Price variable is " r(mean)
> the mean of Price variable is 6165.26

You might wonder what is the benefit of writing dynamic text? The main benefit is reducing human errors when returned values are meant to be used in the documentation. For example, you want to mention the mean of a variable in a text paragraph. The mean, however, can change if you drop an observation. Writing dynamic text will ensure that anytime there is a change in the data, the values in the text will be automatically updated. There is another advantage for using the txt command. Namely, you can produce dynamic text from a loop or a program. For example, imagine you are looping over many varlists and you wish to include the results in separate sections. You could:

foreach lname of varlist  var1 var2 ...    {
  txt "### Analyzing the `lname` Variable
  ...
}

The txt command belongs to Weaver package, but it was updated to support MarkDoc. The reason was to have a single command for writing dynamic text in both packages, instead of introducing another command. You can only use the txt command in MarkDoc, when Weaver is not in use, i.e. your "Weaver log" is off. To check the status of the Weaver log type:

. weave query

The txt command is to some extent similar to display command in Stata. For example, it can be used to carry out a mathematical calculation by typing:

. txt 1+1
> 2

Features

The txt command can:

• Write dynamic text, i.e. text that can interpret scalar and macros.
• It can be used to use the values returned from Stata commands in the interpretation to minimize human errors and make them traceable
• It can also be used to write mono-space font in the document
• It can style text using the same markup language that the document is written with (Markdown, LaTeX, HTML)
• It supports several display directives, similar to the display command in Stata
• It can be included inside loops or programs to produce dynamic text

Syntax

The txt command prints dynamic text on the smcl log

txt [code] [display_directive [display_directive [...]]]

where the display_directive can be:

    "double-quoted string"
    `"compound double-quoted string"'
    [%fmt] [=]exp
    _skip(#)
    _column(#)
    _newline[(#)]
    _dup(#)
    ,
    ,,

The code argument changes the behavior of the txt command to display the text as a code block, using a mono-space font (see below).

Display directives

The supported display_directives are used in do-files and programs to produce formatted output. The directives are:

Display directive	Description
"double-quoted string"	displays the string without the quotes
`"compound double-quoted string"'	display the string without the outer quotes; allows embedded quotes
[%fmt] [=] exp	allows results to be formatted
_skip(#)	skips # columns
_column(#)	skips to the #th column
_newline	goes to a new line
_newline(#)	skips # lines
_dup(#)	repeats the next directive # times
,	displays one blank between two directives
,,	places no blanks between two directives

Styling dynamic text

By default, the txt command writes a text paragraph. However, the text can be displayed differently in the dynamic document using the same markup language that is used in the document. For example, if you are writing your document in Markdown, you can write a "Heading 3" dynamic text as follows:

. txt "### some text ... "

or if you are writing your documentation in LaTeX:

. txt "\subsubsection{some text ...} "

Examples

You can use the txt command for interpreting your results. This works very similar to using the display command.

. sysuse auto
. summarize price
. txt "the mean of Price variable is " r(mean) " and SD is " %9.3f r(sd)
> the mean of Price variable is 6165.26 and SD is 2949.496

Using the display_directives reveals the power of the txt command for producing dynamic text with a particular structure. For example, you can use the _newline or simply _n to begin a new line. However, if you are writing in Markdown, HTML, and LaTeX, breaking the line is not enough to make sure the output also will be in multiple lines, although the txt command will break the lines in the smcl log anyway. In the example below, which assumes writing with markdown, I use double space characters at the end of each line to break the lines in the output. end of each line to ensure the output generated from

txt "this is the first line  " _n ///
    "and this is the second line  "

I can also add indents to the text using the _column() directive:

txt _column(10) "Hello World"
>        Hello World

Or skip a number of characters:

. txt _skip(10) "Hello World"
>           Hello World

Remarks

In contrast to the display command that prints the scalar unformatted, the txt command uses the default %10.2f format for displaying the scalar. This feature helps the users avoid specifying the format for every scalar, due to popularity of this format.

. scalar num = 10.123
. txt "The value of the scalar is " num
> The value of the scalar is 10.12

However, specifying the format expression can overrule the default format. For example, to display the value of the scalar with only 1 decimal place I can change the default format of the txt command:

. txt "The value of the scalar is " %5.1f num
> The value of the scalar is 10.1

The example above will print the scalar with only 1 decimal number. This feature only supports scalar interpretation and does not affect the macro contents.