%
% This is the man-page source for dpic on Unix or Linux systems.
%
% BSD Licence:
% 
% Copyright (c) 2021, J. D. Aplevich
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions
% are met:
% 
% * Redistributions of source code must retain the above copyright
% notice, this list of conditions and the following disclaimer.
% 
% * Redistributions in binary form must reproduce the above copyright
% notice, this list of conditions and the following disclaimer in the
% documentation and/or other materials provided with the distribution.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY
% EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
% PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
% BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
% OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
% ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
% Use {\tt "} instead of ".
%
\phead{DPIC}{1}{2021.11.01}{}{}\shead{NAME}
dpic - convert pic-language input to LaTeX-compatible and other formats
\shead{SYNOPSIS}
{\tt dpic\ [\ -defghmprstvx\ ]\ [\ -z\ ]\ [}
{\it infile}
{\tt ]\ [$>$}
{\it outfile}
{\tt ]}

Typically,
{\it infile}
is of the form
{\it name}
{\tt [.pic]}
and
{\it outfile}
is of
\\\hbox{}\hskip-1pt
the form
{\it name}
{\tt .[tex$|$eps$|$pdf$|$fig$|$mp$|$svg]}
\shead{OPTIONS}
{\tt (none)}
LaTeX picture-environment output (very limited font-based drawing commands)
\\\hbox{}\hskip-1pt
{\tt -d}
PDF output, basic strings
\\\hbox{}\hskip-1pt
{\tt -e}
pict2e output
\\\hbox{}\hskip-1pt
{\tt -f}
Postscript output, strings in psfrag format
\\\hbox{}\hskip-1pt
{\tt -g}
TikZ-pgf output
\\\hbox{}\hskip-1pt
{\tt -h}
write help message and quit
\\\hbox{}\hskip-1pt
{\tt -m}
mfpic output (see mfpic documentation)
\\\hbox{}\hskip-1pt
{\tt -p}
PSTricks output
\\\hbox{}\hskip-1pt
{\tt -r}
raw Postscript output, no automatic string formatting
\\\hbox{}\hskip-1pt
{\tt -s}
MetaPost output
\\\hbox{}\hskip-1pt
{\tt -t}
eepicemu output (slightly less limited than LaTeX picture output)
\\\hbox{}\hskip-1pt
{\tt -v}
svg output
\\\hbox{}\hskip-1pt
{\tt -x}
xfig 3.2 output
\\\hbox{}\hskip-1pt
{\tt -z}
safe mode (access to external files disabled)
%
\shead{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.

\shead{LANGUAGE SUMMARY}
Input consists of a sequence of ASCII text lines.
The characters
{\tt LF}
(\textbackslash n) and
{\tt CR}
(\textbackslash r) have identical effect,
and
{\tt ETX}
(\textbackslash 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
{\tt .PS}
and the last is
{\tt .PE,}
with lines between
these two converted into low-level drawing commands for the postprocessor
chosen by the option.
Lines outside of
{\tt .PS\ ...\ .PE}
pass through dpic unchanged.
\par\hskip-2pc{\bf Coordinates}\\
Coordinate axes in the pic
language point to the right and up.
The drawing units are inches by default but the statement

{\tt \ \ scale\ =\ 25.4}

at the beginning of the diagram has the effect of changing
the units to millimetres.
%
\par\hskip-2pc{\bf Drawn objects}\\
The primitive drawn objects consist of the planar objects
{\tt box,\ circle,\ ellipse;}
the linear objects
{\tt line,\ arrow,\ move,\ spline;}
and
{\tt arc,}
which has characteristics of both planar and linear objects.
A
{\it block}
is a pair of square brackets enclosing other objects:
{\tt [}
{\it anything}
{\tt ]}
and is a planar object.
The complete diagram is contained implicitly in a block.

A
{\it 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
{\tt Here}
is always defined. 
Initially and at the beginning of a block,
{\tt Here}
is 0,0.
Similarly, the current direction, which can be any of
{\tt up,\ down,\ left,\ right,}
is set as
{\tt 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.
\par\hskip-2pc{\bf Labels}\\
A
{\it label}
in
pic
is an alphameric sequence that starts with an uppercase letter.
Dpic allows variables and labels to be subscripted; thus
{\tt T}
and
{\tt 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,

{\tt \ \ \ Post:\ Here\ +\ (1,2)}
\\\hbox{}\hskip-1pt
{\tt \ \ \ Bus[23]:\ line\ right\ 4}
\par\hskip-2pc{\bf Defined points}\\
Once drawn, a linear object has defined points
{\tt .start,\ .center,}
and
{\tt .end,}
which can be referenced as known positions, for example,

{\tt \ \ \ L:\ line;\ line\ up\ 0.5\ from\ L.c}

where
{\tt .center}
has been abbreviated as
{\tt .c}

The defined points for a planar object are the compass points
on its periphery given by
{\tt .n,\ .s,\ .e,\ .w,\ .nw,\ .ne,\ .se,\ .sw,}
together with
{\tt .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
{\tt .start}
and
{\tt .end.}

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

{\tt \ \ \ 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
% .br
   example,
{\tt A.ne}

   A position defined in the block, for example,
{\tt A.T}

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

   The defined points of enumerated objects inside the
% .br
   block, preceded by a dot (but make sure there is a space
% .br
   after the dot if it is followed by a number rather than
% .br
   an expression in braces), for example,
{\tt A.Q.\ 1st\ circle.n}
% .br
   or (better)
{\tt A.Q.\{1\}st\ circle.n}
\par\hskip-2pc{\bf Language elements}\\
The lines defining a picture are separated by newline characters
or semicolons.
Newlines are significant except after
{\tt 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
{\tt .PS}
and
{\tt .PE}
lines.

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

The language elements include the following:

   A drawing command with optional label, for example,
% .br
{\tt box}
or
{\tt A:\ box}

   A position-label definition, for example
{\tt A:}
{\it position}

   An assignment to a variable, for example
{\tt x = 5}

   A
{\it direction}
(to change the default), for example,
{\tt up}

Branching is performed by

{\tt \ \ \ if}
{\it expr}
{\tt then\ \{}
{\it dotrue}
{\tt \}\ else\ \{}
{\it dofalse}
{\tt \}.}

The looping facility is

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

The loop variable is incremented by 1 by default, otherwise by
{\it incr}
(which may be a negative expression)
unless it is preceded by the asterisk, in which case the loop variable
is multiplied by
{\it 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

{\tt \ \ \ \{}
{\it anything}
{\tt \}}

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

{\tt \ \ \ command}
{\it string,}

which inserts the contents of
{\it string}
into the output.
The
{\it 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

{\tt \ \ \ exec}
{\it string}

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

To execute operating-system shell commands, use

{\tt \ \ \ sh}
{\it string}

and to read lines from an external file, use

{\tt \ \ \ copy}
{\it string}

These commands are disabled by the
dpic
option
{\tt -z}
or by a compile-time switch.

The command

{\tt \ \ \ print}
{\it expr$|$position$|$string}
{\tt [\ $>$}
{\it string}
{\tt $|$\ $>$$>$}
{\it string}
{\tt ]}

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.

\par\hskip-2pc{\bf Macros}\\
The
pic
language includes macro definition and expansion, using either

{\tt \ \ \ define}
{\it name}
{\tt \{}
{\it anything}
{\tt \},}

or

{\tt \ \ \ define}
{\it name}
{\tt X}
{\it anything}
{\tt X,}

where X is any character except \{. When
{\it name}
appears alone or with arguments in parentheses as
{\it 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
{\tt \$1}
are replaced literally by the first argument (not by its value, if any),
and so on for other arguments.

The value
{\tt \$+}
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

{\tt \ \ \ undefine}
{\it name}

Macro definitions are global, which may require judicious
undefinition of macros if there is a risk of name clashes.
% \par\hskip-2pc{\bf Object sizes}\\
% Objects are drawn by specifying their size parameters
% .B "height, width, radius, diameter,"
% or truncated as
% .B "ht, wid, rad, diam,"
% respectively, as needed; for example,
% .P
% .B "   A: box [height"
% .I expr]
% .B [width
% .I expr]
% .P
% but a default value is used if any parameter is omitted.
% Thereafter, the size parameters of the object can be used
% in expressions, for example
% .P
% .B "   circle diam A.ht"
\par\hskip-2pc{\bf Drawing commands}\\
An object is drawn using the following general format:

{\it \ \ \ }
{\tt [}
{\it Label}
{\tt :]}
{\it object}
{\tt [}
{\it attributes}
{\tt ]\ [}
{\it placement}
{\tt ]\ [}
{\it strings}
{\tt ]}

The items following
{\it 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

{\tt \ \ \ circle {\tt "}Chew{\tt "}; arrow; box {\tt "}Swallow{\tt "}}
\\\hbox{}\hskip-1pt
{\tt \ \ \ line;\ arc\ cw\ -$>$;\ ellipse\ {\tt "}Digest{\tt "}}

draws a simple flow diagram using default sizes for all objects,
with centered words in the circle, box, and ellipse. 
%
\par\hskip-2pc{\bf Attributes}\\
An
{\it 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:

{\tt \ \ \ height$|$ht$|$width$|$wid$|$radius$|$rad$|$diameter$|$diam$|$scaled}
{\it expr}

When appended to linear objects,
{\tt height}
and
{\tt width}
apply to arrowhead dimensions.
The
{\tt scaled}
attribute scales the object by
{\it 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:

{\it \ \ \ string}
{\tt wid}
{\it expr}
{\tt ht}
{\it expr}

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

{\tt \ \ \ thickness$|$thick}
{\it expr}

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

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

{\tt \ \ \ solid$|$invisible$|$invis}

or with

{\tt \ \ \ dotted$|$dashed\ [}
{\it expr}
{\tt ]}

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:

{\tt \ \ \ $<$-$|$-$>$$|$$<$-$>$\ [}
{\it expr}
{\tt ]}

The default for
{\tt arrow}
objects is
{\tt -$>$.}
The shape parameter
{\it expr}
may be omitted, in which case the value of the environment variable
{\tt 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

{\tt \ \ \ ccw$|$cw}

with
{\tt ccw}
the default.

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

{\tt \ \ \ fill\ [}
{\it expr}
{\tt ]}

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

Line color can be set using

{\tt \ \ \ outline$|$outlined}
{\it 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

{\tt \ \ \ command}
{\it string}

facility so that the postprocessor will know about them.

Filling by color is similar, using the attribute

{\tt \ \ \ shaded}
{\it string}

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

{\tt \ \ \ colour$|$color$|$colored$|$coloured}
{\it string}

in which all four spellings are equivalent.

Finally, the attribute

{\tt \ \ \ 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
{\tt scale}
variable, the size of the complete picture can be set
by appending one or two terms to the
{\tt .PS}
line as shown:

{\tt \ \ \ .PS}
[x [y]]

where x and y evaluate to constant values.
On encountering the 
{\tt .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,

{\tt \ \ \ .PS\ 100/25.4}

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

If the final diagram width exceeds the environment variable
{\tt maxpswid}
or the height exceeds
{\tt maxpsht,}
both of which can be changed by assignment,
then the diagram is scaled as for x and y above.
% 
\par\hskip-2pc{\bf Placement of drawn objects}\\
An object is placed by default so that its entry is at
the current point.

Explicit placement is obtained with

{\it \ \ \ object}
{\tt at}
{\it position}

which centers the object at
{\it position,}
or

{\it \ \ \ object}
{\tt with}
{\it defined point}
{\tt at}
{\it position}

for example,

{\tt \ \ \ arc\ cw\ from}
{\it position}
{\tt to}
{\it position}
{\tt with\ .c\ at}
{\it position}

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

{\tt \ \ \ A:\ [}
{\it contents}
{\tt ]\ with\ (0.5,0.2)\ at}
{\it position.}

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

{\it linespec}
{\tt =\ from}
{\it position}
{\tt $|$\ to}
{\it position}
{\tt $|$}
{\it direction}
{\tt [}
{\it expr}
{\tt ]}
\\\hbox{}\hskip-1pt
{\tt \ \ \ \ \ \ \ \ \ \ $|$}
{\it linespec\ linespec}
\\\hbox{}\hskip-1pt
{\tt \ \ \ \ \ \ \ \ \ \ $|$}
{\it linespec}
{\tt then}
{\it linespec}

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

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

{\tt \ \ \ line\ up\ 2\ right\ 1.5\ then\ down\ 3\ then\ to\ Here}

Exceptionally, the
{\it linespec}

{\tt \ \ \ to}
{\it position}
{\tt to}
{\it position}
{\tt to\ ...}

is multiple and does not require the
{\tt then}
keyword, but this also means that the
{\it linespec}

{\tt \ \ \ up}
{\it expression}
{\tt to}
{\it position}

is multiple and creates a two-segment line.

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

{\tt \ \ \ spline}
{\tt [}
{\it expr}
{\tt ]}
{\it linespec}

for which the
{\it expr}
is a spline tension parameter.
If
{\it 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
{\it 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

{\tt \ \ \ continue}
{\it linespec}

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

The construction

{\tt \ \ \ line\ from}
{\it position}
{\tt to}
{\it position}
{\tt chop}
{\tt [}
{\it expr}
{\tt ]}

truncates the line at each end by the value of
{\it expr}
or, if
{\it expr}
is omitted, by the current value of environment variable
{\tt circlerad}

Otherwise

{\tt \ \ \ line\ from}
{\it position}
{\tt to}
{\it position}
{\tt chop}
{\it expr1}
{\tt chop}
{\it expr2}

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

The attribute

{\tt \ \ \ by}
{\it position}

is for positioning, for example,

{\tt \ \ \ move\ by\ (5,6)}
\par\hskip-2pc{\bf 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
{\tt x}
if it does not already exist in the current scope:

{\tt \ \ \ x\ =}
{\it 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

{\tt \ \ \ x\ :=}
{\it expr}

or any assignment using an operator in the set

{\tt \ \ \ :=\ +=\ -=\ *=\ /=\ \%=}

requires
{\tt 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:

{\tt \ \ \ \^{}}
\\\hbox{}\hskip-1pt
{\tt \ \ \ *\ /\ \%}
\\\hbox{}\hskip-1pt
{\tt \ \ \ +\ -}
\\\hbox{}\hskip-1pt
{\tt \ \ \ ==\ !=\ $>$=\ $<$=\ $<$\ $>$}
\\\hbox{}\hskip-1pt
{\tt \ \ \ \&\&}
\\\hbox{}\hskip-1pt
{\tt \ \ \ $|$$|$}

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
{\tt e}
syntax, a function value, a size value of a drawn object, for example,

{\tt \ \ \ last\ box.ht,}

or the horizontal or vertical coordinate of a
{\tt position,}
obtained respectively as

{\it \ \ \ position}
{\tt .x$|$.y}

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

The two-argument functions are
{\tt atan2,\ max,\ min,\ pmod}
where
{\tt pmod}
is the modulo function delivering a positive value.
% \par\hskip-2pc{\bf Scope of variables}\\
\par\hskip-2pc{\bf Predefined variables}\\
The following variables are predefined on invocation of dpic:
{\tt optTeX, opttTeX, optPict2e, optPSTricks, optPDF, optPGF,}
{\tt optMFpic, optPS, optPSfrag,}
\\\hbox{}\hskip-1pt
{\tt optMpost,}
and
{\tt optSVG.}
Variable
{\tt dpicopt}
is set according to the output option chosen, so that if one of options
{\tt -p}
or
{\tt -g}
has been invoked for example, then the test

{\tt \ \ \ if\ dpicopt\ ==\ optPSTricks\ $|$$|$\ dpicopt\ ==\ optPGF\ then\ \{\ ...\ \}}

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

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

If the
{\tt -x}
(xfig) option has been specified,
then the following two variables are predefined:
{\tt xfigres}
(default value 1200), and
{\tt xdispres}
(default 80).
\par\hskip-2pc{\bf 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

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

When a value is assigned to the environment variable
{\tt scale,}
all of the above values are multiplied by the new value of
{\tt 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
{\tt scale}
value on output.
The following are unaffected by
{\tt scale}
changes:

{\tt \ \ \ arrowhead\ \ \ \ 1\ \ \ }
arrowhead shape
\\\hbox{}\hskip-1pt
{\tt \ \ \ fillval\ \ \ \ \ \ 0.5\ }
fill density
\\\hbox{}\hskip-1pt
{\tt \ \ \ linethick\ \ \ \ 0.8\ }
line thickness in points
\\\hbox{}\hskip-1pt
{\tt \ \ \ maxpsht\ \ \ \ \ \ 11.5}
maximum allowed diagram height
\\\hbox{}\hskip-1pt
{\tt \ \ \ maxpswid\ \ \ \ \ 8.5\ }
maximum allowed diagram width

The variables
{\tt maxpswid}
and
{\tt maxpsht}
may have to be redefined for large diagrams or
landscape figures, for example.
\par\hskip-2pc{\bf Positions}\\
A
{\it position}
is equivalent to a coordinate pair defined in current drawing units,
and can be expressed in the following forms:

{\tt \ \ \ Here}
% .br
   The current drawing position.

{\it \ \ \ \ expr,expr}
% .br
   A pair of expressions separated by a comma.

{\tt \ \ \ (}
{\it position}
{\tt )}
% .br
   A position in parentheses for grouping.

{\tt \ \ \ (}
{\it position}
{\tt ,}
{\it position}
{\tt )}
% .br
   Takes the horizontal value from the first position and
% .br
   the vertical value from the second.

{\it \ \ \ \ position}
{\tt +$|$-}
{\it position}
% .br
   Vector addition.

{\it \ \ \ \ position}
{\tt *$|$/}
{\it expr}
% .br
   Scalar postmultiplication.

{\it \ \ \ \ Label}
% .br
   The label of a defined position or object.
The position
% .br
   is the center of the object.

{\it \ \ \ \ expr}
{\tt [of\ the\ way]\ between}
{\it position}
{\tt and}
{\it position}

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

{\it \ \ \ \ expr}
{\tt $<$}
{\it position, position}
{\tt $>$}
% .br
   An abbreviated equivalent of the previous form.

{\it \ \ \ \ number}
{\tt st$|$rd$|$nd$|$th\ [last]}
{\it object}
% .br
   An object within the current block, enumerated in order of definition.

   The
{\it object}
is one of

{\tt \ \ \ line,\ move,\ arrow,\ arc,\ box,\ ellipse,\ circle,\ spline,\ [],\ {\tt "}{\tt "} .}

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

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

Finally, a position can be given as

{\it \ \ \ object}
{\tt .}
{\it defined point}
\par\hskip-2pc{\bf Strings}\\
A
{\it 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
{\tt +}
operator.
The C-like function

{\tt \ \ \ sprintf(}
{\it format\ string,\ expr,\ ...}
{\tt )}

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
{\tt e,\ f,}
and
{\tt g.}

Multiple strings such as
{\it {\tt "}text1{\tt "} {\tt "}text2{\tt "}}
are stacked and centered vertically.

A string attached to an object overlays the object at the center, and
any
{\tt height}
or
{\tt width}
attributes apply to the object, not the string.
However, the justification attributes
{\tt ljust}
and
{\tt 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
{\it object,}
for example,

{\tt \ \ \ }
{\tt \ \ \ {\tt "}Animal\ crackers{\tt "}\ wid\ 82.3/72\ ht\ 9.7/72\ with\ .sw\ at\ Q}

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

{\tt \ \ \ {\tt "}Animal\ crackers{\tt "}\ at\ Q\ ljust\ above}

places the string above and
{\tt textoffset}
units to the right of
{\tt Q.}
\shead{EXAMPLES}
Source file example.pic:

{\tt \ \ {\tt \char92}documentclass\{article\}}
\\\hbox{}\hskip-1pt
{\tt \ \ {\tt \char92}usepackage\{tikz\}}
\\\hbox{}\hskip-1pt
{\tt \ \ {\tt \char92}begin\{document\}}
\\\hbox{}\hskip-1pt
{\tt \ \ .PS}
\\\hbox{}\hskip-1pt
{\tt \ \ box\ dashed\ {\tt "}Hello{\tt "}\ {\tt "}World{\tt "}}
\\\hbox{}\hskip-1pt
{\tt \ \ .PE}
\\\hbox{}\hskip-1pt
{\tt \ \ {\tt \char92}end\{document\}}

The command


{\tt \ \ \ 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 {\tt \char92}input command,
delete the first three and last lines in the above source
and process using the
{\tt -p}
option of
dpic.

Similarly, the picture source

{\tt \ \ .PS}
\\\hbox{}\hskip-1pt
{\tt \ \ {\tt \char92}definecolor\{puce\}\{rgb\}\{0.8,0.53,0.6\}\%}
\\\hbox{}\hskip-1pt
{\tt \ \ box\ shaded\ {\tt "}puce{\tt "}}
\\\hbox{}\hskip-1pt
{\tt \ \ .PE}

produces a box filled with a flea-like color when processed with
{\tt dpic\ -g}
or
{\tt dpic\ -p}
and the resulting file is inserted into a latex source file invoking,
respectively, the tikz or pstricks package.
\shead{SEE ALSO}

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

J. D. Aplevich,
{\it Drawing with dpic,}
2021,
% .br
\url{http://ece.uwaterloo.ca/~aplevich/dpic/dpic-doc.pdf}
% .br
(Specific discussion of dpic
facilities and extensions, with differences between dpic and GNU pic.)

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

J. D. Aplevich,
{\it M4 Macros for Electric Circuit Diagrams in LaTeX Documents,}
2021.
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.)
%
\shead{AUTHOR}
    Dwight Aplevich $<$aplevich at uwaterloo dot ca$>$
%   Copyright (c) 2021, J. D. Aplevich
%   .SH BSD licence:
%   .P
%   All rights reserved.
%   .P
%   Redistribution and use in source and binary forms, with or without
%   modification, are permitted provided that the following conditions
%   are met:
%   .P
%   * Redistributions of source code must retain the above copyright
%   notice, this list of conditions and the following disclaimer.
%   .P
%   * Redistributions in binary form must reproduce the above copyright
%   notice, this list of conditions and the following disclaimer in the
%   documentation and/or other materials provided with the distribution.
%   .P
%   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY
%   EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
%   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
%   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
%   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
%   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
%   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
%   BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
%   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
%   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
%   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
% .LP
% LIKE ANYTHING ELSE THAT'S FREE, DPIC AND ITS ASSOCIATED UTILITIES ARE
% PROVIDED AS IS AND COME WITH NO WARRANTY OF ANY KIND, EITHER EXPRESSED OR
% IMPLIED. IN NO EVENT WILL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DAMAGES
% RESULTING FROM THE USE OF THIS SOFTWARE.
%
% end of input file: <stdin>
%--------------------------------------------------
