
This is a quick summary of the dpic language.  The differences between
dpic and gpic, described near the end, may be of particular interest.
The output formats produced by gpic and dpic are completely different.

This document is not intended to be an introductory pic manual.  For
elementary examples, sample pictures, and other details, consult a pic or
gpic manual.

   There had better be a disclaimer:  The temptation to change the pic
   language has been resisted most of the time so that valid diagrams
   can be processed with minimal changes using the original
   Documenter's Workbench (DWB) pic, with gpic, or dpic.  There are
   exceptions, of course: embedded word-processor commands principally,
   but also minor differences in defaults for valid pic input.  For
   details, see the last part of this file.  Dpic also contains a few
   extensions that do not change its behaviour for normal input.  It is
   tempting to add more colour and other Postscript-like functions, but
   these can be handled with macros.

To produce .tex output (for LaTeX, PStricks, TikZ-PGF, mfpic
   processing):
   dpic [option] file.pic > file.tex
   or
   cat file.pic | dpic [option] > file.tex

To produce other formats:
   dpic -[e|f|g|h|m|p|r|s|t|x|z] file.pic > file.[tex|eps|mp|fig]

Dpic options:
The -p option is the most powerful and flexible for many purposes.  The
-g option is nearly as powerful and makes .pdf production via pdflatex
easy, although it seems to take more LaTeX processing time.  Mfpic and
MetaPost output is provided for compatibility.  The -r option produces
Postscript .eps files, in which font changes or typesetting must be
done manually.  Output in this form can be imported into CorelDraw and
Adobe Illustrator. The -f option writes Postscript strings in psfrag
format for tex or latex typesetting. The -z option disables the sh and
copy commands.  These commands permanently disabled by the use of a
compile-time flag.

   (none) Latex drawing commands
   -e pict2e output
   -f Postscript output with psfrag strings
   -g TikZ-PGF output
   -h write out these options and quit
   -m mfpic output
   -p PStricks output
   -r raw Postscript output
   -s MetaPost output
   -t eepicemu output
   -x xfig 3.2 output
   -z sh and copy commands disabled

The file Examples.txt contains a minimal example of each of these
options except -z.  Consult the appropriate manual for processing
mfpic, PStricks, MetaPost, pgf, or psfrag output.

Invoking dpic without options produces basic LaTeX drawing commands
by default.  LaTeX line slopes, for example, are very limited and you
must ensure that lines and arrows are drawn only at acceptable slopes.
Dpic sets the maximum slope integer to be 6 for LaTeX, 453 for eepic,
and 1000 for pict2e.  To see the effect of the slope limitations,
process the following:
  .PS
  rtod = 180/atan2(0,-1)
  for theta = 0 to 360 by 2 do {
    line from 0,0 to cos(theta/rtod),sin(theta/rtod)
    }
  line from 0,0 to 2,0
  line from 0,0 to 0,2
  .PE

Basic syntax:
   Diagrams can be mixed with other text in dpic input.  Ordinary text is
passed through unchanged.  A line beginning with .PS denotes the first
input line of a dpic diagram and the last line is .PE, as shown:
.PS
   dpic commands
.PE
The .PS line can contain one or two terms shown as x and y:
   .PS x y
where x and y are terms that evaluate to constant numbers.  A term is a
product of factors, or a parenthesized sum or difference.  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 done independently.
Text and line thickness are not scaled.  The dimensions are inches, so
   .PS 100/25.4
sets the final picture width to 100 mm.  Dpic cannot know the final
dimensions of typeset text or any text objects unless told.  Printed
string text may extend beyond the rectangular boundaries defined by w
and h unless the text dimensions are entered explicitly.

The primitive drawing objects consist of the planar objects
   "box" "circle" "ellipse" "<string>"
where <string> designates a set of characters enclosed in double quotes,
and the linear objects
   "line" "arrow" "move" "spline" "arc"

Coordinates:
   Drawing is done with respect to rectangular coordinates, the horizontal
scale from left to right, the vertical scale from bottom to top.

By default, coordinates are in inches, but there is an environment variable
called scale, so the line
   scale = 25.4
allows all following dimensions to be given in mm, for example.  This
scaling is overridden if the picture exceeds the size specified by the
variables maxpswid and maxpsht.  All this is overridden by the .PS x y
line as described previously.

Current position and direction:
   Every primitive object has an entry and exit position, and the current
position is the exit of the last object.  The current direction may be
set as one of "up" "down" "left" "right".  Thus
   up; box; line
draws a box, exiting at the top, and then a line upwards.

Errors and error messages:
   An input line containing errors is printed out, with error messages,
