


GPIC(1)                                                   GPIC(1)


NNAAMMEE
       gpic - compile pictures for troff or TeX

SSYYNNOOPPSSIISS
       ggppiicc [ --nnvvCC ] [ _f_i_l_e_n_a_m_e ...  ]
       ggppiicc --tt [ --ccvvzzCC ] [ _f_i_l_e_n_a_m_e ...  ]

DDEESSCCRRIIPPTTIIOONN
       This manual page descibes the GNU version of ppiicc, which is
       part of the groff document formatting  system.   ppiicc  com-
       piles  descriptions  of  pictures embedded within ttrrooffff or
       TeX input files into commands that are understood  by  TeX
       or  ttrrooffff.  Each picture starts with a line beginning with
       ..PPSS and ends with a line  beginning  with  ..PPEE.   Anything
       outside of ..PPSS and ..PPEE is passed through without change.

       It  is  the  user's  responsibility to provide appropriate
       definitions of the PPSS and PPEE 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 --mmppiicc: these will center each picture.

OOPPTTIIOONNSS
       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C     Recognize ..PPSS and ..PPEE even when followed by a char-
              acter other than space or newline.

       --n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
              ggrrooffff__oouutt(5).  The --nn option also causes pic not to
              use zero-length lines to draw dots in troff mode.

       --tt     TeX mode.

       --cc     Be more compatible with ttppiicc.  Implies  --t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 ..ppss 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
              by use of the tthhiicckknneessss attribute or by setting the
              lliinneetthhiicckk variable.




Groff Version 1.08        9 August 1992                         1





GPIC(1)                                                   GPIC(1)


       --vv     Print the version number.

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

       The following options supported by other versions  of  ppiicc
       are ignored:

       --DD     Draw  all  lines using the \D escape sequence.  ppiicc
              always does this.

       --TT _d_e_v Generate output for the ttrrooffff device _d_e_v.  This  is
              unnecessary  because  the ttrrooffff output generated by
              ppiicc is device-independent.

UUSSAAGGEE
       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.

   TTeeXX mmooddee
       TeX mode is enabled by the --tt option.  In  TeX  mode,  pic
       will  define  a  vbox called \\ggrraapphh for each picture.  You
       must yourself print that vbox using, for example, the com-
       mand

              \\cceenntteerrlliinnee{{\\bbooxx\\ggrraapphh}}

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

              \\cceenntteerrlliinnee{{\\rraaiissee 11eemm\\bbooxx\\ggrraapphh}}

       would avoid this.

       You must use a TeX driver that supports the ttppiicc 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 \\bbaasseelliinneesskkiipp.  Anything else
       may well produce undesirable  results;  use  at  your  own
       risk.   Lines  beginning  with  a period are not given any
       special treatment.

   CCoommmmaannddss
       ffoorr _v_a_r_i_a_b_l_e == _e_x_p_r_1 ttoo _e_x_p_r_2 [bbyy [**]_e_x_p_r_3] ddoo _X _b_o_d_y _X
              Set _v_a_r_i_a_b_l_e to _e_x_p_r_1.  While the value of _v_a_r_i_a_b_l_e
              is  less than or equal to _e_x_p_r_2, do _b_o_d_y and incre-
              ment _v_a_r_i_a_b_l_e by _e_x_p_r_3; if bbyy is not given,  incre-
              ment _v_a_r_i_a_b_l_e by 1.  If _e_x_p_r_3 is prefixed by ** then
              _v_a_r_i_a_b_l_e will instead be multiplied  by  _e_x_p_r_3.   _X
              can be any character not occurring in _b_o_d_y.



Groff Version 1.08        9 August 1992                         2





