'\"!  eqn | tbl | mmdoc
'\"macro stdmacro
.if n .pH g1.xpr @(#)xpr	40.3 of 1/9/90
.tr ~
.nr X
.if \nX=0 .ds x} XPR 1 "9/1/88" "X\s-2WIN\s+2 3.0" "\&"
.if \nX=1 .ds x} XPR 1 "9/1/88" "X\s-2WIN\s+2 3.0"
.if \nX=2 .ds x} XPR 1 "" "\&"
.if \nX=3 .ds x} XPR "" "" "\&"
.TH \*(x}
.IX applications supported, xpr
.IX \f2xpr\f1 command
'\"
'\"------------------------------------------------------------
.SH "NAME"
xpr \- print an X window dump
'\"
'\"------------------------------------------------------------
.SH "SYNOPSIS"
.B xpr
.RB [ "\-o"
.IR "output-name" ]
.RB [ "\-a"
.IR "path-name\ " [
.BR "\-n" "] ]"
.RB [ "\-d"
.IR "name" ]
.RB [ "\-h"
.IR "text" ]
.RB [ "\-t"
.IR "text" ]
.RB [ "\-W"
.IR "decimal-number" ]
.RB [ "\-H"
.IR "decimal-number" ]
.RB [ "\-l" ]
.RB [ "\-p" ]
.RB [ "\-L"
.IR "decimal-number" ]
.RB [ "\-T"
.IR "decimal-number" ]
.RB [ "\-s"
.IR "integer" ]
.RB [ "\-S"
.IR "integer" ]
.RB [ "\-r" ]
.RI [ path-name ]
.RB [ "\-C" ]
.RI [ color-list ]
.RI [ input-name ]
.fi
'\"------------------------------------------------------------
.SH "DESCRIPTION"
The
.I xpr
program takes as input an X window dump file produced by
.IR "xwd" "(1)"
and formats it for output on one of several printers.
If no
.I "output-name"
argument is given the standard output is used.
If no
.I "input-name"
argument is given the standard input is used.
.P
By default the
.I "xpr"
program prints the largest possible representation of the window
which will fit on the output page.
Options allow the user to add a header and a trailer,
specify margins,
adjust the scale and orientation,
and append multiple window dumps to a single output file.
.SS "\f3Options\fP"
.TP 1i
.BI "\-o\ " "path-name"
The output is directed to the file named by
.I "path-name."
If the file doesn't exist it is created.
If the file already exists its original contents are
overwritten.
.sp .5
When printing files formatted via \f2xpr\fP with \f2lp\fP,
include in the \f2lp\fP command line the 
option
\f3-o stty=opost\fP. This should be all that's needed for
printers administered via \f2lpadmin\fP. If this isn't
sufficient, try adding -T devicetype, where devicetype is the
same that was given in the \f2xpr\fP command (\f3-d
devicetype\fP).
.TP 1i
.BI "\-a\ " "path-name"
The output is appended to the file named by
.I "path-name."
If the file doesn't exist it is created.
It is assumed that the original file already includes any
necessary printer initialization sequences,
so these are not added in the appended contents.  Note that when
using this option on an \f2empty\fP file, the \f2xpr\fP file created
will not contain the printer initialization sequences.  Thus, the
printer must be initialized by other means.
.TP 1i
.B "\-n"
This option can be used only with the
.B "\-a"
option.
It causes the removal of any formfeed or other page break
control sequences from the end of the original content of the
output file.
This allows the new window image to be concatenated to the
previous image.
The default margins,
or margins specified with the
.B "\-L"
and
.B "\-T"
options,
are still applied to the new image,
so you may want to give the
.B "\-T\ 0"
option to force the new image to follow immediately after the
old image. Do not use this option with postscript printers.
.TP 1i
.BI "\-d\ " "name"
The image is converted into a printer-ready version for the
device named in
.I "name."
.TP 1i
.BI "\-h\ " "text"
The header given in
.I "text"
is placed 1/4 inch above the image in approximately 15 point type.
Any printable ASCII text plus spaces may be included in
.I "text."
.TP 1i
.BI "\-t\ " "text"
The trailer given in
.I "text"
is placed 1/4 inch below the image in approximately 15 point type.
Any printable ASCII text plus spaces may be included in
.I "text."
.TP 1i
.BI "\-W\ " "decimal-number"
The image is scaled so that it will be at most
.I "decimal-number"
inches wide.
For some devices the width may be significantly less than
.I "decimal-number."
This option overrides the
.B "\-S"
option.
If the size requested would require a scale of less than one, a scale of 
one is used; thus the image may be larger than requested.
.TP 1i
.BI "\-H\ " "decimal-number"
The image is scaled so that it will be at most
.I "decimal-number"
inches tall.
For some devices the height may be significantly less than
.I "decimal-number."
This option overrides the
.B "\-S"
option.
If the size requested would require a scale of less than one, a scale of 
one is used; thus the image may be larger than requested.
.TP 1i
.B "\-l"
The image is rotated 90 degrees counter-clockwise,
so that it is printed in ``landscape'' mode.
By default the image is printed so that its longest side
parallels the longest edge of the printed page.
.TP 1i
.B "\-p"
The image is printed upright.
By default the image is printed so that its longest side
parallels the longest edge of the printed page.
.TP 1i
.BI "\-L\ " "decimal-number"
The image is printed
.I "decimal-number"
inches in from the leftmost printable column of the paper.
Due to differences in the alignment of the paper in the
printer,
the actual margin may differ.
.TP 1i
.BI "\-T\ " "decimal-number"
The image is printed
.I "decimal-number"
inches down from the top-most printable row of the paper.
Due to differences in the alignment of the paper in the
printer,
the actual margin may differ.
.TP 1i
.BI "\-s\ " "integer"
The image,
including any header and trailer,
is split onto
.I "integer"
pages.
The complete image can be pasted together by hand from the
separate strips printed on each page.
This option is typically only needed for printers that cannot
handle a large image on one page,
due to memory limitations.
.TP 1i
.BI "\-S\ " "integer"
The image is scaled up by the factor
.I "integer."
By default the largest scale that still allows the full image
to be printed on a page,
while limiting the size of individual pixels to less than 1/4
inch on a side,
is used.
.bp
.TP 1i
.B "\-r"
This option can be used to print an \f2xwd\f1 file  dumped from a
monochrome screen or to a monochrome printer.
The printed image is ``intensity inverted,''
that is,
where ink would be applied in the printed image without the
.B "\-r"
option,
ink is not applied,
and vice versa.
.TP 1i
.BI "\-C "  "color-list"
The printer is considered to have a ribbon with the colors given in
\f2color-list\fP.  The colors must be listed from darkest to
lightest.  For example, the typical ribbon used with color printers
would be specified as \f3-C black,cyan,magenta,yellow\fP.
.PP
If a printer that normally has a multicolored ribbon has a
single-color ribbon (e.g., black), use the \f3-C\fP option to get a
monochrome printout, e.g., \f3-C black\fP.
.SH "CAVEATS"
The
.I xpr
program is installed with several Terminfo entries.  
These will overwrite entries currently installed on your
system. Similarly, installing the Terminal Information
Utilities (TIU) will overwrite the Terminfo entries supplied
with \f2xpr\fP. This requires saving any entries which would
be overwritten and adding them at the end of the second
installation.
.sp
\f2 UNIX System V/386 Release 4.0 only:\fP
The Terminfo entries are contained only with TIU.
.PP
These will
overwrite any entries currently resident on the system.
If the
\f2xpr\fP versions of the Terminfo entries are overwritten, you may
get the message
.sp
.in +1.5
xpr:  Device \f2<name>\fP not supported.
.in -1.5
.PP
The \f3-r\fP option may be necessary for printing monochrome images;
i.e. images with no color table.
.PP
When using \f2xpr\fP, certain printers may produce a split
image across pages. This can be corrected by changing margins
and/or height and width.
.PP
Long text strings are truncated and a tab is not expanded but
printed as a space.
.SH "BUGS"
The append (\f3-a\fP) and output (\f3-o\fP) options are now
mutually exclusive. If both options are specified on the same
command line, \f2xpr\fP will exit with an error message. If
the file specified by the append option is unreadable,
\f2xpr\fP will print an error message and exit.
.PP
3B2 only: Vertical one-pixel wide white lines are inserted at
evenly spaced intervals into \f2xpr\fP output when the device
is non-grayscale postscript.
.PP
Bitmaps (or "color" images of depth 1) are not reproduced
using the \f3-dpostscript\fP option (nothing is printed). The
\f3-dps\fP option can be used to print such images.
.PP
Titles are not produced well with the \f3-dpaintjet\fP option
(the header and trailer appear but inside a black box).
.bp
Splitting of images across multiple pages does not work well
with the \f3-dpostscript\fP option (subsequent pages show the
split images but on a dark page). Similarly, the \f3-a\fP
option does not work well with the \f3-dpostscript\fP option
(dark page for subsequent images (without \f3-n\fP), or
subsequent images missing (with \f3-n\fP).
.PP
For low resolution devices, the header and trailer text looks bad.
Try using capital letters.
.PP
Appending images with the \f3-n\fP option behaves differently on various
printers.  In general, page printers, such as the LaserJet\(rg, place the 
second image relative to the upper-left corner of the first page, while
other printers place the second image relative to the last line 
of the first image.
.sp
.SH NOTE
A dual syntax is supported for \f2xpr\fP.  The supported
equivalents are as follows:
.br
.TS
center;
c c
l l.
-o	-output
-a	-append
-n	-noff
-d	-device
-h	-header
-t	-trailer
-W	-width
-H	-height
-l	-landscape
-p	-portrait
-L	-left
-T	-top
-s	-split
-S	-scale
-r	-rv
.TE
.SH "EXAMPLE"
\f3xpr -dpostscript -S4 -h "Figure 1" foo.xwd\fP
.PP
will read the file \f2foo.xwd\fP and format it for a PostScript\(rg printer,
with a caption at the top and a scale factor of four.
.SH SEE ALSO
xwd(1),xwud(1),X(1)
.SH "SUPPORTED PRINTERS"
The
.I xpr
program is presently supporting printers listed in 
the following table:
.TS
center,box;
c| c| c| c
l| l| l| l.
\f3Device Name	Hardware	Emulation	Comments\f1
.sp 0.25
_
.sp 0.25
455	AT&T 455		Daisywheel printer
.sp 0.25
457	AT&T 457		Daisy printer parellel
.sp 0.25
458	AT&T 458		Daisy printer serial
.sp 0.25
477-455	AT&T 477	455
.sp 0.25
477-470	AT&T 477	470
.sp 0.25
477ibmc	AT&T 477	IBM Color printer
.sp 0.25
477ibmg	AT&T 477	IBM Graphics printer
.sp 0.25
477qume	AT&T-477	Qume
.sp 0.25
477-5x6	AT&T 477	Fujitsu DPL24C	5:6 aspect ratio
.sp 0.25
477	AT&T 477	Fujitsu DPL24C	1:1; low resolution
.sp 0.25
477-hi	AT&T 477	Fujitsu DPL24C	1:1; high resolution
.sp 0.25
470	AT&T 470	C.Itoh 8510	8"; parallel matrix printer
.sp 0.25
471	AT&T 471	C.Itoh 1550	14"; parallel matrix printer
.sp 0.25
475	AT&T 475	C. Itoh 8510	8"; serial matrix printer
.sp 0.25
476	AT&T 475	C.Itoh 1550	14"; serial matrix printer
.sp 0.25
473	AT&T 473	C.Itoh 8510EP	8"; IBM Graphics
.sp 0.25
474	AT&T 474	C.Itoh 1550EP	14"; IBM Graphics
.sp 0.25
478	AT&T 478		8"; parallel matrix printer
.sp 0.25
479	AT&T 479		14"; IBM parallel; matrix printer
.sp 0.25
495ibm	AT&T 495	IBM Graphics
.sp 0.25
495qume	AT&T 495	Qume
.sp 0.25
495hp	AT&T 495	HP Laserjet I emulation
.sp 0.25
5310	AT&T 5310		(EMUL set to ANSI)
.sp 0.25
5320	AT&T 5320		(EMUL set to ANSI)
.sp 0.25
570eps	AT&T 570	Epson
.sp 0.25
570ibm	AT&T 570	IBM ProPrinter
.sp 0.25
571eps	AT&T 571	Epson
.sp 0.25
571ibm	AT&T 571	IBM ProPrinter
.sp 0.25
.TE
.SK
.TS
center,box;
c| c| c| c
l| l| l| l.
\f3Device Name	Hardware	Emulation	Comments\f1
.sp 0.25
_
.sp 0.25
572	AT&T 572		9-wire Matrix Printer
.sp 0.25
573	AT&T 573		9-wire Matrix Printer
.sp 0.25
580ibm-5x6	AT&T 580	IBM Proprinter XL	5:6 aspect ratio; low 
			resolution
580ibm	AT&T 580	IBM Proprinter XL in AGM	1:1; low resolution
.sp 0.25
580ibm-hi	AT&T 580	IBM Proprinter XL in AGM	1:1; high resolution
.sp 0.25
581ibm-5x6	AT&T 581	IBM Proprinter XL	5:6 aspect ratio; low 
			resolution
.sp 0.25
581ibm	AT&T 581	IBM Proprinter XL in AGM	1:1; low resolution
.sp 0.25
581ibm-hi	AT&T 581	IBM Proprinter XL in AGM	1:1; high resolution
.sp 0.25
583ibm-5x6	AT&T 583	IBM Proprinter XL	5:6 aspect ratio; low 
			resolution
.sp 0.25
583ibm	AT&T 583	IBM Proprinter XL in AGM	1:1; low resolution
.sp 0.25
583ibm-hi	AT&T 583	IBM Proprinter XL in AGM	1:1; high resolution
.sp 0.25
583ibm-5x6-80	AT&T 583	IBM Proprinter XL	5:6 aspect ratio; low 
			resolution;80-col
.sp 0.25
583ibm-hi-80	AT&T 583	IBM Proprinter XL in AGM	1:1; high resolution; 80-col
.sp 0.25
583ibm-80	AT&T 583	IBM Proprinter XL in AGM	1:1; low resolution; 80-col
.sp 0.25
580eps	AT&T 580	Epson LQ-2500	low resolution
.sp 0.25
580eps-hi	AT&T 580	Epson LQ-2500	high resolution
.sp 0.25
581eps	AT&T 581	Epson LQ-2500	low resolution
.sp 0.25
581eps-hi	AT&T 581	Epson LQ-2500	high resolution
.sp 0.25
583eps	AT&T 583	Epson LQ-2500	low resolution
.sp 0.25
583eps-hi	AT&T 583	Epson LQ-2500	high resolution
.sp 0.25
583eps-80	AT&T 583	Epson LQ-2500	low resolution; 80-col
.sp 0.25
583eps-hi-80	AT&T 583	Epson LQ-2500	high resolution; 80-col
.sp 0.25
593eps	AT&T 593	Epson FX86e
.sp 0.25
593ibm	AT&T 593	IBM ProPrinter XL
.sp 0.25
593hp	AT&T 593	HP Laserjet II
.sp 0.25
postscript	generic
	PostScript
.sp 0.25
hppaintjet	HP PaintJet		90 dots per inch; 16 colors
.sp 0.25
.TE
.PP
Output for the HP PaintJet printer, a color printer capable of
handling 16 colors from a palette of 330, can be produced
using the \f3-dpaintjet\fP option.
.PP
Output for the PostScript printer can now include grayscale
rendering, when the \f3-dpostscript\fP option is used. With
this option, the header and trailer are printed using regular
PostScript fonts, instead of the font images internal to
\f2xpr\fP. The \f3-dps\fP option will produce the dithering
rendering provided before (i.e., X\s-2WIN\s+2 2.0's \f3xpr
-dpostscript\fP option is now X\s-2WIN\s+2 3.0's \f3xpr
-dps\fP option).
.SH "CUSTOMIZING THE TERMINFO DATABASE FOR XPR"
For the \f2xpr\fP program, all printers are currently supported via
the Terminfo database.  By adding new entries or changing the
existing entries using the infocmp(1M) and the tic(1M)
programs, you can customize the printer support.  The Terminfo
capabilities used by the \f2xpr\fP program are listed below; check
the Terminfo(4) for information about these and other
capabilities.
.sp .5
.nf
colors Number of colors in the ribbon (besides black)
initc* Select color band
npins  Number of pins in print-head or graphics unit
porder Matches software bits to print-head pins or unit bits
rblm   End printing bit image graphics
sbim   Start printing bit image graphics
spinh  Spacing of dots horizontally in dots per inch
spinv  Spacing of dots vertically in dots per inch
u1*    Number of passes of print-head per image line
u2*    Type of image printing
u3*    Carriage return while in graphics mode
u4*    Repeat graphics unit
u5*    Newline while in graphics mode
u6*    Start image area
u7*    End image area
u8*    Generate name of ribbon color
.fi
.sp .5
The capabilities marked with an asterisk are only temporary
names; they will change in a future release.  The Terminfo(4)
manual page does not describe their use, so a brief description
is given below:
.TP 8
\f3u1\fP  
For most printers, this value is 1.  The AT&T 5310/5320
provide a higher level dot resolution vertically, as long
as the application (\f2xpr\fP in this case) prints an image row
in two passes.  In general, u1 should be the number of
passes needed to print an image row.  The u5 (graphics
newline) string is used after each pass - it is expected
that the printer takes care of moving the correct distance
before each pass.
.TP 8
\f3u2\fP 
This should be 1 for dot-matrix type printers where each
image row is constructed from byte packets representing
a piece one dot wide and npins dots tall.  It should be
2 for page printers where each image row is constructed
from byte packets representing a piece npins wide and one
dot tall.  In either case, the porder string defines the
mapping of bits in byte packets to printed dots.  The
position of each number in the porder list corresponds to
a bit in the byte packet, most significant bits first. 
The numbers identify a printed dot:  for printers of type
1, the dots are numbered from top to bottom; for printers
of type 2, the dots are numbered from left to right.  See
the terminfo(4) manual page for more information on the
porder capability.
.TP 8
\f3u3\fP
This is the control sequence that moves the current print
position to the left edge of the bit image on the current
row.  It is used with one argument in a call to tparm(3X),
the horizontal position of the left edge in dots.
.LI u4
This is the control sequence used to compress runs of
identical byte packets.  It is used with 2 or more
arguments in a call to tparm(3X).  The first argument is
the string of bytes in the packet, and the second is the
number of times to repeat the packet.  Since the string
may not be in a useful form for some printers, the
individual bytes are available as the third through ninth
arguments.
.TP 8
\f3u5\fP 
This is the control sequence that moves the current print
position to the left edge of the bit image on the next
row.  It is used with one argument in a call to tparm(3X),
the horizontal position of the left edge in dots.
.TP 8
\f3u6\fP
This is the control sequence used to start an image at a
specific location on the page.  It is used with 5
arguments in a call to tparm(3X).  The first two arguments
give the horizontal and vertical position in dots.  The
control sequence should ensure that the printing of the
image starts at that location.  The third and fourth
arguments are the width and height of the image in dots. 
The last is the scale factor; the u6 capability should
conditionally produce a non-null control sequence only for
a scale the printer can handle.  If the printer can't
handle a needed scale, the application (\f2xpr\fP) must simulate
the scale in software.
.TP 8
\f3u7\fP
This is the control sequence to terminate an image area
started with u6.
.TP 8
\f3u8\fP 
This is a conditional Terminfo string used to match the
ribbon colors with the arguments to use with the initc
string.  It is used with one argument in a call to
tparm(3X), the number of the ribbon band.  The string
should produce the name of the corresponding color, or a
null string for bands out of range.  The colors should be
numbered from darkest to lightest, that is, in the order
they should be overstruck to avoid staining the ribbon. 
The color band 0 is reserved for black.
.TP 8
\f3initc\fP
This is the control sequence used to select a ribbon
band for printing.  It is used with one argument in a
call to tparm(3X), the number of the ribbon band.  The
band should stay selected until the next use of this
string.  The argument 0 should always select the black
band.
