TEXT2PS(1) Impressario TEXT2PS(1)NAME
text2ps - convert text files to PostScript
SYNOPSIS
text2ps [-p filename] [-z filename]
[-J printername] [-s pageSize] [-F fontName[size]]
[-F %{a-z}fontName[size]] [-P fontSize]
[-o orientation] [-S pageStyle] [-M numColumns]
[-w lineWrap] [-K maxLines] [-m outputMode]
[-E headerText] [-l locale] [-L leftMargin]
[-R rightMargin] [-B bottomMargin] [-T topMargin]
[-A allMargins] [-n pageNum] [-x]
[-e reencodeFont] [-i prologFile] [-d metricsDir]
[-g pageSizeFile] [-h] [-v] [-Q[Q[Q]]]
[text file ...]
For compatibility with lptops the following options are provided:
[-G] [-N [tb][lcr]pageNum] [-H]
[-V] [-U] [-O arg] [-I arg]
[-D] [-C arg] [-X] [-W]
DESCRIPTION
text2ps formats text using the PostScript page description language. The
program provides a wide variety of formatting options including multiple
column output, page rotation, font selection and page decoration.
Text File Input
One or more text files can be specified on the command line. If no files
are specified on the command line, text2ps will read from the standard
input. Currently, text2ps can accept plain text files in a number of
languages. The program has successfully formatted English, French,
German, and Russian (cyrillic) text files and theoretically should be
able to handle any language that can be expressed using an Adobe Type 1
font in a horizontal writing direction. text2ps cannot currently handle
Adobe Type 0 composite fonts or vertical writing directions.
Besides plain text files, text2ps can accept text files that contain
formatting control characters and special escape sequences. The most
common example of such files are formatted nroff manual pages. text2ps
has successfully handled the complex formatting produced by the tbl and
eqn programs. The following control characters and escape sequences are
recognized by text2ps:
Name Char Code Description
_________________________________________________________
Null 0x00 No action
Bell ^G 0x07 Audible bell
Backspace ^H 0x08 Reverse one character
H Tab ^I 0x09 Forward to next multiple of 8
Page 1
TEXT2PS(1) Impressario TEXT2PS(1)
Newline ^J 0x0A Start new line
V Tab ^K 0x0B Down one line
Formfeed ^L 0x0C Begin new page or column
Return ^M 0x0D Reverse to start of line
Shift Out ^N 0x0E No action
Shift In ^O 0x0F No action
Esc 0x1B Begin escape sequence
Esc-7 Reverse full line feed
Esc-8 Reverse half line feed
Esc-9 Forward half line feed
Esc-D Gaudy header left box text
Esc-H Gaudy header filename area text
Esc-U Gaudy user comment area text
Esc-F Font change sequence
See the Special Escape Sequences section below for details on the Esc-D,
Esc-H, Esc-U and Esc-F sequences.
Control characters and escape sequences not listed above will cause
text2ps to issue a warning indicating the offending character and its
location in the text file. To prevent inadvertently attempting to format
a binary file, text2ps will terminate the processing of any file that
contains more than fifty unrecognized characters unless the -x option has
been specified (see below). To ensure the proper processing of text files
the international locale should be established either by setting the LANG
environment variable prior to running text2ps or by using the -l command
line option.
PostScript Output
text2ps produces Level 1 PostScript code formatted in compliance with the
Adobe Document Structuring Conventions, Version 3.0. The output data is
7-bit clean even when the input data is not. By default, text2ps writes
its PostScript output to the standard output.
Command Line Options
The command line option switches for text2ps are compatible with the
upper case version of the lptops program option letters. text2ps provides
additional functionality typically using lowercase option letters.
-p filename
Specifies the name of the file to which the PostScript output
will be written. If the -p option is not specified, output
will be sent to the standard output.
-z filename
By default, text2ps sends its error, warning and information
messages to the standard error. The -z option specifies the
name of a file to which these messages should be redirected. If
the file specified already exists, any messages generated by
text2ps will be appended to the end of the file.
Page 2
TEXT2PS(1) Impressario TEXT2PS(1)-J printername
Specifies the name of a printer for which the text is to be
formatted. printername is the name of the printer as
registered with the printer spooling system (see printers(1M)
for information on printer installation). The printer may be
physically attached to the system or it may be a network
printer.
Specifying a printer allows text2ps to obtain detailed printer
configuration information such as the currently loaded page
size, available fonts and physical margins. This information is
used to provide the optimum formatting of the text file for the
specified printer.
If the -J option is not specified, text2ps assumes a default
target environment consisting of an A size page with 0.5 inch
margins. If the resulting PostScript file is subsequently sent
to a printer whose printing area is smaller than the default,
the text will be scaled to fit the target page. When scaling is
performed, the aspect ratio of the original page is maintained.
-s pageSize
Specifies a page size to use when formatting text. The default
page size is A (8.5 by 11.0 inches). pageSize may be specified
either as the name of a page size (e.g. A, B, Ledger, Monarch)
or explicitly using page dimensions. The syntax for specifying
page dimensions is <width>x<height>[<units>] where <units> may
be in, cm, mm, pt for inches, centimeters, millimeters and
points respectively. If <units> is not specified, inches are
assumed. Thus, a B size page may be specified by setting
pageSize to B or 11x17in.
If a printer has not been specified (see -J option above),
text2ps looks up the dimensions corresponding to a page size
name in the file /usr/lib/print/data/text2psPageSizes. If a
printer has been specified, it is queried for the dimensions of
the specified page size name. If the page size is not supported
on the printer, the disk based page size table is used. If a
page size name is not found on the printer and in the disk
based table, the default, A size, is used.
Refer to the /usr/lib/print/data/text2psPageSizes for a list of
the supported page size names and for instructions on how to
add new page sizes.
-F fontName[size]
Specifies the font and, optionally, point size to use for the
body text. The body text is all text on the page excluding the
page header. The default body font is Courier10. fontName may
be any Adobe Font Metric (AFM) file name or one of the font
name abbreviations listed in the Font Name Abbreviations
section below. By default, text2ps looks in the directory
Page 3
TEXT2PS(1) Impressario TEXT2PS(1)
/usr/lib/DPS/AFM for font metric files. If the metric file for
a specified font name cannot be found, the Courier font is
substituted. If size is not specified, the default point size
will be used. The default point size is 10 but may be changed
using the -P option. Examples of valid font specifications are
Courier and Courier14.
-F %{a-z}fontName[size]
text2ps allows up to 26 fonts to be registered for later use. A
font is registered by prefixing the font specification with a %
and a lower case letter between a and z inclusive. By embedding
special escape sequences (see section below) in a text file, it
is possible to dynamically change the font used when formatting
the file. text2ps automatically registers the following fonts:
Specification Purpose
__________________________________________________
%rCourier10 Default body font
%hCourier-Bold10 Simple header font
%lTimes-Bold12 Gaudy header time/date font
%cTimes-Roman14 Gaudy header file pathname font
%pHelvetica30 Gaudy header page number font
Note that the %l, %c and %p fonts are registered only when the
gaudy page style is used.
-P fontSize
Specifies the point size to use with fonts that have been
specified only by name (e.g. Courier as opposed to Courier14).
The default point size is 10. Note that all font sizes are
expressed in units of points. Any units specified as part of
fontSize will be silently ignored and the value will be assumed
to be expressed in points.
-o orientation
If orientation is specified as rotate the entire output page
will be rotated 90 degrees counter-clockwise. Using this
option, landscape oriented output can be obtained on a portrait
page. norotate, the default, can be specified to disabled page
rotation.
-S pageStyle
Specifies the page decoration to be used. One of the following
values of pageStyle may be specified:
plain Indicates that no page decoration is to be used. This
is the default style.
pagenum[,[tb][lcr]
Places a page number at the specified location on the
page. The default page number location is at the top,
Page 4
TEXT2PS(1) Impressario TEXT2PS(1)
center of the page. A different location can be
specified by placing a comma after the pagenum value
and then specifying a letter sequence. The letters
indicate a vertical page position (t = top, b =
bottom) and a horizontal page position (l = left, c =
center, r = right). All letters are optional and may
be specified in any order. There must not be any
whitespace between the comma and the letters.
header Places a simple one line text header at the top of
each output page. The header consists of the current
date, the current time, the full pathname of the
input file, if available, and the page number.
gaudy Provides the same information as the simple header
but in a more graphic layout with additional space
for a user supplied comment (see -E below). Note
that file pathnames too long to fit in the available
space will be truncated starting from the left with
leading ellipses added in place of the discarded
text.
-M numColumns
text2ps places a single column of text on the page by default.
The -M option allows the page to be divided into an arbitrary
number of columns. Typically, when using more than a single
column, the font size should be reduced to avoid excessive line
wrapping. A common use of this option is formatting text in
landscape orientation for an A size page. In this case two
columns of seven point Courier type makes excellent use of the
page.
-w lineWrap
When the length of a line of text is greater than the available
width of the page or column the remaining text may either be
discarded (i.e. clipped) or wrapped around to the next line.
lineWrap is either wrap, the default, which wraps long text
lines to the next line or clip which discards text that does
not fit on the line.
-K maxLines
Normally, text2ps places as many lines of text on the page as
will fit (equivalent to specifying maxLines as 0). The -K
option places a maximum limit on the number of lines placed on
a page or column. The number of lines actually produced will
be either maxLines or the number that can fit on the page
whichever is less. However, if the -K option is used with the
fit mode of the -m option, the output page is scaled, if
necessary, to ensure that exactly maxLines number of lines are
produced on the page. See the -m option below for more
information.
Page 5
TEXT2PS(1) Impressario TEXT2PS(1)-m outputMode
By default, text2ps places as many lines of text on the page as
will fit. This is the normal output mode. Certain text files
such as manual pages have been preformatted with page breaks
assuming a specific number of lines per page. To ensure the
proper processing of these files the -m option should be
specified with fit as the outputMode and the -K option should
be specified with the required number of lines per page. The
typical specification for a manual page would be -m fit and -K
66.
-E headerText
Specifies a comment to be placed on the page header. If the -S
option has specified the header page style, the headerText will
replace the file pathname. If the -S option has specified the
gaudy page style, the headerText will be placed above the file
pathname.
-l locale In order to successfully format a text file text2ps must know
the file's language. The language of the text file is conveyed
by specifying an international locale (see environ(5)). If the
-l option is not specified, the locale is determined by the
value of the LANG environment variable. If -l is specified, the
locale is set to the value of locale. The directory
/usr/lib/locale contains entries for each locale available on
the system.
-L leftMargin
-R rightMargin
-B bottomMargin
-T topMargin
-A allMargins
Specifies the margins to be used when formatting the page. The
default text2ps margin is 0.5 inches on all sides. Margins are
specified using the syntax <value>[<units>] where <units> may
be in, cm, mm, pt for inches, centimeters, millimeters and
points respectively. If <units> is not specified, inches are
assumed. Thus, a 5 centimeter margin would be specified as 5cm.
The manual setting of margins is discouraged since it disables
text2ps's automatic scaling mechanism. If a margin is manually
specified that is smaller than a printer's physical margins,
clipping of the output may result. This cannot occur when the
default text2ps margins are used. The -A option is provided as
a convenience when all four margins are to be set to the same
value.
-n pageNum
Specifies the starting value for page numbering. The default
starting page number is 1. pageNum must be greater than or
equal to zero. If multiple input text files are processed, each
will be numbered starting at the specified page number. For
example, if -n 3 is specified and two input text files are
Page 6
TEXT2PS(1) Impressario TEXT2PS(1)
processed, the pages of each file will be numbered starting at
3.
-x text2ps recognizes plain text characters, a number of common
control characters and a set of special escape sequences. All
other characters cause a warning message to be issued
identifying the character and its location in the input file.
If more than 50 characters in a file are unrecognized, the
processing of that file terminates. This prevents inadvertently
attempting to format a binary file. If a file is to be
formatted that contains unrecognizable characters, the -x
option should be specified. This silences all unrecognized
character warnings and allows an unlimited number of
unrecognized characters to be processed.
-e reencodeFont
Each character in a text file has a unique code number. These
code numbers are used to select a character glyph in a font.
When using only ASCII characters the correspondence of
character codes to character glyphs is very straight forward.
However, when formatting text for international locales the
interpretation of character codes outside the ASCII code range
becomes an issue. Many commonly used Adobe Type 1 fonts have a
character code to character glyph mapping that is incorrect for
many European locales. text2ps automatically corrects this by
reencoding the font to provide the correct character glyphs.
This automatic reencoding of a font is performed only if that
font has been encoded using the Adobe Standard Encoding. All
other font encodings are untouched. Reencoded fonts conform to
the ISO 8859-1 specification. The -e option can be used to
disable the automatic reencoding of Adobe Standard Encoding
fonts.
-i prologFile
text2ps places a PostScript code prolog at the start of the
output file. By default, this prolog code is read from the
file /usr/lib/print/data/text2psProlog. The -i switch allows a
different prolog file to be specified. This switch is not
intended for general use.
-d metricsDir
In order to format text, text2ps uses Adobe Font Metric (AFM)
files. The default location for these files is
/usr/lib/DPS/AFM. When metric information is needed for a font,
the metrics directory name is prepended to the font name to
form the full pathname of the AFM file. The -d option allows a
different directory to be specified for the font metrics.
-g pageSizeFile
text2ps maintains a file containing page size names and their
corresponding dimensions. The default page size file is
/usr/lib/print/data/text2psPageSize. The -g option allows a
Page 7
TEXT2PS(1) Impressario TEXT2PS(1)
different page size file to be specified.
-h Prints a program usage message to the standard error.
-v Prints a message summarizing the results of formatting the
specified text.
-Q Specifies that detailed runtime processing information is to be
provided. The more Q's that are specified, the more detailed
the runtime information. Currently, up to three Q's provide
coarse, medium and fine levels of information respectively.
The following command line options are provided only for compatibility
with the lptops program. Certain options are equivalent to standard
text2ps options while others are silently ignored.
-G Equivalent to -S gaudy.
-N [tb][lcr]pageNum
Equivalent to -S pagenum[,[tb][lcr]] -n pageNum.
-H Equivalent to -o rotate.
-V Equivalent to -o norotate.
-U Ignored.
-O arg Ignored.
-I arg Ignored.
-D Equivalent to -e noreencode
-C arg Ignored.
-X Ignored.
-W Equivalent to -w wrap.
Special Escape Sequences
text2ps recognizes a number of special escape sequences. These sequences
can be embedded in a text file to change header text and switch fonts
during processing of the file. The escape sequences are compatible with
those used by the enscript program from the Adobe TranScript product. The
sequences are:
Escape Sequence Description
_______________________________________________________
Esc-D(top)(bottom) Gaudy header left box text
Esc-HheaderText Gaudy header filename area text
Page 8
TEXT2PS(1) Impressario TEXT2PS(1)
Esc-UcommentText Gaudy user comment area text
Esc-Fc Font change sequence where c
is the letter of a font registered
using -F %{a-z} fontName[size]
Font Name Abbreviations
text2ps accepts the following font name abbreviations. These
abbreviations are identical to those used by the lptops program.
Full Name Abbreviation
______________________________________________________
Courier C
Courier-Bold CB
Courier-BoldOblique CBO
Courier-Oblique CO
Helvetica H
Helvetica-Bold HB
Helvetica-BoldOblique HBO
Helvetica-Oblique HO
Symbol S
Times-Bold TB
Times-BoldItalic TBI
Times-Italic TI
Times-Roman T
AvantGarde-Book AGB
AvantGarde-BookOblique AGBO
AvantGarde-Demi AGD
AvantGarde-DemiOblique AGDO
Bookman-Demi BD
Bookman-DemiItalic BDI
Bookman-Light BL
Bookman-LightItalic BLI
Helvetica-Narrow HN
Helvetica-Narrow-Bold HNB
Helvetica-Narrow-BoldOblique HNBO
Helvetica-Narrow-Oblique HNO
NewCenturySchlbk-Bold NCSB
NewCenturySchlbk-BoldItalic NCSBI
NewCenturySchlbk-Italic NCSI
NewCenturySchlbk-Roman NCSR
Palatino-Bold PB
Palatino-BoldItalic PBI
Palatino-Italic PI
Palatino-Roman PR
ZapfChancery-MediumItalic ZCMI
ZapfDingbats ZD
EXAMPLES
1. Formatting a manual page:
Page 9
TEXT2PS(1) Impressario TEXT2PS(1)
pcat csh.z | text2ps -K 66 -m fit > csh.ps
2. Formatting a file using a 14 point Helvetica font:
text2ps -F Helvetica14 /etc/passwd > passwd.ps
3. Formatting a file for two column, landscape oriented output on the
printer 'dj':
text2ps -J dj -o rotate -M 2 -F Courier7 /etc/passwd | lp -ddj
NOTES
1. The text2ps program supersedes the lptops program. The lptops
program should not be used for new development and may be removed
from future releases.
2. The PostScript output produced by text2ps conforms to the Adobe
PostScript Document Structuring Conventions Version 3.0 as specified
in Appendix G of the "PostScript Language Reference Manual", 2nd
edition.
3. If text2ps is given an unrecognized or incomplete command line
option switch, it will print a warning message to the standard
error, ignore the option and continue processing.
4. If a file is specified on the command line, text2ps will not read
its stdin for text files.
5. text2ps can only process a single file when reading from standard
input.
6. Use a of proportional spaced font or dynamically changing fonts when
formatting manual pages can cause misformatting of tables.
7. For compatibility with the lptops program, the units of big points
may be specified using bp for the page size and margin options.
text2ps treats big points equal to points (pt).
8. text2ps uses command line option letters which violate the
Impressario Filter-Driver Specification. This is done to provide
compatibility with the lptops program.
FILES
/usr/lib/print/text2ps Program file
/usr/lib/print/data/text2psProlog PostScript prolog file
/usr/lib/print/data/text2psPageSizes Page size name and dimension
table
Page 10
TEXT2PS(1) Impressario TEXT2PS(1)
/usr/lib/DPS/AFM Font metric files
TRADEMARKS
PostScript is a registered trademark of Adobe Systems, Inc.
SEE ALSOimprint(1), psrip(1), PostScript Language Reference Manual - 2nd ed.,
Adobe Systems, Inc. environ(5)
Page 11