GPIC(1)                                                   GPIC(1)


       iiff _e_x_p_r tthheenn _X _i_f_-_t_r_u_e _X [eellssee _Y _i_f_-_f_a_l_s_e _Y]
              Evaluate  _e_x_p_r;  if it is non-zero then do _i_f_-_t_r_u_e,
              otherwise do _i_f_-_f_a_l_s_e.  _X can be any character  not
              occurring  in  _i_f_-_t_r_u_e.  _Y can be any character not
              occurring in _i_f_-_f_a_l_s_e.

       pprriinntt _a_r_g...
              Concatenate the arguments and print as  a  line  on
              stderr.   Each  _a_r_g  must be an expression, a posi-
              tion, or text.  This is useful for debugging.

       ccoommmmaanndd _a_r_g...
              Concatenate the arguments and pass them through  as
              a line to troff orTeX.  Each _a_r_g 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.

       sshh _X _c_o_m_m_a_n_d _X
              Pass _c_o_m_m_a_n_d to a shell.  _X can  be  any  character
              not occurring in _c_o_m_m_a_n_d.

       ccooppyy ""_f_i_l_e_n_a_m_e""
              Include _f_i_l_e_n_a_m_e at this point in the file.

       ccooppyy [""_f_i_l_e_n_a_m_e""] tthhrruu _X _b_o_d_y _X [uunnttiill ""_w_o_r_d""]
       ccooppyy [""_f_i_l_e_n_a_m_e""] tthhrruu _m_a_c_r_o [uunnttiill ""_w_o_r_d""]
              This  construct  does  _b_o_d_y  once  for each line of
              _f_i_l_e_n_a_m_e; the line is  split  into  blank-delimited
              words, and occurrences of $$_i in _b_o_d_y, for _i between
              1 and 9, are replaced by the _i-th word of the line.
              If  _f_i_l_e_n_a_m_e is not given, lines are taken from the
              current input up to ..PPEE.  If  an  uunnttiill  clause  is
              specified, lines will be read only until a line the
              first word of which is _w_o_r_d; that line will then be
              discarded.  _X can be any character not occurring in
              _b_o_d_y.  For example,

                     ..PPSS
                     ccooppyy tthhrruu %% cciirrccllee aatt (($$11,,$$22)) %% uunnttiill ""EENNDD""
                     11 22
                     33 44
                     55 66
                     EENNDD
                     bbooxx
                     ..PPEE

              is equivalent to

                     ..PPSS
                     cciirrccllee aatt ((11,,22))
                     cciirrccllee aatt ((33,,44))
                     cciirrccllee aatt ((55,,66))
                     bbooxx



Groff Version 1.08        9 August 1992                         3





GPIC(1)                                                   GPIC(1)


                     ..PPEE

              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 tthhrruu.

       rreesseett
       rreesseett _v_a_r_i_a_b_l_e_1,, _v_a_r_i_a_b_l_e_2 _._._.
              Reset pre-defined  variables  _v_a_r_i_a_b_l_e_1,  _v_a_r_i_a_b_l_e_2
              ...  to  their default values.  If no arguments are
              given, reset all  pre-defined  variables  to  their
              default  values.   Note  that  assigning a value to
              ssccaallee also causes all  pre-defined  variables  that
              control  dimensions  to  be  reset to their default
              values times the new value of scale.

       pplloott _e_x_p_r [""_t_e_x_t""]
              This is a text object which is constructed by using
              _t_e_x_t  as  a format string for sprintf with an argu-
              ment of _e_x_p_r.  If _t_e_x_t is omitted a  format  string
              of  ""%%g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 sspprriinnttff.

       _v_a_r_i_a_b_l_e::==_e_x_p_r
              This  is  similar to == except _v_a_r_i_a_b_l_e must already
              be defined, and  the  value  of  _v_a_r_i_a_b_l_e  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

              {{ _a_n_y_t_h_i_n_g }}

       In  this case _a_n_y_t_h_i_n_g can contain balanced occurrences of
       {{ and }}.  Strings may contain _X or imbalanced  occurrences
       of {{ and }}.

   EExxpprreessssiioonnss
       The   syntax   for   expressions  has  been  significantly
       extended:

       _x ^^ _y (exponentiation)
       ssiinn((_x))
       ccooss((_x))



Groff Version 1.08        9 August 1992                         4





