%% mpicp-intro.tex
%% mathspic manual

\documentclass[mathsPICmanual.tex]{subfiles}
\begin{document}
%%=============================
\chapter{Introduction}


{\MathsPICperl}
  is an open source Perl  program for drawing mathematical diagrams and figures\footnote{The first version of {\mathsPIC} (an MS-DOS version) was  presented  at the 1999 Euro{\TeX} conference in Heidelberg, Germany (Nickalls, 1999). A much improved Perl version was then developed, and  a `work-in-progress' presentation was given  at the 2000 Euro{\TeX}  meeting in Oxford, UK (Syropoulos and Nickalls, 2000). The first Perl version  ($1.0$)  was  eventually uploaded to CTAN in 2005.   The \mathsPICperl\ program is written in Perl 5.8.2  built for i86pc-Solaris. {\MathsPICperl} can be freely  downloaded from CTAN (\url{http://www.ctan.org/tex-archive/graphics/mathspic/perl/}).}
  (Nickalls, 1999; Syropoulos and Nickalls, 2000, 2005, 2007).
 More specifically,  {\MathsPIC} is a `filter' program which  parses a plain text  input-file (known as the {\mathsPIC} or  \texttt{.m} file),  and generates a plain text output-file  containing \TeX, \LaTeX\ and  {\PiCTeX}  commands for drawing a diagram. This output-file---which has by default an  \texttt{.mt} filename-extension as it is really a \TeX\ file---can then be processed by \TeX\ or \LaTeX\ in the usual way.  It is anticipated that future versions will be able to generate output files in PostScript and SVG code.

  Spaces and the comment \texttt{\%} symbol  are used by \mathsPIC\ in the same way as \TeX. However, {\mathsPIC} commands are \textit{not} case-sensitive, and do not have a leading backslash (in order to distinguish them from  {\PiCTeX}, \TeX\ and \LaTeX\  commands, all of which can be  freely used in the {\mathsPIC}  script file).
    {\MathsPIC}  also  returns various parameter values in
   the output-file, e.g.,~angles, distances between points,
center and radius of inscribed and
exscribed circles, areas of triangles etc., since such values can be
useful when making adjustments to a diagram.


The original motivation for {\mathsPIC} arose from the need for an easy-to-use filter program for {\PiCTeX},  a versatile and freely available drawing package which offers the convenience of
 graphics code within the \TeX\  document itself (e.g.,~printer-independence).
 In this way, \MathsPIC\ overcomes the main disadvantage of \PiCTeX, which is that
\PiCTeX\ requires you to specify the coordinates
of  all the points. Consequently, this can make {\PiCTeX} extremely
awkward  to use whan making complicated diagrams, particularly
if several coordinates  have to be
re-calculated manually each time the diagram is adjusted.
 
  For example, suppose it is necessary to draw
a triangle $ABC$ with $AB$ 5~cm, $AC$ 3~cm, and included
angle $BAC$ 40~degrees, together with its incircle.
One such  triangle is shown in Figure~\ref{fig:intro} and the
{\PiCTeX} commands for drawing it are as follows
(point~$A$ is at the origin~(0,0) and the units are in cm).

%\strut\smallskip\smallskip  %% add more space above figure

 

\pagebreak


%%------------Figure 1-----------------
%% triangle with incircle
\begin{figure}[htb]
   \centering
   %% small triangle with incircle
  \ifpdf
  \includegraphics[width=6cm]{mpicpm01-1.pdf}
  \else
  \includegraphics[width=7cm]{mpicpm01-1.eps}
  \fi
 \parbox{0.8\textwidth}{\caption{\label{fig:intro}}}%
\end{figure}
%-----------------------------------------


%-----------------------
\begin{verbatim}
\put {$\bullet$} at  0  0                   % point A
\put {$\bullet$} at  4.924039   0.8682409   % point B
\put {$\bullet$} at  1.928363   2.298133    % point C
\plot 0  0   4.924039  0.8682409    1.928363  2.298133   0  0 /
\circulararc 360 degrees from 3.0086 1.2452 center at 2.1568 1.2452
\put {$A$} at -0.5  0
\put {$B$} at  5.424039  .8682409
\put {$C$} at  1.428363  2.298133
\end{verbatim}




Although point $A$ can be placed at the origin for
convenience we have to resort to geometry
and a calculator to determine the coordinates of  points $B$ and $C$,
since in this example $AB$, $AC$, and the included angle are all defined (see above).
   It is then necessary to recall the coordinates of all the points
in order to write the \verb!\plot! command.
Finally, the \verb!\circulararc! command requires
even more geometry and calculation to figure out the radius of
the incircle, the coordinates of its center, and the
coordinates of the starting point of the arc-drawing routine.
  Furthermore, if the initial diagram is not a suitable shape
or size, the calculator has to be used again for any adjustments.
 In practice, therefore, {\PiCTeX} requires a certain
amount of planning and calculation for all but the
simplest of diagrams.


{\MathsPIC} overcomes all these difficulties by
providing an environment for manipulating named points and
variables, which  has the effect of making even very complicated
 mathematical diagrams  easy to create.
   For example, the equivalent  {\mathsPIC}
commands (which do not have a leading backslash) for drawing Figure~\ref{fig:intro} are as follows (the units are in cm as before).




\begin{verbatim}
point(A){0,0}                    % A is at origin
point(B){A,polar(5,10 deg)}      % B is 5 cm from A; AB slope 10 deg
point(C){A,polar(3,50 deg)}      % C is 3 cm from A; BAC = 40 deg
drawPoint(ABC)                   % put $\bullet$ at points A B C
drawline(ABCA)                   % draw the triangle
drawIncircle(ABC)                % draw the incircle
var d = 0.5                      % let d = 0.5 cm
text($A$){A, polar(-d,-140 deg)} % label for A
text($B$){B, shift(d,0)}         % label for B
text($C$){C, shift(-d,0)}        % label for C
\end{verbatim}


%%------------------------
\subsection*{Full \mathsPIC\ file}

The complete \mathsPIC\ file for drawing Figure~\ref{fig:intro} is shown below. 
The style-option  \verb!mathspic.sty! automatically loads \PiCTeX, and also implements the \LaTeX\ command  \verb!\thispagestyle{empty}! to  stop a page number appearing in the figure.

\begin{Verbatim}
% mpicpm01-1.m
\documentclass[a4paper]{article}
\usepackage{mathspic,color}
\begin{document}
%---------------
\beginpicture
\setdashes
\color{blue}%
paper{units(1cm) xrange(-0.5,5), yrange(-0.5,2.5) axes(XY)}
\setsolid
point(A){0,0}
point(B){A, polar(5, 10 deg)}
point(C){A, polar(3, 50 deg)}
\color{black}%
drawpoint(ABC)
drawLine(ABCA)
\color{red}%
drawIncircle(ABC)
\color{black}%
var d = 0.5
text($A$){A, polar(d,-140 deg)}
text($B$){B, shift(d,0)}
text($C$){C, shift(-d,0)}
\endpicture
\end{document}
\end{Verbatim}



All that remains is to generate the PS file using \verb!dvips!, crop the image to the bounding box (using the \verb!-E! option) and generate the   EPS and PDF versions (see Section~\ref{sec:epsandjpg}). For example, if the \mathsPIC\ file is, say, \verb!triangle.m!, then the commands would be as follows:


\begin{Verbatim}
mathspic triangle.m
latex  triangle.mt
dvips triangle.dvi   -o triangle.ps
dvips -E triangle.dvi   -o triangle.eps 
epstopdf triangle.eps
\end{Verbatim}



%%------------------------
\subsection*{Unique facilities}


{\MathsPIC} facilitates the drawing of
{\PiCTeX}  diagrams because not only does it allow points
to be defined in terms of other points (relative addressing),
but it also allows the use of scalar variables which can be
manipulated mathematically.
Consequently, diagrams can be constructed in an intuitive
way, much as one might with a compass and ruler; for example,
constructing a point at a certain position in order to allow
some other point to be constructed, perhaps to draw a line to.
In other words, {\mathsPIC}  offers the freedom to create
`hidden' points having a sort of scaffolding function.
    In particular, this facility allows diagrams to be
constructed in such a way that they remain functionally
connected even when points are moved (see Section~\ref{sec:functionaldiag}).



\MathsPIC\ offers a number of other  facilities, which allow the accurate drawing of  extremely complicated diagrams. Since \mathsPIC\ itself  is a Perl program, both  point coordinates and variables can be defined using all the usual  mathematical functions  and  syntax  we associate with Perl.
Files can be input recursively (using the \verb!inputfile! command); there is  a do--loop  facility; and macros can be defined. In fact two sorts of
 macros can be used in the \mathsPIC\ file, namely (a)~special {\mathsPIC} macros, and (b)~the familiar  TeX macros. Macros can also be stored in a library file (an ordinary ASCII text file) and input as and when necessary.
Furthermore, the standard \LaTeX\ packages can of course be used; e.g.,~the Color package and the Rotation package.

A powerful feature of \mathsPIC\ is its facility for accessing the Perl command-line. This allows users to write their own dedicated  Perl programs for writing configurable chunks of  \mathsPIC\ code on-the-fly to  files which can then be input when required; for example, to draw particular elements of a diagram or even complete diagrams (see Section~\ref{sec:perl}). The ability to use Perl programs in this way is, therefore,  equivalent to having a powerful subroutine facility.
It follows, therefore, that users can create their own library of useful Perl programs as well as libraries of \mathsPIC\ macros.



Finally, note that {\mathsPIC} can also be viewed as a handy tool
for exploring geometry since its  \verb!show! commands 
return the values of various parameters;
for example,  angles, the distance between points, and
areas of triangles.


\end{document}
