## SYNOPSIS

           pic [ -nvCSU ] [ filename ...  ]
           pic -t [ -cvzCSU ] [ 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.
                  (enabled by default)

           -U     Unsafe mode; revert the default option -S.

           -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

           -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,  incre
                  ment 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.

                  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
                         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
                  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:

           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)
           srand(x) (set the random number seed)
           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
           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.

           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
           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
                  }

## CONVERSION

           To  obtain  a stand-alone picture from a pic file, enclose
           your pic code with .PS and .PE requests;  roff  configura
           tion  commands  may be added at the beginning of the file,
           but no roff text.
           groff itself does not provide direct conversion into other
           graphics  file  formats.  But there are lots of possibili
           ties if you first transform your picture into  PostScript®
           format  using  the  groff option -Tps.  Since this ps-file
           lacks BoundingBox information it is  not  very  useful  by
           itself,  but it may be fed into other conversion programs,
           usually named ps2other or pstoother or  the  like.   More
           over,  the  PostScript  interpreter  ghostscript  (gs) has
           built-in graphics conversion devices that are called  with
           the option

                  gs -sDEVICE=<devname>

           Call
                  gs --help

           for a list of the available devices.

           As  the Encapsulated PostScript File Format EPS is getting
           more  and  more  important,  and  the  conversion   wasn't
           regarded  trivial  in  the past you might be interested to
           know that there is a conversion tool  named  ps2eps  which
           does  the  right  job.   It  is  much better than the tool
           ps2epsi packaged with gs.

           For bitmapped graphic formats, you should use pstopnm; the
           resulting (intermediate) PNM file can be then converted to
           virtually any graphics  format  using  the  tools  of  the
           netpbm package .

## FILES

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

## SEE ALSO

           troff(1),    groff_out(5),   tex(1),   gs(1),   ps2eps(1),
           pstopnm(1), ps2epsi(1), pnm(5)

           Tpic: Pic for TeX

           Brian W. Kernighan, PIC -- A Graphics Language  for  Type
           setting  (User Manual).  AT&T Bell Laboratories, Computing
           Science  Technical  Report  No. 116   <URL:http://cm.bell-
           labs.com/cm/cs/cstr/116.ps.gz> (revised May, 1991).

           ps2eps is available from CTAN mirrors, e.g.
           <ftp://ftp.dante.de/tex-archive/support/ps2eps/>

           W. Richard Stevens - Turning PIC Into HTML
           <http://www.kohala.com/start/troff/pic2html.html>

           W. Richard Stevens - Examples of picMacros

    Groff Version 1.17.2       27 June 2001                    PIC(1)