Dynamic text

So far the only way for writing dynamic text - that is text that includes macros and scalars for interpreting the results has been using the txt command. The txt command is very enabling, it can be used inside loops, programs, etc, to display dynamic text in the dynamic document.

But I have been trying to make working with MarkDoc as simple as possible. Recently I developed a new marker, named <!*!> that can be used inside the documentation to view local and global macros, numeric and string scalars, as well as scalars from matrices and data sets. The syntax is fairly simple, instead of the *, put the object that you wish to evaluate. The object can be:

Object	Description
<!scalar!>	Numeric or String scalar
<!matrix[r,c]!>	Numeric scalar from a matrix
<!variable[n]!>	Nth observation of a variable
<!`local'!>	Numeric local macro
<!$global!>	Numeric global macro
<!"`local'"!>	String local macro
<!"$global"!>	String global macro

Examples

1. Assume you have a local macro named a and you want to evaluate it inside your text. You'd write:

local a = 1
scalar b = 2
matrix define A = (20,30\40,50)

/***
This is heading <!`a'!>
=======================

The values of a matrix can be displayed within the text. For example,
you can write <!A[1,1]!> which shows the scalar of the first row and
first column of the matrix in your documentation. This feature makes
writing dynamic text much more convenient compared to the previous procedure.

This is heading <!b!>
---------------------

REMEMBER, that this procedure only works if you execute a do-file with
markdoc, that is, using the `markdoc filename.do, export(format)` syntax.
***/

if you save this script in a Stata do-file -- say example.do -- and execute it with markdoc:

  markdoc example.do, export(html) replace

you see that the local macro a is updated to 1 and scalar b is updated to 2. Note the difference between the way the a and b are called inside the <!*!> markers.

This procedure is much easier than using the txt command and more natural to the way Markdoc takes care of writing the documentation. However, it only works if you execute a do-file with markdoc.