after the complete line has been scanned.  The error is at or prior to
the point indicated by the message.  An error may not be detected until
scanning has reached some distance beyond the offending input, which
therefore may be in the line or lines preceeding the one printed with
the error messages.  Putting a semicolon at the end of the line
containing the error usually forces the line to be printed with
the error message.

Grammar:
   An outline of the grammar follows, with some minor simplifications.

Punctuation symbols (between quotation characters):
  "<" ">" "cw" "ccw"
  "(" ")" "*" "+" "-" "/" "%" ";" = "<NL>"
  "^" "!" "&&" "||" "==" "!=" ">=" "<=" "<<" ">>"
  "," ":" "[" "]" "{" "}" "." "[]" "`" "'"
  "=" ":=" "+=" "-=" "*=" "/=" "%="
  "#" "$"

The symbol "<NL>" corresponds to the end-of-line character or characters in
the input stream.  Symbols equated by the equals sign (";" = "<NL>") are
grammatically equivalent.  The symbols "<<" and ">>" mean "<" and ">"
respectively within logical "if" tests.

Comments are contained between the "#" character and the end of the line.
Lines may be continued if the last character on the line is a backslash
or if a backslash is immediately followed by the "#" character.

More keywords, to be explained later, are:
     "Here" "and" "at" "between" "by" "chop" "command" "continue" "copy"
     "define"
     "diam" = "diameter"
     "do" "else" "exec"
     "fill" = "filled"
     "for" "from"
     ".ht" = ".height"
     "ht" = "height"
     "if" "last" "of" "print"
     ".rad" = ".radius"
     "rad" = "radius"
     "rand" "reset" "same" "scaled" "sh" "sprintf"
     "st" = "rd" = "nd" = "th"
     "the" "then"
     "thick" = "thickness"
     "to" "undef" "way"
     ".wid" = ".width"
     "wid" = "width"
     "with" ".x" ".y"

Function arguments are enclosed within parentheses and separated by commas, e.g.
     atan2(y,x).

The following single-argument mathematical functions are recognized:
     "abs" "acos" "asin" "cos" "exp" "expe" "floor" "int" "log" "loge"
     "sign" "sin" "sqrt" "tan"
The log and exp functions are base 10, loge and expe are base e.

The two-argument functions are:
     "atan2" "max" "min" "pmod"
The function pmod(x,y) returns nonnegative value (x mod abs(y)) for both
positive and negative x.

Primitive drawing objects:
     "box" "circle" "ellipse" "arc" "line" "arrow" "move" "spline"

Where it makes logical sense, points on primitive objects can be referred
to by compass-coordinates or other labels:
     ".t" = ".top" = "top" = ".n" = ".north"
     ".b" = ".bot" = ".bottom" = "bottom" = ".s" = ".south"
     ".left" = ".l" = ".w" = ".west"
     ".right" = ".r" = ".e" = ".east"
     ".center" = ".centre" = ".c"
     ".ne" ".se" ".nw" ".sw"
     ".start" = "start"
     ".end" = "end"
Be warned that not all grammatically acceptable constructs make logical
sense, e.g. the .nw position of a multi-segmented line may not be uniquely
defined.

   e.g. 1st box.ne
   e.g. last [].A  (assuming that position A has been labeled within
             the last block)
   e.g. last box   (the same as last box.c)
   e.g. 3rd last arrow.end
   e.g. 2rd last "".e  (right-centre of the 2nd last string)

Directions:
     "up" "down" "right" "left"
   e.g. line up 2.5   (this draws a line up 2.5 units and leaves the current
                          direction set to up)

Line types:
    "solid" "dotted" "dashed" "invis" = "invisible"
   e.g. arrow up 1 dashed

Line and fill colours are set by the outline and shade parameters:
     "color" = "colour" = "colored" = "coloured"
     "outline" = "outlined"
     "shade" = "shaded"
   e.g.  box outline "red" shaded "blue"
  Both colours can be set to the same value using
    box colour "red"
  The strings specifying colours have to be compatible with the postprocessor,
  such as PStricks, that is used.  MetaPost, for example, requires the
  equivalent of
    box colour "(1,0,0)"

Text positions relative to default or specified positions:
     "centre" = "center" "ljust" "rjust" "above" "below"
   e.g. line dashed right "Text" above
   e.g. "Fig. 1" at 3.5,4 ljust below

Arrowhead locations for lines, arcs and splines:
     "<-" "->" "<->"
   e.g. arrow <- up 2 (draws a downward-pointing arrow of length 2)

Environmental variables are categorized into two groups: those that are
changed when the variable "scale" is changed, and those that are not.
The variables, with their default values, are:

