pic man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



PIC(1)							   PIC(1)

NAME
       pic - compile pictures for troff or TeX

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

Groff Version 1.15	   8 March 2000				1

PIC(1)							   PIC(1)

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

Groff Version 1.15	   8 March 2000				2

PIC(1)							   PIC(1)

       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.

       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

Groff Version 1.15	   8 March 2000				3

PIC(1)							   PIC(1)

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

Groff Version 1.15	   8 March 2000				4

PIC(1)							   PIC(1)

   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)
       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,

Groff Version 1.15	   8 March 2000				5

PIC(1)							   PIC(1)

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

Groff Version 1.15	   8 March 2000				6

PIC(1)							   PIC(1)

       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,

	      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
	      }

Groff Version 1.15	   8 March 2000				7

PIC(1)							   PIC(1)

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

SEE ALSO
       troff(1), groff_out(5), tex(1)
       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).

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.15	   8 March 2000				8

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net