PIC(1)                                                     PIC(1)


NAME
       pic - compile pictures for troff or TeX



SYNOPSIS
       pic [ -nvC ] [ filename ...  ]
       pic -t [ -cvzC ] [ filename ...  ]

DESCRIPTION
       This  manual  page describes the GNU version of pic, which
       is part of the groff document formatting system.  pic com-
       piles  descriptions  of  pictures embedded within troff or
       TeX input files into commands that are understood  by  TeX
       or  troff.  Each picture starts with a line beginning with
       .PS and ends with a line  beginning  with  .PE.   Anything
       outside of .PS and .PE is passed through without change.

       It  is  the  user's  responsibility to provide appropriate
       definitions of the PS and PE macros.  When the macro pack-
       age being used does not supply such definitions (for exam-
       ple, old versions of -ms), appropriate definitions can  be
       obtained with -mpic: these will center each picture.

OPTIONS
       Options that do not take arguments may be grouped behind a
       single -.  The special option -- can be used to  mark  the
       end  of  the options.  A filename of - refers to the stan-
       dard input.

       -C     Recognize .PS and .PE even when followed by a char-
              acter other than space or newline.

       -S     Safer  mode;  do not execute sh commands.  This can
              be useful when operating on untrustworthy input.

       -n     Don't use the groff extensions to the troff drawing
              commands.   You  should use this if you are using a
              postprocessor that  doesn't  support  these  exten-
              sions.     The    extensions   are   described   in
              groff_out(5).  The -n option also causes pic not to
              use zero-length lines to draw dots in troff mode.

       -t     TeX mode.

       -c     Be  more  compatible with tpic.  Implies -t.  Lines
              beginning with \ are not passed  through  transpar-
              ently.   Lines beginning with .  are passed through
              with the initial .  changed to \.  A line beginning
              with  .ps  is  given special treatment: it takes an
              optional  integer  argument  specifying  the   line
              thickness  (pen  size)  in  milliinches;  a missing
              argument restores the previous line thickness;  the
              default  line thickness is 8 milliinches.  The line
              thickness thus specified takes effect only  when  a
              non-negative  line thickness has not been specified



Groff Version 1.11      14 September 1996                       1





PIC(1)                                                     PIC(1)


              by use of the thickness attribute or by setting the
              linethick variable.

       -v     Print the version number.

       -z     In TeX mode draw dots using zero-length lines.

       The  following  options supported by other versions of pic
       are ignored:

       -D     Draw all lines using the \D escape  sequence.   pic
              always does this.

       -T dev Generate  output for the troff device dev.  This is
              unnecessary because the troff output  generated  by
              pic is device-independent.

USAGE
       This  section  describes  only the differences between GNU
       pic and the original version of pic.  Many of  these  dif-
       ferences also apply to newer versions of Unix pic.

   TeX mode
       TeX  mode  is  enabled by the -t option.  In TeX mode, pic
       will define a vbox called \graph for  each  picture.   You
       must yourself print that vbox using, for example, the com-
       mand

              \centerline{\box\graph}

       Actually, since the vbox has a height of  zero  this  will
       produce  slightly  more  vertical  space above the picture
       than below it;

              \centerline{\raise 1em\box\graph}

       would avoid this.

       You must use a TeX driver that supports the tpic specials,
       version 2.

       Lines beginning with \ are passed through transparently; a
       % is added to the  end  of  the  line  to  avoid  unwanted
       spaces.   You  can safely use this feature to change fonts
       or to change the value of  \baselineskip.   Anything  else
       may  well  produce  undesirable  results;  use at your own
       risk.  Lines beginning with a period  are  not  given  any
       special treatment.

   Commands
       for variable = expr1 to expr2 [by [*]expr3] do X body X
              Set variable to expr1.  While the value of variable
              is less than or equal to expr2, do body and  incre-
              ment  variable  by  expr3;  if  by  is  not  given,



Groff Version 1.11      14 September 1996                       2