Scaled variables:
   "arcrad" = 0.25         default radius of arcs
   "arrowht" = 0.1         distance from arrowhead front to back
   "arrowwid" = 0.05       arrowhead width
          The effect of changing arrowhead parameters depends on the
          drawing method (output format) and may not be the same in all cases.
   "boxht" = 0.5           box height and width defaults
   "boxwid" = 0.75
   "circlerad" = 0.25      circle default radius
   "dashwid" = 0.1
   "ellipseht" = 0.5       ellipse height and width defaults
   "ellipsewid" = 0.75
   "lineht" = 0.5          default vertical line length
   "linewid" = 0.5         default horizontal line length
   "moveht" = 0.5          default vertial and horizontal move distances
   "movewid" = 0.5
   "textht" = 0            height and width of text box
   "textwid" = 0
   "textoffset" = 2.5/72.27   space between text and specified position

Unscaled variables:
   "arrowhead" = 2         arrowhead shape number (for compatibility)
   "fillval" = 0.3         gray intensity for filled objects (0=black, 1=white)
   "linethick" = 0.8       default line thickness, in points
   "maxpsht" = 11          default maximum picture height and width, overridden
                           by the .PS line parameters
   "maxpswid" = 8.5
   "scale" = 1             drawing scale factor

Other permissible character sequences:
  "<float>" "<name>" "<Label>" "<LaTeX>" "<string>"

A "<float>" is an integer or floating-point number with or without the `e'
exponential representation, e.g. 5, 0.5, 5., 5.123, -123e2

A "<name>" is a sequence of upper-case or lower-case characters, the
integers 0 to 9, or the underscore _, beginning with a lower-case
letter, but a name may not be one of the keywords of the grammar.
Names are used as variables in expressions.  e.g.
    separation = 0.1 ; move right 3*separation
Names may be subscripted in dpic, e.g. separation[i] where the expression
i is evaluated and rounded to an integer.

A "<Label>" is like a "<name>" but begins with an upper-case letter,
and can be used as the symbolic name of a position or drawn object.
The predefined label "Here" refers to the current drawing position, e.g.
    Pin27: line to Here + (1,2.5) ; line up 1 from Pin27.end
Here has the value (0,0) on entry into a [ ] block or at the beginning
of a diagram (which is the same thing).  Labels may be subscripted in
dpic, e.g. Pin[27] instead of Pin27.

Reasonable defaults are used when drawn objects are not completely specified.
For example,
  line to A
is equivalent by default to
  line from Here to A
whereas
  line from A
is a line of default length starting at A, drawn in the current direction, and
  line
is a line of default length starting at Here, drawn in the current direction.
Similarly,
  box
has default height of boxht and default width of boxwid, whereas
  box ht 1
has height 1 and default width.
If the default result is undesirable, specify the drawn object completely.

The symbol "<LaTeX>" is any line beginning with the "\" character,
to be copied unchanged to the output.  Thus arbitrary TeX, pstricks,
or other commands can be mixed with drawing commands, e.g.
   \rotateleft{
    box "Text"
   \relax}

An alternative for passing arbitrary characters to the output is the
   "command" string
construct.  Thus
   command "\pscircle(0,0){0.5}"
passes the contents of the string to the output.

In the following, symbols between square brackets [ and ] are optional,
but note that in pic input, brackets [ and ] also define a logical
block, as will be described.  The symbol `|' means `or'.  Unquoted
parentheses are for grouping.

Strings are arbitrary character sequences between double quotes, with double
quotes in strings preceeded by the backslash character.  Equivalently, a
string is produced by the C-like sprintf function:
   "sprintf" "(" "<format string>" ["," expression "," ... ] ")"
The C sprintf function is used for implementing this; therefore, the
precision of default formats such as %g may vary by machine and compiler.
To produce transportable results, specify the precision completely,
e.g. %g8.5.  As in C, the pair %% in the format string prints the percent
character.  Only the f,e,g formatting parameters are valid, since expressions
are stored as floating-point numbers, e.g.
   line sprintf("%g%g0", 2, 0 ) above
is equivalent to
   line "200" above
Similarly,
   command sprintf("\pscircle(%g,%g){%g}",0,0,0.5)
places the formatted string into the output.  The numerical sprintf arguments
can be arbitrary expressions rather than the constants shown.

Strings can be associated with drawing objects:
  e.g. arrow right "to France" above
  e.g. circle "Big" "node"
Otherwise, a string can be placed at an arbitrary position and assigned a
height and width as for a box as shown:
  "Arbitrary character sequence" ht 0.16 wid 1.85 with .n at A
where the dimensions of the string have to be obtained by investigating
the final printed output.  Dpic cannot know typeset dimensions in advance.

