Provided by: dpic_2023.06.01-1_amd64 bug

NAME

       dpic ‐ convert pic‐language input to LaTeX‐compatible and other formats

SYNOPSIS

       dpic [ -defghmprstvx ] [ -z ] [ infile ] [> outfile ]

       Typically, infile is of the form name [.pic] and outfile is of
       the form name .[tex|eps|pdf|fig|mp|svg]

OPTIONS

       (none) LaTeX picture-environment output (very limited font‐based drawing commands)
       -d PDF output, basic strings
       -e pict2e output
       -f Postscript output, strings in psfrag format
       -g TikZ‐pgf output
       -h write help message and quit
       -m mfpic output (see mfpic documentation)
       -p PSTricks output
       -r raw Postscript output, no automatic string formatting
       -s MetaPost output
       -t eepicemu output (slightly less limited than LaTeX picture output)
       -v svg output
       -x xfig 3.2 output
       -z safe mode (access to external files disabled)

DESCRIPTION

       Dpic  accepts  a  tight  subset of the pic drawing language accepted by GNU pic (sometimes
       named gpic) or AT&T pic, and emits lower‐level drawing commands for insertion  into  LaTeX
       documents,  for processing by the xfig or Inkscape drawing tools, or for direct display as
       encapsulated Postscript, PDF, or SVG. LaTeX-compatible output can contain  arbitrary  text
       for  formatting.   Commands to be passed through to the postprocessor (PSTricks, Tikz‐pgf,
       etc.)  can be included.  Dpic returns EXIT_SUCCESS (normally 0) if messages no more severe
       than warnings were generated, otherwise EXIT_FAILURE (normally 1).

       A few pic-language extensions unique to dpic are implemented for specific purposes.

