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) ]
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 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
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. 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).
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.
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. 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 then select the graphic, and embed it into the document by using the menu sequence
Edit -> Links
and checking the box marked Save file in document. This is an annoying and labor-intensive feature of 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.
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.
Technical note
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><celldef > s>"
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'
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, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk
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