PIC(1)                                                     PIC(1)


              increment variable by 1.  If expr3 is prefixed by *
              then  variable will instead be multiplied by expr3.
              X can be any character not occurring in body.

       if expr then X if-true X [else Y if-false Y]
              Evaluate expr; if it is non-zero then  do  if-true,
              otherwise  do if-false.  X can be any character not
              occurring in if-true.  Y can be any  character  not
              occurring in if-false.

       print arg...
              Concatenate  the  arguments  and print as a line on
              stderr.  Each arg must be an  expression,  a  posi-
              tion, or text.  This is useful for debugging.

       command arg...
              Concatenate  the arguments and pass them through as
              a line to troff orTeX.  Each arg must be an expres-
              sion,  a  position,  or  text.   This has a similar
              effect to a line beginning with .  or \, but allows
              the values of variables to be passed through.

       sh X command X
              Pass  command  to  a shell.  X can be any character
              not occurring in command.

       copy "filename"
              Include filename at this point in the file.

       copy ["filename"] thru X body X [until "word"]
       copy ["filename"] thru macro [until "word"]
              This construct does body  once  for  each  line  of
              filename;  the  line  is split into blank-delimited
              words, and occurrences of $i in body, for i between
              1 and 9, are replaced by the i-th word of the line.
              If filename is not given, lines are taken from  the
              current  input  up  to  .PE.  If an until clause is
              specified, lines will be read only until a line the
              first word of which is word; that line will then be
              discarded.  X can be any character not occurring in
              body.  For example,

                     .PS
                     copy thru % circle at ($1,$2) % until "END"
                     1 2
                     3 4
                     5 6
                     END
                     box
                     .PE

              is equivalent to

                     .PS



Groff Version 1.11      14 September 1996                       3





PIC(1)                                                     PIC(1)


                     circle at (1,2)
                     circle at (3,4)
                     circle at (5,6)
                     box
                     .PE

              The commands to be performed for each line can also
              be taken from a macro defined earlier by giving the
              name of the macro as the argument to thru.

       reset
       reset variable1, variable2 ...
              Reset  pre-defined  variables  variable1, variable2
              ... to their default values.  If no  arguments  are
              given,  reset  all  pre-defined  variables to their
              default values.  Note that  assigning  a  value  to
              scale  also  causes  all pre-defined variables that
              control dimensions to be  reset  to  their  default
              values times the new value of scale.

       plot expr ["text"]
              This is a text object which is constructed by using
              text as a format string for sprintf with  an  argu-
              ment  of  expr.  If text is omitted a format string
              of "%g" is used.  Attributes can  be  specified  in
              the  same way as for a normal text object.  Be very
              careful that  you  specify  an  appropriate  format
              string;  pic does only very limited checking of the
              string.  This is deprecated in favour of sprintf.

       variable:=expr
              This is similar to = except variable  must  already
              be  defined,  and  the  value  of  variable will be
              changed only in the innermost block in which it  is
              defined.   (By  contrast, = defines the variable in
              the current block if  it  is  not  already  defined
              there,  and  then  changes the value in the current
              block.)

       Arguments of the form

              X anything X

       are also allowed to be of the form

              { anything }

       In this case anything can contain balanced occurrences  of
       {  and }.  Strings may contain X or imbalanced occurrences
       of { and }.

   Expressions
       The  syntax  for  expressions   has   been   significantly
       extended:



Groff Version 1.11      14 September 1996                       4





