%% mpicp-examples.tex
%% mathsPIC manual
%% May 26, 2011

\documentclass[mathsPICmanual.tex]{subfiles}
\begin{document}

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


%%---------------------------
\chapter{Examples}

This section describes some practical examples of figures drawn
using {\mathsPIC}, together with the associated code.

When drawing a new figure or diagram, it seems best 
to start with a graduated coordinate frame
(see Figure~\ref{fig:example1}) using
the \verb!axes! and \verb!ticks! options of the \verb!paper!
command.
The next step is to define an \textit{anchor point} from which other
points can be derived---this has the advantage that the whole
figure can then be moved
by simply changing the coordinates of the anchor point.
If necessary, different parts of a complicated figure can be made
having their own separate anchor points, allowing the various parts
to be easily  adjusted relative to each other.

Remember that the command \verb!\thispagestyle{empty}! is, for convenience, implemented by  \texttt{mathspic.sty} (see  Section~\ref{sec:sty}), in order to prevent page numbers appearing in a figure. 


As regards scales and units, it seems  most
convenient to use the 1mm units and to keep the $x$ and $y$ scales
the same whenever possible (i.e.\ use \verb!paper{units(1mm)...}!),
since this allows easy scaling up and down after the figure has
been finished, as shown in Section~\ref{sec:scaling}.


In practice, the whole process of editing and viewing can be conveniently automated using a small script, to  run \mathsPIC, trim the image to the bounding box (BBox) and generate   the required file formats, as described in Section~\ref{sec:epsandjpg}.


%-----
\section{Input- and output-files}

The following example {\mathsPIC} file (input-file)
illustrates how  some of these commands are used
to draw  Figure~\ref{fig:example1}. Note that the dashed line $BD$ is drawn after
the {\PiCTeX} \verb!\setdashes! command is invoked; following
this \verb!\setsolid! is used before drawing the right-angle
symbol.
Also, the points $A,B,C$ are defined using the \TeX\
\verb!\odot! symbol $\odot$, in conjunction with a line-free
zone of $1.2$~mm in order to make the lines go to the edge of the
symbol---the value of the radius of such \TeX\ symbols
has to be determined by trial and error---see Table~1.


\bigskip

%%------------Figure 7-1-----------------
%% the triangle
%% testing importing a small fig (works OK)
 \begin{figure}[hbt]
 \centering
  \ifpdf
  \includegraphics[width=9cm]{mpicpm07-1.pdf}
  \else
  \includegraphics[width=9cm]{mpicpm07-1.eps}
  \fi
 \caption{\ }
  \label{fig:example1}
\end{figure}
%-----------------------


\begin{verbatim}
% mpicpm07-1.m  (Figure 7.1)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%---------------
\beginpicture
\setdashes
paper{units(1mm),xrange(0,70),yrange(0,50),axes(LRTB),ticks(10,10)}
\setsolid
point(A){10,10}[symbol=$\odot$, radius=1.2]     %% anchor point
point(B){A, polar(40, 50 deg)}[symbol=$\odot$, radius=1.2]
point(C){A, polar(50, 10 deg)}[symbol=$\odot$, radius=1.2]
point(D){perpendicular(B,AC)}
drawPoint(ABCD)
drawLine(ABCA)
\setdashes
drawLine(BD)
\setsolid
drawRightangle(BDC,2.5)
text($B$){B, shift(-1,4)}
text($A$){A, shift(-4,-2)}
text($C$){C, shift(4,-1)}
text($D$){D, shift(1,-4)}
showLength(BD)
showLength(AC)
showArea(ABC)
showAngle(ABC)
\endpicture
\end{document}
\end{verbatim}


When the above \mathsPIC\ file is processed by {\mathsPIC} the
output-file (\verb!.mt! file) is as follows. Note how the
{\PiCTeX} commands are preceded by their
{\mathsPIC} commands (commented out), some of which
have additional information (e.g.~the
coordinates of a derived point---see the
line \verb!%% point(D)...!\ ).
Being able to compare the {\mathsPIC} commands and the resulting {\PiCTeX}
commands in the output-file is particularly useful when
debugging.
Note also  how the  \texttt{show...} commands at the end of the file
return the lengths AD, BC, the area ABC, and the angle ABC.


\begin{Verbatim}
%* -----------------------------------------------
%* mathsPIC (Perl version 0.99.22 Dec 29, 2004)
%* A filter program for use with PiCTeX
%* Copyright (c) 2004 A Syropoulos & RWD Nickalls
%* Command line: mpic09922.pl -b mpicpm07-1.m
%* Input filename : mpicpm07-1.m
%* Output filename: mpicpm07-1.mt
%* Date & time: 2005/01/05    10:00:40
%* -----------------------------------------------
%% mpicpm07-1.m  (figure 7.1)
%% mathsPIC  Perl  triangle
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
\setdashes
%% paper{units(1mm),xrange(0,70),yrange(0,50),axes(LRTB),ticks(10,10)}
\setcoordinatesystem units <1mm,1mm>
\setplotarea x from 0.00000 to 70.00000, y from 0.00000 to 50.00000
\axis left ticks numbered from 0 to 50 by 10 /
\axis right ticks numbered from 0 to 50 by 10 /
\axis top ticks numbered from 0 to 70 by 10 /
\axis bottom ticks numbered from 0 to 70 by 10 /
\setsolid
%% point(A){10,10}[symbol=$\odot$, radius=1.2]
        %% anchor point A = (10.00000, 10.00000)
%% point(B){A, polar(40, 50 deg)}[symbol=$\odot$, radius=1.2]
         B = (35.71150, 40.64178)
%% point(C){A, polar(50, 10 deg)}[symbol=$\odot$, radius=1.2]
         C = (59.24039, 18.68241)
%% point(D){perpendicular(B,AC)} 	D = (40.17626, 15.32089)
%% drawPoint(ABCD)
\put {$\odot$} at 10.00000 10.00000 %% A
\put {$\odot$} at 35.71150 40.64178 %% B
\put {$\odot$} at 59.24039 18.68241 %% C
\put {$\bullet$} at 40.17626 15.32089 %% D
%% drawLine(ABCA)
\plot 10.77135 10.91925	34.94015 39.72253 / %% AB
\plot 36.58878 39.82302	58.36311 19.50117 / %% BC
\plot 58.05862 18.47403	11.18177 10.20838 / %% CA
\setdashes
%% drawLine(BD)
\plot 35.91988 39.46001	40.17626 15.32089 / %% BD
\setsolid
%% drawRightangle(BDC,2.5)
\plot  42.63828 15.75501    42.20416 18.21703   /
\plot  39.74214 17.78291    42.20416 18.21703   /
%% text($B$){B, shift(-1,4)}
\put {$B$} at 34.711500 44.641780
%% text($A$){A, shift(-4,-2)}
\put {$A$} at 6.000000 8.000000
%% text($C$){C, shift(4,-1)}
\put {$C$} at 63.240390 17.682410
%% text($D$){D, shift(1,-4)}
\put {$D$} at 41.176260 11.320890
%% length(bd) = 25.7115062228898
%% length(ac) = 50.0000025076019
%% area(abc) = 642.7877063896
%% angle(abc) = 86.97613 deg ( 1.51802 rad)
\endpicture
\end{document}
\end{Verbatim}




If the above output-file (\verb!.mt! file) is to be included or
\verb!\input! into a document (say, into a
\verb!figure! environment), it is sometimes useful
to reduce the size of the file by disabling the writing of
\verb!%%! comment lines  (using the
command-line \texttt{-c} switch), as well as
some of the header and footer lines which are not now required,
as follows.



\begin{Verbatim}
%* -----------------------------------------------
%* mathsPIC (Perl version 0.99.22 Dec 29, 2004)
%* A filter program for use with PiCTeX
%* Copyright (c) 2004 A Syropoulos & RWD Nickalls
%* Command line: mpic09922.pl -c mpicpm07-1.m
%* Input filename : mpicpm07-1.m
%* Output filename: mpicpm07-1.mt
%* Date & time: 2005/01/05    11:50:14
%* -----------------------------------------------
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%---------------
\beginpicture
\setdashes
\setcoordinatesystem units <1mm,1mm>
\setplotarea x from 0.00000 to 70.00000, y from 0.00000 to 50.00000
\axis left ticks numbered from 0 to 50 by 10 /
\axis right ticks numbered from 0 to 50 by 10 /
\axis top ticks numbered from 0 to 70 by 10 /
\axis bottom ticks numbered from 0 to 70 by 10 /
\setsolid
\put {$\odot$} at 10.00000 10.00000 %% A
\put {$\odot$} at 35.71150 40.64178 %% B
\put {$\odot$} at 59.24039 18.68241 %% C
\put {$\bullet$} at 40.17626 15.32089 %% D
\plot 10.77135 10.91925	34.94015 39.72253 / %% AB
\plot 36.58878 39.82302	58.36311 19.50117 / %% BC
\plot 58.05862 18.47403	11.18177 10.20838 / %% CA
\setdashes
\plot 35.91988 39.46001	40.17626 15.32089 / %% BD
\setsolid
\plot  42.63828 15.75501    42.20416 18.21703   /
\plot  39.74214 17.78291    42.20416 18.21703   /
\put {$B$} at 34.711500 44.641780
\put {$A$} at 6.000000 8.000000
\put {$C$} at 63.240390 17.682410
\put {$D$} at 41.176260 11.320890
%% length(bd) = 25.7115062228898
%% length(ac) = 50.0000025076019
%% area(abc) = 642.7877063896
%% angle(abc) = 86.97613 deg ( 1.51802 rad)
\endpicture
\end{document}
\end{Verbatim}
Note that the remaining comments at the end of the
\verb!\plot! and \verb!\put! lines are generally sufficient to
understand what each line relates to.
Note also that the \texttt{-c} switch only removes comment lines
having a leading \verb!%%! pair of characters (but not the results of the 
\verb!show()! commands); comment lines
prefixed with only a single \verb!%! character remain.


