Provided by: dpic_2014.01.01+dfsg1-0ubuntu1_amd64 bug

NAME

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

SYNOPSIS

       dpic [ -efghmprstvxz ] [ infile ] [> outfile ]

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

OPTIONS

       (none) LaTeX drawing output (very limited font‐based drawing capability)
       -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 drawing 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 or SVG.  Arbitrary text can be inserted into the output for later
       formatting, and arbitrary commands for 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 language extensions unique to dpic are implemented for specific purposes.

LANGUAGE SUMMARY

       Input consists of a sequence of lines.  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,  which  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 but it is 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.
       Using 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 corner 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 the 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

          define name { anything },

       so that, when name appears alone or with arguments as name  (  arg,  ...   )  then  it  is
       replaced  by  the  contents  between the braces in the definition.  A comma in an argument
       list is ignored within a string or parentheses.  In this substitution, occurrences  of  $1
       are  replaced  by  the  first  argument, 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
       The size and other parameters control the  appearance  of  objects.   An  attribute  is  a
       keyword or keywords with expressions as appropriate.

       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  environmental  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  shape  parameter  expr  may  be  omitted,  in which case the value of the environment
       variable arrowhead is used.  The default for arrow is ->.

       The drawing direction of an arc is changed by the attribute

          ccw|cw

       with ccw the default.

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

          fill [ expr ]

       where a value of 1 means white, and  0  means  black.   Paths  can  be  filled  where  the
       postprocessor allows.

       Line color can be set using

          outline|outlined string

       where  the  contents of the string depend on the postprocessor.  The predefined colours of
       LaTeX or Tikz‐pdf packages can be specified.  The pic  language  knows  no  details  about
       color;  the string contents must be compatible with the postprocessor.  Custom colors have
       to 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 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 maxpswid or the height exceeds maxpsht 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
       postion; 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.

       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
       circle radius.  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

       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 one‐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 environment variables
       A set of predefined variables establishes the default values of drawing parameters.  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
          movewid 0.5    length of horizontal moves
          movewid 0.5    length of horizontal moves
          textht 0      assumed height of text
          textoffset 2.5/72 text justification gap
          textwid 0      assumed width of text

       When  a value is assigned to the variable scale, all of the above values are multiplied by
       the new value of scale.  The drawing units are thereby changed but  the  default  physical
       sizes  of drawn objects remain unchanged since, on final output, dimensions are divided by
       the scale value.  In addition, the following are unchanged by scale:

          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
          scale 1      drawing unit scale factor

       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 enumerated object within the current block.

          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 expressed 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.  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,

           "Crunchy 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,

          "Crunchy 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,  E.  S.,  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,          2011,
       http://ece.uwaterloo.ca/~aplevich/dpic/dpicdoc.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,  2011.   File
       CMman.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>

                                            2014 Jan 1                                    DPIC(1)