%                               dpic-doc.tex
\documentclass[11pt]{article}
\usepackage{verbatim,url}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{multicol}
\usepackage{xspace}
\usepackage{wrapfig}
\usepackage{troffman}
\usepackage{tikz}
\usepackage{boxdims}
%                               Fix the table of contents:
\usepackage{tocloft}
%                               For links
\usepackage{bookmark}
\usepackage{pdfcomment}
%                               Fonts
\usepackage[T1]{fontenc}
\usepackage{lmodern}
%                               Adjust the page size
\addtolength{\textwidth}{3cm}
\addtolength{\hoffset}{-1.5cm}
\addtolength{\voffset}{-1.5cm}
\addtolength{\headsep}{-0.5cm}
\addtolength{\textheight}{4cm}
\setcounter{topnumber}{3}
%                               Minimum hyphenation length
\lefthyphenmin=3
\righthyphenmin=3
%                               Left-justified captions
\makeatletter
\long\def\@makecaption#1#2{%
  \vskip\abovecaptionskip
  \sbox\@tempboxa{#1: #2}%
  \ifdim \wd\@tempboxa >\hsize
    #1: #2\par
  \else
    \global \@minipagefalse
    \hb@xt@\hsize{\box\@tempboxa\hfil}%
  \fi
  \vskip\belowcaptionskip}

