PIC(1)                                                     PIC(1)

     NAME
          pic, tpic - troff and tex preprocessors for drawing pictures

     SYNOPSIS
          pic [ files ]

          tpic [ files ]

     DESCRIPTION
          Pic is a troff(1) preprocessor for drawing figures on a
          typesetter.  Pic code is contained between .PS and .PE
          lines:

               .PS optional-width optional-height
               element-list
               .PE

          or in a file mentioned in a .PS line:

               .PS <file

          If optional-width is present, the picture is made that many
          inches wide, regardless of any dimensions used internally.
          The height is scaled in the same proportion unless
          optional-height is present.  If .PF is used instead of .PE,
          the typesetting position after printing is restored to what
          it was upon entry.

          An element-list is a list of elements:
               primitive  attribute-list
               placename : element
               placename : position
               var = expr
               direction
               { element-list }
               [ element-list ]
               for var = expr to expr by expr do { anything }
               if expr then { anything } else { anything }
               copy file,  copy thru macro,  copy file thru macro
               sh { commandline }
               print expr
               reset optional var-list
               troff-command

          Elements are separated by newlines or semicolons; a long
          element may be continued by ending the line with a back-
          slash.  Comments are introduced by a # and terminated by a
          newline.  Variable names begin with a lower case letter;
          place names begin with upper case.  Place and variable names
          retain their values from one picture to the next.

     PIC(1)                                                     PIC(1)

          After each primitive the current position moves in the cur-
          rent direction (up,down, left,right (default)) by the size
          of the primitive.  The current position and direction are
          saved upon entry to a {...} block and restored upon exit.
          Elements within a block enclosed in [...]  are treated as a
          unit; the dimensions are determined by the extreme points of
          the contained objects.  Names, variables, and direction of
          motion within a block are local to that block.

          Troff-command is any line that begins with a period.  Such a
          line is assumed to make sense in the context where it
          appears; generally, this means only size and font changes.

          The primitive objects are:
               box  circle  ellipse  arc  line  arrow  spline  move  text-list
          `arrow' is a synonym for `line ->'.

          An attribute-list is a sequence of zero or more attributes;
          each attribute consists of a keyword, perhaps followed by a
          value.
               h(eigh)t expr       wid(th) expr
               rad(ius) expr       diam(eter) expr
               up opt-expr         down opt-expr
               right opt-expr      left opt-expr
               from position       to position
               at position         with corner
               by expr, expr       then
               dotted opt-expr     dashed opt-expr
               chop opt-expr       ->  <-  <->
               invis               same
               fill opt-expr
               text-list           expr
          Missing attributes and values are filled in from defaults.
          Not all attributes make sense for all primitives; irrelevant
          ones are silently ignored.  The attribute `at' causes the
          geometrical center to be put at the specified place; `with'
          causes the position on the object to be put at the specified
          place.  For lines, splines and arcs, `height' and `width'
          refer to arrowhead size.  A bare expr implies motion in the
          current direction.

          Text is normally an attribute of some primitive; by default
          it is placed at the geometrical center of the object.
          Stand-alone text is also permitted.  A text list is a list
          of text items:
            text-item:
               "..." positioning ...
               sprintf("format", expr, ...) positioning ...
            positioning:
               center  ljust  rjust  above  below
          If there are multiple text items for some primitive, they
          are arranged vertically and centered except as qualified.

     PIC(1)                                                     PIC(1)

          Positioning requests apply to each item independently.  Text
          items may contain troff commands for size and font changes,
          local motions, etc., but make sure that these are balanced
          so that the entering state is restored before exiting.

          A position is ultimately an x,y coordinate pair, but it may
          be specified in other ways.
            position:
               expr, expr
               place ± expr, expr
               place ± ( expr, expr )
               ( position, position )x from one, y the other
               expr [of the way] between position and position
               expr < position , position >
               ( position )

            place:
               placename optional-corner
               corner of placename
               nth primitive optional-corner
               corner of nth primitive
               Here
          An optional-corner is one of the eight compass points or the
          center or the start or end of a primitive.
            optional-corner:
               .n  .e  .w  .s  .ne  .se  .nw  .sw  .c  .start  .end
            corner:
               top  bot  left  right  start  end
          Each object in a picture has an ordinal number; nth refers
          to this.
            nth:
               nth,     nth last

          The built-in variables and their default values are:
               boxwid 0.75         boxht 0.5
               circlerad 0.25      arcrad 0.25
               ellipsewid 0.75     ellipseht 0.5
               linewid 0.5         lineht 0.5
               movewid 0.5         moveht 0.5
               textwid 0           textht 0
               arrowwid 0.05       arrowht 0.1
               dashwid 0.1         arrowhead 2
               scale 1
          These may be changed at any time, and the new values remain
          in force from picture to picture until changed again or
          reset by a `reset' statement.  Variables changed within [
          and ] revert to their previous value upon exit from the
          block.  Dimensions are divided by scale during output.

          Expressions in pic are evaluated in floating point.  All
          numbers representing dimensions are taken to be in inches.
            expr:

     PIC(1)                                                     PIC(1)

               expr op expr
               - expr
               ! expr
               ( expr )
               variable
               number
               place .x  place .y  place .ht  place .wid  place .rad
               sin(expr)  cos(expr)  atan2(expr,expr)  log(expr)  exp(expr)
               sqrt(expr)  max(expr,expr)  min(expr,expr)  int(expr)  rand()
            op:
               +  -  *  /  %  <  <=  >  >=  ==  !=  &&  ||

          The define and undef statements are not part of the grammar.
               define name { replacement text }
               undef name
          Occurrences of $1, $2, etc., in the replacement text will be
          replaced by the corresponding arguments if name is invoked
          as
               name(arg1, arg2, ...)
          Non-existent arguments are replaced by null strings.
          Replacement text may contain newlines.  The undef statement
          removes the definition of a macro.

          Tpic is a tex(1) preprocessor that accepts pic language.  It
          produces Tex commands that define a box called \graph, which
          contains the picture.  The box may be output this way:

               \centerline{\box\graph}

     EXAMPLES
          arrow "input" above; box "process"; arrow "output" above
          move
          A: ellipse
             circle rad .1 with .w at A.e
             circle rad .05 at 0.5 <A.c, A.ne>
             circle rad .065 at 0.5 <A.c, A.ne>
             spline from last circle.nw left .25 then left .05 down .05
             arc from A.c to A.se rad 0.5
             for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 }

          arrow "input" above; box "process"; arrow "output" above
          move A: ellipse
             circle rad .1 with .w at A.e
             circle rad .05 at 0.5 <A.c, A.ne>
             circle rad .065 at 0.5 <A.c, A.ne>
             spline from last circle.nw left .25 then left .05 down
          .05
             arc from A.c to A.se rad 0.5
             for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50
          }

     SOURCE

     PIC(1)                                                     PIC(1)

          /sys/src/cmd/pic

     SEE ALSO
          grap(1), doctype(1), troff(1)
          B. W. Kernighan, ``PIC-a Graphics Language for Typeset-
          ting'', Unix Research System Programmer's Manual, Tenth Edi-
          tion, Volume 2