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

   1 .ds dQ /usr/lib/postscript
   2 .TH POSTMD 1 "DWB 3.2"
   3 .SH NAME
   4 .B postmd
   5 \- matrix display program for PostScript printers
   6 .SH SYNOPSIS
   7 \*(mBpostmd\f1
   8 .OP "" options []
   9 .OP "" files []
  10 .SH DESCRIPTION
  11 .B postmd
  12 reads a series of floating point numbers from
  13 .IR files ,
  14 translates them into a PostScript gray scale image,
  15 and writes the results on the standard output.
  16 In a typical application the numbers might be
  17 the elements of a large matrix,
  18 written in row major order,
  19 while the printed image could help locate
  20 patterns in the matrix.
  21 If no
  22 .I files
  23 are specified, or if
  24 .OP \-
  25 is one of the input
  26 .IR files ,
  27 the standard input is read.
  28 The following
  29 .I options
  30 are understood:
  31 .TP 0.75i
  32 .OP \-b num
  33 Pack the bitmap in the output file using
  34 .I num
  35 byte patterns.
  36 A value of 0 turns off all packing of the output file.
  37 By default
  38 .I num
  39 is 6.
  40 .TP
  41 .OP \-c num
  42 Print
  43 .I num
  44 copies of each page.
  45 By default only one copy is printed.
  46 .TP
  47 .OP \-d dimen
  48 Sets the default matrix dimensions for all input
  49 .I files
  50 to
  51 .IR dimen .
  52 The
  53 .I dimen
  54 string can be given as rows or rows\^\(mu\^columns.
  55 If columns is omitted it will be set to rows.
  56 By default
  57 .B postmd
  58 assumes each matrix is square and sets the number of rows
  59 and columns to the square root of the number of elements in
  60 each input file.
  61 .TP
  62 .OP \-g list
  63 .I list
  64 is a comma- or space-separated string of integers, each lying between
  65 0 and 255 inclusive,
  66 that assigns PostScript gray scales to the regions of the real line
  67 selected by the
  68 .OP \-i
  69 option.
  70 255 corresponds to white and 0 to black.
  71 .B postmd
  72 assigns a default gray scale that omits white (i.e., 255) and gets
  73 darker as the regions move from left to right along the real line.
  74 .TP
  75 .OP \-i list
  76 .I list
  77 is a comma- or space-separated string of
  78 .I N
  79 floating point numbers that
  80 partition the real line into
  81 .RI 2 N +1
  82 regions.
  83 The
  84 .I list
  85 must be given in increasing numerical order.
  86 The partitions are used to map floating point numbers read from the input
  87 .I files
  88 into gray scale integers that are assigned automatically by
  89 .B postmd
  90 or arbitrarily selected using the
  91 .OP \-g
  92 option.
  93 The default interval
  94 .I list
  95 is ``\*(mB\-1,0,1\fP'' which partions the real line into 7 regions.
  96 .TP
  97 .OP \-m num
  98 Magnify each logical page by the factor
  99 .IR num .
 100 Pages are scaled uniformly about the origin,
 101 which by default is located at the center of
 102 each page.
 103 The default magnification is 1.0.
 104 .TP
 105 .OP \-n num
 106 Print
 107 .I num
 108 logical pages on each piece of paper,
 109 where
 110 .I num
 111 can be any positive integer.
 112 By default
 113 .I num
 114 is set to 1.
 115 .TP
 116 .OP \-o list
 117 Print pages whose numbers are given in the comma separated
 118 .IR list .
 119 The list contains single numbers
 120 .I N
 121 and ranges
 122 .IR N1\-\|N2 .
 123 A missing
 124 .I N1
 125 means the lowest numbered page, a missing
 126 .I N2
 127 means the highest.
 128 .TP
 129 .OP \-p mode
 130 Print
 131 .I files
 132 in either \*(mBportrait\fP or \*(mBlandscape\fP
 133 .IR mode .
 134 Only the first character of
 135 .I mode
 136 is significant.
 137 The default
 138 .I mode
 139 is \*(mBportrait\fP.
 140 .TP
 141 .OP \-w window
 142 .I window
 143 is a comma- or space-separated list of four positive integers that
 144 select the upper left and lower right corners of a submatrix from
 145 each of the input
 146 .IR files .
 147 Row and column indices start at 1 in the upper left corner and the
 148 numbers in the input
 149 .I files
 150 are assumed to be written in row major order.
 151 By default the entire matrix is displayed.
 152 .TP
 153 .OP \-x num
 154 Translate the origin
 155 .I num
 156 inches along the positive x axis.
 157 The default
 158 coordinate system has the origin fixed at the
 159 center of the page, with positive
 160 x to the right and positive y up the page.
 161 Positive
 162 .I num
 163 moves everything right.
 164 The default offset is 0 inches.
 165 .TP
 166 .OP \-y num
 167 Translate the origin
 168 .I num
 169 inches along the positive y axis.
 170 Positive
 171 .I num
 172 moves everything up the page.
 173 The default offset is 0.
 174 .TP
 175 .OP \-E name
 176 Set the character encoding for text fonts to
 177 .IR name .
 178 Requesting
 179 .I name
 180 means include file
 181 .MI \*(dQ/ name .enc \f1.
 182 A nonexistent encoding file is silently ignored.
 183 The default selects file
 184 .MR \*(dQ/Default.enc .
 185 .TP
 186 .OP \-L file
 187 Use
 188 .I file
 189 as the PostScript prologue.
 190 .br
 191 The default is
 192 .MR \*(dQ/postmd.ps .
 193 .PP
 194 Three options allow insertion of arbitrary PostScript
 195 at controlled points in the translation process:
 196 .TP 0.75i
 197 .OP \-C file
 198 Copy
 199 .I file
 200 to the output file;
 201 .I file
 202 must contain legitimate PostScript.
 203 .TP
 204 .OP \-P string
 205 Include
 206 .I string
 207 in the output file;
 208 .I string
 209 must be legitimate PostScript.
 210 .TP
 211 .OP \-R action
 212 Requests special
 213 .I action
 214 (e.g.,
 215 .MR manualfeed )
 216 on a per page or global basis.
 217 The
 218 .I action
 219 string can be given as
 220 .IR request ,
 221 .IM request : page\f1\|,
 222 or
 223 .IM request : page : file\f1\|.
 224 If
 225 .I page
 226 is omitted or given as 0, the request
 227 applies to all pages.
 228 If
 229 .I file
 230 is omitted, the request
 231 lookup is done in
 232 .MR \*(dQ/ps.requests .
 233 .PP
 234 Only one matrix is displayed on each logical page,
 235 and each of the input
 236 .I files
 237 must contain complete descriptions of exactly one matrix.
 238 Matrix elements are floating point numbers arranged in row major order in
 239 each input file.
 240 White space, including newlines, is not used to determine matrix
 241 dimensions.
 242 By default
 243 .B postmd
 244 assumes each matrix is square and sets the number of rows and columns
 245 to the square root of the number of elements in the input file.
 246 Supplying default dimensions on the command line using the
 247 .OP \-d
 248 option overrides this default behavior, and in that case the
 249 dimensions apply to all input
 250 .IR files .
 251 .PP
 252 An optional header can be supplied with each input file and is used
 253 to set the matrix dimensions, the partition of the real line, the gray scale
 254 map, and a window into the matrix.
 255 The header consists of keyword/value pairs, each on a separate line.
 256 It begins on the first line of each input file and ends with the
 257 first unrecognized string, which should be the first matrix element.
 258 Values set in the header take precedence, but only apply to the
 259 current input file.
 260 Recognized header keywords are
 261 .MR dimension ,
 262 .MR interval ,
 263 .MR grayscale ,
 264 and
 265 .MR window .
 266 The syntax of the value string that follows each keyword parallels what is
 267 accepted by the
 268 .OP \-d ,
 269 .OP \-i ,
 270 .OP \-g ,
 271 and
 272 .OP \-w
 273 options.
 274 .SH EXAMPLES
 275 For example, suppose
 276 .I file
 277 initially contains the 1000 numbers
 278 in a 20\(mu50 matrix.
 279 Then the command line:
 280 .EX
 281 postmd -d20x50 -i"-100 100" -g0,128,254,128,0 \f2file
 282 .EE
 283 and prepending the header,
 284 .EX
 285 dimension 20x50
 286 interval -100.0 .100e+3
 287 grayscale 0 128 254 128 0
 288 .EE
 289 to
 290 .I file
 291 and typing the command line:
 292 .EX
 293 postmd \f2file
 294 .EE
 295 produce exactly the same output.
 296 The interval list partitions the real line into five regions and
 297 the gray scale list maps numbers less than \-100 or greater than 100
 298 into 0 (i.e., black), numbers equal to \-100 or 100 into 128
 299 (i.e., 50 percent
 300 black), and numbers between \-100 and 100 into 254 (i.e., almost white).
 301 .SH DIAGNOSTICS
 302 A 0 exit status is returned if
 303 .I files
 304 were successfully processed.
 305 .SH WARNINGS
 306 The largest matrix that can be adequately displayed is a function
 307 of the interval and gray scale lists, the printer resolution,
 308 and the paper size.
 309 A 600\(mu600 matrix is an optimistic upper bound for a two element interval
 310 list (i.e. five regions) using 8.5\(mu11 inch paper on a 300 dpi printer.
 311 .PP
 312 Using white (i.e., 255) in a gray scale list is not recommended and will not
 313 show up in the legend and bar graph that
 314 .B postmd
 315 displays below each image.
 316 .SH FILES
 317 .MW \*(dQ/postmd.ps
 318 .br
 319 .MW \*(dQ/forms.ps
 320 .br
 321 .MW \*(dQ/ps.requests
 322 .SH SEE ALSO
 323 .BR dpost (1),
 324 .BR postdaisy (1),
 325 .BR postdmd (1),
 326 .BR postio (1),
 327 .BR postprint (1),
 328 .BR postreverse (1),
 329 .BR posttek (1),
 330 .BR psencoding (1)