1PIC(1)                      General Commands Manual                     PIC(1)
2
3
4

NAME

6       pic - compile pictures for troff or TeX
7

SYNOPSIS

9       pic [-nvCSU] [file ...]
10
11       pic -t [-cvzCSU] [file ...]
12

DESCRIPTION

14       This manual page describes the GNU version of pic, which is part of the
15       groff document formatting system.  pic compiles  descriptions  of  pic‐
16       tures  embedded  within troff or TeX input files into commands that are
17       understood by TeX or troff.  Each picture starts with a line  beginning
18       with  .PS and ends with a line beginning with .PE.  Anything outside of
19       .PS and .PE is passed through without change.
20
21       It is the user's responsibility to provide appropriate  definitions  of
22       the  PS and PE macros.  When the macro package being used does not sup‐
23       ply such definitions (for example, old versions  of  -ms),  appropriate
24       definitions can be obtained with -mpic: These will center each picture.
25

OPTIONS

27       Options  that  do  not take arguments may be grouped behind a single -.
28       The special option -- can be used to mark the end of  the  options.   A
29       filename of - refers to the standard input.
30
31       -C     Recognize  .PS  and  .PE even when followed by a character other
32              than space or newline.
33
34       -S     Safer mode; do not execute sh commands.  This can be useful when
35              operating on untrustworthy input (enabled by default).
36
37       -U     Unsafe mode; revert the default option -S.
38
39       -n     Don't  use  the  groff extensions to the troff drawing commands.
40              You should use this  if  you  are  using  a  postprocessor  that
41              doesn't  support these extensions.  The extensions are described
42              in groff_out(5).  The -n option also causes pic not to use zero-
43              length lines to draw dots in troff mode.
44
45       -t     TeX mode.
46
47       -c     Be more compatible with tpic.  Implies -t.  Lines beginning with
48              \ are not passed through transparently.  Lines beginning with  .
49              are passed through with the initial .  changed to \.  A line be‐
50              ginning with .ps is given special treatment:  it  takes  an  op‐
51              tional integer argument specifying the line thickness (pen size)
52              in milliinches; a missing argument restores  the  previous  line
53              thickness;  the  default  line  thickness is 8 milliinches.  The
54              line thickness thus specified takes effect only when a non-nega‐
55              tive  line thickness has not been specified by use of the thick‐
56              ness attribute or by setting the linethick variable.
57
58       -v     Print the version number.
59
60       -z     In TeX mode draw dots using zero-length lines.
61
62       The following options supported by other versions of pic are ignored:
63
64       -D     Draw all lines using the \D escape sequence.   pic  always  does
65              this.
66
67       -T dev Generate  output  for the troff device dev.  This is unnecessary
68              because the troff output generated by pic is device-independent.
69

USAGE