LANGUAGE SUMMARY

       Input consists of a sequence of ASCII text lines.  The characters LF (\n) and CR (\r) have
       identical effect, and ETX (\003) is reserved for internal  use.   Characters  outside  the
       range of 0 to 127 are allowed in strings but receive no special treatment.

       The  first  line  of  a  picture  is .PS and the last is .PE, with lines between these two
       converted into low‐level drawing commands for the  postprocessor  chosen  by  the  option.
       Lines outside of .PS ... .PE pass through dpic unchanged.

   Coordinates
       Coordinate  axes  in  the  pic  language point to the right and up.  The drawing units are
       inches by default but the statement

         scale = 25.4

       at the beginning of the diagram has the effect of changing the units to millimetres.

   Drawn objects
       The primitive drawn objects consist of the planar objects box, circle, ellipse; the linear
       objects  line,  arrow, move, spline; and arc, which has characteristics of both planar and
       linear objects.  A block is a pair of square brackets enclosing other objects: [  anything
       ] and is a planar object.  The complete diagram is contained implicitly in a block.

       A  string is a planar object similar to a box, but the pic language also allows strings to
       be attached to other objects as overlays, in which case they are part of the object.

       The current drawing position Here is always defined.  Initially and at the beginning of  a
       block, Here is 0,0.  Similarly, the current direction, which can be any of up, down, left,
       right, is set as right initially.

       Each drawn object has an entry point and exit point that depend on the current  direction.
       The  entry point is placed by default at the current position.  Objects can also be placed
       explicitly with respect to absolute coordinates or relative to other  objects.   The  exit
       point becomes the new current position.

   Labels
       A  label  in  pic  is  an  alphameric sequence that starts with an uppercase letter.  Dpic
       allows variables and labels to be subscripted; thus T and T[5] are distinct  labels.   The
       value  in  brackets  can  be any expression, comma-separated expression pair, or a defined
       position, but expressions are rounded to the nearest  integer  value.   A  label  gives  a
       symbolic name to a position or drawn object; for example,

          Post: Here + (1,2)
          Bus[23]: line right 4

   Defined points
       Once  drawn,  a  linear  object has defined points .start, .center, and .end, which can be
       referenced as known positions, for example,

          L: line; line up 0.5 from L.c

       where .center has been abbreviated as .c

       The defined points for a planar object are the compass points on its  periphery  given  by
       .n,  .s,  .e, .w, .nw, .ne, .se, .sw, together with .center, .top, .bottom, .right, .left.
       For an arc, these points correspond to the circle of which the arc is  a  part,  with  the
       addition of .start and .end.

       A  block  has  defined  points similar to a box, but can also have others in its interior.
       For the example

          A: [ circle; Q: [ line; circle ]; T: Q.n ]

       the defined points are as follows:

          The points of the outer block as if it were a box, for
          example, A.ne

          A position defined in the block, for example, A.T

          The defined points of labeled objects inside the block,
          preceded by a dot, for example, A.Q (the centre of
          block Q), or A.Q.ne (the northeast point of Q).

          The defined points of enumerated objects inside the
          block, preceded by a dot (but make sure there is a space
          after the dot if it is followed by a number rather than
          an expression in braces), for example, A.Q. 1st circle.n
          or (better) A.Q.{1}st circle.n

   Language elements
       The lines defining a picture are separated by newline characters or semicolons.   Newlines
       are significant except after then, ;, :, {, else, or newline.

       A line is continued to the next if the rightmost character is a backslash.

       Non-continuation lines beginning with a period are ignored, except for .PS and .PE lines.

       The  pic  source  may  be  commented by placing each comment to the right of a # character
       (unless the # is in a string).

       The language elements include the following:

          A drawing command with optional label, for example, box or A: box

          A position‐label definition, for example A: position

          An assignment to a variable, for example x = 5

          A direction (to change the default), for example, up

       Branching is performed by

          if expr then { dotrue } else { dofalse }.

       The looping facility is

          for variable = expr to expr [by [*] incr ] do { anything }.

       The loop variable is incremented by 1 by default,  otherwise  by  incr  (which  may  be  a
       negative  expression)  unless  it  is  preceded  by  the  asterisk, in which case the loop
       variable is multiplied by incr.  The loop variable may be changed  by  statements  in  the
       loop, thereby controlling the number of loop repetitions.

       Braces occur in several contexts.  When used independently of other language elements, as

          { anything }

       the left brace saves the current position and direction, and the right brace restores them
       to the saved values after the enclosed lines have been processed.

       Arbitrary postprocessor commands can be generated using

          command string,

       which inserts the contents of string  into  the  output.   The  string  contents  must  be
       compatible  with  the  chosen  postprocessor.   Similarly,  any  line  that  begins with a
       backslash is copied literally to the output.

       The line

          exec string

       executes the contents of string as if it were a normal input line.

       To execute operating-system shell commands, use

          sh string

       and to read lines from an external file, use

          copy string

       These commands are disabled by the dpic option -z or by a compile‐time switch.

       The command

          print expr|position|string [ > string | >> string ]

       prints or appends its argument to the file named in the string on the right, or by default
       to the standard error.  Printing to a file is disabled by the -z option.

   Macros
       The pic language includes macro definition and expansion, using either

          define name { anything },

       or

          define name X anything X,

       where  X  is  any  character  except  {.  When  name  appears  alone  or with arguments in
       parentheses as name(arg, ...)  then it is replaced by the contents between the  delimiters
       in  the  macro  definition.   Arguments  are separated by commas except that a comma in an
       argument is ignored within a string, parentheses,  or  brackets.   In  this  substitution,
       occurrences of $1 are replaced literally by the first argument (not by its value, if any),
       and so on for other arguments.

       The value $+ in a macro is the number of arguments given to the macro.  dpic ignores white
       space (spaces, new lines, and tab characters) that directly precede an argument in a macro
       invocation.  A macro definition can be deleted by

          undefine name

       Macro definitions are global, which may require judicious undefinition of macros if  there
       is a risk of name clashes.

   Drawing commands
       An object is drawn using the following general format:

        [ Label :] object [ attributes ] [ placement ] [ strings ]

       The  items following object can occur in any order, but the order can make a difference to
       the drawn result, since lines are read and interpreted from left to right.   Defaults  are
       assumed for all drawing parameters as necessary.  For example, the sequence

          circle "Chew"; arrow; box "Swallow"
          line; arc cw ->; ellipse "Digest"

       draws  a  simple  flow diagram using default sizes for all objects, with centered words in
       the circle, box, and ellipse.

   Attributes
       An attribute is a keyword or keywords followed by expressions as appropriate.   Attributes
       are used to set parameters that control the placement, size, and appearance of objects.

       The dimension attributes are the following, showing valid abbreviations:

          height|ht|width|wid|radius|rad|diameter|diam|scaled expr

       When  appended  to  linear  objects,  height and width apply to arrowhead dimensions.  The
       scaled attribute scales the object by expr.

       The postprocessed size of a string is unknown in advance to the pic  processor,  but  once
       known, the bounding box dimensions can be specified explicitly as for other drawn objects,
       as shown:

          string wid expr ht expr

       The thickness of lines defining an object are  modified  using  the  environment  variable
       linethick or the attribute

          thickness|thick expr

       expressed in points.  Line thickness is independent of any scaling.

       Solid lines are drawn by default; this can be modified with

          solid|invisible|invis

       or with

          dotted|dashed [ expr ]

       the  optional  expression  in the latter setting the length and distance between dashes or
       dots.

       The following attributes are for putting arrowheads at the start, end, or both ends  of  a
       linear object:

          <-|->|<-> [ expr ]

       The  default  for  arrow objects is ->.  The shape parameter expr may be omitted, in which
       case the value of the environment variable arrowhead is used.  The accepted values of expr
       are currently 0, 1, and 3, with 1 the default.

       The drawing direction of an arc is changed by the attribute

          ccw|cw

       with ccw the default.

       To fill an object with a shade of gray, use the attribute

          fill [ expr ]

       where  the  value  of  expr can vary from 1, meaning white, to 0, meaning black.  A linear
       object defining a path can be filled where the postprocessor allows, currently for  MFpic,
       MPost, PDF, PGF, PS, PSfrag, PSTricks, and SVG output.

       Line color can be set using

          outline|outlined string

       The pic language knows no details about color; the string contents must be compatible with
       the postprocessor.  For example, the predefined colours of LaTeX or Tikz‐pdf packages  can
       be specified, or custom colors can be defined using the

          command string

       facility so that the postprocessor will know about them.

       Filling by color is similar, using the attribute

          shaded string

       and,  when the object is planar and both the fill and outline colors are the same, the two
       attributes can be combined as

          colour|color|colored|coloured string

       in which all four spellings are equivalent.

       Finally, the attribute

          same

       duplicates the properties of the previously drawn object of the same type,  but  with  the
       current default placement.

       In  addition  to  scale  changes  effected by the scale variable, the size of the complete
       picture can be set by appending one or two terms to the .PS line as shown:

          .PS [x [y]]

       where x and y evaluate to constant values.  On encountering  the  .PE  line,  the  picture
       width  w  and height h are calculated.  If x > 0 then the picture is scaled so that w = x.
       If h > y > 0 or if x = 0 and y > 0 then the picture is scaled so that h =  y.   Horizontal
       and  vertical  scaling are not independent.  Text size, line thickness, and arrowheads are
       not scaled.  The units are inches, so for example,

          .PS 100/25.4

       sets the final picture width to 100  mm.   Printed  string  text  may  extend  beyond  the
       rectangular  boundaries defined by w and h unless the text dimensions have been explicitly
       set.

       If the final diagram width exceeds the environment variable maxpswid or the height exceeds
       maxpsht,  both  of which can be changed by assignment, then the diagram is scaled as for x
       and y above.

   Placement of drawn objects
       An object is placed by default so that its entry is at the current point.

       Explicit placement is obtained with

          object at position

       which centers the object at position, or

          object with defined point at position

       for example,

          arc cw from position to position with .c at position

       A block can also be positioned by reference to a displacement from its lower left  corner,
       for example,

          A: [ contents ] with (0.5,0.2) at position.

       Linear  objects  are placed by default with the .start point placed at the current drawing
       position; otherwise linear objects are defined using a linespec, which is of the form

       linespec = from position | to position | direction [ expr ]
                 | linespec linespec
                 | linespec then linespec

       where the second line means that  linespecs  can  be  concatenated,  and  the  third  that
       multisegment linear objects are drawn using multiple linespecs separated by then.

       As  an  example,  the  following  draws a triangle with the leftmost vertex at the current
       point:

          line up 2 right 1.5 then down 3 then to Here

       Exceptionally, the linespec

          to position to position to ...

       is multiple and does not require the then keyword, but this also means that the linespec

          up expression to position

       is multiple and creates a two-segment line.

       A single expr is also an acceptable linespec immediately after a linear object  and  means
       that  the  object is drawn to length expr in the current direction.  The exception to this
       is

          spline [ expr ] linespec

       for which the expr is a spline tension parameter.  If expr is omitted, a straight line  is
       drawn  to the midpoint of the first two spline control points and from the midpoint of the
       last two to the last point; the spline is tangent to all midpoints between control points.
       If  expr is present, the spline is tangent at the first and last control points and at all
       other midpoints, and the spline tension can be adjusted.  Tension values between 0  and  1
       are typical.

       In  cases where all of the points of a multisegment linear object are not known in advance
       or inconvenient to calculate, the drawing command

          continue linespec

       will append a segment to the previously drawn linear object as if continue were then, with
       two  differences.   Arbitrary calculations may be done between the previous object and the
       continue statement, and the current point is the exit point of the previous object.

       The construction

          line from position to position chop [ expr ]

       truncates the line at each end by the value of expr or, if expr is omitted, by the current
       value of environment variable circlerad

       Otherwise

          line from position to position chop expr1 chop expr2

       truncates  the  line by the two specified distances at the ends.  Truncation values can be
       negative.

       The attribute

          by position

       is for positioning, for example,

          move by (5,6)

   Variables and expressions
       Variable names are alphameric sequences beginning with  a  lower‐case  letter,  optionally
       subscripted as for labels, and are defined by assignment.  For example, the following line
       defines the variable x if it does not already exist in the current scope:

          x = expr

       The scope of pic variables is the current block  in  which  they  are  defined,  including
       blocks defined later within the current block.  The assignment

          x := expr

       or any assignment using an operator in the set

          := += -= *= /= %=

       requires x to have been defined previously in the current block or an enclosing block.

       Expressions  consist  of  floating‐point  values combined using the unary operator "!" for
       logical negation and the usual parentheses and binary operators  in  decreasing  order  of
       precedence:

          ^
          * / %
          + -
          == != >= <= < >
          &&
          ||

       In  logical  tests,  the  value 0 is equivalent to false and a nonzero value to true, with
       resulting true value of 1.

       A floating‐point value is obtained as an integer, a  number  with  e  syntax,  a  function
       value, a size value of a drawn object, for example,

          last box.ht,

       or the horizontal or vertical coordinate of a position, obtained respectively as

          position .x|.y

       The  single‐argument  functions are abs, acos, asin, cos, exp, expe, int, log, loge, sign,
       sin, sqrt, tan, floor.  The functions exp and  log  are  base  10.   The  function  rand()
       delivers  a  random  number between 0 and 1, and rand (expr) initializes the random number
       generator.

       The two‐argument functions are atan2, max, min, pmod where pmod  is  the  modulo  function
       delivering a positive value.

   Predefined variables
       The  following variables are predefined on invocation of dpic: optTeX, opttTeX, optPict2e,
       optPSTricks, optPDF, optPGF, optMFpic, optPS, optPSfrag,
       optMpost, and optSVG.  Variable dpicopt is set according to the output option  chosen,  so
       that if one of options -p or -g has been invoked for example, then the test

          if dpicopt == optPSTricks || dpicopt == optPGF then { ... }

       will  selectively  execute  its  body statements.  In addition, variable optsafe has value
       true if the -z option has been selected or dpic has been compiled in safe mode.

       If the specified option is one of -v (SVG), -d (PDF), or -r  (raw  postscript),  then  the
       variable dptextratio is defined, with default value 0.66, together with the variable dpPPI
       with default value 0.96.  The latter is the assumed pixel density per inch and the  former
       is the ratio of text height to nominal point size.  These variables are used by the output
       routines and can be changed by assignment.

       If the -x (xfig)  option  has  been  specified,  then  the  following  two  variables  are
       predefined: xfigres (default value 1200), and xdispres (default 80).

   Predefined environment variables
       A set of environment variables establishes the default values of drawing parameters within
       the scope of the current block.  Their values are inherited from the superior  block,  but
       can  be changed by assignment.  They can be used in expressions like other variables.  The
       variables, their default values, and default uses are given below

          arcrad       0.25
          arc radius
          arrowht      0.1
           length of arrowhead
          arrowwid     0.05
          width of arrowhead
          boxht        0.5
           box height
          boxrad       0
              radius of rounded box corners
          boxwid       0.75
          box width
          circlerad    0.25 circle radius
          dashwid      0.05 dash length for dashed lines
          ellipseht    0.5 ellipse height
          ellipsewid   0.75 ellipse width
          lineht       0.5 height of vertical lines
          linewid      0.5 length of horizontal lines
          moveht       0.5 length of vertical moves
          movewid      0.5 length of horizontal moves
          textht       0 assumed height of text (11pt for postscript, PDF, and SVG)
          textoffset   2.5/72 text justification gap
          textwid      0 assumed width of text

       When a value is assigned to the environment variable scale, all of the  above  values  are
       multiplied  by  the  new  value  of  scale.   This is normally done once at the top of the
       outermost scope of a diagram.  Drawing units are thereby changed but the default  physical
       sizes  of  drawn  objects  remain  unchanged since dimensions are divided by the outermost
       scale value on output.  The following are unaffected by scale changes:

          arrowhead    1 arrowhead shape
          fillval      0.5 fill density
          linethick    0.8 line thickness in points
          maxpsht      11.5 maximum allowed diagram height
          maxpswid     8.5 maximum allowed diagram width

       The variables maxpswid and maxpsht  may  have  to  be  redefined  for  large  diagrams  or
       landscape figures, for example.

   Positions
       A position is equivalent to a coordinate pair defined in current drawing units, and can be
       expressed in the following forms:

          Here
          The current drawing position.

           expr,expr
          A pair of expressions separated by a comma.

          ( position )
          A position in parentheses for grouping.

          ( position , position )
          Takes the horizontal value from the first position and
          the vertical value from the second.

           position +|- position
          Vector addition.

           position *|/ expr
          Scalar postmultiplication.

           Label
          The label of a defined position or object.  The position
          is the center of the object.

           expr [of the way] between position and position

          The example x between A and B is equal to A*(1-x) + B*x.
          Any value of expr is allowed.

           expr < position, position >
          An abbreviated equivalent of the previous form.

           number st|rd|nd|th [last] object
          An object within the current block, enumerated in order of definition.

          The object is one of

          line, move, arrow, arc, box, ellipse, circle, spline, [], "" .

       The number can be replaced by { expr }.  For example, last "" means the last  string,  and
       {2^2}nd [] means the fourth block in the current scope.  The position is the center of the
       object.

       Parentheses may be required when composite positions or expressions are used in the  above
       forms.

       Finally, a position can be given as

          object .  defined point

   Strings
       A string is a sequence of characters enclosed in double quotes.  To include a double quote
       in a string, precede it with  a  backslash.  Strings  can  be  concatenated  using  the  +
       operator.  The C‐like function

          sprintf( format string, expr, ...  )

       is  equivalent to a string.  (Its implementation passes arguments singly to the C snprintf
       function.)  Expressions are floating‐point values, so the only applicable  number  formats
       are e, f, and g.

       Multiple strings such as "text1" "text2" are stacked and centered vertically.

       A  string attached to an object overlays the object at the center, and any height or width
       attributes apply to the object, not the string.   However,  the  justification  attributes
       ljust and rjust can be applied to the individual strings of a stack overlaying an object.

       An  independent  string  is  placed with its center at the current point by default, or by
       specifying the position of one of its defined points as for any object, for example,

           "Animal crackers" wid 82.3/72 ht 9.7/72 with .sw at Q

       The placement qualifiers above, below, ljust, rjust place  the  string  above,  below,  or
       justified with respect to the placement point.  For example,

          "Animal crackers" at Q ljust above

       places the string above and textoffset units to the right of Q.

EXAMPLES

       Source file example.pic:

         \documentclass{article}
         \usepackage{tikz}
         \begin{document}
         .PS
         box dashed "Hello" "World"
         .PE
         \end{document}

       The command

          dpic -g example.pic > example.tex; pdflatex example

       produces example.pdf containing a dashed box with Hello and World stacked inside.

       To  produce  a  .tex  file containing PSTricks drawing commands for insertion into a LaTeX
       document using the \input command, delete the first three and  last  lines  in  the  above
       source and process using the -p option of dpic.

       Similarly, the picture source

         .PS
         \definecolor{puce}{rgb}{0.8,0.53,0.6}%
         box shaded "puce"
         .PE

       produces  a  box  filled with a flea‐like color when processed with dpic -g or dpic -p and
       the resulting file is inserted into a latex source file invoking, respectively,  the  tikz
       or pstricks package.

SEE ALSO

       E.  S.  Raymond,  Making  Pictures  with GNU PIC, 1995.  In GNU groff source distribution;
       http://www.kohala.com/start/troff/gpic.raymond.ps  (A  good  introduction   to   the   pic
       language, with elementary illustrations.)

       J.  D.  Aplevich,  Drawing  with  dpic, 2023, http://ece.uwaterloo.ca/~aplevich/dpic/dpic-
       doc.pdf (Specific discussion of dpic facilities and extensions, with  differences  between
       dpic and GNU pic.)

       B.  W.  Kernighan, B. W. and D. M. Richie, PIC  A Graphics Language for Typesetting, User
       Manual, 1991.  AT&T Bell Laboratories,  Computing  Science  Technical  Report  116.   (The
       original Unix pic.)

       J.  D.  Aplevich,  M4 Macros for Electric Circuit Diagrams in LaTeX Documents, 2023.  File
       Circuit_macros.pdf  in  the  graphics/Circuit_macros   section   of   CTAN   repositories.
       (Extension  of the pic language using the m4 macro processor for drawing electric circuits
       and other diagrams.)

AUTHOR

           Dwight Aplevich <aplevich at uwaterloo dot ca>

                                            2023.06.01                                    DPIC(1)