Valid input consists of a sequence of 0 or more pictures.  A picture begins
with .PS and ends with .PE, and contains a list of 0 or more elements
separated by newlines or semicolons, e.g.
.PS
   box
   line; ellipse; arrow
.PE


The elements are:

element = ["<Label>" ":"] object             -- object with optional name
        | "<Label>" ":" [position]           -- named position
        | assignment ["," assignment ...]       -- assignment statements
        | "<direction>"                         -- up, down, left, right
        | "<LaTeX>"                             -- lines starting with \ or .
        | command
        | "{" elementlist "}"
        | "if" expression "then" "{" elementlist "}"
          [ "else" "{" elementlist "}" ]
        |  "for" assignment ["," assignment ...] "to" expression
            ["by" ["*"] expression] "do" "{" elementlist "}"
        | "command" string
        | "exec" string

assignment = ("<name>" | "<envvar>") "=" expression

Examples of named objects:
   A: box
   Bounding_box: [ circle rad 3 "target" ]  -- the [] brackets define a block
   Bounding_box[5]: circle                  -- the [] brackets are a subscript

Example of named position:
   NW: last [].nw                           -- refers to last-defined block

With exceptions, enclosing a sequence of elements in "{" and "}" braces
has the very convenient effect of saving the current drawing position
and direction at the first brace, and restoring these values at the
second brace.  The exceptions are the braces in the `if' construction,
the `for' construction, macro definitions, and the `ncount' construction
described later.

Example `for':
for y = 0 to 1 by 0.05 do {
   t = 2*atan2(sqrt((1-y)/(1+y)),1)
   line right 2*t with .c at (0,y) }

The number of iterations of the loop must be precomputable, and the
loop variable (y above) must not be changed by statements in the loop.

command:
        "print" expression | position | string
        | "reset" [<envvar> ["," ...] ]
        | "sh" string
        | "copy" "<string>"
        | "define" name "{" elements "}"
        | "undef" name

The print command sends the specified quantity to the standard-error
output, which is useful for debugging pictures.  The reset command
resets all or only the designated environment variables of the current
block to the default values.  The sh command sends the string to the
operating system for execution.  The copy command inserts the file
specified in "<string>" into the input stream.  Copy commands may not
be nested. A compile-time option is provided to replace the sh and copy
commands by a warning message when dpic is used in web server mode.
A macro is defined as shown above, and invoked as name(arg1,arg2,...)
with 0 or more arguments separated by commas. Within an invoked macro,
$1 expands to the first argument, $2 to the second, and so on.  The
undef command undefines the macro.

object:
        primitive_object
        | linear_object expression
        | string
        | "[" elementlist "]"

The first of the above lines corresponds to any primitive object;
the second to lines of the form
  arrow 0.5
which is equivalent to
  arrow right 0.5
for example, if the current direction is right.  The fourth
construction gives the language a block structure.  The scope of
environment variables, positions, and defined variables is the current
block, except that if a variable is sought but not found within the
current block, the search will continue within enclosing blocks.  A
block may be given a name and placed just as a box would be placed,
e.g.

A: [ elements, including object B ]
   [ elements, including object C ] with C.sw at A.B.n + (0,1.5)
   box with .s at last [].n

The second block is placed with the south-west corner of internal
object C at 1.5 units above the top of object B in block A.  Then a box
is placed above the previous block.

Objects may be followed by modifyers to specify dimensions, position,
or orientation, as follows:

          ("height"|"width"|"radius"|"diameter"|"scaled") expression
          | ("up"|"down"|"left"|"right") [expression]
          | "by" expression "," expression
          | "then"
          | <line type> [expression]
          | ("chop"|"fill") [expression]
          | <arrowhead type>
          | "cw" | "ccw"
          | "same"
          | "<string>"
          | <text position>
          | ("from"|"to"|"at") position
          | <colrspec> "<string>"

e.g.
Brick: [
   B1: box
      box ht 0.5*boxht wid 0.5*boxwid with .c at B1.c "C"
      ]
   ellipse ht 0.6 wid 3 with .w at Brick.B1.ne "$\theta$"
   arc from 0,0 to 1,1 with .c at 0,1

The word "then" is used to concatenate instances of an object, thus

   line up right then down then up left

draws a line northeast, then a line south, then a line northwest.

In loops, or if calculations have to be done, the "continue"
keyword can be used to add to the most recent drawn object as if "then"
had been used in the original line; thus, the following has the same
effect as the above line:

   line up right
     calculations
   continue down
     more calculations
   continue up left

"Continue" can also be used slightly differently. The line drawn by

  move to 0,0; line right 1 then to (Here,(2,1))

terminates at (0,1) since "Here" is the position (0,0), whereas

  move to 0,0; line right 1; continue to (Here,(2,1))

terminates at (1,1) since "Here" is (1,0).

In fact, "then" is identical to "continue" in the grammar and
(as it turns out) the extra keyword need not have been included,
but it adds to readability.

Changing "line" to "spline ->" in the above,

   spline -> up right then down then up left

draws a spline tangent to the first and last line segments, with the
interior corners as control points, and with an arrowhead at the end.

An object followed by one or more strings has the strings placed at its
center, unless they are modified by text position specifications.  Thus

   box "First line" "Second line" "Third line"

draws a box with the three text lines stacked and centered at the center
of the box.

Arcs are ambiguous in the pic language.  The object

   arc -> from 0.5,0 to 0,0.5

specifies an arc with an arrowhead at the end, by default drawn
counterclockwise, starting at position 0.5,0 and ending at position
0,0.5.   If the radius is not specified then the value `arcrad' is used
if it is large enough, otherwise the radius is half the chord.  However,
there are still two possible arcs, with centres at 0,0 and 1,1.
Dpic chooses the one for which the initial tangent makes an acute angle
with the current direction: up, down, left, or right, e.g.:
   left;  arc -> from 0.5,0 to 0,0.5 rad 0.5
   right; arc -> from 0.5,0 to 0,0.5 rad 0.5 dashed