%---------------------
\section{Line modes}

When drawing figures with both solid and dashed lines
it is necessary to switch between the {\PiCTeX} commands
\verb!\setdashes! and \verb!\setsolid!,
as in the following code for drawing the rectangular box
shown in Figure~\ref{fig:example2}.
The default \verb!\setdashes! gives alternating lines and
spaces, each of width 5pt.


More fancy dash-patterns (see Figure~\ref{fig:example2}) can be easily generated using
the {\mathsPIC} \verb!dasharray()! command which defines
the pattern cycle, and hence takes an even number of
parameters. For example the command
\begin{verbatim}
dasharray(6pt,2pt,1pt,2pt)
\end{verbatim}
generates the  dash pattern used for lines $AH$ and $DE$ in Figure~\ref{fig:example2}.

If several different dash patterns  are required then
it maybe  useful to define them as separate \mathsPIC\
 macros, as follows for example.
\begin{verbatim}
%def fancydashes()  dasharray(6pt,2pt, 1pt, 2pt)
%def simpledashes()  dasharray(4pt,4pt)
\end{verbatim}
The separate patterns can then  be called as required as
follows (see Figure~\ref{fig:example2}).
\begin{verbatim}
...
fancydashes
drawline(AH, DE)
simpledashes
drawline(BG, CF)
...
\end{verbatim}

The equivalent \PiCTeX\ command is the  \verb!\setdashpattern! command which also takes an even number of parameters but has a slightly different syntax as follows.
\begin{verbatim}
\setdashpattern <6pt,2pt,1pt,2pt>
\end{verbatim}
The equivalent \LaTeX\  macro would be as follows.
\begin{verbatim}
\def\fancydashes{\setdashpattern <6pt, 2pt, 1pt, 2pt>}%
...
\fancydashes
\end{verbatim}


Note that in Figure~\ref{fig:example2}  all the points are defined, directly or
indirectly,  relative to point $A$, with the effect that
the position of the whole figure
can  be adjusted simply by altering the coordinates of
point $A$. This can be useful when drawing diagrams
having several components since the relative position
of each component can then be easily adjusted.



%-----figure 5-----------------
\begin{figure}[hbt]
%% the rectangular box
\centering
\ifpdf
  \includegraphics[width=6cm]{mpicpm07-2.pdf}
  \else
  \includegraphics[width=6cm]{mpicpm07-2.eps}
  \fi
  \caption{\ }
   \label{fig:example2}
\end{figure}
%%----------------------




\begin{Verbatim}
%% mpicpm07-2.m (Figure 7.2)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm), xrange(0,50), yrange(0,62)}
var s= 20  % Sides front & back
var L = 34  % Length
var a2 = 56.6  % angle degrees
%def fancydashes() dasharray(6pt,2pt, 1pt, 2pt)%
%def simpledashes() dasharray(4pt,4pt)%
point(A){5,7}
point(B){A, polar(s,90 deg)}
point(C){B, polar(s,0  deg)}
point(D){A, polar(s,0  deg)}
point(H){A, polar(L,a2 deg)}
point(G){B, polar(L,a2 deg)}
point(F){C, polar(L,a2 deg)}
point(E){D, polar(L,a2 deg)}
drawpoint(ABCDEFGH)
linethickness(2pt)
  \setsolid
drawline(ABCDA)
  \setdashes
drawline(HGFEH)
linethickness(default)
&fancydashes
drawline(AH, DE)
&simpledashes
drawline(BG, CF)
text($A$){A, shift(-2,-4)}
text($B$){B, shift(-4,1)}
text($C$){C, shift(4,0)}
text($D$){D, shift(1,-4)}
text($E$){E, shift(4,0)}
text($F$){F, shift(2,4)}
text($G$){G, shift(-1,4)}
text($H$){H, shift(-4,1)}
\endpicture
\end{document}
\end{Verbatim}
%------------------


\newpage
%======================
\section{Arrows}
\label{sec:arrows}

Arrows can be drawn in all possible orientations,
will \textit{stretch} between points, and arrow-heads
are readily customised using the
{\mathsPIC} \texttt{Arrowshape} command (see also Salomon,
1992).

Although arrow shape can of course be controlled using
the standard {\PiCTeX} \verb!\arrow! command,
the {\mathsPIC} \texttt{Arrowshape} command makes this
easier by allowing you to define (in degrees) the angle parameters ($B$ and $C$) of the arrow-head directly (see box).
 The default arrowshape is equivalent to the following command

\begin{verbatim}
Arrowshape(2mm,30,40)
\end{verbatim}
and can be invoked using the command
\begin{verbatim}
ArrowShape(default)
\end{verbatim}


%%--------BOX with arrow diagram----Figure 6----

\begin{figure}[hbt]
\centering
  \ifpdf
  \includegraphics[width=10cm]{mpicpm07-3.pdf}
  \else
  \includegraphics[width=10cm]{mpicpm07-3.eps}
  \fi
  \caption{The \mathsPIC\ code for this figure is given in the appendix}
  \label{fig:example3}
\end{figure}
%%---------------------------------------



If the arrowshape has been altered, it can be reset using the
\verb!ArrowShape(default)! command.
    Curved arrows (circular arcs)  are drawn using the \verb!drawAngleArrow!
command, which takes parameters for the angle, radius of arc,
direction, and whether the angle is internal or external
(see Figures~\ref{fig:example4} and~\ref{fig:example5}).

\pagebreak

%%================================================
%% keep this next triangle fig 4 & code  together
\begin{figure}[hbt]
\noindent
\begin{minipage}{4cm}
%-----------------
\begin{Verbatim}
%% mpicpm07-4.m (Figure 7-4)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm),xrange(5,45),yrange(5,45)}
point(A){30,30}
point(P){10,10}
point(B){30,10}
drawPoint(APB)
drawLine(APBA)
var d = 5
text($A$){A,shift(1,d)}
text($B$){B,shift(d,0)}
text($P$){P,shift(-d,0)}
drawAngleArrow{angle(BPA),radius(11),internal, anticlockwise}
text($\psi$){P,polar(7,22.5 deg)}
drawRightangle(ABP,2.5)
\endpicture
\end{document}
\end{Verbatim}
\end{minipage}
%%-----------
  \hspace{3cm}
%%-----------
\begin{minipage}{4cm}
%% arrow1
   \vspace{.1mm}
   %% small triangle with angle arrow (arrow1)
  \ifpdf
  \includegraphics[width=4cm]{mpicpm07-4.pdf}
  \else
  \includegraphics[width=4cm]{mpicpm07-4.eps}
  \fi 
   \vspace{-9mm}  %%to adjust the position of the caption%%
   \caption{\ }
   \label{fig:example4}
   \vspace{2.5cm}
\end{minipage}
%----------
\hfill
\end{figure}
%%========================================




Arrows can also be used to link elements in a diagram,
 as shown in Figure~\ref{fig:example5}. The right-hand diagram uses the
 \texttt{drawArrow} command; the small gap between the