GPIC(1)                                                   GPIC(1)


       aattaann22((_y,, _x))
       lloogg((_x)) (base 10)
       eexxpp((_x)) (base 10, ie 10_x)
       ssqqrrtt((_x))
       iinntt((_x))
       rraanndd(()) (return a random number between 0 and 1)
       rraanndd((_x)) (return a random number between 1  and  _x;  depre-
       cated)
       mmaaxx((_e_1,, _e_2))
       mmiinn((_e_1,, _e_2))
       !!_e
       _e_1 &&&& _e_2
       _e_1 |||| _e_2
       _e_1 ==== _e_2
       _e_1 !!== _e_2
       _e_1 >>== _e_2
       _e_1 >> _e_2
       _e_1 <<== _e_2
       _e_1 << _e_2
       ""_s_t_r_1"" ==== ""_s_t_r_2""
       ""_s_t_r_1"" !!== ""_s_t_r_2""

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

   OOtthheerr CChhaannggeess
       A bare expression, _e_x_p_r, is acceptable as an attribute; it
       is equivalent to _d_i_r _e_x_p_r, where _d_i_r is the current direc-
       tion.  For example

              lliinnee 22ii

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

       The maximum width and height of the picture are taken from
       the variables mmaaxxppsswwiidd and mmaaxxppsshhtt.  Initially these  have
       values 8.5 and 11.

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

       Text attributes can be compounded.  For example,
              ""ffoooo"" aabboovvee lljjuusstt
       is legal.

       There  is  no  limit  to  the depth to which blocks can be
       examined.  For example,
              [[AA:: [[BB:: [[CC:: bbooxx ]]]]]] wwiitthh ..AA..BB..CC..ssww aatt 11,,22
              cciirrccllee aatt llaasstt [[]]..AA..BB..CC
       is acceptable.

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




Groff Version 1.08        9 August 1992                         5





GPIC(1)                                                   GPIC(1)


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

       Boxes can have rounded corners.  The rraadd attribute  speci-
       fies the radius of the quarter-circles at each corner.  If
       no rraadd or ddiiaamm attribute is given, a radius of  bbooxxrraadd  is
       used.   Initially,  bbooxxrraadd  has  a value of 0.  A box with
       rounded corners can be dotted or dashed.

       The ..PPSS 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 tteexxttwwiidd; 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 tteexxtthhtt.
       Initially tteexxttwwiidd and tteexxtthhtt have a value of 0.

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

              sspprriinnttff((""_f_o_r_m_a_t"",, _a_r_g,,...))

       can  also be used; this will produce the arguments format-
       ted according to _f_o_r_m_a_t,  which  should  be  a  string  as
       described in pprriinnttff(3) appropriate for the number of argu-
       ments supplied, using only the ee, ff, gg or %% format charac-
       ters.

       The  thickness  of  the lines used to draw objects is con-
       trolled by the lliinneetthhiicckk 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c
       option, this means use the line thickness specified by ..ppss
       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
       tthhiicckk[nneessss] attribute.  For example,

              cciirrccllee tthhiicckknneessss 11..55




Groff Version 1.08        9 August 1992                         6





GPIC(1)                                                   GPIC(1)


       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  ssccaallee variable, nor by the width or height
       given in the ..PPSS line.

       Boxes (including boxes with rounded corners), circles  and
       ellipses  can  be  filled  by  giving then an attribute of
       ffiillll[eedd].  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 ffiillllvvaall 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  aarrrroowwhheeaadd is non-zero and either TeX mode is enabled
       or the --xx option has been given.  Initially aarrrroowwhheeaadd  has
       a value of 1.

       The  troff  output  of  pic is device-independent.  The --T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 aalliiggnneedd  attribute.   This  will  only
       work when the postprocessor is ggrrooppss.  Any text associated
       with an  object  having  the  aalliiggnneedd  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 _ntthh is allowed ``_e_x_p_r''tthh is also allowed.
       Note that ''tthh is a  single  token:  no  space  is  allowed
       between the '' and the tthh.  For example,

              ffoorr ii == 11 ttoo 44 ddoo {{
                 line from `i'th box.nw to `i+1'th box.se
              }

FFIILLEESS
       //uu11//ggnnuu//lliibb//ggrrooffff//ttmmaacc//ttmmaacc..ppiicc
              Example definitions of the PPSS and PPEE macros.

SSEEEE AALLSSOO
       ggttrrooffff(1), ggrrooffff__oouutt(5), tteexx(1)



Groff Version 1.08        9 August 1992                         7





GPIC(1)                                                   GPIC(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'.)

BBUUGGSS
       Input characters that are illegal for ggrrooffff (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 ffiillllvvaall is incompatible with the pic
       in 10th edition Unix, which interprets 0 as black and 1 as
       white.










































Groff Version 1.08        9 August 1992                         8


