# pic

## Name



           pic - compile pictures for _troff_ or TeX
    


## Synopsis



           **pic**[**-CnSU**] [_file_ ...]
    
           **pic -t**[**-cCSUz**] [_file_ ...]
    
           **pic --help**
    
           **pic -v**
    
           **pic --version**
    


## Description



           The GNU implementation of _pic_ is part of the _groff_(1) document
           formatting system.  _pic_ is a _troff_(1) preprocessor that translates
           descriptions of diagrammatic pictures embedded in _roff_(7) or TeX
           input into the language understood by TeX or _troff_.  It copies
           each _file_ 's contents to the standard output stream, except for
           lines between **.PS** and any of **.PE** , **.PF** , or **.PY** , which it interprets
           as picture descriptions.  End a _pic_ picture with **.PE** to leave the
           drawing position at the bottom of the picture, and with **.PF** or **.PY**
           to leave it at the top.  Normally, _pic_ is not executed directly by
           the user, but invoked by specifying the **-p** option to _groff_(1).  If
           no _file_ operands are present, or if _file_ is “**-** ”, _pic_ reads the
           standard input stream.
    
           It is the user's responsibility to provide appropriate definitions
           of the **PS** , **PE** , and one or both of the **PF** and **PY** macros.  When a
           macro package does not supply these, obtain simple definitions
           with the _groff_ option **-mpic** ; these horizontally center each
           picture.
    
           GNU _pic_ supports **PY** as a synonym of **PF** to work around a name space
           collision with the _mm_ macro package, which defines **PF** as a page
           footer management macro.  Use **PF** preferentially unless a similar
           problem faces your document.
    


## Options



           **--help** displays a usage message, while **-v** and **--version** show
           version information; all exit afterward.
    
           **-c** Be more compatible with _tpic_ ; implies **-t**.  Lines beginning
                  with **\** are not passed through transparently.  Lines
                  beginning with **.** are passed through with the initial **.**
                  changed to **\**.  GNU _pic_ gives a line beginning with **.ps**
                  special treatment: it takes an optional integer argument
                  specifying the line thickness (pen size) in milliinches, a
                  missing argument restores the previous line thickness, and
                  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 **thickness** attribute or by setting the **linethick**
                  variable.
    
           **-C** Recognize **.PS** , **.PE** , **.PF** , and **.PY** even when followed by a
                  character other than space or newline.
    
           **-n** Don't use _groff_ extensions to the _troff_ drawing commands.
                  Specify this option if a postprocessor you're using doesn't
                  support these extensions, described in _groff_out_(5).  This
                  option also causes _pic_ not to use zero-length lines to draw
                  dots in _troff_ mode.
    
           **-S** Operate in _safer mode;_ **sh** commands are ignored.  This mode,
                  enabled by default, can be useful when operating on
                  untrustworthy input.
    
           **-t** Produce TeX output.
    
           **-U** Operate in _unsafe mode;_ **sh** commands are interpreted.
    
           **-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.  GNU _pic_
                  always does this.
    
           **-T** _dev_ Generate output for the _troff_ device _dev_.  This option is
                  unnecessary in GNU _pic_ because the _troff_ it generates is
                  device-independent.
    