Default values for arc parameters will be used automatically, but
when in doubt, specify the start, end, rotation, and centre, e.g.
   arc ccw from <position> to <position> with .c at <position>

Objects may also be placed by following them by the "with" construction:
        ... "with" ("<corner>"|"start"|"end") "at" position
        ... "with" "." "<Label>" "at" position

A position is a comma-separated pair of expressions, or a location plus
or minus a shift, which is a location in parentheses, or a fraction
of the way between positions:

position = expression "," expression
   e.g. 0,0
         | location shift
   e.g. last box.ne + (1,0.5) - (linewid,0)
         | expression ["of" "the" "way"] "between" position "and" position
         | expression "<" position "," position ">" shift
   e.g. line from 0.1<A,B> to 0.9<A,B>

The construction x<A,B> may not be used within a logical "if" test expression.

location = "(" position ["," position] ")"
         | place

The construction "(" position "," position ")" takes x-coordinate from
the first position, and y-coordinate from the second position.

Places are compound constructions specified in a variety of ways, as
follows:

place = placename ["<corner>"]
      | "<corner>" ["of"] placename
      | "Here"

placename = ("<Label>" | nth primobj)
          | placename "." ("<Label>" | nth primobj)

nth = ncount "th" ["last"] | "last".

primobj = primitive_object | "[]" | "<string>" | "[" "]"

ncount = "<float>" | "`" expression "'" | "{" expression "}" .

e.g. for i = 1 to 10 do { line from {i}th box.ne to {i+1}th box.sw }
e.g. line from 2nd last arrow.end to last ellipse.nw

In the above, of course the place name, or the nth object or block
referred to must have been previously defined.

Expressions are composed of primary floating-point quantities combined
using operators, with the following precedence from lowest to highest:
 ||
 &&
 "==" "!=" "<=" ">=" ">>" "<<"
 "+" "-"
 "*" "/" "%"
 "^" "!" 

Logical quantities are assigned the value 1.0 for true and 0.0 for false.

The primary quantities are:
        environment variable
        | value previously assigned to a name
        | floating-point constant
        | "(" expression or logical expression ")"
        | location (".x"|".y")               -- the location x or y coordinate
        | placename (".ht"|".wid"|".rad"|".diam")
        | "rand" "(" optional expression ")" -- random number between 0 and 1
        | returned function value
        | "(" assignment ")"
        | "(" expression ("<"|">") expression ")"


Lexical error messages:
  Lexical error messages are generated automatically, and state what
lexical value was found, and what was expected.  Some non-obvious
lexical values are:

:             --designates the end of a for iteration
<<            --the "<" operator within logical tests
>>            --the ">" operator within logical tests
<EOF>         --end of input
<ERROR>       --an error is considered valid input during error recovery
<NL>          --new line or ";"
<corner>      --a compass corner or ".c", ".start", ".end" as appropriate
<envvar>      --environmental variable
<func1>       --numerical function with 1 argument
<func2>       --numerical function with 2 arguments
<param>       --".ht", ".wid", ".rad", ".diam"
<primitiv>    --"box", "circle", "ellipse", "arc", "line", "arrow", "move", 
                "spline"

================================================================================