PIC(1)                                                     PIC(1)


       x ^ y (exponentiation)
       sin(x)
       cos(x)
       atan2(y, x)
       log(x) (base 10)
       exp(x) (base 10, ie 10x)
       sqrt(x)
       int(x)
       rand() (return a random number between 0 and 1)
       rand(x)  (return  a  random number between 1 and x; depre-
       cated)
       max(e1, e2)
       min(e1, e2)
       !e
       e1 && e2
       e1 || e2
       e1 == e2
       e1 != e2
       e1 >= e2
       e1 > e2
       e1 <= e2
       e1 < e2
       "str1" == "str2"
       "str1" != "str2"

       String comparison expressions  must  be  parenthesised  in
       some contexts to avoid ambiguity.

   Other Changes
       A bare expression, expr, is acceptable as an attribute; it
       is equivalent to dir expr, where dir is the current direc-
       tion.  For example

              line 2i

       means  draw a line 2 inches long in the current direction.

       The maximum width and height of the picture are taken from
       the  variables maxpswid and maxpsht.  Initially these have
       values 8.5 and 11.

       Scientific notation is allowed for numbers.  For example
              x = 5e-2

       Text attributes can be compounded.  For example,
              "foo" above ljust
       is legal.

       There is no limit to the depth  to  which  blocks  can  be
       examined.  For example,
              [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
              circle at last [].A.B.C
       is acceptable.




Groff Version 1.11      14 September 1996                       5





PIC(1)                                                     PIC(1)


       Arcs  now  have compass points determined by the circle of
       which the arc is a part.

       Circles and arcs can be dotted or  dashed.   In  TeX  mode
       splines can be dotted or dashed.

       Boxes  can have rounded corners.  The rad attribute speci-
       fies the radius of the quarter-circles at each corner.  If
       no  rad  or diam attribute is given, a radius of boxrad is
       used.  Initially, boxrad has a value of  0.   A  box  with
       rounded corners can be dotted or dashed.

       The .PS line can have a second argument specifying a maxi-
       mum height for the picture.  If the width of zero is spec-
       ified  the  width will be ignored in computing the scaling
       factor for the picture.  Note that  GNU  pic  will  always
       scale  a picture by the same amount vertically as horizon-
       tally.  This is different from the DWB 2.0 pic  which  may
       scale a picture by a different amount vertically than hor-
       izontally if a height is specified.

       Each text object has an invisible box associated with  it.
       The compass points of a text object are determined by this
       box.  The implicit motion associated with  the  object  is
       also  determined  by this box.  The dimensions of this box
       are taken from the width and  height  attributes;  if  the
       width  attribute  is  not  supplied then the width will be
       taken to be textwid; if the height attribute is  not  sup-
       plied  then  the  height will be taken to be the number of
       text strings associated  with  the  object  times  textht.
       Initially textwid and textht have a value of 0.

       In  places  where  a  quoted  text  string can be used, an
       expression of the form

              sprintf("format", arg,...)

       can also be used; this will produce the arguments  format-
       ted  according  to  format,  which  should  be a string as
       described in printf(3) appropriate for the number of argu-
       ments supplied, using only the e, f, g or % format charac-
       ters.

       The thickness of the lines used to draw  objects  is  con-
       trolled  by the linethick variable.  This gives the thick-
       ness of lines in points.  A negative value means  use  the
       default  thickness:  in  TeX output mode, this means use a
       thickness of 8 milliinches; in TeX output mode with the -c
       option, this means use the line thickness specified by .ps
       lines; in troff output mode, this means  use  a  thickness
       proportional  to  the  pointsize.  A zero value means draw
       the thinnest possible line supported by the output device.
       Initially  it  has  a  value  of  -1.   There  is  also  a
       thick[ness] attribute.  For example,



Groff Version 1.11      14 September 1996                       6





PIC(1)                                                     PIC(1)


              circle thickness 1.5

       would draw a circle using a line with a thickness  of  1.5
       points.   The  thickness  of  lines is not affected by the
       value of the scale variable, nor by the  width  or  height
       given in the .PS line.

       Boxes  (including boxes with rounded corners), circles and
       ellipses can be filled by  giving  then  an  attribute  of
       fill[ed].   This  takes an optional argument of an expres-
       sion with a value between 0 and 1; 0  will  fill  it  with
       white,  1 with black, values in between with a proportion-
       ally gray shade.  A value greater than 1 can also be used:
       this  means  fill with the shade of gray that is currently
       being used for text and  lines.   Normally  this  will  be
       black,  but  output  devices  may  provide a mechanism for
       changing this.  Without an argument, then the value of the
       variable fillval will be used.  Initially this has a value
       of 0.5.  The invisible attribute does not affect the fill-
       ing  of objects.  Any text associated with a filled object
       will be added after the object has been  filled,  so  that
       the text will not be obscured by the filling.

       Arrow  heads will be drawn as solid triangles if the vari-
       able arrowhead is non-zero and either TeX mode is  enabled
       or  the -x option has been given.  Initially arrowhead has
       a value of 1.

       The troff output of pic  is  device-independent.   The  -T
       option  is  therefore redundant.  All numbers are taken to
       be in inches; numbers are never interpreted to be in troff
       machine units.

       Objects  can  have  an  aligned attribute.  This will only
       work when the postprocessor is grops.  Any text associated
       with  an  object  having  the  aligned  attribute  will be
       rotated about the center of  the  object  so  that  it  is
       aligned  in  the direction from the start point to the end
       point of the object.  Note that this attribute  will  have
       no effect for objects whose start and end points are coin-
       cident.

       In places where nth is allowed `expr'th is  also  allowed.
       Note  that  'th  is  a  single  token: no space is allowed
       between the ' and the th.  For example,

              for i = 1 to 4 do {
                 line from `i'th box.nw to `i+1'th box.se
              }

FILES
       /usr/share/tmac/tmac.pic   Example definitions of  the  PS
                                  and PE macros.




Groff Version 1.11      14 September 1996                       7





PIC(1)                                                     PIC(1)


SEE ALSO
       troff(1), groff_out(5), tex(1)
       Tpic: Pic for TeX
       AT&T Bell Laboratories, Computing Science Technical Report
       No. 116, PIC  --  A  Graphics  Language  for  Typesetting.
       (This  can  be  obtained  by  sending  a  mail  message to
       netlib@research.att.com      with      a      body      of
       `send 116 from research/cstr'.)

BUGS
       Input characters that are illegal for groff (ie those with
       ASCII code 0 or between 013 and 037 octal or between  0200
       and 0237 octal) are rejected even in TeX mode.

       The interpretation of fillval is incompatible with the pic
       in 10th edition Unix, which interprets 0 as black and 1 as
       white.








































Groff Version 1.11      14 September 1996                       8