## Usage



           This section primarily discusses the differences between GNU _pic_
           and the Eighth Edition Unix version of AT&T _pic_ (1985).  Many of
           these differences also apply to later versions of AT&T _pic_.
    
       **TeX mode**
           TeX-compatible output is produced when the **-t** option is specified.
           You must use a TeX driver that supports _tpic_ version 2 specials.
           (_tpic_ was a fork of AT&T _pic_ by Tim Morgan of the University of
           California at Irvine that diverged from its source around 1984.
           It is best known today for lending its name to a group of **\special**
           commands it produced for TeX.)
    
           Lines beginning with **\** are passed through unaltered except for a **%**
           suffix to avoid unwanted spaces.  Use this feature to change fonts
           or the value of **\baselineskip**.  Other applications may produce
           undesirable results; use at your own risk.  By default, lines
           beginning with a dot are not treated specially—but see the **-c**
           option.
    
           In TeX mode, _pic_ defines a vbox called **\graph** for each picture.
           Use GNU _pic_ 's **figname** command to change the name of the vbox.  You
           must print that vbox yourself using the command
                  \centerline{\box\graph}
           for instance.  Since the vbox has a height of zero—it is defined
           with **\vtop** —this produces slightly more vertical space above the
           picture than below it;
                  \centerline{\raise 1em\box\graph}
           would avoid this.  To give the vbox a positive height and a depth
           of zero (as used by LaTeX's _graphics.sty_ , for example), define the
           following macro in your document.
                  \def\gpicbox#1{%
                    \vbox{\unvbox\csname #1\endcsname\kern 0pt}}
           You can then simply say **\gpicbox{graph}** instead of **\box\graph**.
    
       **Commands**
           Several commands new to GNU _pic_ accept delimiters, shown in their
           synopses as braces **{ }**.  Nesting of braces is supported.  Any
           other characters (except a space, tab, or newline) may be used as
           alternative delimiters, in which case the members of a given pair
           must be identical.  GNU _pic_ recognizes double-quoted strings
           within delimiters of either kind; such strings may contain the
           delimiter character or unbalanced braces.
    
           **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 increment _variable_ by
                  _expr3_ ; if **by** is not given, increment _variable_ by 1.  _expr3_
                  can be negative, in which case _variable_ is then tested
                  whether it is greater than or equal to _expr2_.  A ***** prefix
                  on _variable_ multiplies it by _expr3_ (which must be greater
                  than zero) at each iteration rather than incrementing it.
                  If the range constraint on _expr3_ isn't met, the loop does
                  not execute.  _X_ can be any character not 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 in _if-true_.  _Y_ can
                  be any character not in _if-false_.
    
           **print** _arg_ ...
                  Catenate and write arguments to the standard error stream
                  followed by a newline.  Each _arg_ must be an expression, a
                  position, or text.  This feature is useful for debugging.
    
           **command** _arg_ ...
                  Catenate arguments and pass them as a line to _troff_ or TeX.
                  Each _arg_ must be an expression, a position, or text.
                  **command** allows the values of _pic_ variables to be passed to
                  the formatter.  Thus,
                         .PS
                         x = 14
                         command ".ds string x is " x "."
                         .PE
                         \*[string]
                  produces
                         x is 14.
                  when formatted with _troff_.
    
           **sh** _X command X_
                  Pass _command_ to a shell via _system_(3).  Ignored if **-U**
                  option not specified.
    
           **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, GNU _pic_ reads lines only
                  until encountering one beginning with _word_ ; which it then
                  discards.  _X_ can be any character not in _body_.  For
                  example,
                         .PS
                         copy thru % circle at ($1,$2) % until "END"
                         1 2
                         3 4
                         5 6
                         END
                         box
                         .PE
                  and
                         .PS
                         circle at (1,2)
                         circle at (3,4)
                         circle at (5,6)
                         box
                         .PE
                  are equivalent.  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**.  The
                  argument after **thru** is looked up as a macro name first; if
                  not defined, its first character is interpreted as a
                  delimiter.
    
           **reset**
           **reset** _pvar1_[**,**] _pvar2_ ...
                  Reset predefined variables _pvar1_ , _pvar2_ ... to their
                  default values; if no arguments are given, reset all
                  predefined variables to their default values.  Variable
                  names may be separated by commas, spaces, or both.
                  Assigning a value to **scale** also causes all predefined
                  variables that control dimensions to be reset to their
                  default values times the new value of **scale**.
    
           **plot** _expr_ ["_text_ "]
                  Create a text object by using _text_ as a format string for
                  _sprintf_(3) with an argument of _expr_.  If _text_ is omitted,
                  **"%g"** is implied.  Attributes can be specified in the same
                  way as for a normal text object.  _Caution:_ be very careful
                  that you specify an appropriate format string in _text;_
                  _pic_ 's validation of it is limited.  **plot** is deprecated in
                  favour of **sprintf**.
    
           _var_ **:=**_expr_
                  Update an existing variable.  _var_ must already be defined,
                  and _expr_ is assigned to _var_ without creating a variable
                  local to the current block.  (By contrast, **=** defines _var_ in
                  the current block if it is not already defined there, and
                  then changes the value in the current block only.)  For
                  example,
                         **.PS**
                         **x = 3**
                         **y = 3**
                         **[**
                         **x := 5**
                         **y = 5**
                         **]**
                         **print x   y**
                         **.PE**
                  writes
                         5 3
                  to the standard error stream.
    
       **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, i.e. 10^_x_)
           **sqrt(**_x_**)**
           **int(**_x_**)**
           **rand()**(return a random number between 0 and 1)
           **rand(**_x_**)**(return a random number between 1 and _x_ ; deprecated)
           **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 direction.  For
           example, “**line 2i** ” draws a line 2 inches long in the current
           direction.  The ‘i’ (or ‘I’) character is ignored; to use another
           measurement unit, set the **scale** variable to an appropriate value.
    
           The maximum width and height of the picture are taken from the
           variables **maxpswid** and **maxpsht**.  Initially, these have values 8.5
           and 11, respectively.
    
           Scientific notation is allowed for numbers, as with “**x = 5e-2** ”.
    
           Text attributes can be compounded.  For example, “**"foo" above**
           **ljust** ” is valid.
    
           There is no limit to the depth to which blocks can be nested.  For
           example,
                  [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
                  circle at last [].A.B.C
           is acceptable.
    
           Arcs have compass points determined by the circle of which the arc
           is a part.
    
           Circles, ellipses, and arcs can be dotted or dashed.  In TeX mode,
           splines can be dotted or dashed as well.
    
           Boxes can have rounded corners.  The **rad** attribute specifies 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.
    
           Boxes can have slanted sides, generalizing them from rectangles to
           parallelograms.  The **xslanted** and **yslanted** attributes specify the
           _x_ and _y_ offsets of the box's upper right corner from its default
           position.
    
           The **.PS** line accepts a second argument specifying a maximum height
           for the picture.  If a width of zero is specified, it is ignored
           when computing the scaling factor for the picture.  GNU _pic_ always
           scales a picture by the same amount vertically and horizontally.
           This differs from DWB 2.0 _pic_ , which may change the picture's
           aspect ratio if a height is specified.
    
           Each text object has an associated invisible box that determines
           its compass points and implicit motion.  The dimensions of the box
           are taken from its width and height attributes.  If the width
           attribute is not supplied, the value of **textwid** is assumed.  If
           the height attribute is not supplied, the height defaults to the
           number of text strings associated with the object times **textht**.
           Initially, **textwid** and **textht** have values of 0.
    
           In (almost all) places where a quoted text string can be used, an
           expression of the form
    
                  **sprintf("**_format_**",**_arg_**,**...**)**
    
           can be used instead; it transforms its arguments per _format_ , which
           should be a string as described in _printf_(3), and appropriate to
           the quantity of arguments supplied.  GNU _pic_ supports only the
           conversion specifiers **e** , **E** , **f** , **g** , **G** , and **%** , modifiers “**#** ”, “**-** ”,
           “**+** ”, and “ ” [space]), a minimum field width, and an optional
           precision.
    
           The thickness of the lines used to draw objects is controlled by
           the **linethick** variable, which is measured in points.  A negative
           value indicates the default thickness.  In TeX output mode when
           the **-c** option is not given, this means 8 milliinches.  In _troff_
           and TeX **-c** output modes, the default thickness corresponds to the
           type size.  (Thus, if the type size is 10 points, a line is 10
           points thick.)  A **linethick** value of zero draws the thinnest
           possible line supported by the output device.  Initially,
           **linethick** has a value of -1.  A **thick**[**ness**] attribute is also
           available.  For example, “**circle thickness 1.5** ” draws a circle
           with a line 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 or slanted sides),
           circles, and ellipses can be filled by giving them an attribute of
           **fill**[**ed**], which takes an optional expression argument with a value
           between 0 and 1; 0 fills it with white, 1 with black, and values
           in between with a proportionally gray shade.  A value greater than
           1 is interpreted as the shade of gray that is being used for text
           and lines.  Normally this is black, but output devices may provide
           a mechanism for changing this.  Without an argument, the value of
           the variable **fillval** is used.  Initially, **fillval** has a value of
           0.5.  The **invisible** attribute does not affect the filling of
           objects.  Text associated with a filled object is added after the
           object is filled, so that the text is not obscured by the filling.
    
           Additional modifiers are available to draw colored objects:
           **outline**[**d**] sets the color of the outline, **shaded** the fill color,
           and **colo**[**u**]**r**[**ed**] sets both.  All expect a subsequent string
           argument specifying the color.
                  circle shaded "green" outline "black"
           Color is not yet supported in TeX mode.  Device macro files like
           _ps.tmac_ declare color names; you can define additional ones with
           the **defcolor** request (see _groff_(7)).  _pic_ assumes at the beginning
           of each picture that the stroke and fill colors are set to the
           device defaults.
    
           To change the name of the vbox in TeX mode, set the pseudo-
           variable **figname**(which is actually a specially parsed command)
           within a picture.  For example,
                  .PS
                  figname = foobar;
                  circle "dig here";
                  .PE
           makes the picture available in the box **\foobar**.
    
           Arrow heads are drawn as solid triangles if the variable **arrowhead**
           is non-zero and either TeX mode is enabled or the **-n** option is not
           used.  Initially, **arrowhead** has a value of 1.  Solid arrow heads
           are always filled with the current outline (stroke) color.
    
           The _troff_ output of _pic_ is device-independent.  The **-T** option is
           therefore redundant.  Except where noted, all measurements and
           dimensions use inches implicitly; they are never interpreted as
           _troff_ basic units.
    
           Objects can have an **aligned** attribute, but it is supported only by
           the _grops_(1) and _gropdf_(1) output drivers.  Any text associated
           with an **aligned** object is rotated about the object's center such
           that it is oriented along a line connecting the start and end
           points of the object.  **aligned** has no effect on objects whose
           start and end points are coincident.
    
           In places where _n_**th** is allowed, **`**_expr_**'th** is also allowed.  “**'th** ”
           is a single token: no space is allowed between the apostrophe and
           the “**th** ”.  Consider the following example.
    
                  for i = 1 to 4 do {
                     box
                     move right 0.5
                  }
                  for i = 1 to 3 do {
                     arrow from `i'th box.ne to `i+1'th box.sw
                  }
    
           Arbitrary polygons can be drawn using the **polygon** keyword followed
           by a series of _n_ -1 line segments, where _n_ is the number of edges
           of the polygon.  This allows GNU _troff_ to interpret the line
           segments as a complete object such that the **filled** and **shaded**
           attributes may be used.  The last user-specified line segment
           determines the polygon's final drawing position and direction.
           For example, draw and fill a triangle with the following.
    
                  polygon up 1 then right 1 down 0.5 fill 0.5
    
           Two reference point suffixes permit the positioning of drawing
           elements relative to a polygon.  “**.vertex** _expr_ ” locates the
           vertices, and “**.midpoint** _expr_ ” for locating the midpoints of
           edges.  GNU **pic** numbers vertices and midpoints in drawing order
           starting from **1 .** You can abbreviate **.vertex** as **.v** or **.ver** , and
           **.midpoint** as **.mid**.
    
           For example,
    
                  arrow down
                  polygon up 0.5 right 1 \
                  then down 0.5 right 1 \
                  then down 0.5 left 1 \
                  with .v2 at last line.end
                  arrow down from last polygon.v4
    
           creates and correctly places a flowchart decision diamond.
    
           **.center**(**.c**) is also available, but compass points do not work as
           expected and should not be used with polygons.
    
       **Converting _pic_ to other image formats**
           To create a stand-alone graphics file from a _pic_ file, first
           compose the picture.  Bracket your _pic_ code with **.PS** and **.PE**
           tokens.  _groff_ requests that don't produce formatted output may
           precede **.PS** , but format no text, not even any injected by a macro
           package, which may include a page number even on the first page,
           as _mm_ does by default.  Consider writing a “raw” _roff_ document
           that uses no macro package.
    
           Next, convert the _roff_ /_pic_ input into the desired format.  _groff_
           distributes a simple utility, _pic2graph_(1), for this purpose.
           Other possibilities exist, particularly if you first transform
           your picture into PostScript format with “**groff -T ps** ”.  However,
           such a PostScript file lacks bounding box information; _roff_
           formatters produce page-sized output.  Several tools with names
           beginning “psto” or “ps2” exist that can infer the bounding box
           and perform a format conversion.  One of these is the PostScript
           interpreter Ghostscript (_gs_(1)), which exposes format converters
           via its **-sDEVICE=** option.  “**gs --help** ” lists available devices.
    
           Alternatively, produce a PDF with “**groff -T pdf** ”; _gropdf_(1)'s **-p**
           option sets the MediaBox of the file.
    
           The Encapsulated PostScript File (EPS) format is still sometimes
           seen.  The aforementioned Ghostscript offers _ps2epsi_(1), and a
           standalone package and command _ps2eps_(1) is also available.
    
           For raster image formats, use _pstopnm_(1); the resulting _pnm_(5)
           file can be then converted to virtually any image format using the
           _netpbm_ tools.
    


