help for rtfutil(Roger Newson)

Utilities for writing Rich Text Format (RTF) files

Open a new RTF file

rtfopen handle using filename [ , replace template(template_name)
paper(paper_size) landscape
margins(#1 #2 #3 #4)
]

where template_name is

minimal | fnmono1 | fnmono2

and paper_size is

us | usland | a4 | a4land | #1 #2

Open an existing RTF file for appending RTF code

rtfappend handle using filename [ , replace from(filename) ]

Insert some RTF code from an instream line sequence and/or an existing file into an open RTF file

rtfinsert handle [ using filename ]
[ , terminator(string) maxlines(#) ]

Start a new section in an open RTF file

rtfsect handle [ , default
paper(paper_size) landscape
margins(#1 #2 #3 #4)
]

Insert a graphic file as a linked object into an open RTF file

rtflink handle using filename

Insert a hyperlink into an open RTF file

rtfhyper handle , hyperlink(URL) [ text(string) ]

Compute cumulative sums for a number list

rtfcumlist numlist [ , local(local_macro_name) ]

Create a listtab row style for specified cell widths

rtfrstyle [ varlist ] [ , cwidths(numlist)
trgaph(#) trleft(#)
tdposition(tabdef_position)
tdadd(string) cdadd(string_list)
missnum(string)
local(local_macro_name_list)
]

where tabdef_position is

b | e | be | eb

Close an open RTF file

rtfclose handle

where handle is a file handle as recognized by the file utility.

Description

The rtfutil package is a suite of file handling utilities
for producing Rich Text Format (RTF) files in Stata,
possibly containing plots and tables.
These RTF files can then be opened by Microsoft Word,
and possibly by alternative free word processors.
The plots can be included by inserting, as linked objects,
graphics files that might be produced by the graph export command in Stata.
The tables can be included by using the listtab command,
downloadable from SSC,
with the handle() option.

Options for rtfopen

replace specifies that any existing file with the name specified by the filename
will be replaced.

template(template_name) specifies the name of an RTF template,
on which the output RTF file will be based.
A template is a sequence of RTF commands,
which specifies a file with an RTF format but no content,
which will be created if the user uses rtfclose immediately after using rtfopen.
The user may add content by using other commands between rtfopen and rtfclose.
Currently, 3 templates are available.
minimal (the default) specifies that the template begins with the line {\rtf1
and ends with the line },
with no font table, no header, and no formatting commands
(apart from any specified by the paper() and margins() options).
fnmono1 specifies that the template contains a small font table,
no color table, stylesheet, or info group,
a small set of formatting commands,
and a header group,
displaying only the name of the file specified by using
together with the current page number.
fnmono2 specifies the same template as fnmono1,
except that the header group displays the file name, the current page number,
and the total number of pages in the document.
The option template(fnmono2) may produce RTF documents
that cannot be read correctly by RTF readers other than Microsoft Word.

paper(paper_size) specifies the dimensions (width and height) of the paper
for the output RTF document.
These dimensions may be given as two numbers #1 #2,
where #1 is width (in twips) and #2 is height (in twips),
or they may be given as a named paper size us, usland, a4, or a4land,
where us specifies the standard US paper size of width 12240 twips and height 15840 twips,
usland specifies the standard landscaped US paper size of width 15840 twips and height 12240 twips,
a4 specifies the standard A4 paper size of width 11909 twips and height 16834 twips,
and a4land specifies the standard landscaped A4 paper size of width 16834 twips and height 11909 twips.
The implied default dimensions in RTF are papersize(12240 15840), or US paper size.
A twip is 1/1440 of an inch, or 1/20 of a point,
and is the standard unit of length most commonly used in RTF documents.

landscape specifies that the orientation of the document, when printed,
will be landscape.
If landscape is not specified, then the orientation will be portrait.
Note that the landscape option is independent of the paper() option.
Therefore, if the user specifies paper(usland) or paper(a4land),
then the user must also specify landscape
for the document to have a landscape orientation when printed.

margins(#1 #2 #3 #4) specifies the left, right, top and bottom margins (in twips)
for the output RTF document.
The implied default in RTF is margins(1800 1800 1440 1440).

Options for rtfappend

replace specifies that any existing file with the name specified by the using filename
will be replaced.

from(filename) specifies an input file,
to which additional RTF input will be appended to produce the output file specified by the using filename.
If from() is unspecified, then rtfappend inputs the file specified by using,
assuming that that file already exists,
and overwrites it, if replace is specified.

Options for rtfinsert

terminator(string) specifies a terminator string,
used to terminate an instream sequence of lines of RTF code following the rtfinsert command.
If terminator() is present,
then rtfinsert will insert into the open RTF document the following lines,
until a line containing only the terminator() string is encountered,
or until the number of lines is equal to the maxlines() option (see below).
If both a terminator() option and a using qualifier are present,
then rtfinsert will first insert the instream sequence of RTF lines,
and then insert the lines of text from the using file.
Note that the using file may not be an existing RTF document,
but may only contain lines of RTF code as text,
without any head lines.
Note, also, that the instream lines will be left- and right-trimmed
before being output to the open RTF file.
This implies that lines continuing a paragraph need to be prefixed with the string "\ ",
a backslash followed by 2 spaces.

maxlines(#) specifies a maximum number of lines of RTF code
to read from the instream sequence of lines of RTF code.
If maxlines() is absent,
then it is set to a default value of 1024.

Options for rtfsect

default specifies that all section settings will be restored to the document default,
usually as set by rtfopen.

paper(), landscape and margins() are defined as the options of the same names for rtfopen.
However, they apply only to the section, not to the whole document.
This is useful if the user wants to have landscape pages in a mainly portrait document.

Options for rtfhyper

hyperlink(URL) specifies the uniform resource location (URL) for the hyperlink.
This option must be specified.

text(string) specifies the text used in the hypertext for the hyperlink.
If text() is not specified, then the hyperlink() option is used.
Note that it is the user's responsibility to add underlining, colors,
or any other formatting used to indicate hypertext.

Options for rtfcumlist

local(local_macro_name) specifies the name of a local macro,
in which the result will be saved.
rtfcumlist inputs a numlist,
and computes, as output, a second number list,
containing the cumulative sums of the input numlist.
This is useful if the input numlist contains a sequence of table row widths (in twips),
and the user wants the cumulative sums for use in cellxN control words,
defining the corresponding table row right boundaries (in twips).

Options for rtfrstyle

cwidths(numlist) specifies a list of column widths, expressed in twips,
to be used in the generated listtab row style.
A listtab row style is a combination of the listtab options
begin(), delimiter(), end() and missnum().
The column widths must be positive integers.
If a varlist is specified, then the list of column widths is truncated,
or extended on the right with copies of the last column width in the list,
to make the number of column widths equal to the number of variables in the varlist.
If cwidths() is not specified,
then it is initialized to a single width of 1440 twips (equal to one inch),
and then extended with copies if a varlist is specified.
The final list of column widths is used to construct the RTF table row definition,
which will be output as part of the listtab row style.

trgaph(#) specifies half the space between the cells of a table row (expressed in twips).
If absent, then it is set to 40 twips, or 2 points.

trleft(#) specifies the position in twips of the leftmost edge of the table,
with respect to the left edge of its left column.
If absent, then it is set to -trgaph, where trgaph is the number set by trgaph().

tdposition(tabdef_position) specifies whether the RTF table definition
will be part of the begin() option or the end() option
of the listtab row style generated.
It may be set to b, e, be or eb.
If it is set to b, then it will be part of the begin() option.
If it is set to e, then it will be part of the end() option.
If it is set to be or eb, then it will be part of both options.
In RTF documents,
the table definition is sometimes part of the beginning of the row definition (before the cells),
and is sometimes part of the end of the row definition (after the cells),
and is sometimes repeated in both places.

tdadd(string) specifies additional RTF commands to be added to the table row definition,
in order to customize the table rows defined by the row style.
For instance, tdadd("\trqr") specifies that the generated table rows will be right-justified
in their page (or in their containing column).

cdadd(string_list) specifies a list of sequences of additional RTF commands,
to be added to the table cell definitions,
in order to customize the table cells generated by the generated listtab row style.
The list of strings will be truncated,
or extended on the right with copies of the last string in the list,
to make the number of additional strings equal to the final number of columns.
(The final number of columns is defined as the final number of column widths specified by cwidths(),
after any necessary truncation or extension to match the length of the varlist.)
If cdadd() is not specified,
then it is initialized to a single empty string (""),
and then extended with copies if there will be more than one column in the table.
The final list of additional strings is used to construct the RTF table cell definitions,
which will be output as part of the listtab row style.

missnum(string) specifies the missnum() option
of the generated listtab row style.
If not specified, then it is set to an empty string ("").

local(local_macro_name_list) specifies a list of up to 4 names
of local macros,
which, if supplied,
will be set to the begin(), delimiter(), end() and missnum() options,
respectively,
of the row style generated by rtfrstyle.
These macro names can then be used when calling listtab.
They can be useful,
because the strings beginning, delimiting and ending RTF table rows are often long and difficult to remember.

Remarks about rtfopen and rtfclose

The rtfopen command produces minimal Rich Text Format (RTF) documents,
with no character set declaration, default font declaration,
font tables, color tables, stylesheets, info groups,
preliminary formatting commands, headers, footers, or other extra information,
unless the user adds them,
either using the template() option of rtfopen
or using the file write command.
rtfopen opens a file and initializes the output with a line

{\rtf1

and possibly other lines of RTF code specified by the template() option.
The rtfappend command opens an existing RTF file for appending additional RTF code
to the end of the file,
just before the terminal } character used to terminate a well-formed RTF document.
The rtfclose command simply outputs, to a file already open for text output, the line

}

and then closes the open file.
This ensures that, if the user outputs legible code with no unmatched brackets { and },
then the RTF document as a whole will be legible and have no unmatched brackets.

It is a good idea to enclose all code between a rtfopen or rtfappend
command and the corresponding rtfclose command
in a capture noisily block,
beginning with the command

capture noisily {

and ending with the command

}

This ensures that, if any command in the capture noisily block fails,
then Stata will transfer control to the rtfclose command
immediately following the capture noisily block,
and the RTF file specified by rtfopen or rtfappend will be closed,
and will be available for inspection by the user,
using Microsoft Word or other RTF file readers.

Remarks about rtflink

The using filename may be a path containing folder names.
However, if there are folder names, then they should be separated by the forward slash
/
and not by the backward slash \
even under Microsoft Windows.

Note that rtflink inserts a graphics file into a RTF document as a linked object,
and not as an embedded object,
using nonstandard RTF code used by Microsoft Word versions in Word 2000 or above.
This implies that the linked object may not be recognized by non-Microsoft word processors
(or obsolete Microsoft word processors)
that use RTF.
It also implies that, if the RTF document is moved to another folder (or another computer),
then the graphics file may no longer be visible,
unless it is moved as well.
And some versions of Microsoft Word do not necessarily display or print
linked .eps files produced by the Stata graph export command
at the correct size,
as specified by the ysize() and xsize() options
of a Stata graphics command.
The user may have to convert these linked objects to embedded objects,
in order for them to be displayed at the sizes intended by the Stata graphics command.

Users who wish to include graphics files as embedded objects should probably open the RTF document
(using a post-2000 version of Microsoft Word),
and embed the graphics into the document by clicking on the Microsoft Word hypertext

Edit Links to Files

and checking the check box marked Save file in document.
After the user has done this,
it may be a good idea to revisit Edit links to files,
and to check the check box marked Break Link.

This need for manual intervention to produce embedded files
is an annoying and labor-intensive feature of using rtflink.
Also, it has been known for RTF documents with embedded graphics
to have compatability problems when users try to convert them to OpenOffice.
However, it probably requires less work than most other available methods,
if the user wanted to produce a RTF document (with tables and graphics) in a hurry,
for colleagues to read using Microsoft Word.
It may be a good idea to convert the generated RTF document to a standard Microsoft Word .docx file,
in order to save space,
before embedding the linked objects.

Miscellaneous remarks about rtfutil

Note that the rtfhyper command, and the template(fnmono2) option of rtfopen,
also use nonstandard RTF additions.
These also may not work in non-Microsoft word processors,
although they appear to work in Microsoft Word.

In general, RTF is designed as a Rich TEXT Format,
which implements text (and probably tables) to be portable between systems.
Users who introduce graphics, hypertext, and headers or footers containing the total number of pages
into RTF documents for input to Microsoft Word
should probably not expect to be able to port them to other packages.

More information on the use of rtfutil with listtab and other SSC packages
can be found in Newson (2012).
More information on Rich Text Format can be found in Burke (2003).

Technical note about rtfrstyle

rtfrstyle inputs a variable list and/or a list of column widths,
and outputs a listtab row style,
which can be saved in the local macros specified by the local() option,
and has 4 components,
which are values for the listtab options begin(), delimiter(), end() and misnum().
The missnum() option is as specified by the user, defaulting to an empty string ("").
The delimiter() option is the string "\cell\pard\intbl ",
which terminates one RTF table cell and initiates another.
The begin() option is "{\trowd\pard\intbl " if the user specifies tdposition(e),
and otherwise has the syntax "{<tabdef>\pard\intbl ",
where <tabdef> is a RTF table definition.
The end() option is "\cell\row}" if the user specifies tdposition(b)
(either explicitly or by default),
and otherwise has the syntax "\cell<tabdef>\row}".

The RTF table definition <tabdef> has the syntax

"\trowd\trgaph<trgaph_option>\trleft<trleft_option><tdadd_option><celldefs>"

where <trgaph_option> is the trgaph() option, <trleft_option> is the trleft() option,
tdadd_option> is the tdadd() option,
and <celldefs> is a list of RTF cell definitions (with no intervening commas or spaces),
one for each column of the RTF table to be output by listtab.
The kth cell definition of the <celldefs> has the syntax

"<cdadd_item>\cellx<crbound_item>"

where <crbound_item> is the kth cell right boundary
in the final list of cell right boundaries implied by the cwidths() option,
and <cdadd_item> is the kth item in the final list of items
implied by the cdadd() option.
Note that rtfrstyle creates a listtab row style to create RTF table rows
each enclosed within a RTF group,
beginning with { and ending with }.
This prevents paragraph formatting specifications within table rows
from having effects on the formatting of RTF code in the same document after the table.

This syntax allows the user to specify a very wide range of RTF table row styles for input to listtab.
The varlist used with rtfrstyle should be the same varlist later used with listtab,
as this will ensure that the number of <celldefs> is the same as the number of columns in the table,
which is the number of variables in the varlist.
Microsoft Word usually fails uninformatively if a RTF document contains a table row
with a number of cell definitions unequal to the number of cells.

Examples

The following example generates a document mydoc1.rtf,
which includes, as a linked object, a file myplot1.eps,
produced by graph export.
The file command file write is used to add a heading before the plot,
and two paragraphs after the plot,
each containing a hyperlink added using rtfhyper.

. sysuse auto, clear

. scatter mpg weight, by(foreign) scheme(s2color)

. graph export myplot1.eps, replace

. tempname handle1

. rtfopen `handle1' using "mydoc1.rtf", template(fnmono1) replace

. capture noisily {

. file write `handle1' "{\pard\b Plots of mileage against weight by car origin\par}" _n

. rtflink `handle1' using "myplot1.eps"

. file write `handle1' _n "{\line}" _n "{\pard A package for linking plots like these into RTF documents can be downloaded from Roger Newson's website at {\ul "

. rtfhyper `handle1', hyper("http://www.imperial.ac.uk/nhli/r.newson/")

. file write `handle1' "}\par}"

. file write `handle1' "\line" _n "{\pard Find out more about Stata at "

. rtfhyper `handle1', hyper("http://www.stata.com/") text("{\ul The Stata website}")

. file write `handle1' ".\par}" _n "\line" _n

. }

. rtfclose `handle1'

The following example generates a document mydoc2.rtf,
which contains a RTF table of the mileages and weights of the 22 non-American cars in the auto data.
This table is generated using the listtab package,
using a RTF row style generated by rtfrstyle.
The numeric variables mpg and weight are converted to string variables before output,
using the sdecode package,
adding RTF prefixes causing them to be right-justified in the output RTF table.
The string variable make is not prefixed or suffixed,
implying that (by default) it will be left-justified in the output RTF table.
Note the use of the local() option of rtfrstyle,
which generates local macros b, d and e,
containing the begin(), delimiter() and end() options,
respectively,
that are then passed to listtab.
The listtab and sdecode packages can be downloaded from SSC.

. sysuse auto, clear

. keep if foreign==1

. sdecode mpg, replace prefix("\qr{") suffix("}")

. sdecode weight, replace prefix("\qr{") suffix("}")

. tempname handle2

. rtfopen `handle2' using "mydoc2.rtf", template(fnmono1) replace

. capture noisily {

. file write `handle2' "{\pard\b Mileage and weight in non-US cars\par}" _n

. rtfrstyle make mpg weight, cwidths(2160 1440 1440) local(b d e)

. listtab make mpg weight, handle(`handle2') begin("`b'") delim("`d'") end("`e'") head("`b'\ql{\i Make}`d'\qr{\i Mileage (mpg)}`d'\qr{\i Weight (lb)}`e'")

. }

. rtfclose `handle2'

The following example is like the previous example,
except that the generated document is named mydoc3.rtf,
and the table (and its heading) are right-justified on their page,
and the cells of the top row of the table (containing the column titles) have upper and lower treble-line borders.
The right-justification is specified by the option tdadd("\trqr").
The upper and lower borders are specified by the cdadd() option of the first rtfrstyle command,
which generates an alternative begin() option, stored in the macro B.

. sysuse auto, clear

. keep if foreign==1

. sdecode mpg, replace prefix("\qr{") suffix("}")

. sdecode weight, replace prefix("\qr{") suffix("}")

. tempname handle3

. rtfopen `handle3' using "mydoc3.rtf", template(fnmono1) replace

. capture noisily {

. file write `handle3' "{\pard\qr{\b Mileage and weight in non-US cars}\par}" _n

. rtfrstyle make mpg weight, tdadd("\trqr") cdadd("\clbrdrt\brdrw20\brdrtriple\clbrdrb\brdrw20\brdrtriple") cwidths(2160 1440 1440) local(B)

. rtfrstyle make mpg weight, tdadd("\trqr") cwidths(2160 1440 1440) local(b d e)

. listtab make mpg weight, handle(`handle3') begin("`b'") delim("`d'") end("`e'") head("`B'\ql{\i Make}`d'\qr{\i Mileage (mpg)}`d'\qr{\i Weight (lb)}`e'")

. }

. rtfclose `handle3'

The following example demonstrates the use of rtfappend and rtflink
to add a graph to a file mydoc12.rtf,
generated using the estpost and esttab modules of the SSC package estout,
written by Ben Jann.
The estout and rtfutil packages are complementary,
as more users produce tables using estout than using rtfutil and listtab,
but estout cannot produce graphs.

. sysuse auto, clear

. estpost ta foreign

. esttab using mydoc12.rtf, replace

. tempname handle4

. rtfappend `handle4' using mydoc12.rtf, replace

. capture noisily {

. scatter mpg weight, by(foreign)

. graph export myplot3.eps, replace

. rtflink `handle4' using myplot3.eps

. file write `handle4' "\line"

. }

. rtfclose `handle4'

The following example demonstrates the use of rtfinsert
to insert an instream sequence of lines of RTF code,
terminated by the string END_OF_RTF,
into an open RTF document.
Note that lines continuing a paragraph must be prefixed with the string "\ "
(a backslash followed by 2 spaces),
because rtfinsert trims instream lines
on the left and on the right.

. tempname handle18

. rtfopen `handle18' using mydoc18.rtf, replace

. rtfinsert `handle18', term(END_OF_RTF)

. {\pard

. Mary had a little lamb,

. \ she also had a fox.

. \ The little lamb it gave her love,

. \ the fox it gave her {\i Echinococcus granulosus}.

. \par}

. \line

. END_OF_RTF

. rtfclose `handle18'

A more advanced example using rtfutil can be found in Newson (2012).

Saved results

rtfcumlist saves the following in r():

Macros

r(cumlist) list of cumulative sums

rtfrstyle saves the following in r():

Scalars

r(trgaph) trgaph() option

r(trleft) trleft() option

Macros

r(tdadd) tdadd() option

r(cwidths) final list of column widths (in twips)

r(crbounds) final list of column right boundaries (in twips)

r(cdadd) final cdadd() option (string list)

r(celldefs) cell definitions section of table row definition

r(tabdef) table row definition

r(begin) begin() option of generated row style

r(delimiter) delimiter() option of generated row style

r(end) end() option of generated row style

r(missnum) missnum() option of generated row style

Author

Roger Newson, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

References

Burke S. M.
2003.
RTF Pocket Guide.
Sebastopol, CA: O'Reilly & Associates Inc.
Download more information from
Sean Burke's RTF web page.

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12(2): 191-213.
Download from The Stata Journal website.

Also see

Manual: [P] file

Help: [P] file

listtab, sdecode, estout, esttab, estpost if installed