help translate, help translator, help transmap
-------------------------------------------------------------------------------
Title
[R] translate -- Print and translate logs
Syntax
Print log and SMCL files
print filename [, like(ext) name(windowname) override_options]
Translate log files to SMCL files and vice versa
translate filename_in filename_out [, translator(tname)
name(windowname) override_options replace]
View translator parameter settings
translator query [tname]
Change translator parameter settings
translator set [tname setopt setval]
Return translator parameter settings to default values
translator reset tname
List current mappings from one extension to another
transmap query [.ext]
Specify that files with one extension be treated the same as files with
another extension
transmap define .ext_new .ext_old
filename in print, in addition to being a filename to be printed, may be
specified as @Results to mean the Results window and @Viewer to mean
the Viewer window.
filename_in in translate may be specified just as filename in print.
tname in translator specifies the name of a translator; see the
translator() option under Options for translate.
Description
print prints log, SMCL, and text files. Although there is considerable
flexibility in how print (and translate, which print uses) can be set to
work, they have already been set up and should just work:
. print mylog.smcl
. print mylog.log
Unix users may discover that they need to do a bit of setup before print
works; see [R] translate. International Unix users may also wish to
modify the default paper size. All users can tailor print and translate
to their needs.
print may also be used to print the current contents of the Results
window or the Viewer. For instance, the current contents of the Results
window could be printed by typing
. print @Results
translate translates log and SMCL files from one format to another, the
other typically being suitable for printing. translate can also
translate SMCL logs (logs created by typing, say, log using mylog) to
ASCII text:
. translate mylog.smcl mylog.log
You can use translate to recover a log when you have forgotten to start
one. You may type
. translate @Results mylog.txt
to capture as ASCII text what is currently shown in the Results window.
This entry provides a general overview of print and translate and covers
in detail the printing and translation of text (nongraphic) files.
Options for print
like(ext) specifies how the file should be translated to a form suitable
for printing. The default is to determine the translation method
from the extension of filename. Thus mylog.smcl is translated
according to the rule for translating smcl files, myfile.txt is
translated according to the rule for translating txt files, and so
on. (These rules are, in fact, translate's smcl2prn and txt2prn
translators, but put that aside for the moment.)
Rules for the following extensions are predefined:
.txt assume input file contains ASCII text
.log assume input file contains Stata log ASCII text
.smcl assume input file contains SMCL
To print a file that has an extension different from those listed
above, you can define a new extension, but you do not have to do
that. Assume that you wish to print the file read.me, which you know
to contain ASCII text. If you were just to type print read.me, you
would be told that Stata cannot translate .me files. (You would
actually be told that the translator for me2prn was not found.) You
could type print read.me, like(txt) to tell print to print read.me
like a .txt file.
On the other hand, you could type
.transmap define .me .txt
to tell Stata that .me files are always to be treated like .txt
files. If you did that, Stata would remember the new rule, even in
future sessions.
When you specify the like() option, you override the recorded rules,
so if you were to type print mylog.smcl, like(txt), the file would be
printed as ASCII text (meaning that all the SMCL commands would
show).
name(windowname) specifies which window to print when printing a Viewer.
The default is for Stata to print the topmost Viewer [Unix(GUI)
users: See the technical note below]. The name() option is ignored
with printing the Results window.
The window name is located inside the parentheses in the window
title. For example, if the title for a Viewer window is "Viewer (#1)
[help print]", the name for the window is #1.
override_options refers to translate's override options. print uses
translate to translate the file into a format suitable for sending to
the printer. To find out what you can override for the X files
(files ending in .X), type translator query X2prn. For instance, to
find out what you can override when printing .smcl files, type
. translator query smcl2prn
In the omitted output (which varies across operating systems), you
might learn that there is an rmargin # tunable value, which specifies
the right margin in inches. You could specify the override_option
rmargin(#) to temporarily override the default value, or you could
type translator set smcl2prn rmargin # beforehand to permanently
reset the value.
Alternatively, on some computers with some translators, you might
discover that nothing can be set.
Options for translate
translator(tname) specifies the name of the translator to be used to
translate the file. The available translators are
+-------------------------------------------------------------+
| tname | input | output |
|-------------+----------------------+------------------------|
| smcl2ps | SMCL | PostScript |
| log2ps | Stata ASCII text log | PostScript |
| txt2ps | generic ASCII text | PostScript |
| Viewer2ps | Viewer window | PostScript |
| Results2ps | Results window | PostScript |
|-------------+----------------------+------------------------|
| smcl2prn | SMCL | default printer format |
| log2prn | Stata ASCII text log | default printer format |
| txt2prn | generic ASCII text | default printer format |
| Results2prn | Results window | default printer format |
| Viewer2prn | Viewer window | default printer format |
|-------------+----------------------+------------------------|
| smcl2txt | SMCL | generic ASCII text log |
| smcl2log | SMCL | Stata ASCII text log |
| Results2txt | Results window | generic ASCII text |
| Viewer2txt | Viewer window | generic ASCII text |
|-------------+----------------------+------------------------|
| smcl2pdf | SMCL | PDF (Mac only) |
| log2pdf | Stata ASCII text log | PDF (Mac only) |
| txt2pdf | generic ASCII text | PDF (Mac only) |
| Results2pdf | Results window | PDF (Mac only) |
| Viewer2pdf | Viewer window | PDF (Mac only) |
+-------------------------------------------------------------+
If translator() is not specified, translate determines which
translator to use from extensions of the filenames specified. Typing
translate myfile.smcl myfile.ps would use the smcl2ps translator.
Typing translate myfile.smcl myfile.ps, translate(smcl2prn) would
override the default and use the smcl2prn translator.
Actually, when you type translate a.b c.d, translate looks up .b in
the transmap extension synonym table. If .b is not found, the
translator b2d is used. If .b is found in the table, the mapped
extension is used (call it b'), and then the translator b'2d is used.
For example,
command translator used
-----------------------------------------------------------------
. translate myfile.smcl myfile.ps smcl2ps
. translate myfile.odd myfile.ps odd2ps, which does not
exist, so error
. transmap define .odd .txt
. translate myfile.odd myfile.ps txt2ps
-----------------------------------------------------------------
You can list the mappings that translate uses by typing transmap
query.
name(windowname) specifies which window to translate when translating a
Viewer. The default is for Stata to translate the topmost Viewer.
The name() option is ignored when translating the Results window.
The window name is located inside the parentheses in the window
title. For example, if the title for a Viewer window is "Viewer (#1)
[help print]", the name for the window is #1.
override_options override any of the default options of the specified or
implied translator. To find out what what you can override for, say,
log2ps, type
. translator query log2ps
In the omitted output, you might learn that there is an rmargin #
tunable value, which, for log2ps, specifies the right margin in
inches. You could specify the override_option rmargin(#) to
temporarily override the default value or type
translator set log2ps rmargin # beforehand to permanently reset the
value.
replace specifies that filename_out be replaced if it already exists.
Technical note for Unix(GUI) users
Unix(GUI) users should note that X-Windows does not have a concept of a
window z-order, which prevents Stata from determining which is the
topmost window. Instead, Stata determines which window is topmost based
on which window has the focus. However, some window managers will set
the focus to a window without bringing the window to the top. What Stata
considers the topmost window may not appear topmost visually. For this
reason, you should always use the name() option to ensure that the
correct window is printed.
Examples
Translate SMCL log into ASCII text log
. translate mylog.smcl mylog.log
Same as above, but replace mylog.log if it already exists
. translate mylog.smcl mylog.log, replace
Put output from Results window into ASCII
. translate @Results mylog.txt
Translate SMCL log into PostScript file
. translate mylog.smcl mylog.ps
Same as above, but use translator txt2ps and replace mylog.ps if it
already exists
. translate read.me mylog.ps, trans(txt2ps) replace
Saved results
transmap query .ext saves in macro r(suffix) the mapped extension
(without the leading period) or saves ext if the ext is not mapped.
translator query translatorname saves setval in macro r(setopt) for every
setopt, setval pair.
printer query printername (Unix only) saves in macro r(suffix) the
"filetype" of the input that the printer expects (currently "ps" or
"txt") and, in macro r(command), the command to send output to the
printer.
Also see
Manual: [R] translate
Help: [R] log, [G] graph export, [G] graph print, [G] graph set, [P]
smcl
