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