Provided by: dpic_2014.01.01+dfsg1-0ubuntu1_amd64 
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)