sys/man/1/pic

   1 .TH PIC 1
   2 .de PS  \" start picture
   3 .       \" $1 is height, $2 is width, both in inches
   4 .if \\$1>0 .sp .35
   5 .ie \\$1>0 .nr $1 \\$1
   6 .el .nr $1 0
   7 .in (\\n(.lu-\\$2)/2u
   8 .ne \\$1
   9 ..
  10 .de PE  \" end of picture
  11 .in
  12 .if \\n($1>0 .sp .65
  13 ..
  14 .SH NAME
  15 pic \- troff preprocessor for drawing pictures
  16
  17 .SH SYNOPSIS
  18 .B pic
  19 [
  20 .I files
  21 ]
  22 .SH DESCRIPTION
  23 .I Pic
  24 is a
  25 .IR troff (1)
  26 preprocessor for drawing figures on a typesetter.
  27 .I Pic
  28 code is contained between
  29 .B .PS
  30 and
  31 .B .PE
  32 lines:
  33 .IP
  34 .EX
  35 \&.PS \f2optional-width\fP \f2optional-height\fP
  36 \f2element-list\fP
  37 \&.PE
  38 .EE
  39 .LP
  40 or in a file mentioned in a
  41 .B .PS
  42 line:
  43 .IP
  44 .BI .PS " " < file
  45 .LP
  46 If
  47 .IR optional-width
  48 is present, the picture is made that many inches wide,
  49 regardless of any dimensions used internally.
  50 The height is scaled in the same proportion unless
  51 .IR optional-height
  52 is present.
  53 If
  54 .B .PF
  55 is used instead of
  56 .BR .PE ,
  57 the typesetting position after printing is restored to what it was
  58 upon entry.
  59 .PP
  60 An
  61 .IR element-list
  62 is a list of elements:
  63 .EX
  64         \f2primitive  attribute-list\fP
  65         \f2placename\fP : \f2element\fP
  66         \f2placename\fP : \f2position\fP
  67         \f2var\fP = \f2expr\fP
  68         \f2direction\fP
  69         { \f2element-list\fP }
  70         [ \f2element-list\fP ]
  71         for \f2var\fP = \f2expr\fP to \f2expr\fP by \f2expr\fP do { \f2anything\fP }
  72         if \f2expr\fP then { \f2anything\fP } else { \f2anything\fP }
  73         copy \f2file,\fP  copy thru \f2macro,\fP  copy \f2file\fP thru \fPmacro\fP
  74         sh { \f2commandline\fP }
  75         print \f2expr\fP
  76         reset \f2optional var-list\fP
  77         \f2troff-command\fP
  78 .EE
  79 .PP
  80 Elements are separated by newlines or semicolons;
  81 a long element may be continued by ending the line with a backslash.
  82 Comments are introduced by a
  83 .BI #
  84 and terminated by a newline.
  85 Variable names begin with a lower case letter;
  86 place names begin with upper case.
  87 Place and variable names retain their values
  88 from one picture to the next.
  89 .PP
  90 After each primitive
  91 the current position moves in the current direction
  92 .RB ( up , down ,
  93 .BR left , right
  94 (default)) by the size of the primitive.
  95 The current position and direction are saved upon entry
  96 to a
  97 .BR { ... }
  98 block and restored upon exit.
  99 Elements within a block enclosed in
 100 .BR [ ... ]
 101 are treated as a unit;
 102 the dimensions are determined by the extreme points
 103 of the contained objects.
 104 Names, variables, and direction of motion within a block are local to that block.
 105 .PP
 106 .IR Troff-command
 107 is any line that begins with a period.
 108 Such a line is assumed to make sense in the context where it appears;
 109 generally, this means only size and font changes.
 110 .PP
 111 The
 112 .I primitive
 113 objects are:
 114 .br
 115 .EX
 116         box  circle  ellipse  arc  line  arrow  spline  move  \f2text-list\fP
 117 .EE
 118 .L arrow
 119 is a synonym for
 120 .LR "line ->" .
 121 .PP
 122 An
 123 .IR attribute-list
 124 is a sequence of zero or more attributes;
 125 each attribute consists of a keyword, perhaps followed by a value.
 126 .EX
 127 .ta .5i 2.5i
 128         h(eigh)t \f2expr\fP     wid(th) \f2expr\fP
 129         rad(ius) \f2expr\fP     diam(eter) \f2expr\fP
 130         up \f2opt-expr\fP       down \f2opt-expr\fP
 131         right \f2opt-expr\fP    left \f2opt-expr\fP
 132         from \f2position\fP     to \f2position\fP
 133         at \f2position\fP       with \f2corner\fP
 134         by \f2expr, expr\fP     then
 135         dotted \f2opt-expr\fP   dashed \f2opt-expr\fP
 136         chop \f2opt-expr\fP     ->  <-  <->
 137         invis   same
 138         fill \f2opt-expr\fP
 139         \f2text-list\fP \f2expr\fP
 140 .EE
 141 Missing attributes and values are filled in from defaults.
 142 Not all attributes make sense for all primitives;
 143 irrelevant ones are silently ignored.
 144 The attribute
 145 .L at
 146 causes the geometrical center to be put at the specified place;
 147 .L with
 148 causes the position on the object to be put at the specified place.
 149 For lines, splines and arcs,
 150 .L height
 151 and
 152 .L width
 153 refer to arrowhead size.
 154 A bare
 155 .I expr
 156 implies motion in the current direction.
 157 .PP
 158 Text is normally an attribute of some primitive;
 159 by default it is placed at the geometrical center of the object.
 160 Stand-alone text is also permitted.
 161 A text list
 162 is a list of text items:
 163 .EX
 164 \f2  text-item\fP:
 165         "..." \f2positioning ...\fP
 166         sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP
 167 \f2  positioning\fP:
 168         center  ljust  rjust  above  below
 169 .EE
 170 If there are multiple text items for some primitive,
 171 they are arranged vertically and centered except as qualified.
 172 Positioning requests apply to each item independently.
 173 Text items may contain
 174 .I troff
 175 commands for size and font changes, local motions, etc.,
 176 but make sure that these are balanced
 177 so that the entering state is restored before exiting.
 178 .PP
 179 A position is ultimately an
 180 .I x,y
 181 coordinate pair, but it may be specified in other ways.
 182 .EX
 183 \f2  position\fP:
 184         \f2expr, expr\fP
 185         \f2place\fP ± \f2expr, expr\fP
 186         \f2place\fP ± ( \f2expr, expr\fP )
 187         ( \f2position\fP,\f2 position\fP )      \f2x\fP\fR from one, \f2y\fP\fR the other\fP
 188         \f2expr\fP [\fLof the way\fP] between \f2position\fP and \f2position\fP
 189         \f2expr\fP < \f2position\fP , \f2position\fP >
 190         ( \f2position\fP )
 191 .EE
 192 .PP
 193 .EX
 194 \f2  place\fP:
 195         \f2placename\fP \f2optional-corner\fP
 196         \f2corner\fP of \f2placename\fP
 197         \f2nth\fP \f2primitive\fP \f2optional-corner\fP
 198         \f2corner\fP of \f2nth\fP \f2primitive\fP
 199         Here
 200 .EE
 201 An
 202 .IR optional-corner
 203 is one of the eight compass points
 204 or the center or the start or end of a primitive.
 205 .EX
 206 \f2  optional-corner\fP:
 207         .n  .e  .w  .s  .ne  .se  .nw  .sw  .c  .start  .end
 208 \f2  corner\fP:
 209         top  bot  left  right  start  end
 210 .EE
 211 Each object in a picture has an ordinal number;
 212 .IR nth
 213 refers to this.
 214 .EX
 215 \f2  nth\fP:
 216         \f2n\fPth\f2,     n\fPth last
 217 .EE
 218 .PP
 219 The built-in variables and their default values are:
 220 .EX
 221 .ta .5i 2.5i
 222         boxwid 0.75     boxht 0.5
 223         circlerad 0.25  arcrad 0.25
 224         ellipsewid 0.75 ellipseht 0.5
 225         linewid 0.5     lineht 0.5
 226         movewid 0.5     moveht 0.5
 227         textwid 0       textht 0
 228         arrowwid 0.05   arrowht 0.1
 229         dashwid 0.1     arrowhead 2
 230         scale 1
 231 .EE
 232 These may be changed at any time,
 233 and the new values remain in force from picture to picture until changed again
 234 or reset by a
 235 .L reset
 236 statement.
 237 Variables changed within
 238 .B [
 239 and
 240 .B ]
 241 revert to their previous value upon exit from the block.
 242 Dimensions are divided by
 243 .B scale
 244 during output.
 245 .PP
 246 Expressions in
 247 .I pic
 248 are evaluated in floating point.
 249 All numbers representing dimensions are taken to be in inches.
 250 .EX
 251 \f2  expr\fP:
 252         \f2expr\fP \f2op\fP \f2expr\fP
 253         - \f2expr\fP
 254         ! \f2expr\fP
 255         ( \f2expr\fP )
 256         variable
 257         number
 258         \f2place\fP .x  \f2place\fP .y  \f2place\fP .ht  \f2place\fP .wid  \f2place\fP .rad
 259         sin(\f2expr\fP)  cos(\f2expr\fP)  atan2(\f2expr,expr\fP)  log(\f2expr\fP)  exp(\f2expr\fP)
 260         sqrt(\f2expr\fP)  max(\f2expr,expr\fP)  min(\f2expr,expr\fP)  int(\f2expr\fP)  rand()
 261 \f2  op\fP:
 262         +  -  *  /  %  <  <=  >  >=  ==  !=  &&  ||
 263 .EE
 264 .PP
 265 The
 266 .B define
 267 and
 268 .B undef
 269 statements are not part of the grammar.
 270 .EX
 271         define \f2name\fP { \f2replacement text\fP }
 272         undef \f2name\fP
 273 .EE
 274 Occurrences of
 275 .BR $1 ,
 276 .BR $2 ,
 277 etc.,
 278 in the replacement text
 279 will be replaced by the corresponding arguments if
 280 .I name
 281 is invoked as
 282 .EX
 283         \f2name\fP(\f2arg1\fP, \f2arg2\fP, ...)
 284 .EE
 285 Non-existent arguments are replaced by null strings.
 286 Replacement text
 287 may contain newlines.
 288 The
 289 .B undef
 290 statement removes the definition of a macro.
 291 .SH SOURCE
 292 .B /sys/src/cmd/pic
 293 .SH "SEE ALSO"
 294 .IR grap (1),
 295 .IR doctype (1),
 296 .IR troff (1)
 297 .br
 298 B. W. Kernighan,
 299 ``PIC\(ema Graphics Language for Typesetting'',
 300 .I
 301 Unix Research System Programmer's Manual,
 302 Tenth Edition, Volume 2