71       This section describes only the differences between  GNU  pic  and  the
72       original version of pic.  Many of these differences also apply to newer
73       versions of Unix pic.  A complete documentation  is  available  in  the
74       file
75
76              /usr/share/doc/groff/pic.ms
77
78   TeX mode
79       TeX  mode  is enabled by the -t option.  In TeX mode, pic will define a
80       vbox called \graph for each picture.  Use the figname command to change
81       the name of the vbox.  You must yourself print that vbox using, for ex‐
82       ample, the command
83
84              \centerline{\box\graph}
85
86       Actually, since the vbox has a height  of  zero  (it  is  defined  with
87       \vtop) this will produce slightly more vertical space above the picture
88       than below it;
89
90              \centerline{\raise 1em\box\graph}
91
92       would avoid this.
93
94       To make the vbox having a positive height and a depth of zero (as  used
95       e.g. by LaTeX's graphics.sty), define the following macro in your docu‐
96       ment:
97
98              \def\gpicbox#1{%
99                 \vbox{\unvbox\csname #1\endcsname\kern 0pt}}
100
101       Now you can simply say \gpicbox{graph} instead of \box\graph.
102
103       You must use a TeX driver that supports the tpic specials, version 2.
104
105       Lines beginning with \ are passed through transparently; a %  is  added
106       to  the  end  of the line to avoid unwanted spaces.  You can safely use
107       this feature to change fonts or to change the value  of  \baselineskip.
108       Anything  else  may  well  produce undesirable results; use at your own
109       risk.  Lines beginning with a period are not given any  special  treat‐
110       ment.
111
112   Commands
113       for variable = expr1 to expr2 [by [*]expr3] do X body X
114              Set variable to expr1.  While the value of variable is less than
115              or equal to expr2, do body and increment variable by  expr3;  if
116              by  is not given, increment variable by 1.  If expr3 is prefixed
117              by * then variable will instead be  multiplied  by  expr3.   The
118              value  of  expr3 can be negative for the additive case; variable
119              is then tested whether it is greater than  or  equal  to  expr2.
120              For  the  multiplicative  case, expr3 must be greater than zero.
121              If the constraints aren't met, the loop isn't executed.   X  can
122              be any character not occurring in body.
123
124       if expr then X if-true X [else Y if-false Y]
125              Evaluate  expr;  if it is non-zero then do if-true, otherwise do
126              if-false.  X can be any character not occurring in  if-true.   Y
127              can be any character not occurring in if-false.
128
129       print arg...
130              Concatenate  the  arguments and print as a line on stderr.  Each
131              arg must be an expression, a position, or text.  This is  useful
132              for debugging.
133
134       command arg...
135              Concatenate  the  arguments  and  pass them through as a line to
136              troff or TeX.  Each arg must be an expression,  a  position,  or
137              text.   This  has a similar effect to a line beginning with . or
138              \, but allows the values of variables to be passed through.  For
139              example,
140
141                     .PS
142                     x = 14
143                     command ".ds string x is " x "."
144                     .PE
145                     \*[string]
146
147              prints
148
149                     x is 14.
150
151       sh X command X
152              Pass  command  to a shell.  X can be any character not occurring
153              in command.
154
155       copy "filename"
156              Include filename at this point in the file.
157
158       copy ["filename"] thru X body X [until "word"]
159       copy ["filename"] thru macro [until "word"]
160              This construct does body once for each  line  of  filename;  the
161              line  is split into blank-delimited words, and occurrences of $i
162              in body, for i between 1 and 9, are replaced by the i-th word of
163              the  line.   If  filename is not given, lines are taken from the
164              current input up to .PE.  If an until clause is specified, lines
165              will  be read only until a line the first word of which is word;
166              that line will then be discarded.  X can be  any  character  not
167              occurring in body.  For example,
168
169                     .PS
170                     copy thru % circle at ($1,$2) % until "END"
171                     1 2
172                     3 4
173                     5 6
174                     END
175                     box
176                     .PE
177
178              is equivalent to
179
180                     .PS
181                     circle at (1,2)
182                     circle at (3,4)
183                     circle at (5,6)
184                     box
185                     .PE
186
187              The  commands  to  be  performed for each line can also be taken
188              from a macro defined earlier by giving the name of the macro  as
189              the argument to thru.
190
191       reset
192       reset variable1[,] variable2 ...
193              Reset  pre-defined  variables  variable1, variable2 ... to their
194              default values.  If no arguments are given,  reset  all  pre-de‐
195              fined  variables to their default values.  Note that assigning a
196              value to scale also causes all pre-defined variables  that  con‐
197              trol  dimensions  to  be reset to their default values times the
198              new value of scale.
199
200       plot expr ["text"]
201              This is a text object which is constructed by using  text  as  a
202              format  string for sprintf with an argument of expr.  If text is
203              omitted a format string of "%g"  is  used.   Attributes  can  be
204              specified  in the same way as for a normal text object.  Be very
205              careful that you specify an appropriate format string; pic  does
206              only very limited checking of the string.  This is deprecated in
207              favour of sprintf.
208
209       variable := expr
210              This is similar to = except variable must  already  be  defined,
211              and  expr  will be assigned to variable without creating a vari‐
212              able local to the current block.  (By contrast,  =  defines  the
213              variable  in  the  current  block  if  it is not already defined
214              there, and then changes the value in the  current  block  only.)
215              For example, the following:
216
217                     .PS
218                     x = 3
219                     y = 3
220                     [
221                       x := 5
222                       y = 5
223                     ]
224                     print x " " y
225                     .PE
226
227              prints
228
229                     5 3
230
231       Arguments of the form
232
233              X anything X
234
235       are also allowed to be of the form
236
237              { anything }
238
239       In  this  case  anything  can  contain balanced occurrences of { and }.
240       Strings may contain X or imbalanced occurrences of { and }.
241
242   Expressions
243       The syntax for expressions has been significantly extended:
244
245       x ^ y (exponentiation)
246       sin(x)
247       cos(x)
248       atan2(y, x)
249       log(x) (base 10)
250       exp(x) (base 10, i.e. 10^x)
251       sqrt(x)
252       int(x)
253       rand() (return a random number between 0 and 1)
254       rand(x) (return a random number between 1 and x; deprecated)
255       srand(x) (set the random number seed)
256       max(e1, e2)
257       min(e1, e2)
258       !e
259       e1 && e2
260       e1 || e2
261       e1 == e2
262       e1 != e2
263       e1 >= e2
264       e1 > e2
265       e1 <= e2
266       e1 < e2
267       "str1" == "str2"
268       "str1" != "str2"
269
270       String comparison expressions must be parenthesised in some contexts to
271       avoid ambiguity.
272
273   Other Changes
274       A  bare  expression, expr, is acceptable as an attribute; it is equiva‐
275       lent to dir expr, where dir is the current direction.  For example
276
277              line 2i
278
279       means draw a line 2 inches long in the current direction.  The ‘i’  (or
280       ‘I’)  character  is  ignored;  to use another measurement unit, set the
281       scale variable to an appropriate value.
282
283       The maximum width and height of the picture are taken  from  the  vari‐
284       ables maxpswid and maxpsht.  Initially these have values 8.5 and 11.
285
286       Scientific notation is allowed for numbers.  For example
287
288              x = 5e-2
289
290       Text attributes can be compounded.  For example,
291
292              "foo" above ljust
293
294       is valid.
295
296       There  is  no  limit to the depth to which blocks can be examined.  For
297       example,
298
299              [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
300              circle at last [].A.B.C
301
302       is acceptable.
303
304       Arcs now have compass points determined by the circle of which the  arc
305       is a part.
306
307       Circles,  ellipses,  and  arcs  can  be  dotted or dashed.  In TeX mode
308       splines can be dotted or dashed also.
309
310       Boxes can have rounded corners.  The rad attribute specifies the radius
311       of  the quarter-circles at each corner.  If no rad or diam attribute is
312       given, a radius of boxrad is used.  Initially, boxrad has a value of 0.
313       A box with rounded corners can be dotted or dashed.
314
315       Boxes  can have slanted sides.  This effectively changes the shape of a
316       box from a rectangle to an arbitrary parallelogram.  The  xslanted  and
317       yslanted attributes specify the x and y offset of the box's upper right
318       corner from its default position.
319
320       The .PS line can have a second argument specifying a maximum height for
321       the  picture.   If the width of zero is specified the width will be ig‐
322       nored in computing the scaling factor for the picture.  Note  that  GNU
323       pic  will  always scale a picture by the same amount vertically as well
324       as horizontally.  This is different from the  DWB  2.0  pic  which  may
325       scale a picture by a different amount vertically than horizontally if a
326       height is specified.
327
328       Each text object has an invisible box associated with it.  The  compass
329       points  of  a text object are determined by this box.  The implicit mo‐
330       tion associated with the object is also determined by  this  box.   The
331       dimensions  of this box are taken from the width and height attributes;
332       if the width attribute is not supplied then the width will be taken  to
333       be  textwid;  if  the  height attribute is not supplied then the height
334       will be taken to be the number of text strings associated with the  ob‐
335       ject times textht.  Initially textwid and textht have a value of 0.
336
337       In  (almost  all) places where a quoted text string can be used, an ex‐
338       pression of the form
339
340              sprintf("format", arg,...)
341
342       can also be used; this will produce the arguments  formatted  according
343       to format, which should be a string as described in printf(3) appropri‐
344       ate for the number of arguments supplied.
345
346       The thickness of the lines used to draw objects is  controlled  by  the
347       linethick  variable.   This  gives the thickness of lines in points.  A
348       negative value means use the default thickness:  in  TeX  output  mode,
349       this  means  use  a thickness of 8 milliinches; in TeX output mode with
350       the -c option, this means use  the  line  thickness  specified  by  .ps
351       lines; in troff output mode, this means use a thickness proportional to
352       the pointsize.  A zero value means draw the thinnest possible line sup‐
353       ported by the output device.  Initially it has a value of -1.  There is
354       also a thick[ness] attribute.  For example,
355
356              circle thickness 1.5
357
358       would draw a circle using a line with a thickness of 1.5  points.   The
359       thickness  of lines is not affected by the value of the scale variable,
360       nor by the width or height given in the .PS line.
361
362       Boxes (including boxes with rounded corners or slanted sides),  circles
363       and  ellipses  can  be  filled by giving them an attribute of fill[ed].
364       This takes an optional argument of an expression with a value between 0
365       and  1; 0 will fill it with white, 1 with black, values in between with
366       a proportionally gray shade.  A value greater than 1 can also be  used:
367       this means fill with the shade of gray that is currently being used for
368       text and lines.  Normally this will be black, but  output  devices  may
369       provide  a  mechanism for changing this.  Without an argument, then the
370       value of the variable fillval will be used.  Initially this has a value
371       of  0.5.   The  invisible  attribute does not affect the filling of ob‐
372       jects.  Any text associated with a filled object will  be  added  after
373       the  object  has  been filled, so that the text will not be obscured by
374       the filling.
375
376       Three additional modifiers are available to  specify  colored  objects:
377       outline[d]  sets  the  color of the outline, shaded the fill color, and
378       colo[u]r[ed] sets both.  All three keywords expect a suffix  specifying
379       the color, for example
380
381              circle shaded "green" outline "black"
382
383       Currently, color support isn't available in TeX mode.  Predefined color
384       names for groff are in the device macro files, for example ps.tmac; ad‐
385       ditional colors can be defined with the .defcolor request (see the man‐
386       ual page of troff(1) for more details).
387
388       To change the name of the vbox in TeX  mode,  set  the  pseudo-variable
389       figname  (which  is  actually a specially parsed command) within a pic‐
390       ture.  Example:
391
392              .PS
393              figname = foobar;
394              ...
395              .PE
396
397       The picture is then available in the box \foobar.
398
399       pic assumes that at the beginning of a  picture  both  glyph  and  fill
400       color are set to the default value.
401
402       Arrow  heads will be drawn as solid triangles if the variable arrowhead
403       is non-zero and either TeX mode is enabled or the  -n  option  has  not
404       been given.  Initially arrowhead has a value of 1.  Note that solid ar‐
405       row heads are always filled with the current outline color.
406
407       The troff output of pic is device-independent.  The -T option is there‐
408       fore  redundant.   All  numbers  are taken to be in inches; numbers are
409       never interpreted to be in troff machine units.
410
411       Objects can have an aligned attribute.  This  will  only  work  if  the
412       postprocessor  is grops, or gropdf.  Any text associated with an object
413       having the aligned attribute will be rotated about the  center  of  the
414       object  so  that it is aligned in the direction from the start point to
415       the end point of the object.  Note that this attribute will have no ef‐
416       fect for objects whose start and end points are coincident.
417
418       In places where nth is allowed expr’th is also allowed.  Note that ’th
419       is a single token: no space is allowed between the and the  th.   For
420       example,
421
422              for i = 1 to 4 do {
423                 line from ‘i’th box.nw to ‘i+1’th box.se
424              }
425

CONVERSION

427       To  obtain a stand-alone picture from a pic file, enclose your pic code
428       with .PS and .PE requests; roff configuration commands may be added  at
429       the beginning of the file, but no roff text.
430
431       It  is  necessary  to feed this file into groff without adding any page
432       information, so you must check which .PS and .PE requests are  actually
433       called.  For example, the mm macro package adds a page number, which is
434       very annoying.  At the moment, calling standard groff without any macro
435       package  works.   Alternatively, you can define your own requests, e.g.
436       to do nothing:
437
438              .de PS
439              ..
440              .de PE
441              ..
442
443       groff itself does not provide direct  conversion  into  other  graphics
444       file  formats.  But there are lots of possibilities if you first trans‐
445       form your picture into PostScript® format using the groff option  -Tps.
446       Since  this ps-file lacks BoundingBox information it is not very useful
447       by itself, but it may be fed into other  conversion  programs,  usually
448       named  ps2other or pstoother or the like.  Moreover, the PostScript in‐
449       terpreter ghostscript (gs) has  built-in  graphics  conversion  devices
450       that are called with the option
451
452              gs -sDEVICE=<devname>
453
454       Call
455
456              gs --help
457
458       for a list of the available devices.
459
460       An  alternative  may be to use the -Tpdf option to convert your picture
461       directly into PDF format.  The MediaBox of the  file  produced  can  be
462       controlled by passing a -P-p papersize to groff.
463
464       As the Encapsulated PostScript File Format EPS is getting more and more
465       important, and the conversion wasn't regarded trivial in the  past  you
466       might  be  interested  to  know  that  there is a conversion tool named
467       ps2eps which does the right job.  It  is  much  better  than  the  tool
468       ps2epsi packaged with gs.
469
470       For  bitmapped  graphic  formats, you should use pstopnm; the resulting
471       (intermediate) PNM file can be then converted to virtually any graphics
472       format using the tools of the netpbm package.
473

FILES

475       /usr/share/groff/1.22.4/tmac/pic.tmac
476              Example definitions of the PS and PE macros.
477

SEE ALSO

479       troff(1),   groff_out(5),   tex(1),   gs(1),   ps2eps(1),   pstopnm(1),
480       ps2epsi(1), pnm(5)
481
482       Eric S. Raymond, Making Pictures With GNU PIC.
483       /usr/share/doc/groff/pic.ps (this file, together with its source  file,
484       pic.ms, is part of the groff documentation)
485
486       Tpic: Pic for TeX
487
488       Brian  W.  Kernighan,  PIC   A Graphics Language for Typesetting (User
489       Manual)http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz⟩.  AT&T Bell Lab‐
490       oratories,  Computing  Science  Technical  Report No. 116 (revised May,
491       1991).
492
493       ps2eps  is  available  from  CTAN  mirrors,  e.g.  ⟨ftp://ftp.dante.de/
494       tex-archive/support/ps2eps/⟩
495
496       W. Richard Stevens, Turning PIC into HTMLhttp://www.kohala.com/start/
497       troff/pic2html.html⟩
498
499       W. Richard Stevens,  Examples  of  pic  Macroshttp://www.kohala.com/
500       start/troff/pic.examples.ps⟩
501

BUGS

503       Input  characters  that  are  invalid for groff (i.e., those with ASCII
504       code 0, or 013 octal, or between 015 and 037 octal, or between 0200 and
505       0237 octal) are rejected even in TeX mode.
506
507       The interpretation of fillval is incompatible with the pic in 10th edi‐
508       tion Unix, which interprets 0 as black and 1 as white.
509
510       PostScript® is a registered trademark of Adobe Systems Incorporation.
511
512
513
514groff 1.22.4                    19 January 2023                         PIC(1)
Impressum