arrows and the letters $P,Q,R,T$ being due to the 5 unit
line-free radius associated with these points
(see Figure~\ref{fig:example5}b. The arrows
are easily `stretched' to accommodate their labels
 simply by adjusting the separation of the nodes using the
 \texttt{polar($r$,$\theta$)} commands (see  Feruglio, 1994).


\bigskip

%%------------Figure 8-----------------
%% the plotting area
\begin{figure}[hbt]
\begin{center}
\noindent
%\framebox{
\begin{minipage}{3cm}
   \centering
   \vspace{2.6cm}  %% controls top space
  \ifpdf
  \includegraphics[width=3cm]{mpicpm07-5a.pdf}
  \else
  \includegraphics[width=3cm]{mpicpm07-5a.eps}
  \fi 
    %\vspace{5mm}  %% controls space between pict and caption
    a. Circular arrows
\end{minipage}
%} % end of framebox
%-----------------------
\hspace{12mm} %% controls space between figs
%%\bigskip\bigskip  %% use this to place vertically
%% use this when making A5 booklet to put vertically
%% and use with \clearpage to flush the floats
%%----------------------
%\framebox{
\begin{minipage}{5cm}
 \centering
  %\vspace{3mm}  %% controls top space
   \ifpdf
  \includegraphics[width=5cm]{mpicpm07-5b.pdf}
  \else
  \includegraphics[width=5cm]{mpicpm07-5b.eps}
  \fi 
  %\vspace{5mm}  %% controls space between pict and caption
     b.  Straight arrows
\end{minipage}
%} % end of framebox
\caption{\hspace{7mm} }
\label{fig:example5}
\end{center}
\end{figure}
%-----------------------



\begin{Verbatim}
%% mpicpm07-5a.m (Figure 5a)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm),xrange(10,40),yrange(0,45)}%, axes(LB), ticks(10,10)}
point(N){15,20}
point(S){N,shift(20,0)}
text(\framebox{$N$}){N,shift(0,-2.5)}
text(\framebox{$S$}){S,shift(0,-2.5)}
point(Z){midpoint(NS)}
drawAngleArrow{angle(NZS),radius(NZ),internal,clockwise}
point(N1){N,shift(2,1)}
point(S1){S,shift(-2,1)}
point(Z1){Z,shift(0,-3)}
drawAngleArrow{angle(N1Z1S1),radius(N1Z1),internal,clockwise}
point(N2){N1,shift(2,-0.5)}
point(S2){S1,shift(-2,-0.5)}
point(Z2){Z,shift(0,-10)}
drawAngleArrow{angle(N2Z2S2),radius(N2Z2),internal,clockwise}
\endpicture
\end{document}
\end{Verbatim}
%--------------

\bigskip

\begin{Verbatim}
%% mpicpm07-5b.m (Figure 7.5b)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm),xrange(0,45),yrange(0,45)}%, axes(LB), ticks(10,10)}
point(P){5,10}[symbol=$P$,radius=5]
point(Q){P,polar(30,90 deg)}[symbol=$Q$,radius=5]
point(R){Q,polar(40,0 deg)}[symbol=$R$,radius=5]
point(T){P,polar(30,0 deg)}[symbol=$T$,radius=5]
drawPoint(PQRT)
drawArrow(PQ,QR,PT,TR,PR)
point(P1){midpoint(PQ)}
text($p_1$){P1,shift(3,0)}
point(P2){midpoint(PT)}
text($p_2$){P2,shift(0,-3)}
point(P3){midpoint(PR)}
text($p_3$){P3,shift(2,-2)}
point(T1){midpoint(TR)}
text($t$){T1,shift(3,0)}
point(Q1){midpoint(QR)}
%% use a LaTeX macro for the label
\newcommand{\q}{$q \star q \star q \star q \star q$}
text(\q){Q1,shift(-1,3)}
\endpicture
\end{document}
\end{Verbatim}



%%==========================
\section{Circles \& colour}

{\MathsPIC} allows the point-symbol to be designated as a
circle using the option 
\linebreak\verb![symbol=circle(r),radius=z]! to the
\texttt{point()} command, which not only gives
the circles an internal line-free zone,  but
also arranges that they are drawn by the
\texttt{drawPoint} command,  as shown in Figure~\ref{fig:example6}.
This construction greatly simplifies the drawing of directed
graphs, trees and equivalent structures.
In Figure~\ref{fig:example6} we have also made use of the \LaTeX\ Color package to make the circles red, the lines blue, and the text and labels black, as can be seen from the code in the \mathsPIC\ file. 
Some DVI-viewers may not show colours.
\bigskip



\begin{Verbatim}
%% mpicpm07-6.m  (figure 7.6)
%% 4 circles figure
\documentclass[a4paper]{article}
\usepackage{mathspic,color}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm),xrange(0,70),yrange(0,60)}%
point(A){30,11}[symbol=circle(8),radius=8]
point(B){A,shift(-10,30)}[symbol=circle(15),radius=15]
point(C){A,polar(30,20 deg)}[symbol=circle(5),radius=5]
point(D){A,polar(45,50 deg)}[symbol=circle(7),radius=7]
\color{red}%
drawPoint(ABCD)
\color{blue}%
drawLine(AB,AC,BC,BD,CD)
\setdashes
drawLine(AD)
\color{black}%
text($A$){A}
%% use a macro for the formula
\newcommand{\formula}{%
\     $\displaystyle \sum_{p\ge0} \Delta_{jp} z^{(p+1)}$%
\     }%
text(\formula){B}
text($C$){C}
text($D$){D}
\endpicture
\end{document}
\end{Verbatim}


%-------------figure 9----------
\begin{figure}[hbt]
\centering
  %% 4 circles
 \ifpdf
  \includegraphics[width=7cm]{mpicpm07-6.pdf}
  \else
  \includegraphics[width=7cm]{mpicpm07-6.eps}
  \fi 
  \caption{\ }
  \label{fig:example6}
\end{figure}
%-----------------------



Note that in this particular case it is necessary to define the
maths formula using the \LaTeX\ \verb!\displaystyle!, in order to
avoid the embedded \verb!\textwidth! white space  associated with
using  \verb!\vbox{\formula}! in the \verb!\text()! command,
 and hence allow centering of the figure.
Note also how the {\mathsPIC} \texttt{$\backslash$\gap...}
commands make it easy to include multi-line macros
in the {\mathsPIC} file.



%%---------------

Points on circles (and their labels) are most easily defined
and positioned using the   \texttt{polar($r$,$\theta$)} option,
as shown in the {\mathsPIC} file for Figure~\ref{fig:example7}.
Notice the use of the variable \verb!r! for the radius of the
circle (allocated using the command \verb!var r = 20!),
which then allows the use of \verb!r! to define the radius in
the \verb!polar! commands for the points $P,Q,S$.

%%---------Figure 10 circles---------------------
\begin{figure}[hbt]
\centering
  %% circle and chord with two angles
 \ifpdf
  \includegraphics[width=5cm]{mpicpm07-7.pdf}
  \else
  \includegraphics[width=5cm]{mpicpm07-7.eps}
  \fi 
  \caption{\ }
   \label{fig:example7}
\end{figure}
%%--------------------------



\begin{Verbatim}
%% mpicpm07-7.m (Figure 7.7)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm), xrange(5,55), yrange(5,55)}
point(C){30,30}[symbol=$\odot$,radius=1.2]   %% center
var r = 20                     %% radius
drawcircle(C,r)
point(P){C, polar(r,250 deg)}
point(Q){C, polar(r,120 deg)}
point(S){C, polar(r,-30 deg)}
drawpoint(CPQS)
drawline(PCSQP)
text($P$){P, polar(5,250 deg)}
text($Q$){Q, polar(5,120 deg)}
text($S$){S, polar(5,-30 deg)}
drawAngleArrow{angle(PCS), radius(8) internal anticlockwise}
text($\beta$){C, polar(5,285 deg)}
drawAngleArrow{angle(PQS), radius(12) internal anticlockwise}
text($\alpha$){Q, polar(8,-65 deg)}
showangle(PQS)     % alpha
showangle(PCS)     % beta
\endpicture
\end{document}
\end{Verbatim}
%----------------

Note that the returned values in the output-file
from the \texttt{showAngle} commands   (see below)
for Figure~\ref{fig:example7} indicate that $\beta$ is twice $\alpha$,
as one would expect.


\begin{verbatim}
%% angle(pqs) = 40.00000 deg ( 0.69813 rad)  %alpha
%% angle(pcs) = 80.00000 deg ( 1.39626 rad)  %beta
\end{verbatim}

%---------


{\MathsPIC} offers a range of other circle commands
(\texttt{drawIncircle},
{\newline}\texttt{drawExcircle},
\texttt{drawCircumcircle})
  specifically for geometry diagrams, as shown in Figure~\ref{fig:example8}.

\bigskip

%%---------------------------
\begin{figure}[hbt]
\centering
%% the incircles
 \ifpdf
  \includegraphics[width=8cm]{mpicpm07-8.pdf}
  \else
  \includegraphics[width=8cm]{mpicpm07-8.eps}
  \fi 
   \caption{\ }
   \label{fig:example8}
\end{figure}
%%-----------------------------


\begin{Verbatim}
%% mpicpm07-8.m  (Figure 7.8)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
\setdashes
paper{units(1mm),xrange(0,70),yrange(0,60),axes(LBT*R*),ticks(10,10)}
\setsolid
point(A){10,10}   %% anchor point
point(B){A, polar(50,50 deg)}
point(C){A,polar(50,0 deg)}
point(J){pointonline(AB,30)}
point(K){perpendicular(J,AC)}
drawRightangle(JKC,3)
drawLine(AB,AC,JK)
drawIncircle(AJK)
drawExcircle(AJK,JK)
\setplotsymbol({\large .}) \setdots
drawCircumcircle(AJK)
\setplotsymbol({\tiny .})
point(I){IncircleCenter(AJK)}[symbol=$\odot$, radius=1.2]
point(E){ExcircleCenter(AJK,JK)}[symbol=$\odot$, radius=1.2]
point(P1){perpendicular(E,AC)}
var r = EP1  %% radius of excircle
var d = 72   %% angle of pentagon (deg)
var a1 = -90, a2=a1+d, a3=a2+d, a4=a3+d, a5=a4+d
point(P2){E, polar(r,a2 deg)}
point(P3){E, polar(r,a3 deg)}
point(P4){E, polar(r,a4 deg)}
point(P5){E, polar(r,a5 deg)}
drawPoint(ABCJKIEP1P2P3P4P5)
\setdashes
drawLine(P1P2P3P4P5P1,EP1,EP2)
\setsolid
drawAngleArc{angle(P2EP1),radius(9),internal,clockwise}
\newcommand{\figtitle}{%
   \fbox{%
   \begin{minipage}{30mm}%
   \  Triangle, pentagon and three circles%
   \end{minipage}%
   \  }}%
text(\figtitle){20,52}
var s = 5
text($A$){A,polar(s,230 deg)}
text($B$){B,polar(s,50 deg)}
text($C$){C,polar(s,0 deg)}
text($J$){J,polar(s,90 deg)}
text($K$){K,polar(s,270 deg)}
text($E$){E,polar(s,a3 deg)}
text($72$){E,polar(5.5,-54 deg)}
text($I$){I,shift(3, 0)}
text($P_1$){P1,polar(s, a1 deg)}
text($P_2$){P2,polar(s, a2 deg)}
text($P_3$){P3,polar(s, a3 deg)}
\endpicture
\end{document}
\end{Verbatim}
%------------------


%==========================================
\section{Functionally connected diagrams}
\label{sec:functionaldiag}

When constructing diagrams it is often useful to write the
{\mathsPIC} file in such a way that the position of each new point
is related to that of earlier points, since then the structure
of the diagram is maintained even when points are moved
as shown in  Figure~\ref{fig:example9}.
Although the two diagrams appear to be quite different
the {\mathsPIC} code
for the two diagrams differs \emph{only} in the angle of the
line $AB$ (left diagram, 60 degrees; right diagram, 5~degrees)
as defined in the \verb!point(B){...}! command as follows.


\begin{itemize}
  \item Left-hand diagram: \verb!point(B){A,polar(45,60 deg)}!
  \item Right-hand diagram: \verb!point(B){A,polar(45,5 deg)}!
\end{itemize}


\bigskip

%%--------figure 12-----------------
%% dynamic.m
 \begin{figure}[hbt]
\centering
 %% dynamic figure
 \ifpdf
  \includegraphics[width=11cm]{mpicpm07-9.pdf}
  \else
  \includegraphics[width=11cm]{mpicpm07-9.eps}
  \fi 
  \caption{The {\mathsPIC} code for the two diagrams differs
	   \emph{only} in the angle of the line $AB$ as defined
	   in the \texttt{point(B)\char`\{...\char`\}} command
	   (see \texttt{mpicpm07-9.m}).}
	   \label{fig:example9}
  \end{figure}
%-----------------------





\begin{Verbatim}
%% mpicpm07-9.m (Figure 7.9)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm), xrange(5,110), yrange(0,45)}
point(A){15,5}[symbol=$\odot$, radius=1.2]
point(P){A, shift(10,30)}[symbol=$\odot$, radius=1.2]
point(B){A, polar(45,60 deg)}
point(Q){perpendicular(P,AB)}
drawRightangle(PQA,2)
drawPoint(ABPQ)
drawLine(ABPQ)
drawIncircle(PQB)
var d = 5
text($A$){A,shift(-d, 0)}
text($B$){B,shift(d, 0)}
text($P$){P,shift(-d, 0)}
point(S){pointOnLine(QP,-5)}
text($Q$){S}
point(N){A,shift(0,10)}
\setdashes
drawline(AN)
\setsolid
drawAngleArrow{angle(NAB), radius(5.7), internal, clockwise}
%%---------  second figure --------------------
point*(A){60,5}[symbol=$\odot$, radius=1.2]
point*(P){A, shift(10,30)}[symbol=$\odot$, radius=1.2]
point*(B){A, polar(45,5 deg)} %%5 60 deg
point*(Q){perpendicular(P,AB)}
drawRightangle(PQA,2)
drawPoint(ABPQ)
drawLine(ABPQ)
drawIncircle(PQB)
text($A$){A,shift(-5, 0)}
text($B$){B,shift(5, 0)}
text($P$){P,shift(-5, 0)}
point*(S){pointOnLine(QP,-5)}
text($Q$){S}
point*(N){A,shift(0,10)}
\setdashes
drawline(AN)
\setsolid
drawAngleArrow{angle(NAB), radius(5.7), internal, clockwise}
\endpicture
\end{document}
\end{Verbatim}
%-------------------

Note that in Figure~\ref{fig:example9}
 the location of the label `Q' is made to
lie outside the figure by placing the label at
point~S, which is defined as being 5 mm to the right of the
line $AB$ and in-line with the points PQ, using the command
{\newline}\verb!point(S){pointOnLine(QP,-5)}!.


%%================================================
\section{Inputting the same data-file repeatedly}

There are two methods:
\begin{itemize}
\item use the \texttt{beginloop [n] \ldots\ endloop} environment

The file \texttt{myfile.dat} is input six
times sequentially using the commands
\begin{verbatim}
beginLOOP 6
    inputfile(myfile.dat)
endLOOP
\end{verbatim}

\item use the \verb!inputfile [n]! command

The file \texttt{myfile.dat} is input six
times sequentially using the single command
{\newline}\verb!inputfile(myfile.dat)[6]!.
\end{itemize}

%%---------figure 13-----------
\begin{figure}[hbt]
\centering
  %% spiral
 \ifpdf
  \includegraphics[width=5.5cm]{mpicpm07-10.pdf}
  \else
  \includegraphics[width=5.5cm]{mpicpm07-10.eps}
  \fi 
  \caption{\ }
  \label{fig:example10}
\end{figure}
%-----------------------

 Figure~\ref{fig:example10} was produced by the following
code  which inputs a small file of {\mathsPIC}
code (\verb!mpicpm07-10.dat!) repeatedly 35 times using the
command
{\newline}\verb!inputfile(mpicpm07-10.dat)[35]!.
Note the use of the \verb!point*! commands in the data-file
to re-allocate points.


\begin{Verbatim}
%% mpicpm07-10.m  (figure 7-10)
%% mathsPIC  small spiral by recursion
%%  (requires datafile mpicpm07-10.dat)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1mm), xrange(0,60), yrange(0,60)}% axes(LB), ticks(10,10)}
point(C){30,30}   % circle center
drawcircle(C,25)
%% initialise the reusable points and variables
var a=315  % angle degrees
var r=20   % start radius
var s=5    % square semi-diagonal (see datafile)
point(T){C,polar(r,330 deg)}
%% cycle datafile 35 times
inputfile(mpicpm07-10.dat)[35]
\endpicture
\end{document}
\end{Verbatim}
%---------------
\begin{Verbatim}
      %% mpicpm07-10.dat --------first line----------------
      %% mathsPIC  (spiral data)  input by file mpicpm07-10.m
      var a = a+15, r = r-0.5   %% increment angle and radius
      point*(P){C,polar(r,a deg)} % increment point P
      drawpoint(P)
      drawline(TP)        %% draw line from OLD T to NEW P
      point*(T){P}        %% reallocate T <-- P
      %% make a rotated square centered on P with side/2=s
      point*(Q1){P,polar(s,0 deg)}
      point*(Q2){P,polar(s,90 deg)}
      point*(Q3){P,polar(s,180 deg)}
      point*(Q4){P,polar(s,270 deg)}
      drawline(Q1Q2Q3Q4Q1)
      %% eof ============================================