Differences between dpic and gpic are summarized below.  Normally, the
only changes required to process correct original pic or gpic code with
dpic are chages to {...} instead of X...X syntax, and text formatting
changes if the original code was written for groff.  The remaining
differences documented below are small syntactical differences or
relate to the use of PSTricks or the other dpic output formats.
Sometimes differences in default syntax (such as for arcs) must be
considered.

Gpic is being actively maintained so some of the items below apply only
to older versions.

Command-line options:  They are completely different, of course.

Output formats:
  Gpic -t output consists of a sequence of \special statements
  contained in the TeX box \box\graph.  The \special statements are
  automatically copied into the .dvi file for interpretation by a
  printer driver such as dvips.  Dpic does not generate tpic specials.
  See the option list at the top of this file for output formats.

. lines and program-generated pic:
  Gpic passes lines beginning with . through to the output, thereby allowing
  arbitrary Troff macros to be interspersed with pic drawing commands.  Some
  programs that generate pic output automatically insert the Troff line .ps 11
  on the assumption that the text point size should be 11.  Dpic ignores lines
  beginning with . within pictures.  Some programs (e.g., pstoedit) add Troff
  comment lines beginning with .\" outside the .PS, .PE delimiters.  These
  lines must be dealt with separately.

\ lines:
  Both gpic and dpic pass lines beginning with \ to the output but
  dpic does not automatically append a % at the end as gpic does.

for-loop and if bodies:  In gpic, a for loop has the form
    for variable = expr1 to expr2 [by [*]expr3] do X body X
  where X is any character not occurring in body, but { body }
  is also allowed.  In dpic only the latter is allowed.
  Similarly, the required form of an if statement for dpic is
    if expr then { if-true } [else { if-false }]

end of line:
  The line-end is significant in the pic language.  The construction 
    if condition then { if-true }
    else { if-false }
  produces an error with all pic interpreters.  To avoid this error, write
    if condition then { if-true } \
    else { if-false }
  However, dpic ignores line-ends following "then", "{", "else", or line-end.
  Both the CR (octal 015) and NL (octal 012) characters are treated as
  line-ends.

logic:
  Dpic and gpic give slightly different default precedences to the logical
  operators "!" "&&" "||" "==" "!=" ">=" "<=" "<" ">", so judicious use of
  parentheses may sometimes be in order to guarantee identical behavior.

then:
  Versions of gpic up to 1.19 ignore the "then" keyword, so that "spline ->
  then right 0.5" is the same as "spline -> right 0.5", whereas dpic
  does not ignore "then".

line/spline/arrow/move:
  Dpic treats the defaults for linear objects consistently with planar
  objects with respect to the 'at' modifier.  Versions of gpic up to 1.19
  treat them differently:
  In dpic, 'line at Here' means 'line with .center at Here'.
  In gpic, 'line at Here' means 'line with .start at Here'.

  In dpic, the location corresponding to 'last line' is last line.c.
  In gpic, the location corresponding to 'last line' is last line.start.

  Gpic and ATT pic use .start for all of the compass corners of these
  objects, whereas dpic attempts a slightly more elaborate computation. 
  The compass corners of linear objects are not defined in the manuals
  and their use is to be deprecated.

  Be explicit in placing objects rather than relying on defaults.

arc defaults:  gpic and dpic have different algorithms for picking
  a default radius.  The best practice is to specify arcs completely.
  Note the ambiguity in the pic language: 'arc cw rad x from A to B'
  does not uniquely define the arc.  Use 'arc cw from A to B with .c at C'
  instead.

print arg,...
  Dpic allows only one argument, which may be an expression, position,
  or string.  To print several quantities at once, use sprintf(...) to
  generate a string.

command arg,...
  As for print, send arbitrary commands to the output stream using sprintf(...)

sh <string> is the required form for a dpic shell (operating system) command.

copy:
  dpic supports the command
    copy "filename"
  but does not directly support the commands
    copy ["filename"] thru X body X [until "word"]
    copy ["filename"] thru macro [until "word"]

  These functions (and more) are readily implementable with dpic in any
  unix-like environment.  To customize an operation such as
    copy "filename" thru macro
  modify the following, as appropriate:
  .PS
  #                               Suppose that file.dat contains rows of data
  #                               delimited by spaces.

  #                               Macro to process a row of data eg
  #                               save the first 4 values:
    define store { n = n+1; x[n] = $1; y[n] = $2; z[n] = $3; w[n] = $4 }

  #                               Use sed to convert the data to a sequence
  #                               of calls to the store macro:
    sh "sed -e 's/^ */store(/' -e 's/ *$/)/' -e 's/  */,/g' file.dat >tempfile"

  #                               Initialize the counter and process the data
    n = 0; copy "tempfile"
  #                               Delete the temporary file
    sh "rm tempfile"
  .PE

