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.
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
...
}
10000
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
The txt command can:
- Write dynamic text, i.e. text that can interpret
scalarandmacros. - 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 fontin 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
displaycommand in Stata - It can be included inside loops or programs to produce dynamic text
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).
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 |
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 ...} "
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
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.