## Exit status



           _pic_ exits with status **0** on successful operation, status **2** if the
           program cannot interpret its command-line arguments, and status **1**
           if it encounters an error during operation.
    


## Files



           _/usr/local/share/groff/1.23.0/tmac/pic.tmac_
                  offers simple definitions of the **PS** , **PE** , **PF** , and **PY** macros.
                  Load it with the **mso** request when eschewing a full-service
                  macro package, or using one that doesn't supply its own
                  definitions for them.
    


## Bugs



           Characters that are invalid as input to GNU _troff_ (see the _groff_
           Texinfo manual or _groff_char_(7) for a list) are rejected even in
           TeX mode.
    
           Research Tenth Edition Unix _pic_ 's **fillval** interprets 0 as black
           and 1 as white, incompatibly with GNU _pic_.
    


## See also



           _/usr/local/share/doc/groff-1.23.0/pic.ps_
                  “Making Pictures with GNU pic”, by Eric S. Raymond ⟨esr@
                  thyrsus.com⟩.  This file, together with its source, _pic.ms_ ,
                  is part of the _groff_ distribution.
    
           “PIC—A Graphics Language for Typesetting: User Manual”, by Brian
           W. Kernighan, 1984 (revised 1991), AT&T Bell Laboratories
           Computing Science Technical Report No. 116
    
           _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_ pic _Macros_ 
           ⟨http://www.kohala.com/start/troff/pic.examples.ps⟩
    
           _troff_(1), _groff_out_(5), _tex_(1), _gs_(1), _ps2eps_(1), _pstopnm_(1),
           _ps2epsi_(1), _pnm_(5)
    


* * *