.\"
.\" Changes by Gunnar Ritter, Freiburg i. Br., Germany, September 2005.
.\"
.\" Derived from Plan 9 v4 /opt/unix/plan9v4/sys/src/cmd/postscript/picpack/picpack.1
.\"
.\" Copyright (C) 2003, Lucent Technologies Inc. and others.
.\" All Rights Reserved.
.\"
.\" Distributed under the terms of the Lucent Public License Version 1.02.
.\"
.\" Sccsid @(#)picpack.1	1.3 (gritter) 2/2/07
.TH PICPACK 1 "2/2/07" "Heirloom Documentation Tools" "User Commands"
.SH NAME
picpack \- PostScript picture packing preprocessor
.SH SYNOPSIS
\fB/usr/ucb/picpack\fR [\fB\-k\fI\ list\fR] [\fB\-q\fR] [\fIfile\fR] ...
.SH DESCRIPTION
.B picpack
copies
.I files
to stdout, expanding picture inclusion requests
(marked by the
.B .BP
or
.B .PI
macros) into an in-line
format that can be passed through
.B troff
and handled by
.BR dpost .
If no
.I files
are specified
or if
.B \-
is one of the input
.I files
standard input is read.
The following
.I options
are understood:
.TP 10n
\fB\-k\fI\ list\fR
.I list
is a comma- or space-separated string of words used to locate
picture inclusion requests.
The start of every line in the input
.I files
is compared with each word in
.I list .
If there is a match, the second string on the line is
taken as the pathname of a picture file that is added
to the output file.
The default
.I list
is
.RI `` ".BP .PI" ''.
.TP
.B \-q
Suppress ``missing picture file'' error messages.
.PP
.B picpack
is a trivial preprocessor that, in a sense, duplicates some of the
picture inclusion capabilities already available in
.BR dpost .
.B picpack
should not be used if your formatting command line includes
a call to
.BR dpost .
Its only purpose is to combine picture files with text in a single
file that can be passed through
.B troff
and unpacked, at some later time, by
.BR dpost .
The original picture inclusion mechanism, with files are pulled in by
.BR dpost ,
is the preferred approach.
.SH EXAMPLES
A typical application might be in a distributed printing environment
where everything up to
.B troff
is run by the user and everything after
.B troff
is handled by a spooling daemon (perhaps
.BR lp ).
In that case the command line would be,
.sp
.nf
    pic \fIfile\fP | tbl | eqn | picpack | troff \-mm \-Tpost | lp
.fi
.sp
.EE
A poor example, although one that should still work, would be,
.sp
.nf
    pic \fIfile\fP | tbl | eqn | picpack | troff \-mm | dpost >\fIfile\fP.ps
.fi
.sp
In this case picture inclusion requests could (and should) be handled by
.BR dpost .
Running
.B picpack
is not needed or even recommended.
It should be dropped from any pipeline that includes a call to
.BR dpost .
.SH DIAGNOSTICS
A 0 exit status is returned if
.I files
were successfully processed.
.SH WARNINGS
.PP
Combining pictures and text using the capabilities available in
.B dpost
is the recommended approach and is always guaranteed to be more
efficient than
.BR picpack .
Running
.B picpack
and
.B dpost
in the same pipeline makes little sense.
.PP
Using
.B picpack
will likely result in files that can no longer be reliably passed
through other important
.B troff
postprocessors like
.BR proof .
At present
.B picpack
is only guaranteed to work with
.BR dpost .
.SH SEE ALSO
.BR dpost (1),
.BR troff (1B)