strings:
  dpic allows strings to be concatenated by the + operator; thus
  "string1" + sprintf(" string%g",2) is equivalent to "string1 string2".

  Both dpic and gpic treat "\" as an escape character prior to the
  quote character in strings, so "\"" is a length-one string containing
  the double quote.  Otherwise, the backslash is an ordinary string
  character.  In a macro, a dollar sign followed by an integer in a
  string will expand to the corresponding macro argument if it is
  defined.  Separate the dollar sign from the integer to avoid
  expansion, as in the TeX strings "{\$}1", "$\$ 1$", or "${0}$", for
  example.  Some previous versions of dpic allowed \$ to escape the
  dollar sign in strings but this created other difficulties.

  String height and width are not scaled on final output in dpic.

plot
  Deprecated in gpic and not allowed in dpic.

rand(x)
  The argument to rand() is deprecated in gpic and not allowed in dpic.

line thickness:
  A negative value is meaningless in dpic.
  Big points are used (1/72 in) in MetaPost output to conform to PSTricks.

fill values:  in gpic, 0 is white, 1 is black.  Dpic uses 0 as black, 1 as
  white as do Postscript and the original pic.

fill: the pic language specifies fill only for box, ellipse, and circle,
  whereas xfig allows linear objects to have a fill value and this is
  supported by dpic.  The concept of a path containing several arbitrary
  linear objects does not exist in the pic language.

scaling: Dpic implements a "scaled" attribute, so that
  box scaled 1.2
  produces a box with dimensions scaled by 1.2, and
  [box; line scaled 3; circle] scaled 0.5
  scales all objects within the block by 0.5.  The latter can be used
  in place of setting the scale environment variable when, for example,
  different parts of a diagram require different scaling.  As always,
  line thicknesses are not scaled.

arrowheads:
  These depend on the output format, and consequently have limited variety
  built into the pic grammar.  Arrowhead and other parameters can be
  adjusted using the
    command "string" 
  construct for post-processor commands.

  There is a subtle language problem concerning arrowheads.  Let us
  agree that the following examples should produce an arrow of length 1
  inch and arrowhead width 1 millimetre:
    .PS
      arrow right 1 width 1/25.4
    .PE
    .PS
      scale = 25.4
      arrow right 25.4 width 1
    .PE
    .PS 1
      arrow right 1/4 width 1/25.4
    .PE

  The original (DWB) pic fails on the second example, insisting that
  arrowhead dimensions be given in inches.  Gpic fails on the third by
  scaling the arrowhead on final output.  Although it might be argued
  that this is a feature, it causes serious awkwardness when diagrams
  are to be scaled to exact final dimensions using the ".PS x"
  construction, since the effective scale factor is unknown until the
  .PE line is processed.  Dpic generates the same arrow in all three
  cases, treating arrowhead parameters like line thickness (unscaled)
  parameters on final output.

compass corners:
  dpic consistently requires a dot before compass corners, so the gpic line
    "x" at center of last box
  should be written for dpic as
    "x" at .center of last box

continue:
  dpic implements the "continue" function described previously.

subscripted variables and locations:
  Dpic allows arrays of variables or positions, as an aid in geometric
  calculations such as fitting splines to a set of points.  Thus
  Pos[expression] is a valid name for a position.  The rounded integer
  value of the expression is used.  Similarly, x[expression] is a valid
  variable name.  There are no array operations, but it is easy to write
  macros for them.

macro arguments:
  Inside a macro, $n expands to the nth argument, which may be nul, if
  at least one argument has been defined and n is a positive integer.
  Otherwise $n is not evaluated.

macro argument count:
  In a dpic macro, the value of $+ is the number of arguments given to
  the macro on invocation.  Thus if x is a macro name, the values of $+
  when the macro is invoked as x, x(), x(8), x(8,9), and x(,,) are
  respectively 0, 1, 1, 2, and 3.

macro expansion:
  The macro
    define spot {
      circle at $1
    }
  invoked as
    A: spot((1,2))
  is expanded by gpic to
    A: circle at (1,2)

  whereas it is is expanded literally by dpic to
    A:
      circle at (1,2)

  (Gpic ignores the white space after the "{" but not before the "}").
  To emulate the gpic behaviour, write
    define spot {\
      circle at $1
    }
  or simply use
    define spot { circle at $1 }
  To allow, for example,
    A: spot((1,2)) dashed
  use the last definition above or write
    define spot {\
      circle at $1 \
    }

