DPIC(1)

🌸 NAME 🌸

okay so bestie, this is dpic(1) — from the General Commands Manual — and its whole personality is: convert pic-language input to LaTeX-compatible and other formats. literally its job. ✨

✨ SYNOPSIS ✨

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

Typically, infile is of the form name [.pic] but if this file is not given then the standard input is used. Outfile is typically of the form name .[tex|eps|pdf|fig|mp|svg] but if it is not given then the standard output is used. 🫶

💅 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. no cap.

🧚 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. cute and metric of it. 💖

🎀 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. lowkey iconic shorthand. 💅

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. bestie, watch those names. 😭

✏️ 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. slay little diagram. 🔥

🎨 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 as the default. Iconic little directional moment 💅

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. slay for path fills ✨

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. iykyk, the postprocessor is the main character here 🎀

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. four spellings, zero drama 💛

Finally, the attribute

same

duplicates the properties of the previously drawn object of the same type, but with the current default placement. copy-paste energy but make it legal 💖

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. so your text can absolutely spill the tea past the box, bestie 🫶

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. scale check: passed, maybe ✨

📍 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.

lower-left-corner girlies rise 🌸

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

triangle era 🔺✨

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. not me discovering extra segments 😭

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. spline tension: very demure, very mindful 🧚

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. continue is lowkey the plot twist 💜

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. negative chop? bold. iconic. 💅

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. scope check before you assign, bestie 🫶

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. math but make it make sense ✨

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. random girl math 🎲

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

🎀 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. conditional slay ✨

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. pixel density lore 🎀

If the -x (xfig) option has been specified, then the following two variables are predefined: xfigres (default value 1200), and xdispres (default 80). xfig besties, this one's for you 💅

🌸 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

the whole default-value lineup is here and accounted for, no cap 🌈

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. landscape figure girlies, adjust your limits 🫶

🗺️ 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.

positions understood, coordinates secured, vibe immaculate 💖✨

Okay so the next little syntax snack is:

expr < position, position >

It’s just an abbreviated equivalent of the previous form — same energy, shorter fit 💅

number st|rd|nd|th [last] object

That’s an object within the current block, enumerated in order of definition. The object is one of:

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

Your number can be swapped for { 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. Tiny caveat, not a vibe killer 🫶

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, 2024, 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, 2024. 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> — an icon, honestly 💖

That’s the DPIC(1) page, dated 2024.01.01 — bye bestie, go draw something iconic 🎀✨💅