pic(1) — Linux manual page

Name | Synopsis | Description | Options | Usage | Files | Bugs | See also | COLOPHON

pic(1)                   General Commands Manual                  pic(1)

Name         top

       pic - compile pictures for troff or TeX

Synopsis         top

       pic [-CnSU] [file ...]

       pic -t [-cCSUz] [file ...]

       pic --help

       pic -v

       pic --version

Description         top

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

       --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 \.  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
              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 is
              unnecessary because the troff output generated by GNU pic
              is device-independent.

Usage         top

       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 will define 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 will produce 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.  Strings are recognized within delimiters of
       either kind; they 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 will 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 ...
              Concatenate 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 ...
              Concatenate 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.

       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 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 will be 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 will
       be ignored when computing the scaling factor for the picture.
       GNU pic will always scale a picture by the same amount vertically
       as well as horizontally.  This is different from DWB 2.0 pic,
       which may scale a picture by a different amount vertically than
       horizontally 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 will default 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; this will produce the arguments per the
       format, which should be a string as described in printf(3), and
       appropriate to the quantity of arguments supplied.  Only the
       modifiers “#”, “-”, “+”, and “ ” [space]), a minimum field width,
       an optional precision, and the conversion specifiers %e, %E, %f,
       %g, %G, and %% are supported.

       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 will fill it with white, 1 with black,
       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 will be 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 nth is allowed, 'expr'th is also allowed.  “'th“
       is a single token: no space is allowed between the apostrophe and
       the “th”.  For example,

              for i = 1 to 4 do {
                 line from 'i'th box.nw to 'i+1'th box.se
              }

   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 no text should be formatted.  That restriction
       applies to the injection of text by macro packages, which may
       include a page number even on the first page, as mm does by
       default.  Writing a “raw” roff document that uses no macro
       package is an economical approach.

       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 will lack 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 will set 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.

Files         top

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

       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.

       The interpretation of fillval is incompatible with the pic in
       Research Tenth Edition Unix, which interprets 0 as black and 1 as
       white.

See also         top

       /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 HTMLhttp://www.kohala.com/start/troff/pic2html.html⟩

       W. Richard Stevens, Examples of pic Macroshttp://www.kohala.com/start/troff/pic.examples.pstroff(1), groff_out(5), tex(1), gs(1), ps2eps(1), pstopnm(1),
       ps2epsi(1), pnm(5)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨http://www.gnu.org/software/groff/⟩.  If you have a bug report
       for this manual page, see ⟨http://www.gnu.org/software/groff/⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-10.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

groff 1.23.0.1273-9d53-dirty   6 June 2024                        pic(1)