splines:
  Gpic extends the DWB pic grammar to make "line 0.5" legal and mean "a
  line of length 0.5 in the current direction." All linear objects are
  treated similarly.  Dpic does the same except for splines.  In the
  statement "spline x from A to B then to C" the parameter x is a
  tension parameter between 0 and 1 to control the spline curvature.
  If x is not present as in the normal pic grammar, the curve starts
  with a straight line halfway along the first segment and ends with a
  straight line along the last half of the last segment.  However
  when x is present, the spline is drawn from the start of the first
  segment to the end of the last segment.

vector arithmetic:
  The dpic grammar permits the following: X: Y + Z where Y and Z are
  defined positions.  Gpic requires X: Y + (Z.x,Z.y).  Dpic also allows
  scalar multiplication: X: Y*2/3 (but not X: 2/3*Y).

positions:
  If X is a position, then (X) is a valid position for dpic but
  not older versions of gpic, which give an error for
  (a between A and B) + (x,y)
  Dropping the parentheses to avoid the error gives
  a between A and B + (x,y)
  which is not the same resulting position. Use dpic or the latest gpic
  if you need this construction.

int():
  Gpic int() up to version 1.19 computed the floor of its argument
  rather than the integer part as specified by DWB pic.  Dpic provides
  both the floor() and int() functions but int() does not compute the
  same value as these versions of gpic int() for non-integer negative
  arguments.

exec:
  In dpic the contents of a string can be executed using
   exec "string"
  or
   exec sprintf("string", args)
  as if the string were the next line of input.  This enables the
  programmed generation of names and labels, for example:
  for i=1 to 10 do { exec sprintf("A%g: x%g,y%g",i,2*i,3*i) }
 
A few additional mathematical functions are defined in dpic:
  "abs" "acos" "asin" "expe" "floor" "loge" "sign" "tan" "pmod"

color:
  From version 18, gpic allows coloured lines and filled objects as follows:
    <object> outlined "string"
    <object> shaded "string"
    <object> colored "string"
  where "string" is a colour included in quotes and where the third case
  is equivalent to
    <object> outlined "string" shaded "string"
  Dpic supports these very basic options with PSTricks and other output
  formats where postprocessing supports them. More elabourate PSTricks
  options can also be invoked. For example, the sequence
    box shaded "lightgray,fillstyle=hlines*,linecolor=blue,
      hatchwidth=0.5pt,hatchsep=5pt,hatchcolor=red,hatchangle=45"
  produces a hatched multicoloured fill and is equivalent to
    command "\pscustom[fillcolor=lightgray,fillstyle=hlines*,linecolor=blue,"
    command "hatchwidth=0.5pt,hatchsep=5pt,hatchcolor=red,hatchangle=45]{%"
      box
    command "}%"

Arbitrary filled paths:
  The unaugmented pic language and its gpic extensions do not allow the
  filling of arbitrary closed curves other than boxes, circles, and
  ellipses.  Use the \pscustom function of PSTricks as shown above for
  these.

Bounding boxes:
  The Postscript produced by dpic -r deserves attention because the
  output is not always meant to be imported into LaTeX or printed on
  paper.  For example, the output can be converted to formats suitable
  for Internet display.  However, because choice of line width, mitred
  joints, splines, over-painting, arbitrary text, arbitrary Postscript
  commands, and other complications are allowed within a diagram, dpic
  can only provide an estimate of the exact bounding box.

  For a while, the %%BoundingBox output line simply gave the nominal
  bounding box determined by line ends and other control points.  The
  use of dpic in server mode has induced a change that correctly
  defines the bounding box for very basic diagrams.  More explicitly,
  consider

  .PS
  box with .sw at 0,0
  .PE

  which draws a box with southwest corner line centres intersecting at
  Postscript coordinates 0,0 and northeast intersection at 54,36.
  Dpic -r augments this nominal bounding box by half of the last
  linethick value in the outermost diagram scope (default 0.8 pt) to
  produce the Postscript bounding-box definitions

  %%BoundingBox: -1 -1 55 37
  %%HiResBoundingBox: -0.4 -0.4 54.4 36.4

  The %%BoundingBox line contains integer values that enclose the
  high-resolution coordinates given in the next line.

  Tuning of the bounding box may be necessary.  To zero the above
  adjustment, put linethick=0 at the end of the outermost scope.  Then
  arbitrary margins can be added to the nominal box as shown below,
  where 2, 1, 1, and 0 Postscript points are added to the left, bottom,
  right, and top margins respectively:

  .PS
  Diagram: [
    drawing commands
    ]
  linethick = 0
  move from Diagram.sw-(2,1)/72*scale to Diagram.ne+(1,0)/72*scale
  .PE
