pic(1) - f39

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

Name

6       pic - compile pictures for troff or TeX
7

Synopsis

9       pic [-CnSU] [file ...]
10
11       pic -t [-cCSUz] [file ...]
12
13       pic --help
14
15       pic -v
16       pic --version
17

Description

19       The  GNU implementation of pic is part of the groff(1) document format‐
20       ting system.  pic is a troff(1) preprocessor that  translates  descrip‐
21       tions  of  diagrammatic pictures embedded in roff(7) or TeX input files
22       into the language understood by TeX or troff.  It copies  the  contents
23       of  each  file to the standard output stream, except that lines between
24       .PS and any of .PE, .PF, or .PY are interpreted as picture descriptions
25       in  the  pic language.  End a pic picture with .PE to leave the drawing
26       position at the bottom of the picture, and with .PF or .PY to leave  it
27       at  the  top.   Normally, pic is not executed directly by the user, but
28       invoked by specifying the -p option to groff(1).  If no  file  operands
29       are  given  on  the command line, or if file is “-”, the standard input
30       stream is read.
31
32       It is the user's responsibility to provide appropriate  definitions  of
33       the  PS,  PE,  and  one  or both of the PF and PY macros.  When a macro
34       package does not supply these, obtain simple definitions with the groff
35       option -mpic; these will center each picture.
36
37       GNU pic supports PY as a synonym of PF to work around a name space col‐
38       lision with the mm macro package, which defines PF  as  a  page  footer
39       management macro.  Use PF preferentially unless a similar problem faces
40       your document.
41

Options

43       --help displays a usage message, while -v and  --version  show  version
44       information; all exit afterward.
45
46       -c     Be  more compatible with tpic; implies -t.  Lines beginning with
47              \ are not passed through transparently.  Lines beginning with  .
48              are  passed through with the initial . changed to \.  A line be‐
49              ginning with .ps is given special treatment:  it  takes  an  op‐
50              tional integer argument specifying the line thickness (pen size)
51              in milliinches; a missing argument restores  the  previous  line
52              thickness;  the  default  line  thickness is 8 milliinches.  The
53              line thickness thus specified takes effect only when a non-nega‐
54              tive  line  thickness  has  not  been  specified  by  use of the
55              thickness attribute or by setting the linethick variable.
56
57       -C     Recognize .PS, .PE, .PF, and .PY even when followed by a charac‐
58              ter other than space or newline.
59
60       -n     Don't use groff extensions to the troff drawing commands.  Spec‐
61              ify this option if a postprocessor you're using doesn't  support
62              these  extensions,  described in groff_out(5).  This option also
63              causes pic not to use zero-length lines to draw  dots  in  troff
64              mode.
65
66       -S     Operate  in safer mode; sh commands are ignored.  This mode, en‐
67              abled by default, can be useful when operating on  untrustworthy
68              input.
69
70       -t     Produce TeX output.
71
72       -U     Operate in unsafe mode; sh commands are interpreted.
73
74       -z     In TeX mode, draw dots using zero-length lines.
75
76       The following options supported by other versions of pic are ignored.
77
78       -D     Draw  all  lines  using  the \D escape sequence.  GNU pic always
79              does this.
80
81       -T dev Generate output for the troff device dev.  This  is  unnecessary
82              because the troff output generated by GNU pic is device-indepen‐
83              dent.
84

Usage

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

Conversion

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

Files

470       /usr/share/groff/1.23.0/tmac/pic.tmac
471              offers simple definitions of the PS, PE, PF, and PY macros.
472

Bugs

474       Characters  that  are invalid as input to GNU troff (see the groff Tex‐
475       info manual or groff_char(7) for a list) are rejected even in TeX mode.
476
477       The interpretation of fillval is incompatible with  the  pic  in  Tenth
478       Edition Research Unix, which interprets 0 as black and 1 as white.
479