text2ps(1)
text2ps - convert text files to PostScript
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
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 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. -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 /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, 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. -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 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 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 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: 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 /usr/lib/DPS/AFM Font metric files TRADEMARKS PostScript is a registered trademark of Adobe Systems, Inc. SEE ALSO imprint(1), psrip(1), PostScript Language Reference Manual - 2nd ed., Adobe Systems, Inc. environ(5)