Stata 15 help for translatetext

[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. translate translates log and SMCL files from one format to another, the other typically being suitable for printing. translate can also translate SMCL logs to plain text.

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 plain text .log assume input file contains Stata log plain 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 plain 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 plain 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 options for overriding default values. print uses translate to translate the file into a format suitable for sending to the printer, and thus translate's override_options may also be used with print. The settings available vary between each translator (for example, smcl2ps will have different settings than smcl2txt) and may also differ across operating systems (for example, Windows may have different printing options than macOS). To find out what you can override when printing .smcl files, type

. translator query smcl2prn

In the omitted output, 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 text log | PostScript | | txt2ps | generic text file | PostScript | | Viewer2ps | Viewer window | PostScript | | Results2ps | Results window | PostScript | |-------------+----------------------+------------------------| | smcl2prn | SMCL | default printer format | | log2prn | Stata text log | default printer format | | txt2prn | generic text log | default printer format | | Results2prn | Results window | default printer format | | Viewer2prn | Viewer window | default printer format | |-------------+----------------------+------------------------| | smcl2txt | SMCL | generic text log | | smcl2log | SMCL | Stata text log | | Results2txt | Results window | generic text file | | Viewer2txt | Viewer window | generic text file | |-------------+----------------------+------------------------| | smcl2pdf | SMCL | PDF | | log2pdf | Stata text log | PDF | | txt2pdf | generic text log | PDF | | Results2pdf | Results window | PDF | | Viewer2pdf | Viewer window | PDF | +-------------------------------------------------------------+

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 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.

Remarks

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 Printing files, Unix in [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 plain 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 plain 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.

translator query, translator set, and translator reset show, change, and restore the default values of the settings for each translator.

transmap define and transmap query create and show mappings from one file extension to another for use with print and translate.

For example, print myfile.txt knows to use a translator appropriate for printing text files because of the .txt extension. However, it does not know what to do with .xyz files. If you have .xyz files and always wish to treat them as .txt files, you can type transmap define .xyz .txt.

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.

Technical note for using PDF translators (Windows and Unix)

When using translate to translate a log, SMCL, or text file or a Stata graph into a PDF file, some characters may not display correctly in the resulting PDF file. This happens when translating content that contains Unicode characters from different languages; one font may not be adequate to display every character used. If an appropriate font is not available for a character, that character will not display correctly in the resulting PDF file.

Specific fonts can be used to build a font chain. Those fonts are specified using fontname and are separated by commas. The most preferred font should be listed first, followed by the less preferred fonts. A maximum of 16 fonts can be specified. Stata will inspect each character in the original content, and if a glyph for the corresponding character is not available in the default font, then each font in the font chain will be checked until a font is found to display that character.

You can set fonts in the font chain by specifying addfonts for each PDF translator as follows:

. translator set tname addfonts fontname

Here, tname is the name of a PDF translator, which can be smcl2pdf, log2pdf, txt2pdf, Results2pdf, Viewer2pdf, or Graph2pdf. See the translator() option under Options for translate.

Stata has the ability to select a font automatically if the default font and the fonts in the font chain do not contain a glyph for the character. Automatic font selection can be controlled using the following:

. translator set tname autofont on|off

By default, autofont is on. Unix (console) users will need to set the font directories so the fonts can be found.

PDF files accept Base14 fonts, Type 1 fonts, and TrueType fonts with an extension of .ttf or .ttc. If fontname refers to a TrueType font or a Type 1 font, the corresponding TrueType or Type 1 font file will be searched for within the default font directory. Unix (console) users can type

. translator set tname fontdir fontdirectory

to set the default font directory. fontdirectory can contain multiple font directories separated by semicolons. If the specified TrueType or Type 1 font cannot be found under the current font directory, an error message will be issued.

Examples

Translate SMCL log into plain-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 plain-text file . 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

Stored results

transmap query .ext stores in macro r(suffix) the mapped extension (without the leading period) or stores ext if the ext is not mapped.

translator query translatorname stores setval in macro r(setopt) for every setopt, setval pair.

printer query printername (Unix only) stores 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.


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index