%\def\@date{February 01, 2015}
\makeatother
%                               Customizations
\newcommand{\bq}{}
\newcommand{\pic}{{\bq pic}\xspace}
\newcommand{\dvips}{{\bq dvips}\xspace}
\newcommand{\Pic}{{\bq Pic}\xspace}
\newcommand{\gpic}{{\bq gpic}\xspace}
\newcommand{\Gpic}{{\bq Gpic}\xspace}
\newcommand{\Dpic}{{\bq Dpic}\xspace}
\newcommand{\tpic}{{\bq tpic}\xspace}
%\renewcommand{\LaTeX}{{LaTeX}\xspace}
\newcommand{\mfpic}{{\bq mfpic}\xspace}
\newcommand{\groff}{{\bq groff}\xspace}
\newcommand{\xfig}{{\bq xfig}\xspace}
\newcommand{\PSTricks}{{\bq PSTricks}\xspace}
\newcommand{\MetaPost}{{\bq MetaPost}\xspace}
\newcommand{\Postscript}{{\bq Postscript}\xspace}
\newcommand{\dpic}{{\bq dpic}\xspace}
\newcommand{\Mfour}{{\bq m4}\xspace}
\newcommand{\TPGF}{{\bq Ti{\it k}z~PGF}\xspace}
%
\setlength{\parindent}{0pt}
\addtolength{\parskip}{1ex}
\newcommand{\ntt}[1]{\\\hbox{}\quad{\tt #1}}
\newcommand{\VL}{\hbox{$|$}}
\newcommand{\tRA}{{\tt\char62}}
\newcommand{\tBS}{{\tt\char92}}
\newcommand{\tLB}{{\tt\char123}}
\newcommand{\tRB}{{\tt\char125}}
%
\newcommand{\SR}[1]{\hyperref[#1]{Section~\ref*{#1}}}
\newcommand{\PR}[1]{\hyperref[#1]{page~\pageref*{#1}}}
\newcommand{\FR}[1]{\hyperref[#1]{Figure~\ref*{#1}}}
%
\hypersetup{
 pdflang=English,
 unicode=true,
 colorlinks=true,
 linkcolor=purple,
 citecolor=purple}

\begin{document}
%\title{Drawing with dpic}
%\author{Dwight Aplevich%
%\date{\the\day\ \monthname[\the\month]\ \the\year}
%\footnote{Copyright \textcopyright\ \the\year\ J.\ D.\ Aplevich,
%all rights reserved.  This document version is made available
%under the Creative Commons attribution licence version 3.0
%(\protect{\tt http://creativecommons.org/licenses/by/3.0/});
%you are free to copy
%and distribute this document provided proper attribution is given by
%identifying the author.
%}}
%\maketitle%
%
\begin{centering}
{\LARGE Drawing with dpic}\\
{\large
Dwight Aplevich%
\footnote{Copyright \textcopyright\ \the\year\ J.\ D.\ Aplevich,
  all rights reserved.  This document version is made available
  under the Creative Commons attribution licence version 3.0
  (\protect{\tt http://creativecommons.org/licenses/by/3.0/});
  you are free to copy
  and distribute this document provided proper attribution is given by
  identifying the author.
  }\\
%\the\day\ \monthname[\the\month]\ \the\year}\\
\input{VERSION.tex}}\\
\end{centering}

%
\pdfbookmark[section]{\contentsname}{toc}
\begin{multicols}{2}
\tableofcontents
\end{multicols}
\section{Introduction}

This document is meant for persons using dpic to produce diagrams for
\LaTeX\ documents or web files.  You are assumed to have basic knowledge
of the pic language as described for the original Documenter's
Workbench (ATT) pic~\cite{KRpic} or the
current GNU pic (gpic) processor~\cite{Raymond95}.
However, a concise dpic language reference is included here in
Appendix~A, and the context-free dpic input grammar is given in Appendix~B.

The pic ``little language''
is particularly suited for easily creating line diagrams
such as electric circuits, and many persons use a set of macros
called Circuit\_macros, which are processed using the m4 macro processor
and \dpic.
The pic language itself allows macro definitions, and both pic and m4 macros
will be described.

Many other software tools can produce line diagrams and the choice of
tool is often subjective or a matter of prior knowledge. The advantages of
\dpic\ are that its basic use is easy to learn and that
arbitrary formatted diagram text can be included using \LaTeX.
\Dpic\ will also produce
SVG output for web files but the advantage of employing a word processor
for text is not then directly available. A route to sophisticated text
in SVG is to use \LaTeX\ to produce a pdf file, followed by a pdf-to-svg
converter.

\Dpic accepts gpic input for the most part but
there are minor differences.  The outputs of gpic and dpic are quite
different but both can serve as preprocessors that create diagrams for
inclusion in \LaTeX\ documents.

\Dpic usage will be reviewed, some programming examples that illustrate
dpic extensions of the pic language will be given, and then
the differences among pic translators will be itemized, particularly
the differences between gpic and dpic.

   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 (ATT) pic, with gpic, or dpic.  There are
   exceptions: embedded word-processor commands principally,
   but also minor differences in defaults for valid pic input, a few
   gpic constructs that dpic does not implement directly, and some dpic
   extensions that gpic does not implement.
   For details, see \SR{Diffs:}.

\section{Dpic usage}\label{Usage:}
In the following, items in square brackets [~] are optional
and items separated by a vertical line~\VL~are alternatives.
To produce .tex output (for \LaTeX, \PSTricks, TikZ-PGF, \mfpic
   processing):
   \ntt{dpic {\rm[}{\sl options}{\rm]} {\sl file}.pic \tRA\ {\sl file}.tex}\\
   or
   \ntt{cat {\sl file}.pic | dpic {\rm[}{\sl options}{\rm]} 
     \tRA\ {\sl file}.tex}

To produce other formats:
   \ntt{dpic
   {\rm[}-d{\VL}e{\VL}f{\VL}g{\VL}h{\VL}m%
    {\VL}p{\VL}r{\VL}s{\VL}t{\VL}v{\VL}x{\rm]}
   {\rm[}-z{\rm]}
   {\sl file}.pic
     \tRA\ {\sl file}{\rm[}.tex{\VL}eps{\VL}pdf{\VL}mp{\VL}fig{\VL}svg{\rm]}}

\pagebreak
\subsection{Options}
\Dpic accepts the following options:
\begin{tabbing}
\quad\=\hbox{(none)\ }\= \kill
\> (none) \> Latex picture-environment output (very limited font-based
 drawing commands)\\
\> {\tt -d} \> PDF output \\
\> {\tt -e} \> pict2e output \\
\> {\tt -f} \> Postscript output with psfrag strings \\
\> {\tt -g} \> TikZ-PGF output \\
\> {\tt -h} \> write out these options and quit \\
\> {\tt -m} \> mfpic output \\
\> {\tt -p} \> PSTricks output \\
\> {\tt -r} \> raw Postscript output \\
\> {\tt -s} \> MetaPost output \\
\> {\tt -t} \> eepicemu output \\
\> {\tt -v} \> SVG output \\
\> {\tt -x} \> xfig 3.2 output \\
\> {\tt -z} \> safe mode (disabled {\tt sh}, {\tt copy}, and print to file)
\end{tabbing}

The {\tt -p} option produces output for postprocessing by the
\LaTeX\ package \PSTricks.
Similarly, the {\tt -g} option produces output
for the TikZ-PGF packages and makes pdf production
via pdflatex a one-step process.

Mfpic and \MetaPost output are provided for
compatibility.

The {\tt -r} option produces \Postscript\ {\tt .eps}
files, in which font changes or typesetting must be done explicitly.
% Output in this form can be imported into CorelDraw and Adobe Illustrator. 
The {\tt -f} option writes \Postscript strings in psfrag
format for tex or latex typesetting.

The {\tt -d} option produces PDF files.
This format is most useful for diagrams containing graphics only, since
there is no simple way to change or manipulate fonts for labels.
The Courier fixed-width font is employed by default.
To produce PDF files containing significant text content,
use an option such as TikZ with pdflatex.

The {\tt -v} option produces SVG for inserting figures into web documents or for
further processing by the Inkscape graphics editor, for which SVG is the
native format.
When the SVG output is used directly in a web document,
then any required text formatting generally must be included explicitly.
One other possibility for SVG output is that an SVG library of elements
can be drawn with dpic, and Inkscape used to place and connect copies
of the elements.  Then Inkscape can export the graphics as eps for
processing by \LaTeX\ or as pdf for processing by pdflatex.  Inkscape
will also export a tex file from which labels can be formatted and
overlaid on the imported eps or pdf. A third possibility
is to produce the graphic without text and then overlay the text elements.

The {\tt -z} option disables the commands that access external files.
These commands can be permanently disabled by the use of a compile-time
option.

In all cases, arbitrary postprocessor commands (that is, arbitrary \PSTricks,
SVG, \Postscript, or other commands) can be inserted into the dpic output
directly from the source.
This possibility adds considerable power for manipulating diagram
elements.
% at the expense of integrating them into normal dpic output.

The use of output formats meant to be processed by \LaTeX\ is quite different
from the other formats.  If a word processor is not part of the process,
the selection and formatting of diagram text
requires the insertion of postprocessor commands into the output.
Dpic knows nothing of text formatting except for SVG output, for which
basic sizing and placement are provided.

The file Examples.txt contains a minimal example of each of these
options except {\tt -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:
\begin{verbatim}
  .PS
  dtor = atan2(0,-1)/180
  for d = 0 to 360 by 2 do {
    line from (0,0) to (cos(d*dtor),sin(d*dtor))
    }
  line from (-1.2,0) to (1.2,0)
  line from (0,-1.2) to (0,1.2)
  .PE
\end{verbatim}


\subsection{Error messages}
%\vspace*{-\baselineskip}
The following is an example of an error message:
\begin{verbatim}
*** dpic ERROR: in macro "A", file "B.pic" line 16:
x = y
Variable not found
Search failure for "y"
\end{verbatim}
Dpic displays the input file name with the number of the line to which
scanning has progressed.  The name of the current macro is also given
if one is being executed.  Most often, scanning stops on or near the
offending line, which is displayed up to where reading ceased.  However,
the source of the problem might be a considerable distance from the
indicated line number if the error is in a for loop or a macro.  In the above
example, line 16 of file B.pic happens to be
\ntt{A(5)}\\
which invokes macro {\tt A,}
so one has to find the definition of {\tt A} and look for the line
\ntt{x = y}\\
within it.

Syntax error messages show the offending line and state the lexical
object that was found at or immediately before the error, together with
expected (permissible) objects.  Other errors are signalled according
to the circumstances.


%\enlargethispage{\baselineskip}
\section{Dpic programming}
%\vspace*{-\baselineskip}
Pic is a simple language with a good ratio of power to complexity, so
surprisingly sophisticated diagrams can be produced in several areas of
application.
Arbitrary postprocessor commands can be included in the output and several
of the postprocessors are powerful drawing languages in their own right,
so it can be argued that dpic has all the power of these languages.
However, if you find yourself writing extensive postprocessor code then
you might ask why you are not programming exclusively in that language.
Similarly, pic floating-point operations and macro facilities allow complex
numerical computations at the price of number-crunching in an interpreted
language, but sometimes there is convenience in calculating plotted
values in the same source as graphing them.

Pic is very suitable for line diagrams, and recent language extensions
allow for basic color.  Elaborate fills and cropping are the domain of
the postprocessors, but can be included easily with the use of macros.

The following sections are intended to help you become familiar
with dpic language syntax.  Some of these details
are exclusive to dpic and are not described in the GNU manual
but are discussed in \SR{Diffs:} of this document.

\subsection{Blocks}
The basic planar objects in pic are {\tt box}, {\tt circle}, and {\tt ellipse},
the placing of which is done according to the current drawing direction or
by explicit placement such as
\ntt{box at {\sl position}}\\
which places the object so that its center is at {\sl position}.

A block (or a composite object) is a group of elements enclosed by square
brackets, such as
\ntt{Q: [ B: [A: arc]; circle ]}.\\

\subsubsection{Positioning blocks}
A block is placed by default as if it were a box, after which the
compass points
({\tt Q.n}, {\tt Q.sw},~$\ldots$ in the previous example)
are automatically defined as for a box of the same size and position.

A block can also be positioned by specifying the location of
one of its defined points.  A defined point is one of the following:
\begin{enumerate}
 \item A compass corner {\tt .center}, {\tt .n}, {\tt .ne},~$\ldots$
  of the block, e.g.,
   \ntt{ Q: [ B: [A: arc]; circle ] with .ne at {\sl position}}
 \item A defined point of a labeled object or position within the
   block, preceded by a dot, e.g.,
   \ntt{ Q: [ B: [A: arc]; circle ] with .B.A.ne at {\sl position}}
\item A defined point of an enumerated object in the block,
 preceded by a dot (but make sure there is a space after the dot if it
 is followed by a number), e.g.,
\ntt{ Q: [ B: [A: arc]; circle ] with .\ 1st circle at {\sl position}}\\
 Even better, put braces around the ordinal value, which can now be
 any expression, e.g.,
\ntt{~$\ldots$ with .\tLB{}10-9\tRB{}th circle at~$\ldots$}
\item A displacement {\tt (x,y)} from the lower left corner of the block, e.g.,
\ntt{ Q: [ B: [A: arc]; circle ] with (0.5,0.2) at {\sl position}}
\end{enumerate}
Reference to a defined point
 may correspond to drilling down through several block layers,
 as the second example above shows.

\subsubsection{Defining scope}\label{Scope:}
Variables defined within a block are accessible only within the block
itself or its sub-blocks.
Thus, the statement {\tt x = 5} creates the variable {\tt x}
and assigns it a value.  If the statement is {\tt x~:=~5} then {\tt x}
must already have been defined either in the block or in a scope
containing the block.  Limiting the scope to a block avoids name conflicts
but occasionaly results in subtle behavior. The code 
\ntt{x = 5}
\ntt{[ x = x + 2; print x ]}
\ntt{print x}\\
prints 7 on the first line and 5 on the second because the assignment
within brackets creates variable {\tt x} with scope within the brackets.
However, \Dpic allows a second line of the form
\ntt{[ x += 2; print x ]}\\
which changes the previously defined variable {\tt x} and the value
7 is printed twice.

Locations inside a block are accessible
from outside as shown in the previous section,
but the values of variables are not; thus, an error results from
\ntt{Q: [ v = 5 ]; y = Q.v}\\
The {\tt :=} assignment operator in
\ntt{v = 0; Q: [ v := 5 ]; y = v}\\
works around this problem, but this method requires the internal name {\tt v}
to be known and defined in advance of the block.

Variable values can be exported by the use of macro arguments as shown
later in \SR{Macros:} or, if you must, by using the following trick:
\ntt{Q: [ v = 5; w = 6}
\ntt{\quad Origin:\ (0,0); Export:\ (v,w) ]}
\ntt{v = Q.Export.x - Q.Origin.x}
\ntt{w = Q.Export.y - Q.Origin.y}\\
This method works because all locations ({\tt Origin} and {\tt Export})
inside the block will be
translated by the same amount no matter where the block is positioned.

\subsection{Dpic macros}\label{Macros:}
Macros can be used to turn the basic dpic language into a powerful
tool for producing line drawings. A macro serves to
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}
\item specialize the pic language in order to draw components from an
  application area
\item abbreviate long sequences of repetitive commands
\item substitute particular values in commands by the use of macro arguments
\item provide conditional text replacement depending on the value of its
 arguments
\item provide recursive looping
\end{itemize}
Macro definitions are not local to blocks so care must be taken
to avoid conflicts with macro names.

The pic language includes basic macro facilities, but the m4 macro processor
\cite{KRm4,Seindal94} makes a good companion to the language, so both will
be mentioned.
General-purpose macro definitions can be stored in files external to the
diagram source and read in automatically.
In particular, the author has written a package
called Circuit\_macros~\cite{Aplevich09} for drawing electric circuits
and other diagrams using dpic and m4,
from which examples will be taken.

%\subsection{Dpic macros}
A dpic macro is defined by the statement
\ntt{define {\sl name} \tLB\ {\sl contents} \tRB}\\
where {\sl name} may begin with a lowercase or uppercase letter.
The form
\ntt{define {\sl name} X {\sl contents} X}\\
is also allowed, where {\tt X} is any character except \tLB.
Then any separate appearance of {\sl name} in the following lines is replaced
by the {\sl contents} characters, including newlines.
If the name is given arguments of the form
\ntt{{\sl name}({\sl x, y, z,~$\ldots$})}\\
then, in the macro body,
 {\tt\$}$n$ expands to the $n$th argument, which may be nul, if
  at least one argument has been defined and $n$ is a positive integer.
  Otherwise {\tt\$}$n$ is not evaluated.

The line
\ntt{undefine {\sl name}}\\
deletes the macro definition.

\Dpic skips white space immediately preceding macro arguments so that,
 for example, 
\ntt{{\sl name}( x, }
\ntt{ y, z )}\\
is equivalent to
\ntt{{\sl name}(x,y,z )}

In a macro invocation, the arguments are separated by commas.  An argument
may contain commas if they are enclosed within strings or
{\tt (~)} parentheses.  A double quote character within a string
must be preceded by a backslash.
Thus, for example, the macro invocation
\ntt{{\sl name}(ABc"{\textbackslash}"t,"(,DE,F))}\\
has one argument.

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

To check whether an argument is null, put it in a string; for example,
\ntt{if "\$3" == "" then \{ $\ldots$ \}}

Values internal to a scope can be passed back through macro arguments
with the {\tt :=} operator;
thus, executing the following
\ntt{define m \{[ v = 5; \$1 := v ]\}; y = 0; m(y)}\\
gives {\tt y} the internal value of {\tt v}.
Notice that {\tt y} must be defined prior to macro expansion.

The use of macros will be illustrated in the following examples, for which
source can be found in the {\tt dpictools.pic} file in the
Circuit\_macros distribution~\cite{Aplevich09}.

\subsubsection{Finding roots}
A root finder is a powerful tool for determining where lines or
curves intersect in diagrams, and can be implemented using
a macro.
Consider the trivial example in which
we wish to find the root of $x^2-1$ between $0$ and $2$.
First, define a macro called {\tt bisect} by reading in a library file
containing definitions using a command such as
\ntt{copy "{\sl filename}"}\\
or by writing a definition such as given below, which employs
the method of bisection,
a suitably robust (but not particularly fast) algorithm.
Define the two-argument macro corresponding to the function
of which we want to calculate the root:
\ntt{define parabola \tLB\ \$2 = (\$1)\char94{}2 - 1 \tRB}\\
In general, many statements might be required to calculate the function,
but the essential statement is to assign the function value to the name given
by the second argument.
Then call the {\tt bisect} macro using a command such as
\ntt{bisect( parabola, 0, 2, 1e-8, x )}\\
where the second and third arguments define
the search interval, the fourth argument specifies the solution
precision, and the fifth argument is the name of the variable to be set
to the root.  A basic version of {\tt bisect} is given by
\begin{verbatim}
define bisect {
  x_m = $2; x_M = $3
  x_c = (x_m+x_M)/2
  if (abs(x_m-x_M) <= $4) then { $5 = x_c } else {
     $1(x_m,f_m)
     $1(x_c,f_c)
     if (sign(f_c)==sign(f_m)) then { bisect($1,x_c,x_M,$4,$5) } \
     else { bisect($1,x_m,x_c,$4,$5) } }
  }
\end{verbatim}
%\begin{wrapfigure}[12]{r}{0.4\textwidth}%
\begin{wrapfigure}[9]{r}{0.4\textwidth}%
  \vspace*{-4\baselineskip}%
  \hspace*{1em}%
  \parbox{0.4\textwidth}{\input{Spiral.tex}}%
 \end{wrapfigure}%

This macro repeatedly calls {\tt parabola} and then itself,
halving the search interval until it is smaller than the
prescribed precision.
The Circuit\_macros library version
operates essentially as above but avoids name clashes by appending
the value of the first argument to the internal names.

A somewhat more sophisticated use of a root finder is shown at the right.
Drawing the spiral on the surface of the sphere requires knowing the
points of transition of the curve from visible to hidden and back.
A root finder provides
a method that is both simple and adaptable to other shapes.
The source file {\tt Spiral.m4} makes use of both m4 macros and pic macros.

\subsubsection{Composing statements}
\Dpic macro arguments can be expanded almost anywhere.
Suppose that circles {\tt A} and {\tt B} have been
defined, with intersections at positions {\tt AB} and {\tt BA} found
using the macro {\tt cintersect} from Circuit\_macros, for example.
Then the boundary of the region within both circles might be drawn using the
macro shown, invoked as {\tt lozenge(A,B)}:
\begin{verbatim}
define lozenge {
  arc from $1$2 to $2$1 with .c at $2
  arc from $2$1 to $1$2 with .c at $1 }
\end{verbatim}
\smash{\hspace*{4in}\input circles.tex}%
\vspace*{-\baselineskip}

\subsubsection{Evaluating arguments}
A macro argument is referenced as {\tt\$}$n$,
where $n$ must be an integer and
may not be an integer expression.  Consequently, the following does
not work in a \dpic macro:
\ntt{for j=1 to \$+ do \tLB\ c[j] = \$j \tRB}\\
Instead, use the dpic statement
\ntt{exec {\sl string}}\\
which executes the contents of {\sl string} as if it were
the current input line.
Since
\ntt{sprintf("{\sl format}",{\sl expression},$\ldots$)}\\
behaves like a string, the following works:
\ntt{for j=1 to \$+ do \tLB\ exec sprintf("c[j] = \$\%g",j); \tRB}

Macro arguments are passed verbatim, as for example,
{\tt function(x,y+z)}, inside which {\tt \$1} is replaced by {\tt x}
and {\tt \$2} is replaced by {\tt y+z}.
To pass arguments by value, use {\tt exec sprintf ...}, for example,
{\tt exec sprintf("function(\%g,\%g)",x,y+z)}.
The recursive calls near the bottom of the sorting algorithm shown
are another example:
\begin{verbatim}
#                               dpquicksort(a,lo,hi,ix)
#                               Given array a[lo:hi] and index
#                               array ix[lo:hi] = lo,lo+1,lo+2,...hi, sort
#                               a[lo:hi] and do identical exchanges on ix
define dpquicksort { [ if $3 > $2 then {
  pivot = $1[($2+($3))/2]
  loop(lo = $2; hi = $3, lo <= hi,
    loop(,$1[lo] < pivot, lo = lo + 1)
    loop(,$1[hi] > pivot, hi = hi - 1)
    if lo < hi then {
      tmp = $1[lo]; $1[lo] := $1[hi]; $1[hi] := tmp
      tmp = $4[lo]; $4[lo] := $4[hi]; $4[hi] := tmp }
    if lo <= hi then { lo = lo + 1; hi = hi - 1 } )
  if hi > $2 then { exec sprintf("dpquicksort($1,%g,%g,$4)",$2,hi) }
  if lo < $3 then { exec sprintf("dpquicksort($1,%g,%g,$4)",lo,$3) }
  } ] }
\end{verbatim}

\subsubsection{Branching}\label{Branching:}
Pic has a basic if-statement of the form
\ntt{if {\sl expression} then \tLB\ {\sl if-true} \tRB\ else
 \tLB\ {\sl if-false} \tRB}\\
but lacks a case statement.  Multiple branches
can be defined by nested {\tt if} statements but there is another way.
The macro
\ntt{define case \tLB\ exec sprintf("\$\%g",floor(\$1+0.5)+1); \tRB}\\
adds 1 to its rounded first argument to determine which
alternative among the remaining arguments should be executed.
The semicolon (or a newline) forces
dpic to perform the {\tt exec} statement before leaving the macro.
For example,
\ntt{case(2,}
\ntt{\quad print "A",}
\ntt{\quad print "B")}\\
executes the second alternative (the third argument) and prints B.

A semicolon or newline is also required in
the following {\tt if} test with an {\tt else} clause:
\ntt{if (sh "test -f fileA.pic")==0 then \tLB $\;$ copy "fileA.pic"; \tRB \tBS}
\ntt{else \tLB $\;$ copy "fileB.pic" \tRB}\\
The semicolon ensures that the {\tt copy} command completes before exiting
the first pair of braces.

\subsection{Hiding variables}
As mentioned in \SR{Scope:}, locations inside a block are accessible
from outside, but the values of variables are not.  Therefore, a block
can be used to hide variables internal to a macro, as in the following example:
\begin{verbatim}
define rgbtohsv { $4=0; $5=0; $6=0; [
  r = $1; g = $2; b = $3
  maxc = max(max(r,g),b)
  minc = min(min(r,g),b)
  if maxc==minc then { $4 := 0 } \
  else {if maxc == r then { $4 := pmod(60*((g-b)/(maxc-minc)),360) } \
  else {if maxc == g then { $4 := 60*((b-r)/(maxc-minc)) + 120 } \
  else                    { $4 := 60*((r-g)/(maxc-minc)) + 240 }}}
  if maxc == 0 then { $5 := 0 } else { $5 := 1 - (minc/maxc) }
  $6 := maxc
  ] }
\end{verbatim}
The three assignments in the first line of the example
ensure that the variables exist when the {\tt :=} assignments
are performed.

This is not the full story, however. Macro arguments are called by name
rather than by value; should the fourth argument, for example, be
literally {\tt x[minc]}, then the interior variable {\tt minc} prevails.
A block is only a partial solution to the problem of hiding variables, and
care must be exercised in chosing the names of arguments.
A more robust solution is to call by value using {\tt exec}; thus,

{\tt exec sprintf("rgbtohsv(\%g, \%g, \%g, h, s, v)",%
{\sl expr1},{\sl expr2},{\sl expr3})}

In this case however, the last three arguments remain vulnerable to
name clashes and should be named with care.

When, as in the example, no drawing commands appear in a {\tt [ ]} block,
then the block has zero size but has position {\tt Here} so the block
can affect the diagram bounding box if {\tt Here} happens to be outside the
bounding box of drawn elements. An alternative to this complication is to
omit the {\tt [ ]} brackets and rename the local variables to avoid
name clashes. For example, {\tt r} above could be {\tt r\_rgbtohsv} and
so on for other variables. 

\subsection{Looping}
The pic language includes a basic for-loop, such as the following:
\ntt{for x = 1 to 10 by 2 do \{ print x \}}\\
but there is no explicit language element (except macro recursion)
for executing a block of code an
indefinite number of times. However, the {\tt for} variable can be reset
within the executable code, as in the following example where
the first macro argument is printed and doubled
repeatedly until it becomes greater than the second argument:
\ntt{define series \{ x = \$1; for i=1 to 2 do \{}
\ntt{  if x \tRA\ \$2 then \{ i = 2 \} else \{ print x; x = x*2; i=1 \} \} \}}

If this trick seems like an abuse of language, it can be disguised somewhat
by the definition of a C-like loop. For example, suppose we wish to
write
\ntt{loop(\ x=1,\ x<10,\ x*=2,}
\ntt{ \ loop(\ y=1,\ y<=4,\ y+=1,}
\ntt{ \ \ print (x,y)\ )\ )}

Then the following defines a suitable mechanism with a loop depth index to
allow nesting:
\ntt{ld\_\_ = 0}
\ntt{define loop \{ld\_\_+=1; \$1}
\ntt{\ for lx\_\_[ld\_\_]=0 to 1 do \{}
\ntt{\ \ if \$2 then \{ lx\_\_[ld\_\_]=0; \$4; \$3 \}
 else \{lx\_\_[ld\_\_]=1\}\}}
\ntt{\ ld\_\_-=1;\}}

However, {\tt loop()} is a macro, so references to arguments
in the body will refer to {\tt loop()} arguments, which may not be desired.
In that case, use a {\tt for} loop.

\subsection{Complex numbers}
A complex number is an ordered pair of real numbers like a
position, so it is natural to do complex algebra using macros such as
the following example, which evaluates the
product of two complex-number arguments:
\ntt{%
  define Zprod \{ ( \$1.x*\$2.x - \$1.y*\$2.y, \$1.y*\$2.x + \$1.x*\$2.y ) \} }

\subsection{M4 macros}
M4 is a simple but powerful macro language originally distributed with
Unix systems \cite{KRm4}, but free versions are available for
other operating systems.  The use of this language requires an extra
processing step, but the power and flexibility of the macros easily
make up for it.  The macro definitions are read before the text to
be processed, typically by a system command such as
\ntt{m4 {\sl configurationfile}.m4 {\sl diagram}.m4 | dpic -g
 \tRA\ {\sl diagram}.tex}

An m4 macro is defined as follows:
\ntt{define(`{\sl name}',`{\sl contents}')}\\
so that distinct occurrences of {\sl name} will be replaced by {\sl contents}
in the following text. This basic description is a vast simplification
of the power that results from conditional substitution,
recursion, file inclusion, integer arithmetic, shell commands, and
multiple input and output streams.  The online manual \cite{Seindal94}
is a good source of details.

A general rule might be that floating point computation is in the domain
of dpic macros but text substitution is often better done in m4 macros.

When m4 reads text, it strips off pairs of single quotes: thus,
{\tt `text'} becomes {\tt text}.  If {\tt text} is read again, as
when it is a macro argument, for example, then the process is repeated.
The single quotes serve to delay the evaluation of macros within
{\tt text}, as in macro definitions described above.  Therefore, to
avoid m4 changing dpic macro definitions or \LaTeX, enclose
them in single quote pairs.

Some simple applications of m4 macros are illustrated in the subsections
that follow.

\subsubsection{M4 branching}
As an illustration of m4 macros, suppose that commands
that are specific to the postprocessor must be generated.
Then the macro
\ntt{ifpgf(`{\sl pgf-specific commands}',`{\sl other commands}')}\\
for example,
should expand to its first argument if pgf is to be the postprocessor, otherwise
it should expand to the second argument.  To implement this, {\tt ifpgf}
is defined in the statement
\ntt{define(`ifpgf',`ifelse(m4postprocessor,pgf,`\$1',`\$2')')}\\
which tests for equality of the character sequences {\tt m4postprocessor}
and {\tt pgf}.  However, if {\tt m4postprocessor} is a macro,
it is replaced by the macro text before the test is performed,
and if the macro text is {\tt pgf}, then
the first argument of {\tt ifpgf} is evaluated.  In the Circuit\_macros package,
m4 is required to read a postprocessor-specific file before anything
else, and that file contains the required definition of {\tt m4postprocessor}.

The built-in macro {\tt ifelse} can have multiple branches, as illustrated
below:
\ntt{ifelse(m4postprocessor,pstricks,`{\sl PSTricks code}',}
\ntt{  m4postprocessor,pgf,`{\sl TikZ PGF code}',}
\ntt{  m4postprocessor,mfpic,`{\sl Mfpic code}',}
\ntt{  m4postprocessor,mpost,`{\sl MetaPost code}',}
\ntt{  m4postprocessor,xfig,`{\sl Xfig code}',}
\ntt{  m4postprocessor,postscript,`{\sl Postscript code}',}
\ntt{  m4postprocessor,pdf,`{\sl PDF code}',}
\ntt{  m4postprocessor,svg,`{\sl SVG code}',}
\ntt{  `{\sl default code}')}

%\enlargethispage{\baselineskip}
\subsubsection{Extending pic: perpendiculars}
The Circuit\_macros {\tt vperp} macro illustrates how m4 macros can extend
the pic language.  The purpose is to generate a pair of values representing
the unit vector perpendicular to a given line, say.
\vspace*{-0.5\baselineskip}
\begin{verbatim}
define(`vperp',
 `define(`m4pdx',`(`$1'.end.x-`$1'.start.x)')dnl
  define(`m4pdy',`(`$1'.end.y-`$1'.start.y)')dnl
  -m4pdy/vlength(m4pdx,m4pdy),m4pdx/vlength(m4pdx,m4pdy)')
\end{verbatim}
The macro can be invoked as {\tt vperp(A)} where {\tt A} is the name of a line.
Another invocation might be {\tt vperp(last line)}.
First, two macros (beginning with {\tt m4} to avoid name clashes) are defined
as the $x$-distance $dx$ and $y$-distance $dy$ of the end of the line from
the start.  The macro evaluates to the pair
$-dy/\sqrt{(dx)^2+(dy)^2},\,dx/\sqrt{(dx)^2+(dy)^2},$ where the denominators
are calculated by the macro {\tt vlength}.

\subsubsection{Setting directions}
The pic language defines the concept of the current drawing direction, which
is limited to {\tt up}, {\tt down}, {\tt left}, and {\tt right}.
Two-terminal circuit elements, for example, might have to be drawn in
any direction, which calls for the ability to define diagrams without
knowing their final orientation and to rotate the result at will.
This capability can be added to the basic pic language
by judicious use of macros.

First, instead of specifying positions in the usual way, such as in
\ntt{line from (x1,y1) to (x2,y2)}\\
for example, let us agree to write
\ntt{line from vec\_(x1,y1) to vec\_(x2,y2)}\\
where {\tt vec\_(x1,y1)} evaluates to
\ntt{(a*x1 + b*y1, c*x1 + d*y1)}\\
Then if {\tt a} and {\tt d} are {\tt cos(theta)}, {\tt b} is
{\tt -sin(theta)}, and {\tt c} is {\tt sin(theta)}, this transformation
corresponds to rotating the argument vector by an angle {\tt theta}.
To produce relative coordinates, the macro {\tt rvec\_(x,y)}
evaluates to
\ntt{Here + vec\_(x,y)},\\
so writing
\ntt{line to rvec\_(x1,y1)}\\
draws a line from the current position
{\tt Here} to a point {\tt (x1,y1)} defined with respect to rotated
coordinates relative to {\tt Here}.

The Circuit\_macros package makes extensive use of versions of the above two
macros.
The angle and transformation constants are set using macros
\ntt{Point\_({\sl degrees})}, {\tt point\_({\sl radians})},
or {\tt setdir\_(}{\tt[U|D|L|R|}{\sl degrees}{\tt],}{\sl default}{\tt)}\\
which have angles as arguments.

This usage is illustrated by the macro {\tt lbox}, which draws a
pic-like box oriented in the current direction. It can be defined as
\begin{verbatim}
define(`lbox',
 `define(`m4bwd',ifelse(`$1',,boxwid,`($1)'))dnl
  define(`m4bht',ifelse(`$2',,boxht,`($2)'))dnl
  line from rvec_(m4bwd,0) to rvec_(m4bwd,m4bht/2) \
    then to rvec_(0,m4bht/2) \
    then to rvec_(0,-m4bht/2) \
    then to rvec_(m4bwd,-m4bht/2) \
    then to rvec_(m4bwd,0) `$3' ')
\end{verbatim}
The macro is invoked as {\tt lbox({\sl width}, {\sl height}, {\sl type})};
for example,
\ntt{Point\_(20); lbox(,{},fill 0.9)}\\
draws a light gray-filled box of default size at an angle of 20 degrees from
the horizontal. 
In the macro, the width and height of the box are first defined,
using default values
if the first and second arguments are not given.  Then a line is drawn
to outline the box, and the {\tt fill 0.9} argument is appended to the
line command to fill the box.  A slightly more elaborate version
that encloses the box in {\tt [}, {\tt ]} brackets is given by the
Circuit\_macros {\tt rotbox} macro.

\subsection{Subscripts\label{Subscripts:}}
\Dpic allows variables and labels to have a single or double subscript; thus
{\tt x,} {\tt x[4],} and {\tt x[4,2]} are distinct variable names,
and can be employed in expressions as usual.
Similarly, {\tt P} and {\tt P[3]} are distinct labels.
Writing the subscript as {\tt [{\sl position}]} for any defined
position is the same as {\tt [{\sl position}.x, {\sl position}.y]}.
When using older versions of \dpic,
in cases where a double-subscripted variable or label is part of a macro
argument, protect the comma in the subscript with parentheses
by writing, for example, {\tt x[(i,j)]} instead of {\tt x[i,j]}.
Recent versions of \dpic\ do not require this, as the brackets protect
the comma.

\subsubsection{Assigning an array of numbers}
We can assign an array of numbers to subscripted variables using
statements such as
\ntt{x[1] = 47}
\ntt{x[2] = 63}
\ntt{$\vdots$}\\
and so on, but generating the subscripts is inconvenient, particularly
when these statements are obtained by editing a data file.
One way of entering the data is to employ the m4 macro definition
\ntt{define(`inx',`define(`m4x',ifdef(`m4x',`incr(m4x)',1))m4x')}\\
Then, writing
\ntt{x[inx] = 47}
\ntt{x[inx] = 63}
\ntt{$\vdots$}\\
and processing with m4 automatically generates the required subscripts.
The macro sets {\tt m4x} to 1 if it is not yet defined, otherwise it
increments {\tt m4x}, and then it evaluates to {\tt m4x}.  On completion
of the assignments, {\tt m4x} has the value of the last subscript.

Another way of assigning variables to a subscripted variable is by
the definition
\ntt{define array \tLB}
\ntt{\quad for i=2 to \$+ do \tLB\ exec sprintf("\$1[\%g] = \$\%g",i-1,i);
 \tRB\ \tRB }\\
which equates the subscripted first argument to the values in argument 2, 3,
$\ldots$ so that, for example,
\ntt{array(x,9,-4,7,4.2,0,0,7.9,0,0,10,11,12,13,14,10)}\\
assigns the second to sixteenth arguments to {\tt x[1]} to {\tt x[15]}
respectively.

\Dpic does not define vector operations, but it is easy to define macros
for them. For example, macros can be used to define 3-dimensional vectors,
transform them, and to project them onto a drawing plane.

\subsection{Splines}
\Dpic implements standard pic splines by default, as on the left in the
following figure, which shows the result of the command
\ntt{spline up 1.5 then right 2 then down 1.5}\\[-1.5\baselineskip]
\input spline.tex
\par
%\enlargethispage{\baselineskip}
A straight line is drawn along
the first half of the first segment and the last half of the last segment.
The curve is tangent to the centres of the segments.
The dpic result of including an expression after {\tt spline}, as in
\ntt{spline x up 1.5 then right 2 then down 1.5}\\
is shown on the right of the figure, as the tension parameter {\tt x}
varies from 0.2 to 1.4.  The curve begins at the start of the first
segment and terminates at the end of the last segment.
The tension parameter can be varied to assist in fitting a multisegment
spline to a curve.  It turns out, for example, that the optimum tension
for approximating a circle using four splines is the value 0.551784.

\subsubsection{Curve fitting}
Splines are drawn with respect to control points, but only pass through
the first and last point.  Suppose that a sequence of points
{\tt X[0]}, {\tt X[1]},~$\ldots$ {\tt X[n]}
has been given, and a spline is to be
found to pass through each point.  The control points
{\tt P[0]}, {\tt P[1]},~$\ldots$ {\tt P[n]}
have to be calculated.  These points satisfy the following equations:
\ntt{P[0] = X[0]}\
\ntt{P[i-1]/8 + P[i]*3/4 + P[i+1]/8 = X[i]} for {\tt i = 1} to {\tt n-1}
\ntt{P[n] = X[n]}\\
The Circuit\_macros {\tt fitcurve} macro performs the required calculations
and draws the spline to pass through the given points.

\subsection{Text}
Pic interpreters are not wordprocessors, but
generate output compatible with
\LaTeX\ in the case of \dpic and \groff or \LaTeX\ in the case of \gpic.
\Dpic also generates
output formats in which font choice and formatting, if any, must be done
according to the context, as for example, postscript output containing psfrag
strings, or SVG output formatted by macros or by hand.
The result is that the size and position of text may need to be adjusted
by hand for the particular workflow and postprocessor to be employed.

  The \dpic\ {\tt textht} environment variable
  (see \SR{Appendix A:})
  often gives \dpic a good estimate
  of the actual height of embedded text, but the width of the text is more
  difficult to estimate.
  Consequently, text is sometimes truncated by the figure 
  bounding box at the left or right edge of the figure.
  Setting the width of strategic strings by hand,
  e.g., {\tt "{\it text}" wid 0.65}
  can serve as a quick cure in specific cases, but is better done
  automatically as described in the Circuit\_macros documentation
  \cite{Aplevich09}.
  Briefly summarized, \LaTeX\ can write the exact height, width, and depth
  of formatted text (or anything that creates a box) to a file.
  The file is read by dpic during a second processing of the diagram, so that
  the width $x$ and height $y$ are known numerical values in the phrase  
  \ntt{"{\sl text}" wid $x$ ht $y$}\\
  Text in PDF and SVG output is mentioned further in Section \ref{SVGtext:}.

Justified text deserves special mention.  The second line in
  \ntt{A: circle rad 0.01 at (0,0)}
  \ntt{S: "Hello" at A}
  \ntt{   box wid S.wid ht S.ht at S}\\
produces a greeting centered at {\tt A} as expected. The bounding
box of the text is also centered at {\tt A} but has default
height and width {\tt textht} and {\tt textwid} (that is, zero in
most cases) respectively.
The revised version
  \ntt{S: "Hello" wid 24.7/72 ht 7.6/72 at A}\\
(where the formatted size in points has been obtained automatically
or by measurement) produces a correct bounding box.
There are minor differences in the way \gpic and \dpic handle
justification, as discussed in Section \ref{Justified:}. 


\subsection{Postprocessor commands and color}
Arbitrary postprocessor commands can be interspersed with pic
statements  to achieve effects such as gradient fills, clipping,
and transformations. There are two ways of passing
commands into dpic output.

\Dpic lines beginning with the backslash \tBS\ are passed through to the
output without modification.  This method works well for TeX statements,
\LaTeX\ statements, and commands to postprocessors that rely on the TeX macro
processing.

The second method is the form
\ntt{command "{\sl text}"}\\
or
\ntt{command sprintf("{\sl format}",{\sl expression},$\ldots$)}\\
both of which pass the contents of the string into the
output stream without the enclosing quotes. The string need not start
with a backslash.

Both of the above methods add considerable power to the pic language, but there
are two issues.  The first is that if a postprocessor transformation changes
the size of a drawn element, the pic processor will not know the new size
parameters unless they are explicitly calculated.  The second is
the challenge of designing a single macro that
produces appropriate postprocessor code to have
identical effect with different postprocessors.

%The gradient fill operations for \PSTricks or SVG, for example, are a good use
%of this facility.  Path operations such as clipping can also be used,
%depending on the postprocessor.
%It is more of a challenge to design
%macros that have identical effect with a variety of postprocessors,
%since their syntax differs.
%\pagebreak
The Circuit\_macros library contains
several routines that produce equivalent or nearly equivalent results
for several postprocessors.  It is probably a good rule to stick with
one or two postprocessors such as Tikz-pgf or \PSTricks.

  Dpic defines a number of internal variables for controlling
  actions that depend on output format. Internal variables
  {\tt optTeX}, {\tt opttTeX}, {\tt optpict2e}, {\tt optPSTricks},
  {\tt optPDF}, {\tt optPGF}, {\tt optMFpic}, {\tt optPS}, {\tt optPSfrag},
  {\tt optMpost}, {\tt optSVG},
 and {\tt optxfig} have numerical values 1 to 12
  respectively, and
  variable {\tt dpicopt} is given the value corresponding to the output format
  specified on the command line.
  Therefore, conditional drawing with a {\tt case} statement as described on
  \PR{Branching:}, or with {\tt if} as in the following can be
  performed:\\
  \ntt{if (dpicopt==optPS) || (dpicopt==optPDF) then \tLB}\\
      \hspace*{2em}{\sl drawing commands for postscript or pdf}$\;$ \tRB \tBS
  \ntt{else \tLB$\;$ {\sl drawing commands for latex-related formats} \tRB}\\

  The variable {\tt optsafe} is set to true if option {\tt -z} has been
  specified or if dpic has been compiled to allow only safe mode.

\subsubsection{Color}
  From version 18, gpic allows coloured lines and filled objects as follows,
  and dpic allows them where the postprocessor supports them:
    \ntt{{\sl object} outlined {\sl string}}
    \ntt{{\sl object} shaded {\sl string}}
    \ntt{{\sl object} colored {\sl string}}\\
  where {\sl string} specifies a colour compatible with the postprocessor.
  For planar objects, the third case
  is equivalent to
    \ntt{{\sl object} outlined {\sl string} shaded {\sl string}}\\
  For the linear objects line, arrow, spline,
  dpic treats
    \ntt{colored {\sl string}}\\
  to be the same as
    \ntt{outlined {\sl string}}\\
  but fill can be added by explicitly writing
    \ntt{outlined {\sl string} shaded {\sl string}}

  The original pic language did not include the {\tt outlined} or
  {\tt shaded} attributes.  Current processors recognize these but
  know nothing about color except as strings attached to drawing
  elements.  What the string should contain depends on the postprocessor.

\subsubsection{Filling with color}
Basic pic shapes such as boxes, circles, and ellipses
can be colored and filled using, for example,
\ntt{ellipse shaded "{\sl color}" outlined "{\sl color}"}\\
and, if the two colors are the same, this can be abbreviated as
\ntt{ellipse colored "{\sl color}"}\\
where the color strings are compatible with the postprocessor.
The \Mfour\ macro
\ntt{rgbstring({\sl red fraction,green fraction,blue fraction})}\\
evaluates to a string compatible with the postprocessor
(for postprocessors that allow it; that is, \TPGF, \PSTricks, SVG, \MetaPost,
  PDF, and raw \Postscript)
so that the following produces a circle filled in gold, for example:
\ntt{circle shaded rgbstring(1,0.84,0)}.

  More elaborate options can also be invoked. For example,
  with \TPGF output, the command
    \ntt{box shaded "orange, opacity=0.5"}\\
  sets the opacity of the fill,
  and with \PSTricks output, the sequence
    \ntt{box shaded "lightgray,fillstyle=hlines*,linecolor=blue,}
    \ntt{hatchwidth=0.5pt,hatchsep=5pt,hatchcolor=red,hatchangle=45"}\\
  produces a hatched multicoloured fill and is equivalent to
    \ntt{command "\tBS{}pscustom[fillcolor=lightgray,fillstyle=hlines*,linecolor=blue,"}
    \ntt{command "hatchwidth=0.5pt,hatchsep=5pt,hatchcolor=red,hatchangle=45]\tLB\%"}
      \ntt{\quad box}
    \ntt{command "\tRB\%"}

One limitation of the pic language is that it lacks the concept of a path
composed of different basic curves such as lines, splines, and
arcs.
\Dpic, however, extends the {\tt shaded} and {\tt outlined} directives to
linear objects such as lines or splines where the output postprocessor allows.
Consider, for example, the following macro:
\begin{verbatim}
define slantbox { [ # wid, ht, xslant, yslant, attributes
  w = $1 ; h = $2 ; xs = $3 ; ys = $4
  NE: (w+xs,h+ys)/2 ; SE: (w-xs,-h+ys)/2
  SW: (-w-xs,-h-ys)/2 ; NW: (-w+xs,h-ys)/2
  N: 0.5 between NW and NE ; E: 0.5 between NE and SE
  S: 0.5 between SE and SW ; W: 0.5 between SW and NW
  C: 0.5 between SW and NE
  line $5 from N to NE then to SE then to SW then to NW then to N
  ] }
\end{verbatim}
\vspace*{-1ex}
This macro implements a version of
the {\tt xslanted} and {\tt yslanted}
attributes recently introduced for gpic boxes, for example
\ntt{box wid 0.1 ht 0.5 xslanted 0 yslanted 0.1 \tBS}
\ntt{\quad shaded "Dandelion" outlined "black"}\\
The {\tt slantbox} macro
defines the implied compass corners {\tt N,} {\tt S}, {\tt NE},~$\ldots$.
Its fifth argument can be used to fill or otherwise specify the line.
For example, the command
\ntt{slantbox(0.1,0.5,0,0.1,shaded "Dandelion" outlined "black")}\\
is equivalent to the gpic example.  The above macro can be
modified easily to produce arbitrary polygons, for example.
The color {\tt Dandelion} is automatically defined for \PSTricks
by the \LaTeX\ line
\ntt{\tBS{}usepackage[dvipsnames]\tLB{}pstricks\tRB}\\
For TikZ-PGF, try
\ntt{\tBS{}usepackage[usenames,dvipsnames]\tLB{}xcolor\tRB}
\ntt{\tBS{}usepackage\tLB{}tikz\tRB}

\subsubsection{External files}
  Dpic can send print output to a file (operating system permitting)
  using the command
    \ntt{print {\sl arg} \tRA\ "{\sl filename}"}\\
  which creates the named file, or
    \ntt{print {\sl arg} \tRA\tRA\ "{\sl filename}"}\\
  which appends output to the named file if it exists and creates the file
  if not.
  If the {\tt -z} option has been invoked or dpic was compiled in safe mode,
  both of these give warning messages rather than writing to the file.

  External files can be used to implement forward referencing.  For
  example, sometimes the final size of a diagram component is required in
  order to draw a background object that will be overlaid by the
  component.  One solution is to process the diagram twice.  In the
  following code fragment, an assignment to {\tt x} is written to an
  external file so that the required value of {\tt x} will be known after
  the file is read on the second pass.
%\enlargethispage{\baselineskip}
  \ntt{x = {\sl default value}}
  \ntt{print "" >> "datafile" \hfill      \# Make sure the file exists}
  \ntt{copy "datafile" \hfill \# On second pass, read x = required value}
  \ntt{{\sl ... draw objects and calculate required value y ...}}
  \ntt{print sprintf("x = \%g",y) > "datafile"\hfill
    \# Write out the assignment}
\\

%===============================================================================

\section{SVG, PDF, and Postscript output}\label{SVG:}

The {\tt-r} (raw \Postscript),
{\tt-v} (SVG),
{\tt-d} (PDF),
and {\tt-x} (\xfig) options
of dpic produce output that is not intended to be processed directly by
\LaTeX\ or, in some cases, printed on paper.
%  \Postscript output can be inserted
%into a document with the {\tt \tBS{}includegraphics} macro. This command
%will also import pdf for processing by pdflatex. 

  As a ``little language,'' \Pic and its interpreters 
  leave text sizing and formatting to word processors, which are
  flavours of \LaTeX\ in the case of \dpic, and \groff or \LaTeX\ in the case
  of \gpic.
  Text formatting is specified by the text content itself or by
  the string contents of {\tt command} lines.
  The exception to this is that text is also a
  graphical element; its size and location is sometimes required,
  and the interpreter must also be able to stack multiple text strings
  vertically.
  
  In most cases, placing text using
    \ntt{"{\sl Text}" wid {\it x} ht {\it y} at {\it location}}\\
  is sufficient.
  \LaTeX\ can write the height and width of the formatted text
  (which can be anything that produces a TeX box)
  to an external file, which is passed to the \pic processor for use
  on a second pass over a diagram, as described in
  detail in reference \cite{Aplevich09}, so the values of
  {\it x} and {\it y} can
  be obtained automatically and macros can generate the
  above line without intervention by hand.

  Other output formats, however, require different treatment.
  This is specially true of SVG output for the web.
% There are several issues: selecting the font and determining the
% height, width, and position of text.

\subsection{SVG text\label{SVGtext:}}
  In contrast with the various dpic \LaTeX\ output formats for which
  text size is established by postprocessor commands,
  the size of SVG text has to be set by the \pic interpreter
  (at least until an automatic way of returning formatted sizes from
  renderer back to \pic interpreter is established).
\begin{wrapfigure}[9]{r}{0.3\textwidth}%
  \vspace*{-\baselineskip}%
  \hspace*{1em}%
  \parbox{0.3\textwidth}{\input{Xtest.tex}}%
 \end{wrapfigure}%
  One difficulty is that
  the formatted height of text is generally a fraction of the nominal size.
  For example, the Times letter X at 100\,bp placed on a 100\,bp by
  100\,bp grid is shown at the right.
  The height of the X is
  approximately 66\,bp or 0.66 of the nominal height.
  This ratio depends on the font.
  Consequently, a language issue arises: if the attribute {\tt ht~{\it y}}
  is to be used to set text size,
  should the value of {\it y} be the nominal height (the point size) or
  the formatted height of the text?
% Initial versions of the experimental
% SVG output of \dpic used the
% nominal height but later versions now conform to \LaTeX\ usage by treating
  \Dpic treats {\it y} as the true graphical height in drawing units.
  Thus for example, {\tt "text" ht 10*(scale/72)} produces output
  {\tt 10bp} high.

  To assist with the above and similar issues
  when the {\tt -v} option is invoked, \dpic performs the equivalent
  of
    \ntt{dpPPI = 96}
    \ntt{dptextratio = 0.66}\\
  in the outermost scope of the diagram.  These are ordinary variables
  that can be referenced as usual.
  The variable {\tt dpPPI} is given the inital value 96 which is
  pixels per inch
  on a 20-inch wide computer monitor of 1920 pixels width.
  On such a monitor, dpic output should be close to true size.
  This parameter can be changed using the assignmnent
    \ntt{dpPPI := {\sl value}}\\
  for different screen resolution, and {\tt dptextratio} can
  be similarly changed.
  (For \xfig\ output, the following are defined under the {\tt -x} option:
  {\tt xfdispres = 80; xfigres = 1200}.)


  When \dpic sees the {\tt ht {\it y}} attribute attached to SVG text,
  it sets the nominal text size
  to $y/\tt{dptextratio}$ expressed in points.
  Otherwise, \dpic uses the current value of the environment
  variable {\tt textht}, which has default value $11/72 \times 0.66,$
  to set the default size to 11\,bp.

  The Circuit\_macros configuration file {\tt svg.m4} contains a macro
  {\tt svg\_font} that can simplify font specification, and a macro
  {\tt svgfontratio} that can be used to set {\tt dptextratio} and
  {\tt textht} automatically for common HTML fonts.

  \Dpic sets the width of text
  to the current value of {\tt textwid} by default but,
  as always, it is best not to rely on
  default behaviour. Specify the object (text in this case) completely
  using {\tt wid {\it expression} ht {\it expression}}.
  In the absence of an automatic means of determining it, text width can
  be measured approximately when displayed full-size on a monitor.
  Fortunately on many diagrams, knowing the width is unnecessary or
  is required for only a few key strings.
  In principle, this process might be automated using suitable macros
  and scripting (JavaScript, probably).

\enlargethispage{\baselineskip}
\subsection{Bounding boxes}
  The bounding box of a diagram is not always known exactly or even defined
  exactly, since it can depend on the context in which the diagram is to be
  used.  Within a diagram, different line widths, mitred joints, splines,
  colored output, overpainting, arbitrary text, arbitrary \Postscript or SVG,
  and other complications are allowed; consequently dpic can only provide an
  estimate of the exact bounding box.

  Strategic {\tt move} commands can be used
  to enlarge the bounding box as illustrated at the end of the discussion
  below.

  Dpic uses the constant-width Courier font in pdf files, thus allowing
  the width of strings to be calculated from their height, which is
  specified by {\tt textht} with default $11\,$pt, or by the
  ``{\tt height} {\sl expression}'' attribute.  The string width is calculated
  from the height and character count, but can be set explicitly
  by using {\tt width} {\sl expression} as the rightmost string attribute.

  {\em Psfrag output} is another special case.  If {\tt textht} is set to a
  nonzero value, then its value relative to $11\,$bp is
  given as a scale factor to the psfrag {\tt \tBS{}tex} command.
  An alternative way of changing the diagram text height is to set it in
  the main document; for example,
  {\tt \tLB\tBS{}small \tBS{}includegraphics\tLB{\sl file}.eps\tRB\tRB}.

  {\em Postscript bounding boxes:}
  For a while, the dpic\verb|%%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
\begin{verbatim}
  .PS
  box with .sw at 0,0
  .PE
\end{verbatim}
  which draws a box with southwest corner line centres intersecting at
  \Postscript coordinates 0,0 and northeast intersection at 54,36.
  Dpic {\tt -r} augments this nominal bounding box by half of the last
  {\tt linethick} value (default {\tt linethick} is 0.8 bp)
  in the outermost diagram scope to
  produce the \Postscript bounding-box definitions
\begin{verbatim}
  %%BoundingBox: -1 -1 55 37
  %%HiResBoundingBox: -0.4 -0.4 54.4 36.4
\end{verbatim}
  The\verb|%%BoundingBox| line contains integer values that enclose the
  high-resolution coordinates.

  {\em PDF bounding boxes:}
  PDF includes a MediaBox element which serves approximately the same
  purpose as the postscript BoundingBox, and is calculated the same way.
  By default, dpic puts the lower left corner of PDF output
  at coordinates $(0,0)$.

  {\em Manual bounding box adjustment:}
  It may be necessary to adjust the bounding box manually.  To zero the
  automatic adjustment,
  put {\tt 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 points are added to the left,
  bottom, right, and top margins respectively:\\
  \ntt{.PS}
  \ntt{Diagram: [}
    \ntt{\quad{\sl drawing commands}}
    \ntt{]}
  \ntt{linethick = 0}
  \ntt{move from Diagram.sw-(2,1)/72*scale to Diagram.ne+(1,0)/72*scale}
  \ntt{.PE}

%===============================================================================

\section{Pic processor differences}\label{Diffs:}
Differences among processors, and between dpic and gpic particularly,
are summarized below.
These differences result from incomplete language definition and
from different implementation contexts.
Normally, the
only changes required to process correct pic or gpic input with dpic are
changes to \tLB$\ldots$\tRB\ instead of {\tt X}$\ldots${\tt X}
syntax as explained below, together with text formatting
if the original code was written for \groff.
Sometimes, differences in default behavior (such as for arcs or object
placement) must be considered.
The remaining items are reasonably small syntactical differences or
relate to the use of \LaTeX\ or the other dpic output formats.

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

\subsection{Command-line options}  They are completely different, of course.
  Type dpic -h to see a list of dpic options.

\subsection{Output formats}
  Gpic {\tt-t} output consists of a sequence of\verb|\special| statements
  contained in the TeX box\verb|\box\graph|.  The\verb|\special| statements
  are
  automatically copied into the {\tt.dvi} file for interpretation by a
  printer driver such as dvips.

  Dpic does not generate tpic specials.
  See the option list in \SR{Usage:} for output formats.

\subsection{``{.}'' and ``\textbackslash''\ lines}
  Gpic passes lines beginning with {\tt.}\ 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
  \ntt{.ps 11}\\
  on the assumption that the text point size should be 11.  Dpic ignores
  non-continuation lines beginning with {\tt.}\ within pictures.
  Some programs (e.g., pstoedit) add Troff
  comment lines beginning with\verb|.\"| outside the
  {\tt.PS}, {\tt.PE} delimiters.  These
  lines must be dealt with separately.

%\subsection{``\textbackslash''\ lines}
  Both gpic and dpic pass lines beginning with \tBS\ to the output but
  dpic does not automatically append a {\tt\%} at the end as gpic does.

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

  The test for termination of the multiplicative form of the for loop
  is not identical for dpic and gpic but the effects are identical for
  positive parameters.

  Both gpic and dpic allow the
  loop index variable to be changed within the loop, so infinite
  repetition or control of termination by a test are possible.

\subsection{End of line}
  The line end is significant in the pic grammar.
  However, dpic ignores line ends following {\tt then}, {\tt \tLB},
  {\tt :}, {\tt else}, or end of line.
  Both the CR (octal 015) and NL (octal 012) characters are treated as
  line ends.

  If the last character of a line is \tBS\ (but not within a string),
  then reading is continued on the next line. Dpic allows this to occur
  within keywords or constants.  Strings can contain multiple lines.

  The {\tt\#} character begins a comment which ends at the end of the line.

  The construction
    \ntt{if {\sl condition} then \tLB\ {\sl if-true} \tRB}
    \ntt{else \tLB\ {\sl if-false} \tRB}\\
  produces an error with all pic interpreters.  To avoid this error, write
    \ntt{if {\sl condition} then \tLB\ {\sl if-true} \tRB\ \tBS}
    \ntt{else \tLB\ {\sl if-false} \tRB}\\

\subsection{Logic}
  Dpic and gpic give slightly different default precedences to the logical
  operators {\tt !}, {\tt \&\&}, {\tt ||}, {\tt ==}, {\tt !=}, {\tt >=},
  {\tt <=}, {\tt <}, and {\tt >}, so judicious use of
  parentheses may sometimes be in order.
  Dpic also requires comparisons and logical operations to be put in
  parentheses in numerical expressions; e.g., 
  \ntt{x = ("{\sl text1}" == "{\sl text2}")}

  The construct {\tt x<A,B>} is intended to have the same meaning as
  {\tt (x between A and B)} but, in some obscure
  circumstances, all pic interpreters have difficulty determining whether
  the {\tt<} character is part of such an expression or is a logical comparison
  operator.  Dpic treats {\tt<}
  as a comparison in the expression following {\tt if} so
  the form {\tt(x between A and B)} should be used in such expressions,
  e.g.
   \ntt{\tt if (0.5 between A and B).y < 2 then }\tLB~$\ldots$ \tRB\\

% In all cases, putting comparisons inside parentheses will
% render them robust to logical agreement and to error messages.

\iffalse
\subsection{{\tt then}}
  Versions of gpic up to 1.19 ignore the {\tt then} keyword, so that
   \ntt{line -> then up 0.5}\\
  draws one line segment and is the same as
   \ntt{line -> up 0.5}\\
  whereas dpic does not ignore {\tt then}, and draws two line segments.
  Newer versions of gpic also draw two segments.
\fi

\subsection{{\tt line}, {\tt spline}, {\tt arrow}, {\tt move}}
  Dpic treats the defaults for linear objects consistently with planar
  objects with respect to the {\tt at} modifier.
% Versions of gpic up to 1.19 treated
  Gpic treats
  them differently:

  In dpic, {\tt line at Here} means {\tt line with .center at Here}.\\
  In gpic, {\tt line at Here} means {\tt line with .start at Here}.

  In dpic, the location corresponding to {\tt last line} is
    {\tt last line.c}.\\
  In gpic, the location corresponding to {\tt last line} is
    {\tt last line.start}.

  In current versions of dpic,
  {\tt last line.wid} returns the arrowhead width of the line or the default
  arrowhead width if the line has not been given an arrowhead;
  similarly for {\tt .ht} and for the other linear objects including {\tt move}
  and, of course, {\tt arrow}.

  The compass corners of multisegmented linear objects are not
  defined in descriptions of the \pic grammar
  and they should be used with care.

\subsection{Arc defaults}  Gpic and dpic have different algorithms for picking
  a default radius.  The best practice is to specify arcs completely.
  There is also ambiguity in the pic language.  The statement
   \ntt{arc cw rad x from A to B}\\
  does not define a unique arc.
  There are two arcs, with centres on opposite sides of the line
  joining {\tt A} and {\tt B}, that satisfy this specification, and the
  interpreter will choose one by attempting to minimize the angle between
  the current direction and the initial arc tangent.
  Instead, use
   \ntt{arc cw from A to B with .c at C}

\subsection{Strings} 
% and justified text\label{Strings:}}
Strings are arbitrary character sequences between double quotes.
% with double
%quotes in strings preceded by the backslash character.
Equivalently, a string is produced by the C-like sprintf function
\ntt{sprintf("{\sl format}" {\rm[}, expression,~$\ldots$ {\rm]})}\\
The C sprintf function is used for implementing this; therefore, the
precision of default formats such as {\tt \%g} may vary by machine and compiler.
To produce transportable results, specify the precision completely,
e.g., {\tt \%8.5f}.  As in C, the pair {\tt \%\%}
in the format string prints the percent
character.  Only the {\tt f}, {\tt e}, {\tt g} formatting parameters are
valid, since expressions are stored as floating-point numbers, e.g.
\ntt{line sprintf("\%g\%g0", 2, 0 ) above}\\
is equivalent to
\ntt{line "200" above}

\enlargethispage{\baselineskip}
Similarly,
\ntt{command sprintf("\tBS{}pscircle(\%g,\%g)\tLB\%g\tRB",0,0,0.5)}\\
places a line containing the formatted string without the quotes into
the output.
The numerical {\tt sprintf}
arguments can be arbitrary expressions rather than the constants shown.

  Dpic allows strings to be concatenated by the {\tt+} operator; thus,
  \ntt{"abc" + sprintf(" def\%g",2)}\\
  is equivalent to {\tt"abc def2"}.

  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
   {\tt"\tLB\tBS\$\tRB{}1"}, {\tt"\$\tBS\$ 1\$"}, or {\tt"\$\tLB 0\tRB\$"},
  for example.

  Both dpic and gpic treat \tBS\ as an escape character prior to the
  double-quote
  character in a string, so {\tt"\tBS""} is a length-one string containing
  the double quote.  Otherwise, the backslash is an ordinary string
  character.
  For example, the characters\verb|\\"u| in a string are output as\verb|\"u|
  to produce \"u when processed by \LaTeX.
  A string with a backslash as last character
  has to be generated using a macro; for example, if we write
  {\tt define charstr \tLB"\$1"\tRB} then {\tt charstr(abc\tBS)}
  evaluates to a string containing the required final backslash.

  A string cannot be assigned to a varable name; the nearest equivalent
  is to define a macro containing the string as the body.

  Both dpic and gpic allow logical comparison of strings.
  Put the comparison in parentheses if it is to be used in an
  expression.

  String height and width are unscaled on final output from dpic since
  these may depend on later formatting by \LaTeX.

\subsection{{\tt print} {\sl arg},~$\ldots$}
  Dpic allows only one argument, which may be an expression, position,
  or string.  To print several quantities at once, use
   \ntt{print sprintf($\ldots$)}\\
  to generate a string and, if the string is complicated, remember that
  {\tt {\sl string1} + {\sl string2} +~$\ldots$} evaluates to one string.

\subsection{{\tt command} {\sl arg},~$\ldots$}
  Arbitrary commands are sent to the standard output stream.  Dpic allows only
  one argument, which is a string or {\tt sprintf($\ldots$)}.

\subsection{Operating system commands}
  With dpic, the required form for a shell (operating system) command is
   \ntt{sh "{\sl shell command}"}\\
  or
   \ntt{sh sprintf("{\sl format}",{\sl expression},$\ldots$)}.\\
  The value returned by the operating system can be captured by putting
  the command in parentheses; for example,
   \ntt{if (sh "{\sl shell command}") == 0 then \tLB\ldots\tRB }

\subsection{{\tt copy}}
  \Dpic supports the command
    \ntt{copy "{\sl filename}"}\\
  but does not directly support the \gpic commands
    \ntt{copy {\rm[}{\sl filename}{\rm]}
      thru X {\sl body} X {\rm[} until {\sl word} {\rm]}}
    \ntt{copy {\rm[}{\sl filename}{\rm]}
      thru {\sl macro} {\rm[} until {\sl word} {\rm]}}

  These functions and many more are readily implementable with dpic in any
  Unix-like environment.
%  To customize an operation such as
%    \ntt{copy {\sl filename} thru {\sl macro}}\\
%  modify the following example, as appropriate.
%  This usage is not as
%  simple as a built-in function but allows much more flexibility of data.
%\begin{verbatim}
%  .PS
%  #                               Suppose that file.dat contains rows of data
%  #                               delimited by spaces.
%
%  #                               Macro to process a row of data, e.g.
%  #                               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
%\end{verbatim}
For example, a basic implementation of
{\tt copy {\sl filename} thru {\sl macro}}
is given by the following macro:
\begin{verbatim}
#                               copythru(macro_name,"filename")
#                               Implements copy filename thru macro_name 
#                               for data separated by commas, spaces, or tabs
define copythru { sh "sed -e 's/^[ \t]*/$1(/' -e 's/[ \t]*$/)/' \
  -e 's/[, \t][ \t]*/,/g' $2 > copy_tmp__"
copy "copy_tmp__"
sh "rm -f copy_tmp__" }
\end{verbatim}
The lines of the {\sl filename} file are changed to calls of the {\tt
macro\_name} macro and written into a temporary file, which is then
read by \dpic.  Such usage is not as simple as a built-in function but
allows greater flexibility of data because the {\tt copythru}
macro can be replaced by one customized to suit. For example, the {\tt sh}
command might invoke another program to generate the data.

\subsection{{\tt plot}}
  The {\tt plot} command is deprecated in gpic and not allowed in dpic.

\subsection{{\tt fill}}
  In gpic, a fill value of 0 means white, 1 means black.
  Dpic uses 0 as black and 1 as
  white as do \Postscript and the original ATT pic.

  The pic language specifies fill only for box, ellipse, and circle.
  With dpic, the {\tt shaded} directive fills a path defined by a linear
  object, where allowed by the postprocessor.
  The concept of a path
  containing several arbitrary linear objects does not exist in the pic
  language but can be implemented using postprocessor commands inserted
  into {\tt command {\sl string}} statements.
  Arbitrary paths can also be constructed using a single spline and the
  {\tt continue} statement.

\subsection{Scaling}
  Dpic implements a {\tt scaled} attribute, so that
  \ntt{box scaled 1.2}\\
  produces a box with dimensions scaled by 1.2, and
  \ntt{[box; line scaled 3; circle] scaled 0.5}\\
  scales all objects within the block by 0.5.  The latter can be used
  when different parts of a diagram require different scaling.
  For example, if file {\tt component.pic} contains a component
  scaled by 25.4, then the following allow it to be used:
  \ntt{[ copy "component.pic" ] scaled 1/25.4}\\
  As always, line thicknesses are not scaled.

\subsection{Arrowheads}
  Pic processors provide a limited variety of built-in arrowhead
  shapes.
  Dpic draws arrowheads according to the environment variable {\tt arrowhead}
  as shown below.
\par
\input arrow.tex
\par
  Any other value of {\tt arrowhead}
  produces the default filled head shown but also
  results in an a head shape native to the postprocessor in some cases.
  The default
  value of {\tt arrowhead} is 1 in conformance with other pic processors.
  Postprocessor parameters can be changed using lines of the form
    \ntt{command "{\sl postprocessor commands}"}

% Dpic also allows arrowhead shape to be locally specified by appending
% a parameter after {\tt ->}, {\tt <-}, or {\tt <->}; for example,
%   \ntt{line -> 0 thick 3 wid 0.2 ht 0.3 ... }

  Changing the line thickness does not affect arrowhead size
  parameters, which have to be changed explicitly by either of the
  following methods.  The line thickness is specified in points but the
  arrowhead size parameters are in drawing units:
%\enlargethispage{0.5\baselineskip}\vspace*{-0.5\baselineskip}
\begin{verbatim}
# Method 1 (global change within the current block):
  linethick = 2    # default 0.8 (bp)
  arrowht = 0.18   # default 0.1 (in)
  arrowwid = 0.09  # default 0.05 (in)
  arrowhead = 0    # default 1
  arrow

# Method 2 (put a type 0 arrowhead on the current object):
  arrow -> 0 thick 2 ht 0.18 wid 0.09
\end{verbatim}

  There is a subtle language problem concerning arrowheads.  Let us
  agree that the following examples should all produce an arrow of
  length 1 inch and arrowhead width 1 millimetre:
\begin{verbatim}
  .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
\end{verbatim}

  The original (ATT) 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 {\tt.PS} $x$
  construction, since the effective scale factor is unknown until the
  {\tt.PE} line is processed.  Dpic generates the same arrow in all three
  cases, treating arrowhead parameters like line thickness (unscaled)
  parameters on final output.

\subsection{Compass corners and justified text\label{Justified:}}
  Dpic consistently requires a dot before compass corners, so the gpic line
    \ntt{x at center of last box}\\
  should be written for dpic as
    \ntt{x at .center of last box}

Justification is performed by the postprocessor, and combining
justified text with drawing elements requires special consideration.
The lines
  \ntt{S: "Hello" wid 24.7/72 ht 7.6/72 at A ljust}
  \ntt{box wid S.wid ht S.ht at S}\\
produce a box of the correct size but centered at {\tt A} because
the location ({\tt A}) and a justification command are given to the postprocessor.
This behavior could be easily changed but would affect much legacy
code and has been kept for \dpic, which will produce a justified
box using
  \ntt{box wid S.wid ht S.ht with .w at S.w}

\Gpic and \dpic place justified text slightly differently.  In the
previous example, \gpic places the text with its left edge exactly
at {\tt A}, with similar effect for right justification.  \Dpic
uses the environment variable {\tt textoffset}, which is 2\,pt by
default, to place the left edge of the text at {\tt A + (textoffset,0)}
with a similar gap for other relative positioning.  Assigning {\tt textoffset}
to 0 sets the gap added by \dpic to zero.

\subsection{{\tt continue}}
  In dpic, the {\tt continue} command appends a linear drawn object to
  the previous drawn object as if {\tt then} had been used in the original
  command, but calculations can be performed to determine size or placement
  of the appended part as in, for example,
   \ntt{line up right}
     \ntt{\quad\sl calculations}
   \ntt{continue down}
     \ntt{\quad\sl more calculations}
   \ntt{continue up left}

  The keyword {\tt continue} can also be used slightly differently. The line
  drawn by
   \ntt{move to (0,0); line right 1 then to (Here,(2,1))}\\
  terminates at {\tt(0,1)} since {\tt Here} is the position {\tt(0,0)},
  whereas the
  following terminates at {\tt(1,1)} since {\tt Here} is {\tt(1,0)}:
   \ntt{move to (0,0); line right 1; continue to (Here,(2,1))}

% Input parsing would be possible if {\tt continue} were to be replaced by
% {\tt then}:
%  \ntt{move to (0,0); line right 1; then to (Here,(2,1))}\\
% The keyword {\tt continue} is not strictly necessary
% but it has been retained for historical compatibility.

\subsection{Subscripted variables and labels}
  Dpic allows subscripted variables and capitalized labels, as described in
  \SR{Subscripts:}.
\iffalse
  as an aid in
  geometric calculations such as fitting splines to a set of points.
  For example, {\tt Pos[{\sl expression}]} is a valid name for a position.
  The rounded integer value of the expression is used.  Up to two subscripts
  are allowed, and 
  {\tt x[{\sl expression},{\sl expression}]} is
  a valid variable name.  There are no array operations, but it is easy
  to write macros for them.
\fi

\subsection{Splines}
  Gpic extends the ATT pic grammar to make {\tt 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
   \ntt{spline $x$ from A to B then to C}~$\ldots$\\
  the parameter $x$ is a
  tension parameter, normally 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 second half of the last segment.
  When $x$ is present however, dpic draws the spline from the start of the
  first segment to the end of the last segment.

\subsection{Arithmetic}
  In an expression, \gpic allows terms of the form {\tt x*-y}, whereas
  \dpic produces an error message. Use {\tt x*(-y)} or the equivalent.

  \Dpic allows the assignment operators {\tt +=}, {\tt -=}, {\tt *=}, 
    {\tt /=}, {\tt \%=}, which do not create a new variable but update
    the value of the variable already defined.
    Thus, the assignment {\tt x += 1} is equivalent to
    {\tt x := x + 1}.

\subsection{Vector arithmetic}
  The dpic grammar permits the following:
  \ntt{X: Y + Z}\\
  where {\tt Y} and {\tt Z} are
  defined positions.  Gpic requires
  \ntt{X: Y + (Z.x,Z.y)}\\
  Dpic also allows
  scalar postmultiplication:
  \ntt{X: Y*2/3}\ (but not {\tt X: 2/3*Y})

\iffalse
\subsection{Positions}
  If {\tt X} is a position, then {\tt (X)} is a valid position for dpic but
  not old versions of gpic, which gave an error for
  \ntt{(a between A and B) + (x,y)}\\
  Dropping the parentheses to avoid the error gives
  \ntt{a between A and B + (x,y)}\\
  which is not the same resulting position. Use dpic or a recent gpic
  if you need this construction.
\fi

\iffalse
\subsection{{\tt int()}}
% Gpic {\tt int()} up to version 1.19 computed the floor of its argument
% rather than the integer part as specified by ATT pic.
  Dpic provides
  both the {\tt floor()} and {\tt int()} functions but {\tt int()}
  does not compute the
  same value as pre-1.19 versions of gpic {\tt int()} for non-integer negative
  arguments.
\fi

\subsection{{\tt exec}}
  In dpic the contents of a string can be executed using
   \ntt{exec {\sl string}}\\
  or
   \ntt{exec sprintf({\sl format string}, {\sl args})}\\
  as if the string were the next line of input.  This enables the
  programmed generation of names and labels, for example:
   \ntt{for i=1 to 10 do { exec sprintf("A\%g: x\%g,y\%g",i,2*i,3*i) }}

\subsection{Functions}
A few additional mathematical functions are defined in dpic:
  {\tt abs}, {\tt acos}, {\tt asin}, {\tt expe}, {\tt floor},
  {\tt loge}, {\tt sign}, {\tt tan}, and {\tt pmod}.

\subsection{PSTricks anomaly}
  At some time between the years 2000 and 2010,
  the behaviour of the low-level \PSTricks command
  {\tt \tBS{}psbezier}
  was changed to match the existing context-dependent behavior
  of the {\tt \tBS{}pscurve} command within the\verb|\pscustom| environment%
\footnote{%
  The context-dependency of {\tt \tBS{}pscurve} was taken to be a feature
  rather than a bug.
  An alternative that preserves command orthogonality would have been
  to define two curve (and spline) commands for the in-pscustom and out of
  pscustom contexts.
% presumably without consideration of independently
% generated coordinate data.
% Since curve-defining code then has to be modified
% depending on where it occurs with respect to {\tt \tBS{}pscustom},
% the functionality could have been kept while preserving command
% orthogonality by the use of command options or additional commands.
  Such are the difficulties of software library maintenance.%
}.
  \Dpic does not generate the {\tt \tBS{}pscurve} command,
  but the new behaviour affects \dpic-defined filled splines.
  The ``normal'' \PSTricks spline syntax is
   \ntt{\tBS psbezier(x1,y1)(x2,y2)(x3,y3)(x4,y4)~$\ldots$}\\
  However, if a correctly defined path containing this spline as its second
  or later subpath is now enclosed in a\verb|\pscustom| environment, the
  path coordinates are incorrect;
% the\verb|\psbezier| command is not the
% first segment of a path within a\verb|\pscustom| environment then
  {\tt (x1,y1)} must be omitted since, under these
  conditions,\verb|\psbezier|
  takes its first coordinate pair to be the current position.
  This anomaly would not
  be a significant problem if it were always known at the time of
  generating the\verb|\psbezier| coordinates whether the curve will be enclosed
  within\verb|\pscustom|, but such is not the case.

% Within the pic language in particular, the\verb|\pscustom| command may be
% introduced via {\tt command} {\sl string} independently of anything else,
% so \dpic cannot know automatically
% whether\verb|\pscustom| has been invoked.

  Dpic always generates four (or
  more) coordinate-pair arguments as in the normal syntax, sometimes
  resulting in the addition of an extraneous path segment produced
  within\verb|\pscustom|.

  For some versions of \PSTricks,
  a workaround for the problem has been to insert a
  \PSTricks patch in your \LaTeX\ code if you are enclosing splines
  within\verb|\pscustom| commands.
  More recent versions of the \PSTricks package have changed
  again but, starting from the
  August~27, 2010 {\tt pstricks.tex} distribution file, a parameter
  {\tt noCurrentPoint} has been introduced,
  which prevents\verb|\psbezier| (and other commands)
  from taking the current point as the first coordinate pair.
  The following line inserted into a latex document avoids an
  error if the \PSTricks version is August 2010 or later:
\begin{verbatim}
 \psset{noCurrentPoint}
\end{verbatim}
%  As a result, the following file inserted into a latex document seems
%  to handle both cases in which a workaround is possible: 
  Older versions of \PSTricks are handled using the following workaround:
\begin{verbatim}
command "\makeatletter\@ifundefined{ifPst@noCurrentPoint}%
{\@ifundefined{MPS@Patch}{\gdef\MPS@Patch{}%
 \typeout{ Dpic -p: patching psbezier in pstricks.tex (some versions) }%
 \def\psbezier@ii{\addto@pscode{%
  \ifshowpoints true \else false \fi\tx@OpenBezier%
  \ifshowpoints\tx@BezierShowPoints\fi}\end@OpenObj}}{}}%
{\@ifundefined{MPS@PatchMsg}{\gdef\MPS@PatchMsg{}%
 \typeout{ Dpic -p: Setting noCurrentPoint to use all coord pairs }}{}%
 \psset{noCurrentPoint}}\makeatother%"
\end{verbatim}

  This patch need only be executed once per \LaTeX\ run rather than with
  every diagram.

  If the above fix does not work then, for now,
  do not insert {\tt spline} commands into paths within the {\tt \tBS pscustom}
  environment, {\em unless} the spline is the first path segment. It is probably
  safe to say that this anomaly does not occur very often, but it
  can cause considerable difficulty when it does; the cure is to update your
  \PSTricks files.

  Legacy diagrams can often be treated in the following way, if pstricks97.tex
  is available on your machine as in MiKTeX distributions, for example.
  Replace the line\verb|\usepackage{pstricks}|
  with\verb|\usepackage[97]{pstricks}| or\verb|\input{pstricks97.tex}|.
  However, this method precludes using the newer \PSTricks facilities.

%\pagebreak
\pdfbookmark[section]{\refname}{refs}
\bibliographystyle{plain}
%\addcontentsline{toc}{section}{\protect{\hspace*{1em}$\;$}References}
\bibliography{./dpic-doc}

%===============================================================================
%\iffalse
\clearpage
\section{Appendix A: dpic man page}\label{Appendix A:}
%\verbatiminput{dpic.man}
\input dpic_man.tex
%\fi
%===============================================================================
\clearpage
\section{Appendix B: dpic grammar}
The tokens recognized by the dpic parser are as shown.  The tokens
in {\tt <} {\tt >} pairs are generated internally.  Equated tokens
({\tt ";" = "<NL>"}) have identical effect.

\begin{verbatim}
    
    terminals:
         "<EMPTY>" "<ERROR>"
         "<" "cw" "ccw"
         "(" ")" "*" "+" "-" "/" "%" ";" = "<NL>"
         "^" "!" "&&" "||" 
         "," ":" "[" "]" "{" "}" "." "[]" "`" "'"
         "=" ":=" "+=" "-=" "*=" "/=" "%=" (* the order matters *)
         "&"
         "<float>" "<name>" "<Label>" "<LaTeX>"
         '"' = "<string>"
         "#"
         "$" = "<arg>"
         "<START>" "<END>"
         "ht" = "height" "wid" = "width"
         "rad" = "radius" "diam" = "diameter"
         "thick" = "thickness"
         "scaled"
         "from" "to" "at" "with" "by" "then" "continue"
         "chop" "same"
         "of" "the" "way" "between" "and" "Here"
         "st" = "rd" = "nd" = "th" "last"
         "fill" = "filled"
         ".x" ".y"
         "print" "copy" "reset" "exec" "sh" "command"
         "define" "undef" = "undefine"
         "rand"
         "if" "else" "for" "do" "<endfor>"
         "sprintf"
      "<corner>"
         ".ne" ".se" ".nw" ".sw"
         ".t" = ".top" = "top" = ".north" = ".n"
         ".b" = ".bot" = ".bottom" = "bottom" = ".south" = ".s"
         ".right" = ".r" = ".east" = ".e"
         ".left" = ".l" = ".west" = ".w"
         ".start" = "start"
         ".end" = "end"
         ".center" = ".centre" = ".c"
      "<compare>"
         "==" "!=" ">=" "<=" ">"
      "<param>"
         ".height" = ".ht"
         ".width" = ".wid"
         ".radius" = ".rad"
         ".diameter" = ".diam"
         ".thickness" = ".thick"
         ".length"
      "<func1>"
         "abs" "acos" "asin" "cos" "exp" "expe" "int" "log" "loge"
         "sign" "sin" "sqrt" "tan" "floor"
      "<func2>"
         "atan2" "max" "min" "pmod"
      "<linetype>"
         "solid" "dotted" "dashed" "invis" = "invisible"
      "<colrspec>"
         "color" = "colour" = "colored" = "coloured"
         "outline" = "outlined"
         "shade" = "shaded"
      "<textpos>"
         "centre" = "center" "ljust" "rjust" "above" "below"
      "<arrowhd>"
         "<-" "->" "<->"
      "<directon>"
         "up" "down" "right" "left"
      "<primitiv>"
         "box" "circle" "ellipse" "arc" "line" "arrow" "move" "spline"
      "<envvar>"
        "arcrad" "arrowht" "arrowwid" "boxht" "boxrad" "boxwid"
        "circlerad" "dashwid" "ellipseht" "ellipsewid" "lineht"
        "linewid" "moveht" "movewid" "textht" "textoffset" "textwid"
      = "<lastsc>"          (* marker for last scaled env var *)
        "arrowhead" "fillval" "linethick" "maxpsht" "maxpswid" "scale" 
      = "<lastenv>"         (* marker for last env var *)
\end{verbatim}


The expanded dpic grammar follows:
\begin{verbatim}
        input = "<EMPTY>" 
              | input picture NL 

        picture = start NL elementlist optnl "<END>" 

        NL = ";" 
           | "<ERROR>" 

        start = "<START>" 
              | "<START>" term 
              | "<START>" term term 

        elementlist = "<EMPTY>" 
                    | element 
                    | elementlist NL element 

        optnl = "<EMPTY>" 
              | NL 

        term = factor 
             | term "*" factor 
             | term "/" factor 
             | term "%" factor 

        element = namedobj 
                | "<Label>" suffix ":" position 
                | assignlist 
                | "<directon>" 
                | "<LaTeX>" 
                | command 
                | lbrace elementlist optnl "}" 
                | ifpart 
                | elsehead elementlist optnl "}" 
                | for "}" 
                | "command" stringexpr 
                | "exec" stringexpr 

        lbrace = "{" 

        namedobj = object 
                 | "<Label>" suffix ":" object 

        suffix = "<EMPTY>" 
               | "[" expression "]" 
               | "[" position "]" 

        position = pair 
                 | expression "between" position "and" position 
                 | expression "of" "the" "way" "between" position "and" position 
                 | expression "<" position "," position "<compare>" shift 

        assignlist = assignment 
                   | assignlist "," assignment 

        command = "print" expression redirect 
                | "print" position redirect 
                | "print" stringexpr redirect 
                | "reset" 
                | "reset" resetlist 
                | systemcmd 
                | "copy" stringexpr 
                | "define" "<name>" 
                | "define" "<Label>" 
                | "undefine" "<name>" 
                | "undefine" "<Label>" 

        ifpart = ifhead elementlist optnl "}" 

        elsehead = ifpart "else" "{" 

        for = forhead elementlist optnl 
            | for forincr elementlist optnl 

        stringexpr = string 
                   | stringexpr "+" string 

        string = "<string>" 
               | sprintf ")" 

        assignment = "<name>" suffix "=" assignrhs 
                   | "<envvar>" "=" assignrhs 

        assignrhs = expression 
                  | assignment 

        expression = term 
                   | "+" term 
                   | "-" term 
                   | expression "+" term 
                   | expression "-" term 

        ifhead = setlogic logexpr "then" "{" 

        setlogic = "if" 

        logexpr = logprod 
                | logexpr "||" logprod 

        forhead = "for" assignlist "to" expression do "{"

        forincr = "<endfor>" 

        do = "do" 
           | by expression "do" 

        by = "by" 
           | "by" "*" 

        redirect = "<EMPTY>" 
                 | "<compare>" stringexpr 
                 | "<compare>" "<compare>" stringexpr 

        resetlist = "<envvar>" 
                  | resetlist "," "<envvar>" 

        systemcmd = "sh" stringexpr 

        defhead = "<EMPTY>" 

        sprintf = "sprintf" "(" stringexpr 
                | "sprintf" "(" stringexpr "," exprlist 

        exprlist = expression 
                 | expression "," exprlist 

        object = block 
               | object "height" expression 
               | object "width" expression 
               | object "radius" expression 
               | object "diameter" expression 
               | object "thickness" expression 
               | object "scaled" expression 
               | object "<directon>" optexp 
               | object "<linetype>" optexp 
               | object "chop" optexp 
               | object "filled" optexp 
               | object "<arrowhd>" optexp 
               | object "then" 
               | object "cw" 
               | object "ccw" 
               | object "same" 
               | object stringexpr 
               | object "by" position 
               | object "from" position 
               | object "to" position 
               | object "at" position 
               | object "<textpos>" 
               | object "<colrspec>" stringexpr 
               | objectwith "at" position 
               | objectwith "<corner>" "at" position 
               | objectwith pair "at" position 
               | "continue" 

        openblock = "[" 

        block = "<primitiv>" optexp 
              | stringexpr 
              | openblock closeblock "]" 
              | "[]" 

        optexp = "<EMPTY>" 
               | expression 

        closeblock = elementlist optnl 

        objectwith = object "with" 
                   | objectwith "." "<Label>" suffix 
                   | objectwith "." nth primobj 

        pair = expression "," expression 
             | location shift 

        nth = ncount "th" 
            | ncount "th" "last" 
            | "last" 

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

        shift = "<EMPTY>" 
              | shift "+" location 
              | shift "-" location 

        location = "(" position ")" 
                 | "(" position "," position ")" 
                 | place 
                 | location "*" factor 
                 | location "/" factor 

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

        factor = primary 
               | "!" primary 
               | primary "^" factor 

        placename = "<Label>" suffix 
                  | nth primobj 
                  | placename "." "<Label>" suffix 
                  | placename "." nth primobj 

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

        logprod = logval 
                | logprod "&&" logval 

        logval = lcompare 
               | stringexpr "<" stringexpr 
               | expression "<" expression 

        lcompare = expression 
                 | stringexpr 
                 | lcompare "<compare>" expression 
                 | lcompare "<compare>" stringexpr 

        primary = "<envvar>" 
                | "<name>" suffix 
                | "<float>" 
                | "(" logexpr ")" 
                | location ".x" 
                | location ".y" 
                | placename "<param>" 
                | "rand" "(" ")" 
                | "rand" "(" expression ")" 
                | "<func1>" "(" expression ")" 
                | "<func2>" "(" expression "," expression ")" 
                | "(" assignlist ")" 
                | "(" systemcmd ")" 
\end{verbatim}
\end{document}\endinput
