sys/src/cmd/postscript/picpack/picpack.1.man

   1 .TH PICPACK 1
   2 .SH NAME
   3 .B picpack
   4 \- PostScript picture packing preprocessor
   5 .SH SYNOPSIS
   6 \*(mBpicpack\f1
   7 .OP "" options []
   8 .OP "" files []
   9 .SH DESCRIPTION
  10 .B picpack
  11 copies
  12 .I files
  13 to stdout, expanding picture inclusion requests
  14 (marked by the
  15 .MW .BP
  16 or
  17 .MW .PI
  18 macros) into an in-line
  19 format that can be passed through
  20 .B troff
  21 and handled by
  22 .BR dpost .
  23 If no
  24 .I files
  25 are specified
  26 or if
  27 .OP \-
  28 is one of the input
  29 .I files
  30 standard input is read.
  31 The following
  32 .I options
  33 are understood:
  34 .TP 0.75i
  35 .OP \-k list
  36 .I list
  37 is a comma- or space-separated string of words used to locate
  38 picture inclusion requests.
  39 The start of every line in the input
  40 .I files
  41 is compared with each word in
  42 .I list .
  43 If there is a match, the second string on the line is
  44 taken as the pathname of a picture file that is added
  45 to the output file.
  46 The default
  47 .I list
  48 is
  49 .RM `` ".BP .PI ''.
  50 .TP
  51 .OP \-q
  52 Suppress ``missing picture file'' error messages.
  53 .PP
  54 .B picpack
  55 is a trivial preprocessor that, in a sense, duplicates some of the
  56 picture inclusion capabilities already available in
  57 .BR dpost .
  58 .B picpack
  59 should not be used if your formatting command line includes
  60 a call to
  61 .BR dpost .
  62 Its only purpose is to combine picture files with text in a single
  63 file that can be passed through
  64 .B troff
  65 and unpacked, at some later time, by
  66 .BR dpost .
  67 The original picture inclusion mechanism, with files are pulled in by
  68 .BR dpost ,
  69 is the preferred approach.
  70 .SH EXAMPLES
  71 A typical application might be in a distributed printing environment
  72 where everything up to
  73 .B troff
  74 is run by the user and everything after
  75 .B troff
  76 is handled by a spooling daemon (perhaps
  77 .BR lp ).
  78 In that case the command line would be,
  79 .EX
  80 pic  \f2file\fP | tbl | eqn | picpack | troff -mm -Tpost | lp
  81 .EE
  82 A poor example, although one that should still work, would be,
  83 .EX
  84 pic  \f2file\fP | tbl | eqn | picpack | troff -mm -Tpost | dpost >\f2file\fP.ps
  85 .EE
  86 In this case picture inclusion requests could (and should) be handled by
  87 .BR dpost .
  88 Running
  89 .B picpack
  90 is not needed or even recommended.
  91 It should be dropped from any pipeline that includes a call to
  92 .BR dpost .
  93 .SH DIAGNOSTICS
  94 A 0 exit status is returned if
  95 .I files
  96 were successfully processed.
  97 .SH WARNINGS
  98 .PP
  99 Combining pictures and text using the capabilities available in
 100 .B dpost
 101 is the recommended approach and is always guaranteed to be more
 102 efficient than
 103 .BR picpack .
 104 Running
 105 .B picpack
 106 and
 107 .B dpost
 108 in the same pipeline makes little sense.
 109 .PP
 110 Using
 111 .B picpack
 112 will likely result in files that can no longer be reliably passed
 113 through other important
 114 .B troff
 115 postprocessors like
 116 .BR proof .
 117 At present
 118 .B picpack
 119 is only guaranteed to work with
 120 .BR dpost .
 121 .SH SEE ALSO
 122 .BR dpost (1),
 123 .BR troff (1)