\end{Verbatim}
When the \verb!inputfile! command is used
\mathsPIC\ writes the iteration number to the output file, prefixed using three \verb!%! symbols (to make sure they are not deleted when using the \verb!-c! switch,  as follows.
\begin{verbatim}
%%% Iteration number: 26
\end{verbatim}

For example, the following extract  shows the resulting output \verb!.mt! file showing how \mathsPIC\  writes the iteration number of each data-file input to the output file just before it inputs the data-file.
This example includes the whole of the 26th cycle of data-file input. It also demonstrates the value of labelling the beginning and the end of the data-file differently in order to make it easy to see the cycling of the input file. This is very  helpful
as it allows you to check whether the data-file is working correctly.

\begin{Verbatim}
...
...
\plot 31.49519 26.25000	36.49519 21.25000 / %% Q3Q4
\plot 36.49519 21.25000	41.49519 26.25000 / %% Q4Q1
%% eof ============================================
%%% Iteration number: 26
%% mpicpm07-10.dat --------first line----------------
%% mathsPIC  (spiral data)  input by file mpicpm07-10.m
%% var a = a+15, r = r-0.5   %% increment angle and radius
%% a = 705
%% r = 7
%% point*(P){C,polar(r,a deg)} %increment P, P=(36.76148, 28.18827)
%% drawpoint(P)
\put {$\bullet$} at 36.76148 28.18827 %% P
%% drawline(TP)        %% draw line from OLD T to NEW P
\plot 36.49519 26.25000	36.76148 28.18827 / %% TP
%% point*(T){P} %% reallocate T <-- P 	T = (36.76148, 28.18827)
%% make a square on P  with side/2=s (s is defined in mpicpm07-10.m)
%% point*(Q1){P,polar(s,0 deg)} 	Q1 = (41.76148, 28.18827)
%% point*(Q2){P,polar(s,90 deg)} 	Q2 = (36.76148, 33.18827)
%% point*(Q3){P,polar(s,180 deg)} 	Q3 = (31.76148, 28.18827)
%% point*(Q4){P,polar(s,270 deg)} 	Q4 = (36.76148, 23.18827)
%% drawline(Q1Q2Q3Q4Q1)
\plot 41.76148 28.18827	36.76148 33.18827 / %% Q1Q2
\plot 36.76148 33.18827	31.76148 28.18827 / %% Q2Q3
\plot 31.76148 28.18827	36.76148 23.18827 / %% Q3Q4
\plot 36.76148 23.18827	41.76148 28.18827 / %% Q4Q1
%% eof ============================================
%%% Iteration number: 27
%% mpicpm07-10.dat --------first line----------------
...
...
\end{Verbatim}
Because \mathsPIC\ prefixes the iteration number comment with \verb!%%%! these comments  remain even when the \verb!-c! switch is used, as the following extract of the same data shows.
\begin{Verbatim}
...
...
\plot 31.49519 26.25000	36.49519 21.25000 / %% Q3Q4
\plot 36.49519 21.25000	41.49519 26.25000 / %% Q4Q1
%%% Iteration number: 26
\put {$\bullet$} at 36.76148 28.18827 %% P
\plot 36.49519 26.25000	36.76148 28.18827 / %% TP
\plot 41.76148 28.18827	36.76148 33.18827 / %% Q1Q2
\plot 36.76148 33.18827	31.76148 28.18827 / %% Q2Q3
\plot 31.76148 28.18827	36.76148 23.18827 / %% Q3Q4
\plot 36.76148 23.18827	41.76148 28.18827 / %% Q4Q1
%%% Iteration number: 27
\put {$\bullet$} at 36.50000 30.00000 %% P
...
...
\end{Verbatim}



%%----------------------
\subsection{Using the \texttt{beginloop...endloop} environment}

The  script for the  previous spiral figure of squares
can be written  more simply (i.e.~without repeatedly inputting a separate file) using the \verb!beginloop...endloop!
environment as shown in the following example. Some care needs to be
 taken in initialising (before the loop) all those quantities which get changed or incremented with each cycle of the loop. Note also that  (a)~since we are not using the \verb!inputfile! command it is useful to create  a loop counter~($n$) so we can see which loop is which when we read the output \texttt{.mt} file,
(b)~the squares will not be rotated in this particular example as we are using the \verb![symbol=square(s)]! option with the point command in order to generate the square, and (c)~since all {\mathsPIC} commands are case-insensitive we have chosen to capitalise the `loop' of the  commands for clarity.

\begin{Verbatim}
\beginpicture
paper{units(1mm), xrange(0,60), yrange(0,60) axes(LB), ticks(10,10)}
point(C){30,30}   % circle center
drawcircle(C,25)
%% initialise loop counter (n), angle (a), radius (r), side (s)
var n=0, a=315, r=20, s=7
point(T){C,polar(r,330 deg)}
beginLOOP 35       % loop 35 times
    %% increment loop counter (n), angle (a) and radius (r)
    var n=n+1, a = a+15, r = r-0.5
    %% increment position of new square with side s
    point*(P){C,polar(r,a deg)}[symbol=square(s)]
    drawpoint(P)         % draw new square
    text($\bullet$){P}   % draw bullet in center of new square
    drawline(TP)         % draw line from OLD T to NEW P
    point*(T){P}         % reallocate T <-- P
endLOOP
\endpicture
\end{Verbatim}


%%----------------------
\subsection{Using \LaTeX\ to cycle a loopcounter}

A slightly irritating problem associated with processing diagrams which involve repeated loops is that while the \verb!.mt! file is  being processed  by \LaTeX\  there is no screen activity to show how things are proceeding.

In this example program we therefore  illustrate a simple way of using some  \LaTeX\ register commands (Knuth (1990) p~118--121; 272-273; Eijkhout (1992) p~242--244) in order to make \LaTeX\  indicate the loop status on the screen while it is  processing the \verb!.mt! file. This can be useful for debugging especially if the loop is cycled many times.


We first allocate a suitable name to  an unused \TeX\ integer register (a so-called \verb!count! register) using the \TeX\ \verb!\newcount! command (here we have used the name \verb!\loopcounter!), and then we initialise it to zero, as follows (all in the main calling program).
\begin{verbatim}
\newcount\loopcounter
\loopcounter=0
\end{verbatim}
Then in the loop (or in the data file itself) we increment the counter and also print the result to the screen using the \verb!\typeout{...}%! command, remembering to include a \verb!%! symbol at the end.
\begin{verbatim}
\advance\loopcounter by 1
\typeout{loop = \the\loopcounter}%
\end{verbatim}
A typical use might therefore be as follows:-
\begin{Verbatim}
\beginpicture
\newcount\loopcounter  %% allocate a TeX rigester
\loopcounter=0         %% initialise the register
%% create a convenient macro
\newcommand{\showloopnumber}{%
   \advance\loopcounter by 1           %increment TeX loop counter
   \typeout{loop = \the\loopcounter}%  %print loop no to screen
   \ }%
...
beginLOOP 26
    \showloopnumber%
    ....
endLOOP
\endpicture
\end{Verbatim}



The screen  output during the \LaTeX\ processing (with respect to  the command \verb!latex mpicpm07-10.mt!)  then appears as the following (see Figure~7.10).
\begin{Verbatim}
This is TeX, Version 3.14159 (Web2C 7.4.5)
(./mpicpm07-10.mt
LaTeX2e <2001/06/01>
Babel <v3.7h> and hyphenation patterns for american, french, german,
basque, italian, portuges, russian, spanish, nohyphenation, loaded.
(/usr/share/texmf/tex/latex/base/article.cls
Document Class: article 2001/04/21 v1.4e Standard LaTeX document class
(/usr/share/texmf/tex/latex/base/size10.clo))
(/usr/share/texmf/tex/latex/base/mathspic.sty
Loading mathsPIC package (c) RWD Nickalls & A Syropoulos 08/08/2004
(/usr/share/texmf/tex/generic/pictex/prepictex.tex)
(/usr/share/texmf/tex/generic/pictex/pictexwd.tex)
(/usr/share/texmf/tex/generic/pictex/postpictex.tex)) (./mpicpm07-10.aux)
loop = 1
loop = 2
loop = 3
loop = 4
...
...
loop = 33
loop = 34
loop = 35
[1] (./mpicpm07-10.aux) )
Output written on mpicpm07-10.dvi (1 page, 106560 bytes).
Transcript written on mpicpm07-10.log.
\end{Verbatim}


%%==========================
\section{Plotting graphs}
\label{sec:plotting}

Data-files which do \textit{not} contain {\mathsPIC} commands can be input
using the \verb!inputfile*()! command. This command inputs files
\textit{verbatim}, and so can be used for inputting files
containing, for example, only \PiCTeX\ commands and/or
points for plotting curves.
For example, the following {\mathsPIC} code (\texttt{mpicpm07-11.m})
draws the quartic curve shown in  Figure~\ref{fig:example11}, by inputting
in \textit{verbatim} a datafile containing some
{\PiCTeX} commands and a set of data points for plotting.
Note that in this example the $x$-axis is stretched by using
\verb!units(3cm,cm)! in the \verb!paper{}! command.


\bigskip

%%---------figure 14-----------
\begin{figure}[hbt]
\centering
  %% quartic equation
 \ifpdf
  \includegraphics[width=10cm]{mpicpm07-11.pdf}
  \else
  \includegraphics[width=10cm]{mpicpm07-11.eps}
  \fi 
  \caption{\ }
  \label{fig:example11}
\end{figure}
%-----------------------

\begin{Verbatim}
%% mpicpm07-11.m  (Figure 7-11)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
\linethickness=1pt  %% make a thick line for the axes
paper{units(3cm,1cm),xrange(-1,2),yrange(-2,4),axes(XY),ticks(1,1)}
\linethickness=0.4pt       %% reset to default value
\headingtoplotskip=8mm
\plotheading{\fbox{\Large A quartic equation}}
%% now load file containing data points for curve
inputfile*(mpicpm07-11.dat)
pointsymbol(default,0.3)  % define line-free-radius
point(E1){1,3.5}
text($f(x)=6x^4 - 8x^3 + 1$){E1}  % center the equation at E1
point(E2){1.4,2}
drawarrow(E1E2)
point(J1){0.55,2}
text(inflection points){J1}  % center inflection text at J1
point(J2){0,1}
point(J3){0.6,0}
drawarrow(J1J2,J1J3)
\endpicture
\end{document}
\end{Verbatim}
%------------------
\pagebreak
The datafile for the curve is as follows---note the leading $\backslash\gap$ on the data-point lines to force \mathsPIC\ to read these lines as data (i.e.,~to copy the lines unchanged into the \texttt{.mt} file) and not to process them as \mathsPIC\ commands.
Remember  that {\PiCTeX} requires an \textit{odd} number of pairs of
data points to satisfy its curve-drawing algorithm.\footnote{See
the \PiCTeX\ manual (Wichura, 1992).}
Note also that the final data-point in the sequence must be `terminated' using a $\gap/$ pair, as shown below.
\begin{Verbatim}
%% mpicm07-11.dat  (Figure 7.11)
%% quartic curve data (use an odd number of data points)
\setquadratic
\plot
\  -0.6      3.50
\  -0.5      2.37
\  -0.4      1.66
\  -0.35     1.43
\  ...
\  ...
\  1.15    -0.67
\  1.25     0.02
\  1.35     1.24
\  1.45     3.13  /
\setlinear
%%EOF
 \end{Verbatim}
However, when there are only a few data points, it is sometimes
more convenient just to plot the points separately and then
draw connecting lines, as shown in Figure~\ref{fig:example12}.

\bigskip

%%---------figure 15-----------
\begin{figure}[hbt]
\centering
  %% diet graph
 \ifpdf
  \includegraphics[width=9cm]{mpicpm07-12.pdf}
  \else
  \includegraphics[width=9cm]{mpicpm07-12.eps}
  \fi 
  \caption{\ }
  \label{fig:example12}
\end{figure}
%-----------------------

\begin{Verbatim}
%% mpicpm07-12.m  (Figure 7.12)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\usepackage{amssymb}
\begin{document}
%%--------------
\beginpicture
paper{units(1cm),xrange(0,6),yrange(73,77),axes(LBT*R*),ticks(1,1)}
pointsymbol($\odot$,0.2)
point(d1){1, 76.2}
point(d2){2, 76.2}
point(d3){3, 75.5}
point(d4){4, 75.7}
point(d5){5, 74.6}
drawpoint(d1d2d3d4d5)
drawline(d1d2d3d4d5)
%
pointsymbol($\boxdot$, 0.2)
point(k1){1, 75.2}
point(k2){2, 75.4}
point(k3){3, 74.8}
point(k4){4, 74.1}
point(k5){5, 74.0}
drawpoint(k1k2k3k4k5)
\setdashpattern <2pt, 2pt>
drawline(k1k2k3k4k5)
%
\plotheading{\textsf{\Large Weight change with diet}}
text(\shortstack{\textsf{\large Weight}\\($kg$)}){-1.5,75.3}
text(\textsf{\large Weeks}){3,72}
\endpicture
\end{document}
\end{Verbatim}
%---------------


%=================================
\section{Drawing other curves}


The \verb!drawcurve! command can also be used for drawing smooth
curves linking a number of points or touching lines.
For example, Figure~\ref{fig:example13} shows a smooth curve touching
a piecewise linear closed
line\footnote{Figure~\ref{fig:example13} was constructed and drawn by
Franti\v{s}ek Chv\'{a}la.},
 some of the points being constructed using a B\'{e}zier
technique\footnote{see \textit{The Metafont book} by DE Knuth,
chapter~3 for details regarding B\'{e}zier curves.}.
The smooth curve is drawn using the \verb!drawcurve()! command for
successive three-point sequences.



%%---------figure 16-----------
\begin{figure}[hbt]
\centering
  %% smooth curve from Frantisek
  \ifpdf
  \includegraphics[width=10cm]{mpicpm07-13.pdf}
  \else
  \includegraphics[width=10cm]{mpicpm07-13.eps}
  \fi 
  \caption{A smooth curve inscribed in the intersecting
	    closed line $ABCDEFGA$}
   \label{fig:example13}
\end{figure}
%-----------------------


\begin{Verbatim}
%% mpicpm07-13.m  (Figure 7.13)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
var u = 12    %%  units = 12 mm
paper{units(Umm),xRange(0.5,8.5),yRange(-0.5,5.5)}
var r = 0.7  %% line-free radius of \circ (0.7mm)
var r = r/u  %% line free radius scaled for U mm
pointsymbol($\circ$,r)
Point(A){1,1}
Point(B){2,4}
Point(C){5,3}
Point(D){6,0}
Point(E){8,2}
Point(F){8,5}
Point(G){3,0}
pointsymbol(default)  %% restore $\bullet$
%
Point(A1){midpoint(AB)}
Point(B1){midpoint(BC)}
Point(C1){midpoint(CD)}
Point(D1){midpoint(DE)}
Point(E1){midpoint(EF)}
Point(F1){midpoint(FG)}
Point(G1){midpoint(GA)}
%
Point(A2){midpoint(G1A1)}
Point*(A2){midpoint(AA2)}
Point(B2){midpoint(A1B1)}
Point*(B2){midpoint(BB2)}
Point(C2){midpoint(B1C1)}
Point*(C2){midpoint(CC2)}
Point(D2){midpoint(C1D1)}
Point*(D2){midpoint(DD2)}
Point(E2){midpoint(D1E1)}
Point*(E2){midpoint(EE2)}
Point(F2){midpoint(E1F1)}
Point*(F2){midpoint(FF2)}
Point(G2){midpoint(F1G1)}
Point*(G2){midpoint(GG2)}
%
DrawPoint(ABCDEFG)
DrawPoint(A1B1C1D1E1F1G1)
DrawPoint(A2B2C2D2E2F2G2)
%
DrawLine(ABCDEFGA)
\setplotsymbol ({\Large.})
DrawCurve(A1B2B1)
DrawCurve(B1C2C1)
DrawCurve(C1D2D1)
DrawCurve(D1E2E1)
DrawCurve(E1F2F1)
DrawCurve(F1G2G1)
DrawCurve(G1A2A1)
%
Text($A$){A,shift(-0.2,0)}
Text($B$){B,shift(-0.2,0.1)}
Text($C$){C,shift(0,0.25)}
Text($D$){D,shift(0,-0.25)}
Text($E$){E,shift(0.2,0)}
Text($F$){F,shift(0,0.25)}
Text($G$){G,shift(0,-0.25)}
\scriptsize
Text($A_1$){A1,shift(0.25,0)}
Text($B_1$){B1,shift(0,-0.2)}
Text($C_1$){C1,shift(0.25,0)}
Text($D_1$){D1,shift(-0.2,0.15)} %
Text($E_1$){E1,shift(-0.2,0)}
Text($F_1$){F1,shift(0.15,-0.15)}
Text($G_1$){G1,shift(0.1,0.2)}
Text($A_2$){A2,shift(0.25,0)}
Text($B_2$){B2,shift(0.1,-0.2)}
Text($C_2$){C2,shift(-0.1,-0.15)}
Text($D_2$){D2,shift(0.1,0.2)}
Text($E_2$){E2,shift(-0.25,0.05)} %
Text($F_2$){F2,shift(0.05,-0.2)}  %
Text($G_2$){G2,shift(0,0.25)}    %
\endpicture
\end{document}
\end{Verbatim}
%--------------


\pagebreak
%%============================================================
\section{Scaling}
\label{sec:scaling}


Note the technique used in the code for Figure~\ref{fig:example13} above, for making
the \textit{physical} line-free radius (r) invariant with respect to
the scaling value (u) (i.e.\ does not change when the figure is
enlarged or reduced by varying the value of the variable u),
as follows.

\begin{Verbatim}
....
var u = 12             %%  units = 12 mm
paper{units(u mm),xRange(0,9),yRange(-1,6)}
var r = 0.7            %% line-free radius of \circ = 0.7mm
var r = r/u    %% scaled linefree radius for u mm
pointsymbol($\circ$, r)
point(A){1,1}
....
\end{Verbatim}

This technique can be very useful when it is necessary to
scale the figure after having designed the figure in
order, say, to make it fit into a particular space in a document.




%%============================================================
\section{Using Perl programs}
\label{sec:perl}

Since \mathsPIC\ allows access to the command-line via the \texttt{system()} command, users can write  Perl programs which can then be used as a powerful aid for drawing complicated \mathsPIC\ diagrams.
In other words, components of a diagram (particularly those components which are frequently used) can be encoded as a small Perl program which
can then be invoked via the \mathsPIC\ \texttt{system()} command. Particularly useful is the fact that Perl programs can have parameters passed to them, which greatly increases their value and utility with regard to \mathsPIC. Indeed, a \mathsPIC\ file for drawing a particularly complicated diagram could usefully input several Perl programs, each drawing separate elements of the diagram.

In view of the interplay between the \mathsPIC\ file and the Perl program it calls, we now describe two typical examples in some detail. In the following some familiarity with the Perl programming language is assumed.


%-------------------
\subsection{Example-1}

This  example (see Figure~\ref{fig:example14}) uses the small Perl program \verb!drawcurvedarrow.pl! (see below) to generate the \mathsPIC\ commands for drawing a curved arrow (note that there is no \mathsPIC\ command for doing this at the moment), and place them in a temporary file which can then be accessed by the \mathsPIC\ file.
%%---------figure 17-----------
\begin{figure}[hbt]
\centering
  %% curved arrow
 \ifpdf
  \includegraphics[width=6.5cm]{mpicpm07-14.pdf}
  \else
  \includegraphics[width=6.5cm]{mpicpm07-14.eps}
  \fi 
  \parbox{0.6\textwidth}{\caption{\label{fig:example14}A curved arrow drawn using the Perl program \texttt{drawcurvedarrow.pl}}}  
\end{figure}
%-----------------------

%-----------
\subsubsection*{Perl program (\texttt{drawcurvedarrow.pl})}

\begin{Verbatim}
#!/usr/bin/perl
## drawcurvedarrow.pl
# 5 command-line parameters A B C h filename
my ($A, $B, $C, $h, $filename)=@ARGV;
open (outfile, ">$filename")|| die "ERROR can't create file $filename\n";
print (outfile  "Point*(P999){pointonline($B$A, -($A$B)/3)}\n");
print (outfile  "Point*(H999){pointonline($C P999,$h)}\n");
print (outfile  "Drawcurve($A$B H999)\n");
print (outfile  "drawArrow(H999 $C)\n");
close (outfile);
\end{Verbatim}
The above Perl program accepts five parameters and writes the \mathsPIC\ commands required for drawing  a curved arrow through the three points $A,B,C$ (from $A$ to $C$). The program places an arrowhead (length $h$) at the end pointing at point $C$, and places all the necessary \mathsPIC\ commands into the temporary file \texttt{filename}.

Note that in this example all new points defined in the Perl program are defined using the \verb!point*()! command, since this allows the program to be reused without needing to know which points have been defined before.
The point names \texttt{P999} and \texttt{H999} have been chosen in order to try and avoid clashing with any point names likely to be used in the \mathsPIC\ file.
Indeed, the authors suggest that point numbers $\geq900$ be reserved for use in Perl programs in this way.
Note also that these particular point names (e.g.~H999) need to be separated by a space from a previous string name \hbox{(e.g.~\verb!$A$B H999!)} since they are not Perl variable names (Perl variable names are prefixed with a \$ symbol).


%------------
\subsubsection*{\texttt{System()} command}

\MathsPIC\ `calls' a Perl program  (with appropriate parameters) via the \verb!system()! command. For example, the following \mathsPIC\ commands (a) call the Perl program \verb!drawcurvedarrow.pl! to draw the curved arrow $PQR$ with an arrowhead length $0.4$ units, and places the commands in the file \texttt{temp.txt}, and (b) inputs the temporary file which then contains the commands.
\begin{verbatim}
....
system("perl drawcurvedarrow.pl P Q R 0.4 temp.txt")
inputfile(temp.txt)
....
\end{verbatim}
 It is useful to include the filename as one of the parameters, since this allows us to  write the \mathsPIC\ command to input the same file immediately afterwards.
Note also  that since we are, in effect, using the command-line here then the parameters following the program name must be separated by spaces, as required by Perl syntax.

%-------------
\subsubsection*{The \mathsPIC\ file}

The following example \mathsPIC\ file  uses the above commands to draw a curved arrow from a \fbox{START}  box (just below  the first point $P$) to an \fbox{END} box (below the last point $R$) as shown in Figure~\ref{fig:example14}.
Note the use of the \texttt{[t]} option at the end of two of the \texttt{text()} commands which places the point at the [t]op of the \verb!\fbox{}!.
%----------------

\begin{Verbatim}
%% mpicpm07-14.m  (Figure 7.14)
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
paper{units(1cm) xrange(0,5)  yrange(0,4), axis(LRTB),ticks(1,1)}
point(P){1.25,1}
point(Q){P, polar(2, 65 deg)}
point(R){Q, polar(2,-40 deg)}
drawpoint(Q)
text(\fbox{START}){P}[t]
text($Q$){Q, shift(0,0.5)}
text(\raisebox{-5mm}{\fbox{END}}){R}[t]
linethickness(1pt)
arrowshape(0.4cm, 30,40)
system("perl drawcurvedarrow.pl P Q R 0.4 temp.txt")
inputfile(temp.txt)
\endpicture
\end{document}
\end{Verbatim}
%---------------------


%---------------------------------
\subsubsection*{The temporary file}

When the above \mathsPIC\ file is run it creates (in the same directory) the following four-line temporary ASCII text-file (named \verb!temp.txt!) containing the \mathsPIC\ commands which actually draw the curve,  and then inputs the file \texttt{temp.txt} into the \mathsPIC\ file for processing.
\begin{verbatim}
Point*(P999){pointonline(QP, -(PQ)/3)}
Point*(H999){pointonline(R P999,0.4)}
Drawcurve(PQ H999)
drawArrow(H999 R)
\end{verbatim}


%%-----------------------
\subsubsection*{Output file}

The output \TeX\ file which is generated by running the file \verb!mpicpm07-14.m! through \mathsPIC\ is as follows.
Towards the end of the file you can see the temporary file code and the results after processing by \mathsPIC\ located between the following two lines
\begin{verbatim}
%% ... start of file <temp.txt> loop [1]
...
%% ... end of file <temp.txt> loop [1]
\end{verbatim}
The full output file is as follows.
%------------------------

\begin{Verbatim}
%* -----------------------------------------------
%* mathsPIC (Perl version 0.99.22 Dec 29, 2004)
%* A filter program for use with PiCTeX
%* Copyright (c) 2004 A Syropoulos & RWD Nickalls
%* Command line: mpic09922.pl mpicpm07-14.m
%* Input filename : mpicpm07-14.m
%* Output filename: mpicpm07-14.mt
%* Date & time: 2005/01/05    09:30:55
%* -----------------------------------------------
%% mpicpm07-14.m  (Figure 7.14)
%% curved arrow
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
%% paper{units(1cm) xrange(0,5)  yrange(0,4), axis(LRTB),ticks(1,1)}
\setcoordinatesystem units <1cm,1cm>
\setplotarea x from 0.00000 to 5.00000, y from 0.00000 to 4.00000
\axis left ticks numbered from 0 to 4 by 1 /
\axis right ticks numbered from 0 to 4 by 1 /
\axis top ticks numbered from 0 to 5 by 1 /
\axis bottom ticks numbered from 0 to 5 by 1 /
%% point(P){1.25,1} 	P = (1.25000, 1.00000)
%% point(Q){P, polar(2, 65 deg)} 	Q = (2.09524, 2.81262)
%% point(R){Q, polar(2,-40 deg)} 	R = (3.62733, 1.52704)
%% drawpoint(Q)
\put {$\bullet$} at 2.09524 2.81262 %% Q
%% text(\fbox{START}){P}[t]
\put {\fbox{START}} [t] at 1.250000 1.000000
%% text($Q$){Q, shift(0,0.5)}
\put {$Q$} at 2.095240 3.312620
%% text(\raisebox{-5mm}{\fbox{END}}){R}[t]
\put {\raisebox{-5mm}{\fbox{END}}} [t] at 3.627330 1.527040
%% linethickness(1pt)
\linethickness=1.00000pt\Linethickness{1.00000pt}%
\font\CM=cmr10 at 9.97226pt%
\setplotsymbol  ({\CM .})%
%% arrowshape(0.4cm, 30,40)
%% arrowLength = 0.4cm, arrowAngleB = 30 and arrowAngleC = 40
%% system("perl drawcurvedarrow.pl P Q R 0.4 temp.txt")
%% inputfile(temp.txt)
%% ... start of file <temp.txt> loop [1]
%%% Iteration number: 1
%% point*(P999){pointonline(QP, -(PQ)/3)} 	P999 = (2.37699, 3.41683)
%% point*(H999){pointonline(R P999,0.4)} 	H999 = (3.40661, 1.86063)
%% Drawcurve(PQ H999)
\setquadratic
\plot
	1.25000  1.00000 %P
	2.09524  2.81262 %Q
	3.40661  1.86063 / %H999
\setlinear
%% drawArrow(H999 R)
\arrow <0.40000cm> [0.2679,0.7279] from 3.4066 1.8606 to 3.6273 1.5270
%% ... end of file <temp.txt> loop [1]
\endpicture
\end{document}
\end{Verbatim}
%---------------------
{\LaTeX}ing this file then generates the DVI file for Figure~\ref{fig:example14}.


%%-----------------------
\subsection{Example-2}

Once the main working part of a Perl program has been debugged, then some finishing touches can be added. In the following example (\texttt{drawcube.pl}; to draw a cube) we have, therefore, made it a somewhat more sophisticated program by including (a)~error messages, (b)~made it delete the temporary file automatically, (c)~useful macros, (d)~added colour.

Note also how the one-line \verb!system()! command  in the \mathsPIC\ file calling the \verb!drawcube.pl! program is processed into the temporary file necessary for drawing the cube. This illustrates the value of being able to encode certain elements of a diagram as a separate Perl program capable of receiving parameters, and so making it possible for them to be used as and when necessary.

%------------------------------------
\subsubsection*{Delete temporary file}

In Linux we can automatically delete the temporary file
 by writing the \mathsPIC\ command
\begin{verbatim}
system("rm temp.txt")
\end{verbatim}
(where \verb!rm! is the Linux command for `remove').

Now, this can be done by the Perl program itself (providing the temporary file is not to be input more than once), in which case it would have to output the above command. However, in order for it to do this (i.e.,.~for Perl to write itself a Perl command), the Perl command would have to be written as follows:-
\begin{verbatim}
print (outfile  qq(system("rm $filename")\n));
\end{verbatim}
where the \verb!qq()! command exports the argument in inverted commas,
as required.


%--------------
\subsubsection*{Useful macros}

In addition, we have made  the \mathsPIC\ file more readable by creating the macros  \verb!&center()!,  \verb!&side()!  and  \verb!&filename()! to hold the three parameters, namely  center point, the sidelength and the temporary filename.
 In this way we can pass $P$, $s$ and \verb!temp.txt! as \verb!&center(P)!, \verb!&side(s)! and \verb!&filename(temp.txt)! (note that when \mathsPIC\ macros are used then they need to be prefixed with the \verb!&! symbol).
\begin{verbatim}
%def center(j)j%     %%center point
%def side(j)j%       %%sidelength
%def filename(j)j%   %% temporary file name
point(P){5,5}[symbol=$\bigodot$]
var s=4  %% sidelength
system("perl drawcube.pl  &center(P)  &side(s)  &filename(temp.txt)")
inputfile(temp.txt)
\end{verbatim}

%--------------
\subsubsection*{Added colour}
We have also made use of the \LaTeX\ Color package and coloured the sides of the cube blue, the diagonals red, and the points and labels black. Always load the color package \textit{after} the \mathsPIC\ package. 

%--------------
\subsubsection*{\MathsPIC\ program}

All these improvements are implemented in the following  example \mathsPIC\ script \& Perl  program \verb!drawcube.pl! which draws  a simple cube (side $s$) about   a central point $P$ (see Figure~\ref{fig:example15}).


\begin{Verbatim}
%% mpicpm07-15.m  (Figure 7.15)
\documentclass[a4paper]{article}
\usepackage{mathspic,color}
\begin{document}
%%--------------
\beginpicture
\normalcolor%
paper{units(1cm) xrange(0,6)  yrange(0,6), axis(LB),ticks(1,1)}
point(P){3,3}[symbol=$\bigodot$]  %center of the cube
%def center(j)j%     %% center point
%def side(j)j%       %% sidelength
%def filename(j)j%   %% temp filename
var s=3  %% sidelength
system("perl drawcube.pl &center(P) &side(s) &filename(temp.txt)")
inputfile(temp.txt)
\normalcolor%
\endpicture
\end{document}
\end{Verbatim}
%--------------------
Note that the point-name $P$, side-length $s$, and filename \texttt{temp.txt} are all passed to the Perl program as parameters using the  \verb!system()! command. The code of the Perl program \texttt{drawcube.pl} is listed below.


%---------------------
\subsubsection*{Perl program (\texttt{drawcube.pl})}

\begin{Verbatim}
#!/usr/bin/perl
## drawcube.pl
# pickup command line parameters P,s,filename
# use: system("perl drawcube.pl P s3 temp.txt")
#===========================
my ($argnumber) = $#ARGV +1;
if ($argnumber != 3){
  print "============================\n";
  print "ERROR: drawcube.pl requires 3 arguments\n";
  print "USE:   drawcube.pl  <pointname> <sidelength> <filename> \n";
  print "============================\n";
  exit(1);
}
my ($point, $side, $filename)=@ARGV;
open (outfile, ">$filename")|| die "ERROR can't create file $filename\n";
print (outfile  <<EOF);
\%\%------mathsPIC code----------------
var r=$side*sqrt(2)/2
var a=30 %% angle degrees
Point*(P990){$point, polar(r/2, (a-180) deg)}
Point*(P991){P990, polar(r, 45 deg)}
Point*(P992){P991, rotate(P990, 90)}
Point*(P993){P991, rotate(P990, 180)}
Point*(P994){P991, rotate(P990, 270)}
Point*(P995){P991, polar(r, a deg)}
Point*(P996){P992, polar(r, a deg)}
Point*(P997){P993, polar(r, a deg)}
Point*(P998){P994, polar(r, a deg)}
%% draw the sides
\\color{blue}
drawline(P991 P992 P993 P994 P991, P994 P998 P995 P996 P992, P991 P995)
\\setdashes
drawline(P993 P997 P998, P997 P996)
%% draw the diagonals
\\color{red}
drawline(P991 P997, P992 P998, P996 P994, P995 P993)
%% draw the points and labels
\\setsolid\\color{black}
drawpoint($point P991 P992 P993 P994 P995 P996 P997 P998)
text(\$$point\$){$point, shift(-0.5,-0.1)}
text(\$P991\$){P991, shift(-0.3,0.3)}
text(\$P995\$){P995, shift(-0.3,0.3)}
%%------end of mathspic code----------------------
EOF
# now delete the temp file
print (outfile  qq(system("rm $filename")\n));
close outfile
__END__
\end{Verbatim}
Note the use of the \verb!<<EOF!\ldots\verb!EOF! environment  in the Perl programme to contain the chunk of \mathsPIC\ code which is written to text file \verb!temp.txt!.
Note also that where you want \$ and $\backslash$ characters written to the output file (temporary file---for use by {\mathsPIC}) by the Perl program, it is important to remember that these characters need to be  `escaped' using a preceding backslash. In the above example the point name $P$ is held in the Perl variable \verb!$point!; consequently  since we need the Perl program to write the \mathsPIC\ command \verb!text($P$){P,shift(-0.5, -0.1)}! to the temporary file the  Perl code needs to be \verb!text(\$$point\$){$point, shift(-0.5,-0.1)}!

%---------------
\subsubsection*{The temporary file}
\begin{Verbatim}
%%------mathsPIC code----------------
var r=s*sqrt(2)/2
var a=30 %% angle degrees
Point*(P990){P, polar(r/2, (a-180) deg)}
Point*(P991){P990, polar(r, 45 deg)}
Point*(P992){P991, rotate(P990, 90)}
Point*(P993){P991, rotate(P990, 180)}
Point*(P994){P991, rotate(P990, 270)}
Point*(P995){P991, polar(r, a deg)}
Point*(P996){P992, polar(r, a deg)}
Point*(P997){P993, polar(r, a deg)}
Point*(P998){P994, polar(r, a deg)}
%% draw the sides
\color{blue}
drawline(P991 P992 P993 P994 P991, P994 P998 P995 P996 P992, P991 P995)
\setdashes
drawline(P993 P997 P998, P997 P996)
%% draw the diagonals
\color{red}
drawline(P991 P997, P992 P998, P996 P994, P995 P993)
%% draw the points and labels
\setsolid\color{black}
drawpoint(P P991 P992 P993 P994 P995 P996 P997 P998)
text($P$){P, shift(-0.5,-0.1)}
text($P991$){P991, shift(-0.3,0.3)}
text($P995$){P995, shift(-0.3,0.3)}
system("rm $filename")
%%----------------------------
\end{Verbatim}

%--------------
\subsubsection*{Output file}

When the \mathsPIC\ script is run the output file is as follows.


\begin{Verbatim}
%* -----------------------------------------------
%* mathsPIC (Perl version 0.99.22 Dec 29, 2004)
%* A filter program for use with PiCTeX
%* Copyright (c) 2004 A Syropoulos & RWD Nickalls
%* Command line: mpic09922.pl mpicpm07-15.m
%* Input filename : mpicpm07-15.m
%* Output filename: mpicpm07-15.mt
%* Date & time: 2005/01/05    09:46:22
%* -----------------------------------------------
%% mpicpm07-15.m  (Figure 7.15)
\documentclass[a4paper]{article}
\usepackage{mathspic,color}
\begin{document}
%%--------------
\beginpicture
%% paper{units(1cm) xrange(0,6)  yrange(0,6), axis(LB),ticks(1,1)}
\setcoordinatesystem units <1cm,1cm>
\setplotarea x from 0.00000 to 6.00000, y from 0.00000 to 6.00000
\axis left ticks numbered from 0 to 6 by 1 /
\axis bottom ticks numbered from 0 to 6 by 1 /
%% point(P){3,3}[symbol=$\bigodot$]  %center P = (3.00000, 3.00000)
%def center(j)j%     %% center point
%def filename(j)j%   %% temp filename
%def side(j)j%       %% sidelength
%% var s=3  %% sidelength
%% s = 3
%% system("perl drawcube.pl P s temp.txt")
%% ... start of file <temp.txt> loop [1]
%%% Iteration number: 1
%%------mathsPIC code----------------
%% var r=s*sqrt(2)/2
%% r = 2.12132034355964
%% var a=30 %% angle degrees
%% a = 30
%% point*(P990){P, polar(r/2, (a-180) deg)} 	P990 = (2.08144, 2.46967)
%% point*(P991){P990, polar(r, 45 deg)} 	P991 = (3.58144, 3.96967)
%% point*(P992){P991, rotate(P990, 90)} 	P992 = (0.58144, 3.96967)
%% point*(P993){P991, rotate(P990, 180)} 	P993 = (0.58144, 0.96967)
%% point*(P994){P991, rotate(P990, 270)} 	P994 = (3.58144, 0.96967)
%% point*(P995){P991, polar(r, a deg)} 	P995 = (5.41856, 5.03033)
%% point*(P996){P992, polar(r, a deg)} 	P996 = (2.41856, 5.03033)
%% point*(P997){P993, polar(r, a deg)} 	P997 = (2.41856, 2.03033)
%% point*(P998){P994, polar(r, a deg)} 	P998 = (5.41856, 2.03033)
%% draw the sides
\color{blue}
%% drawline(P991 P992 P993 P994 P991, P994 P998 P995 P996 P992, P991 P995)
\putrule from 3.58144 3.96967 to 0.58144 3.96967 %% P991P992
\putrule from 0.58144 3.96967 to 0.58144 0.96967 %% P992P993
\putrule from 0.58144 0.96967 to 3.58144 0.96967 %% P993P994
\putrule from 3.58144 0.96967 to 3.58144 3.96967 %% P994P991
\plot 3.58144 0.96967	5.41856 2.03033 / %% P994P998
\putrule from 5.41856 2.03033 to 5.41856 5.03033 %% P998P995
\putrule from 5.41856 5.03033 to 2.41856 5.03033 %% P995P996
\plot 2.41856 5.03033	0.58144 3.96967 / %% P996P992
\plot 3.58144 3.96967	5.41856 5.03033 / %% P991P995
\setdashes
%% drawline(P993 P997 P998, P997 P996)
\plot 0.58144 0.96967	2.41856 2.03033 / %% P993P997
\putrule from 2.41856 2.03033 to 5.41856 2.03033 %% P997P998
\putrule from 2.41856 2.03033 to 2.41856 5.03033 %% P997P996
%% draw the diagonals
\color{red}
%% drawline(P991 P997, P992 P998, P996 P994, P995 P993)
\plot 3.58144 3.96967	2.41856 2.03033 / %% P991P997
\plot 0.58144 3.96967	5.41856 2.03033 / %% P992P998
\plot 2.41856 5.03033	3.58144 0.96967 / %% P996P994
\plot 5.41856 5.03033	0.58144 0.96967 / %% P995P993
%% draw the points and labels
\setsolid\color{black}
%% drawpoint(P P991 P992 P993 P994 P995 P996 P997 P998)
\put {$\bigodot$} at 3.00000 3.00000 %% P
\put {$\bullet$} at 3.58144 3.96967 %% P991
\put {$\bullet$} at 0.58144 3.96967 %% P992
\put {$\bullet$} at 0.58144 0.96967 %% P993
\put {$\bullet$} at 3.58144 0.96967 %% P994
\put {$\bullet$} at 5.41856 5.03033 %% P995
\put {$\bullet$} at 2.41856 5.03033 %% P996
\put {$\bullet$} at 2.41856 2.03033 %% P997
\put {$\bullet$} at 5.41856 2.03033 %% P998
%% text($P$){P, shift(-0.4,-0.1)}
\put {$P$} at 2.600000 2.900000
%% text($P991$){P991, shift(-0.3,0.3)}
\put {$P991$} at 3.281440 4.269670
%% text($P995$){P995, shift(-0.3,0.3)}
\put {$P995$} at 5.118560 5.330330
%%----------------------------
%% system("rm temp.txt")
%% ... end of file <temp.txt> loop [1]
\endpicture
\end{document}
\end{Verbatim}
%-----------------------
and the diagram is shown in Figure~\ref{fig:example15}.

%%---------figure 7.15-----------
\begin{figure}[hbt]
  \centering
  \ifpdf
    \includegraphics[width=6cm]{mpicpm07-15.pdf}
    \else
    \includegraphics[width=7cm]{mpicpm07-15.eps}
  \fi
  \begin{minipage}{0.92\textwidth}
        \caption{\label{fig:example15}}
{3-D cube drawn about a central point $P$ ($3,3$) and with sidelength $s$ ($s=3$).  The PDF  and PostScript versions of the output show the sides coloured blue, the diagonals red, and the points and labels black.   The \mathsPIC\ command used was:-
{\newline}\verb!system("perl drawcube.pl &center(P) &side(s) &filename(temp.txt)")!.}
   \end{minipage}
\end{figure}
%-----------------------


%---------------
\subsection{Commands for processing the files}
In Linux the command-line commands used to generate  and print figure~\ref{fig:example15} were as follows:

\begin{verbatim}
perl mathspic.pl mpicpm07-15.m
latex mpicpm07-15.mt
xdvi mpicpm07-15.dvi   %% to view dvi file
dvips -o  mpicpm07-15.ps mpicpm07-15.dvi %% generate the .ps version
gv mpicpm07-15.ps      %% view the .ps version
lpr mpicpm07-15.ps     %% print the .ps version
\end{verbatim}



\end{document}
