%% mpicp-script.tex
%% mathsPIC manual
%%  RWD Nickalls


\documentclass[mathsPICmanual.tex]{subfiles}
%% note that there is a set of \ttstrut macros in this chapter
%% they are used in the Beccari table towards the end

\begin{document}
%%=============================


%%--------------------------------
\chapter{The {\mathsPIC} script  file}

All commands for generating a diagram (the script) are written  to  a plain ASCII file, known as the \mathsPIC\ file, using a text editor in the usual way. This file is then processed by the \mathsPIC\ program (\texttt{mathspic.pl}) as described in the previous chapter. While the \mathsPIC\ file can of course have any filename and extension, in this manual all \mathsPIC\ files have the filename extension of \texttt{.m}
in order to distinguish them from the various derived files.

We distinguish three types of command, namely (a)~\mathsPIC\ commands, (b)~\PiCTeX\ commands, and (c)~\TeX\ or \LaTeX\ commands. All these commands are detailed in the subsequent three chapters. Since \mathsPIC\ currently only outputs a \TeX\ file then the \mathsPIC\ file can also contain  appropriate \PiCTeX, \TeX\ and \LaTeX\
commands\footnote{However, it is anticipated that future versions of \mathsPIC\ will be able output
PostScript and SVG files, in which case only \mathsPIC\ commands will be allowed.}.

\section{\mathsPIC\ style option}
Since  the style option not only inputs  some \PiCTeX\ files but also  redefines some of the  \PiCTeX\  commands,  it is therefore necessary to always use the \mathsPIC\   style option (\texttt{mathspic.sty}) by using the command
\begin{verbatim}
\usepackage{mathspic}
\end{verbatim}
 Note that in the file \texttt{mathspic.sty} the line \verb!\let\Linethickness\linethickness%!
is placed before inputting \texttt{pictexwd.tex}
since both \PiCTeX\ and the \LaTeX\ picture environment  use the same  command name, i.e.~\verb!\linethickness!.


%%------------------------------------
\section{Headers and footers}
\label{sec:headfoot}

It is particularly useful to include in the
{\mathsPIC} file any \TeX\ or \LaTeX\ headers and footers
which would otherwise have to be
added manually to the output-file before {\LaTeX}ing the file.
For example,  a typical format which allows for both \LaTeXe\ and pdf\LaTeX\ processing\footnote{The \bs\texttt{ifx}...\bs\texttt{else}...\bs\texttt{fi} sequence is from \texttt{science.sty} (available on CTAN).}, might be as follows
(this works nicely with \LaTeXe, \texttt{dvips}, \texttt{ps2pdf}, and pdf\LaTeX\ in Linux).
Note that it is important to load the \texttt{color} package (see Section~\ref{sec:color}) \textit{after} \texttt{mathspic}.

Note also that the \LaTeX\ command \verb!\thispagestyle{empty}! is included  for convenience in  \texttt{mathspic.sty} in order to stop a page number appearing in a figure (see Section~\ref{sec:sty} for details).

\begin{verbatim}
\documentclass[a4paper]{article}
\usepackage{mathspic,color}
\begin{document}
%---------------
\beginpicture
....
....
\endpicture
\end{document}
\end{verbatim}



For  users  of plain \TeX\ a typical format might be as
follows. Note the need in this case to include the  line redefining the \verb!\linethickness! command (in \verb!mathspic.sty!)

\begin{Verbatim}
\input latexpic.tex
\let\Linethickness\linethickness%  %% redefinition for mathsPIC
\input pictexwd.tex
\font\tiny=cmr5      %% used for drawing lines
\font\large=cmr12    %% used for drawing thicklines
%----------------
\beginpicture
....
....
\endpicture
\bye
\end{Verbatim}

If it is necessary (or just convenient) to extend a
{\TeX} or {\LaTeX} command across several lines, then each
additional line must be protected within the {\mathsPIC} file
using a leading \verb!\!\gap\ldots\ sequence
unless a line actually starts with a \TeX\ command.
A typical example is the following macro (used in Figure~7.6)
which defines a `display' maths formula.
The macro is split across several lines, as follows.
\begin{Verbatim}
\newcommand{\formula}{%
\     $\displaystyle \sum_{p\ge0} \Delta_{jp} z^{(p+1)}$%
\     }%
text(\formula){B1}
\end{Verbatim}

\textbf{Important}: Note that when using {\TeX} or {\LaTeX} commands \textit{within}
the {\PiCTeX} picture environment (\verb!\beginpicture! ... \verb!\endpicture!), it is very important
to include the  comment \verb!%! symbol at the end of such lines,
to prevent {\PiCTeX} accumulating additional \verb!<space>! characters from
the ends of non-{\PiCTeX} commands,
since otherwise {\PiCTeX} incorporates such space characters
into the horizontal distance used for representing
 $x$-coordinates, with the effect that all subsequent picture elements
may be displaced slightly to the right.


This effect  relates to how \TeX\ expands macros, as explained in the following texhax comment by Philip Ratcliffe (May 8, 2007).
\begin{quote}
{\small
\ldots\  a reasonable rule-of-thumb is to put a comment (\,\%\,) at the end of every line that would otherwise end with a right brace (\,\}\,). That is, write
\begin{verbatim}
\typeout{Hello World}%
\end{verbatim}
To be more explicit, a simple command with no parameters, such as 
\verb!\par!, \verb!\else!, \verb!\centering!, will always eat the following space while, say, {\newline}\verb!\typeout{Hello World}!, will not (i.e.,~the space will remain as a physical space in your output). An the end-of-line character is always interpreted as a space.
}
\end{quote}
For other  \TeX\ and \LaTeX\ commands useful in \mathsPIC\ see 
Chapter~\ref{chap:texcommands}.


%%----------------------------
\section{Commands}

The idea underlying the {\mathsPIC} file (input-file) is that it
should be able to contain
everything required to generate the proposed
figure (i.e.~all {\mathsPIC} commands, comments,
{\TeX} and {\LaTeX} commands including headers and footers,
{\PiCTeX} commands, as well as lines to be copied verbatim)
so that the output-file can be
immediately {\TeX}ed to generate the graphic.
Some general points relating to the {\mathsPIC} file are
as follows.
\begin{itemize}

\item
  {\mathsPIC} commands are \textit{not} prefixed by backslashes. They
   are therefore easily distinguished from
   \TeX, \LaTeX\  and {\PiCTeX} commands.

\item
Each {\mathsPIC} command must be on a separate line.
This is  because \hbox{\mathsPIC} frequently adds data to
the end of a line in the output-file (see below).

\item
As with \TeX, spaces can be used to enhance readability.
This is particularly useful when writing lists of points.
For example the command \texttt{drawpoint(PQR1R2)}
can be made easier to read by writing it as
{\newline}\texttt{drawpoint(P Q R1 R2)}.



\item
{\mathsPIC} commands  and point-names are \textit{not}
case sensitive. This  allows the user
to customise the commands to enhance readability. Thus the command
\texttt{drawpoint} can therefore be written as \texttt{drawPoint} or
\texttt{DrawPoint} etc.


\item
Delimiters have a hierarchical structure as follows:
{\newline}Curved brackets contain the primary
      argument; e.g.\ \verb!drawline(AB)!
\newline
   Braces contain required supporting arguments;
    e.g.\ \verb!point(A){5,6}!
\newline
   Square brackets contain optional arguments;
{\newline}e.g.\ \verb!point(D){midpoint(PQ)}[symbol=$\odot$]!


\item
Logically distinct groups within brackets must be separated
by commas.
{\newline}e.g.\ \verb!point(B2){A,polar(3,40deg)}[symbol=$\odot$, radius=2]!


\item
Comments are prefixed by the {\%} symbol in the usual way.
Lines having a leading {\%} symbol are copied verbatim through
to the output-file.

\item
Lines having a leading backslash command (i.e.\
where there is \textit{no} inter-word space immediately
following the backslash, e.g.\ \verb!\setdashes!
or
{\newline}\verb!\begin{document}!)
are copied verbatim through to the output-file.
Consequently, all {\TeX}, {\LaTeX} and {\PiCTeX} commands
can be used in the normal way providing
the command is restricted to a single line.
However, if such commands do run on to the subsequent
lines, these lines will need to be
prevented from being processed as {\mathsPIC} commands,
by prefixing them with
 \texttt{$\backslash$\gap} (see below)---unless of course
they also start with a backslash command.



\item
Lines having a leading \texttt{$\backslash$\gap}
(i.e.\ where the  \texttt{$\backslash$} is followed immediately by
one or more inter-word spaces {\gap} \hbox{e.g.\ \verb!\  25.3  16.8!)}
are copied verbatim through to the output-file \textit{without}
the leading backslash.



\item
Data-files containing {\mathsPIC} commands can be input using the
\verb!inputfile()! command.
Files can also be input \textit{verbatim} using the
\verb!inputfile*()! command (useful for inputting files containing
only {\PiCTeX} commands and/or coordinate data;
 for example, a list of data points as part
of a {\PiCTeX} \verb!\plot! command).

\item The \verb!system()! command gives access to the command-line.

\end{itemize}



%%=================================
\section{Macros}
\label{sec:macros}


\MathsPIC\ currently allows macros consisting of a single command, either with or without parameters. (see Section~\ref{sec:macros2}).
 \MathsPIC\ macros are subject to a number of rules as follows:-

\begin{itemize}
\item  Macros are created using the \verb!%def! command, and destroyed using the \verb!%undef! command.

\item  When a macro is used in a command then the macro-name \textit{must} have a \verb!&! prefix (to distinguish it as a macro).

\item Macro names are case-sensitive (unlike all other  \mathsPIC\ command-names which are \textit{not} case sensitive)

\item  Macros must evaluate to a `numerical expression' (see Section~\ref{sec:numexpr}) (i.e.~not to strings).
\end{itemize}
It is strongly recommended that a \verb!%! is placed at the end of the macro definition (as is done with \LaTeX\ commands) in order to prevent \PiCTeX\ from including additional horizontal whitespace.


%-----------------------------
\subsection*{No parameters}

Examples of macros which do not take any parameters are the following two commands which create the two macros \texttt{fancydashes}  and \texttt{plaindashes}.
\begin{verbatim}
%def fancydashes() dasharray(1pt,2pt,3pt,4pt)%
%def plaindashes() dasharray(1pt,1pt)%
\end{verbatim}
Note that in the macro-definition command the curved bracket (the parameter bracket) at the end of the word \texttt{fancydashes()} remains empty if there are no parameters. This pair of curved brackets marks the end of the command-name and the beginning of the macro definition (i.e.~some \mathsPIC\ commands).

To use the macro (as a command) it is necessary to use the \& prefix. The \texttt{()} brackets are only necessary if the macro takes parameter(s), as follows.

\begin{verbatim}
...
&fancydashes
drawline(AB)
&plaindashes
drawline(PQ)
...
\end{verbatim}
The macro \texttt{fancydashes()} is deleted using the  following command.

\begin{verbatim}
%undef fancydashes()
\end{verbatim}


%-----------------
\subsection*{Single parameter}
An example of a macro taking a single parameter is as follows:
\begin{verbatim}
%def thick(t) linethickness(t pt)%
\end{verbatim}
Here the command \verb!&thick(2)! is equivalent to the command \texttt{linethickness(2pt)}.

\subsection*{Multiple parameters}
An example of a  macro taking multiple parameters is as follows:
\begin{verbatim}
%def mypoint(P,x,y) point(P){x,y}%
\end{verbatim}
If we now write the command \verb!&mypoint(Q7,3,5)! this command will be processed to generate the point $Q7$ as shown in the following comment in the output file.
\begin{verbatim}
%% point(Q7){3,5} 	Q7 = (3, 5)
\end{verbatim}
It is anticipated that the macro facility will be upgraded in subsequent versions of \mathsPIC\ to allow a multi-line macros facility.


%---------------------------
\subsection{Macro library}
\label{sec:macrolibrary}

It may be useful to create a file for storing frequently used \mathsPIC\  macros, say, the text file \texttt{mathspic.lib} (see more on macros in  Section~\ref{sec:maths}).
For example, we could  put together some of the macros described  above into one file as follows:

\begin{verbatim}
%%--- mathspic.lib---
%def fancydashes() dasharray(1pt,2pt,3pt,4pt)%
%def plaindashes() dasharray(1pt,1pt)%
%%--- end of library ---
\end{verbatim}
and input the file  at the start (for processing by \mathsPIC) by placing the  command \texttt{inputfile(mathspic.lib)} in the \mathsPIC\ file
 just after \verb!\begin{document}!.



%%--------------------------------
\section{The plotting area}

\subsection{Axes}

When drawing a new figure it is often useful to have a graduated ruled frame
to guide placement of picture elements.
This task is greatly simplified by using {\mathsPIC}'s one-line
\verb!paper! command, which has
optional \verb!axes! and \verb!ticks! parameters\footnote{Since
{\PiCTeX} uses the name `axis', \textsf{mathsPIC} recognises
both spellings (`axis' and `axes').}.
The axes-codes used in the \texttt{axes()} option are
\texttt{L}~(Left), \texttt{R}~(Right), \texttt{T}~(Top),
\texttt{B}~(Bottom), \texttt{X}~(X-axis), \texttt{Y}~(Y-axis).
  For example, the following  \texttt{paper} command
generates a drawing area 5~cm $\times$ 5~cm with a ruled frame on
four sides as shown in Figure~\ref{fig:axes}a.
\begin{Verbatim}
paper{units(1mm),xrange(0,50),yrange(0,50),axes(LRTB),ticks(10,10)}
\end{Verbatim}
This particular \verb!paper! command\footnote{Note that the order of the \texttt{units(), xrange(), yrange(), ...} etc in the \texttt{paper()} command  is critical, and changing this order will generate an error message. This command will be made more flexible in future versions.} is
converted by {\mathsPIC}  into the following {\PiCTeX} code
in the output-file (\verb!.mt! file).
\begin{Verbatim}
\setcoordinatesystem units <1mm,1mm>
\setplotarea x from  0 to  50 , y from  0 to  50
\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  50 by 10 /
\axis bottom ticks numbered from  0 to  50 by 10 /
\end{Verbatim}
For graphs it is more usual for the axes to be centered on the
origin $(0,0)$, and this is provided for by the
\texttt{XY} options. For example, Figure~\ref{fig:axes}b was generated
using the following \verb!paper! command,
\begin{verbatim}
paper{units(1cm),xrange(-2,3),yrange(-2,3),axes(XY),ticks(1,1)}
\end{verbatim}
which is converted by {\mathsPIC} into the following {\PiCTeX}
code in the output-file.
\begin{verbatim}
\setcoordinatesystem units <1cm, 1cm>
\setplotarea x from -2 to  3, y from -2 to  3
\axis left shiftedto x=0 ticks numbered from -2 to -1 by  1
      from  1 to  3 by  1  /
\axis bottom shiftedto y=0 ticks numbered from -2 to -1 by  1
      from  1 to  3 by  1  /
\end{verbatim}
The tick-marks associated with an axis can be prevented by using a *
after the axes-code (e.g.\ \verb!axis(LBT*R*)! gives four axes but
generates tick-marks only on the Left and Bottom axes).
Note that any combination of axes-codes can be used. For example,
the options ...\texttt{axes(LRTBX*Y*), ticks(10,10)} will generate
a rectangular axes frame (with ticks) containing the
$XY$ axes (without ticks).
The line-thickness of axes and tick-marks  is controlled by
the {\PiCTeX} \verb!\linethickness! command.


Once the figure is finished, then the frame or axes can be
easily adjusted or even removed. The figure can also
be scaled in size simply by altering the \texttt{units}
parameters. For example, the option \verb!units(3cm,1cm)! will
generate an $X$-axis having three times the scale as the $Y$-axis
(see Figure~\ref{fig:example11}).
If complicated or more demanding axis configurations are
required, then the {\PiCTeX} Manual (see Section~\ref{sec:pictexmanual})
will need to be consulted.
See also Chapter~\ref{chap:posfig} for details on positioning figures within
\LaTeX\ documents.



%%------------Figure 2-----------------
%% the plotting area
\begin{figure}[hbt]
\centering
\begin{minipage}{6cm}
    %\vspace{2cm}  %% controls space above picture
  \ifpdf
  \includegraphics[width=6cm]{mpicpm03-1a.pdf}
  \else
  \includegraphics[width=6cm]{mpicpm03-1a.eps}
  \fi
  \vspace{5mm}  %% controls space between pict and caption
    \begin{center}
       a.   Using \texttt{...axes(LRTB)}
    \end{center}
\end{minipage}
%-----------------------
%%\hspace{1cm} %% controls space between figs
%% use this when making A5 booklet to put vertically
%% and use with \clearpage to flush the floats

\bigskip\bigskip\bigskip  %% use this to place vertically
%%                        %% remember to leave an empty line
%%                        %% above \bigskip etc
%%----------------------
%\framebox{
\begin{minipage}{5cm}
  \vspace{3mm}  %% controls space between pict and caption
  \ifpdf
  \includegraphics[width=5cm]{mpicpm03-1b.pdf}
  \else
  \includegraphics[width=5cm]{mpicpm03-1b.eps}
  \fi
  \vspace{10mm}  %% controls space between pict and caption
  \begin{center}
     b.   Using \texttt{...axes(XY)}
  \end{center}
\end{minipage}
%} % end of framebox
\caption{\ }
\label{fig:axes}
\end{figure}
%-----------------------
%%***********************************************
\clearpage %to flush this float onto one page
%% needs to be part of a paragraph to work
%%***********************************************




%-------------------
\subsection*{Example}

Sometimes it is useful to use axes with a different scale in order to accommodate, say,  an equation, as shown in the following example, where we have to specify the   two Y-values and their positions on the axis.

\begin{verbatim}
\documentclass[a4paper]{article}
\usepackage{mathspic}
\begin{document}
%%--------------
\beginpicture
\setsolid
%% compress Y scale to fit equation onto paper
var u=1, v=0.075 
paper{units(u cm, v cm), xrange(-4,5), yrange(-50,10),  axes(XY), ticks(1,0)}
%% place values at ends of the Y-axis
\axis left shiftedto x=0 
    \   ticks withvalues $-50$  $10$   /
    \                  at -50   10     /  /
\endpicture
\end{document}
\end{verbatim}


%%------------Figure -----------------
%% rectangular text box
\begin{figure}[hbt]
\centering
   %% X and Y axes
    \ifpdf
  \includegraphics[width=6cm]{mpicpm03-1c.pdf}
  \else
  \includegraphics[width=6cm]{mpicpm03-1c.eps}
  \fi
 %  \caption{\ }
%   \label{fig:XYaxes}
\end{figure}
%----------------------



%----------------------------
\subsection{Second y-axis}
Sometimes a second (different) $y$-axis is needed (on the right). An example of how this can be achieved is as follows.
\begin{verbatim}
paper{units(1cm),xrange(0,6),yrange(72,77),axes(LBT*),ticks(1,1)}
\axis right
\    label {\lines {weight\cr  (lbs)\cr {\ }\cr {\ } }}
\    ticks withvalues  0   1   2   3   4   5  /
\                  at  72  73  74  75  76  77 /  /
\end{verbatim}



\pagebreak

\subsection{Units}

In addition to the usual units \verb!mm!, \verb!cm!, and
\verb!pt!, {\PiCTeX} accommodates all  the other units used by
{\TeX} (see Knuth (1990), Chapter~10),
and also uses the same two-letter codes,
 namely \verb!pc! (pica), \verb!in! (inch), \verb!bp! (big
point), \verb!dd! (didot), \verb!cc! (cicero), \verb!sp! (scaled
point). The available units thus embrace the Metric system (mm,
cm), the Didot system (didot, cicero), and the UK system
(point, big point, pica, inch)---see Table~\ref{tab:convert}.


%%----------------------------------------
\begin{table}[tb]
\centering
\begin{minipage}{0.8\textwidth}
\caption[]{\label{tab:convert}Conversion factors for the units used by \LaTeX.
{\newline}From: Beccari 1991 (with permission).}
\label{tab:uconv}
\end{minipage}%% requires an empty line for PS

\vspace{\baselineskip}
\makebox[\textwidth]{\let\t\tt\def\s{\rule{0pt}{2.5ex}}\footnotesize
\begin{tabular}{|l*{9}{|r}|}
\hline \s   &\multicolumn{1}{|c}{\t mm}
                         &\multicolumn{1}{|c}{\t cm}
                                     &\multicolumn{1}{|c}{\t pt}
                                                 &\multicolumn{1}{|c}{\t bp}
                                                             &\multicolumn{1}{|c}{\t
pc}
                                                                         &\multicolumn{1}{|c}{\t
in}
                                                                                     &\multicolumn{1}{|c}{\t
dd}
                                                                                                 &\multicolumn{1}{|c}{\t
cc}
                                                                                                             &\multicolumn{1}{|c|}{\t
sp}\\[0.5ex]
\hline
\s{1\,mm}   &1,000      &0,100      &2,845      &2,835      &0,2371
&0,03937    &2,659      &0,2216     &186\,467,98\phantom{0}\\
{1\,cm}     &10,00      &1,000      &28,45      &28,35      &2,371
&0,3937     &26,59      &2,216      &1\,864\,679,8\phantom{00}\\
{1\,pt}     &0,3515     &0,03515    &1,000      &0,9963     &0,08333
&0,01384    &0,9346     &0,07788    &65\,536\phantom{,000}\\
{1\,bp}     &0,3528     &0,03528    &1,004      &1,000      &0,08365
&0,01389    &0,9381     &0,07817    &65\,781,76\phantom{0}\\
{1\,pc}     &4,218      &0,4218     &12,00      &11,96      &1,000
&0,1660     &11,21      &0,9346     &786\,432\phantom{,000}\\
{1\,in}     &25,40      &2,540      &72,27      &72,00      &6,023
&1,000      &67,54      &5,628      &4\,736\,286,7\phantom{00}\\
{1\,dd}     &0,3760     &0,03760    &1,070      &1,066      &0,08917
&0,01481    &1,000      &0,08333    &70\,124,086\\
{1\,cc}     &4,513      &0,4513     &12,84      &12,79      &1,070
&0,1777     &12,00      &1,000      &841\,489,04\phantom{0}\\[0.5ex]
\hline
\end{tabular}}
\end{table}
%%----------------------------------------------------------

Note that if only \textit{one} unit is indicated in the
\verb!units! option, then {\mathsPIC} uses the \textit{same} unit
for both the  $x$ and $y$ axes.
Thus  the option \verb!units(1mm)! in the
\texttt{paper} command is translated by {\mathsPIC} into
the following {\PiCTeX} command in the output-file.
Note that it is very important to include a numeric value with the units, or alternatively a variable with the units.
\begin{verbatim}
\setcoordinatesystem units <1mm,1mm>
\end{verbatim}
If different scales are required (most commonly when drawing
curves and equations)
then both need to be specified
in the {\mathsPIC} \verb!units! option. For example, if
units of 1 cm and 2 mm are required for the $x$ and $y$ axes
respectively, then this will be implemented by the {mathsPIC}
command \verb!units(1cm,2mm)!.
However, when the $x$ and $y$ scales \textit{are} different
strange effects can occasionally occur, particularly if
drawing ellipses or circular arcs.
In view of this {\mathsPIC} writes a warning note to the output-file
and log-file when different units are being used.
The drawing of complete circles will only be affected if the $x$-units
is changed, since the {\mathsPIC} starts the arc at a location
having the same $y$-coordinate as that of the center.
In general users are therefore recommended to avoid using
different $x$ and $y$ units in the \verb!paper! command
if at all possible.


Note that variables can also be used to control the $x$ and $y$
units, as shown in the following example, where the radius
(\verb!r!)
and the distance (\verb!s!) between the label $A$ and its
point-location
are fixed irrespective of scaling (i.e.\ with
changes in the value of \verb!u!) by dividing the relevant variables
by the scaling value \verb!u!.
\begin{verbatim}
var u = 1.5   %% units
paper{units(u mm), xrange(0,100), yrange(0,100)}
...
var r = 2/u, s = 4/u
point(A){30,20}[symbol=circle(r)]
text($A$){A, shift(-s,s)}
\end{verbatim}



%------------------
\subsection{Tick-marks}

It is recommended that integers are used with the \verb!ticks()!
option; the numeric  format for the \verb!ticks()! arguments must agree with that used by the \verb!xrange()! and \verb!yrange()! arguments. For example,  if the \texttt{paper()} command uses \verb!xrange(-5.5,5.5)! then the \verb!ticks()! option should also use decimals, perhaps \verb!ticks(1.0, 1.0)!. If this rule is not adhered to then  {\PiCTeX} may sometimes give unpredictable results when executing the \verb!paper{}! command.
In general {\PiCTeX} gives more pleasing axes if integers are
used throughout the \verb!paper! command.



 %------------------
\section{Points}

 Each point is associated with a point-name which is defined
 using the \verb!point! command. For example, the following command
 allocates the point-name $A$ to the coordinates (5,7).
\begin{verbatim}
point(A){5,7}
\end{verbatim}
 Once defined, points can be referred to by name.
 Consequently, points can be defined in relation to other points
 or lines simply by using point-names, as shown by the
 following commands.
\begin{verbatim}
point(C){midpoint(AB)}
point(E){intersection(AB,CD)}
point(J){Q, rotate(P, 25 deg)}  %% J = Q rotated about P by 25 deg
\end{verbatim}

Points are interpreted according to their grouping and context.
Thus two points represent either a line or its Pythagorean length.
 For example, the command \verb!drawCircle(P,AB)! means
 draw a circle,  center $P$ with radius equal to the length of the line $AB$.
A group of three points represents either a triangle, an angle,
or two contiguous line-segments, depending on the circumstances.




%-----
\subsection{Point-name}


A point-name \textit{must} begin
with a \textit{single} letter,
and may have up to a \textit{maximum} of three following
digits. The following are valid point-names: {$A, B, C3, d185$}.
Since {\mathsPIC} is not case sensitive the points {$d45$}
and {$D45$} are regarded as being the same point.

Sometimes it is necessary to re-allocate new coordinates
to an existing point-name, in which case the \verb!point*!
command is used. This is often used during   recursive operations
whereby the {\mathsPIC} file inputs another  file (using
the \verb!inputfile! command) containing commands which
alter the value of pre-existing points. For example,
the following command increments the $x$-coordinate of
point~$A$ by 5~units.
\begin{verbatim}
point*(A){xcoord(A)+5, ycoord(A)}
point(P){Q}    %% make P the same as Q
\end{verbatim}

%%---------------
\subsection{Point-symbol}

The default point-symbol is  $\bullet$ (\verb!$\bullet$!).
However, {\mathsPIC} allows the optional use of any \TeX\
character or string of characters to represent a particular point,
by defining it in a following square bracket.
For example, the  point~$A$(5,10) can be
represented by the $\triangle$ symbol by defining it as follows.
\begin{verbatim}
point(A){5,10}[symbol=$\triangle$]
\end{verbatim}
Other examples using the \texttt{circle()} and \texttt{square()} options are:
\begin{verbatim}
point(B){A, shift(2,6)}[symbol=circle(2)]
point(C){A, polar(3,26}[symbol=square(3)]
\end{verbatim}
The argument for the circle is the radius, while the argument for the square is the side length.

  The default point-symbol can also be changed to a circle, square, or  any \TeX\ character
or string of characters by using the
{\mathsPIC} \verb!PointSymbol! command. Note that
the \verb!PointSymbol! command only influences
subsequent \verb!point! commands.
For example, the
character $\odot$ (\verb!$\odot$!) can be made the new global
point-symbol by using the command \verb!PointSymbol($\odot$)!.
The original default point-symbol ($\bullet$) can be
re-instituted (reset) using the command \verb!PointSymbol(default)!.
    The point-symbol is drawn at the point-location
using the \texttt{drawPoint} command; for example,
\texttt{drawPoint(A)}, or \texttt{drawPoint(ABCD)}.


Since most \TeX\ characters and symbols are typeset
asymmetrically in relation to the baseline,
they will not, in general,  be positioned symmetrically over a point-location.
Most characters are therefore not ideal for use as point-symbols,
as they generally require some slight vertical adjustment in order to
position them symmetrically.
In view of this Table~\ref{tab:pointtable} lists
those \TeX\ characters
which \textit{are} particularly suitable, since they are  automatically
positioned by \TeX\ symmetrically with respect to a point-location
(for example the $\odot$ character \verb!$\odot$!), and  are
therefore ideal for use in this setting.



%%---------------------------
\subsection{Line-free zone}

When lines are drawn to a point, the line will (unless
otherwise instructed) extend to the point-location. However,
this can be prevented by  allocating an optional
circular line-free zone to a point by specifying the line-free radius
in a following square bracket.
 For example, lines to a $\triangle$ symbol at point~$A$
can be prevented from being drawn through the triangle to its center
by allocating a 5 unit line-free zone to the point, as follows.
\begin{verbatim}
point(A){3,10}[symbol=$\triangle$,radius=5]
\end{verbatim}
If only the line-free radius  is to be specified for the default point-symbol  then we can  use the command \verb!pointsymbol(default,5)!.
To change the line-free radius of an \textit{existing} point then use the following command.
\begin{verbatim}
point*(A){A}[radius=10]
\end{verbatim}
which is equivalent to
\begin{verbatim}
point*(A){xcoord(A), ycoord(A)}[radius=10]
\end{verbatim}



Table~\ref{tab:pointsymbols} gives a list of useful point-symbols which \TeX\ places symmetrically over a point-location
(note that \verb!$\Box$! and \verb!$\Diamond$! are not placed
symmetrically over a point location, but \verb!$\square$!
and \verb!$\lozenge$! are).
Other useful symbols are available from the
\verb!textcomp! fonts\footnote{See Harold Harders' useful
file (\texttt{textcomp.tex}) which shows the characters
of the \texttt{textcomp} font together with their names.
It can be found at \texttt{CTAN: /tex-archive/info/texcomp-info/}.} (see also the `symbol list' compiled by Pakin which shows virtually all the available symbols\footnote{\texttt{CTAN: /tex-archive/info/symbols/}}).

   For example, the following commands will draw lines between
points ABC, such that the lines just touch the edge of the
$\odot$ point-symbol (line-free radius 1.2 mm; 10pt font).
\begin{verbatim}
pointSymbol($\odot$, 1.2)
point(A){1,1}
point(B){2,2}
point(C){1,3}
drawline(ABC)
\end{verbatim}


%----table~1  of line free zones-----------------------------------
\newcommand{\ttstrut}{\rule{0pt}{14pt}}   % for top line
\newcommand{\mmstrut}{\rule[-2pt]{0pt}{14pt}}  % middle lines
\newcommand{\bbstrut}{\rule[-6pt]{0pt}{17pt}}  % bottom lines

% small table for line-free radius
\begin{table}[hbt]
\begin{center}
\caption{\label{tab:pointsymbols}Useful point-symbols and their radii for 10--12pt fonts.}
{\vspace{0.5\baselineskip}}
\label{tab:pointtable}    %% line between caption and table
\begin{tabular}{|l|c|c|c|}
\hline
\multicolumn{2}{|c|}{\raisebox{-3mm}{symbol}} &
      \multicolumn{1}{|c|}{\ttstrut\ radius mm} &
      \multicolumn{1}{|c|}{\raisebox{-3mm}{symbol package}} \\
\cline{3-3}
\multicolumn{2}{|c|}{{\mmstrut}\ } &
      \multicolumn{1}{|c|}{10pt / 11pt / 12pt} &
      \multicolumn{1}{|c|}{\ } \\
\cline{1-2}\cline{3-4}
\verb!$\circ$! &  $\circ$ & 0.70 / 0.75 / 0.80  & standard     {\ttstrut} \\
\verb!$\odot$! &  $\odot$ & 1.20 / 1.35 / 1.50  & standard     {\mmstrut} \\
\verb!$\oplus$! &  $\oplus$ & 1.20 / 1.35 / 1.50  & standard   {\mmstrut} \\
\verb!$\ominus$! &  $\ominus$ & 1.20 / 1.35 / 1.50 & standard  {\mmstrut} \\
\verb!$\oslash$! &  $\oslash$ & 1.20 / 1.35 / 1.50 & standard  {\mmstrut}\\
\verb!$\otimes$! &  $\otimes$ & 1.20 / 1.35 / 1.50 & standard  {\mmstrut} \\
\verb!$\bigcirc$! &  $\bigcirc$ & 1.70 / 1.85 / 2.05 & standard {\mmstrut} \\
\verb!$\bigodot$! &  $\bigodot$ & 1.70 / 1.85 / 2.05 & standard {\mmstrut} \\
\verb!$\bigoplus$! &  $\bigoplus$ & 1.70 / 1.85 / 2.05 & standard {\mmstrut} \\
\verb!$\bigotimes$! &  $\bigotimes$ & 1.70 / 1.85 / 2.05 & standard {\mmstrut} \\
\verb!$\star$! &  $\star$ & --- & standard {\mmstrut} \\
\verb!$\triangle$! &  $\triangle$ & --- & standard {\mmstrut} \\
\verb!$\square$! &  $\square$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\blacksquare$! &  $\blacksquare$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\lozenge$! &  $\lozenge$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\blacklozenge$! &  $\blacklozenge$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\bigstar$! &  $\bigstar$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\boxdot$! &  $\boxdot$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\boxtimes$! &  $\boxtimes$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\boxminus$! &  $\boxminus$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\boxplus$! &  $\boxplus$ & --- & amssymb.sty {\mmstrut} \\
\verb!$\divideontimes$! &  $\divideontimes$ & --- & amssymb.sty {\bbstrut} \\
\hline
\end{tabular}
\end{center}
\end{table}
%%----------------------------------------------------------
%%***********************************************
\clearpage %to flush this float onto one page
%% this command needs to be part of a paragraph to work
%%***********************************************



 It is often useful to adjust the line-free radius
associated with a particular point  before drawing
lines or arrows to it, in order to optimise the distance
between an object centered at the point and the line or arrow.
For example, one can use the  \verb!point*! command
to set a line-free radius of 2 units for a pre-existing
point ($P$), as follows.
\begin{verbatim}
point*(P){P}[radius=2]
\end{verbatim}

By way of illustration, this command is used in
drawing  Figure~\ref{fig:textbox}
where arrows are being drawn  from various
directions ($B$, $S$) to a text box centered on  point $P$
$\odot$ (the code is shown below as \texttt{mpicpm03-2.m}).
By setting the line-free radius (dashed circles)
associated with point $P$ before drawing each particular arrow,
one can easily adjust and optimise the distance between the
arrowhead and the text box.
The arrowshape used here is the default shape which is defined as follows (see Section~\ref{sec:arrows} for details).
\begin{Verbatim}
arrowshape(2mm,30,40)
\end{Verbatim}

%%------------Figure 2-----------------
%% rectangular text box
\begin{figure}[hbt]
\centering
   %% rectangular text box
    \ifpdf
  \includegraphics[width=6cm]{mpicpm03-2.pdf}
  \else
  \includegraphics[width=6cm]{mpicpm03-2.eps}
  \fi
   \caption{\ }
   \label{fig:textbox}
\end{figure}
%----------------------

\begin{Verbatim}
%% mpicpm03-2.m (Figure 3.2)
\usepackage{mathspic}
%---------------------------
\beginpicture
paper{units(1cm),xrange(0,6),yrange(0,3),axes(LBT*R*),ticks(1,1)}
point(P){4,2}[symbol=$\odot$]
point(B){2,0.5}
point(S){1,2}
drawPoint(PBS)
\setdashes
\inboundscheckon        %% restrict circles to drawing area
drawcircle(P,1)
drawcircle(P,2)
\setsolid
%% change line-free radius of P to 1cm
point*(P){P}[radius=1]
drawArrow(BP)           %% draw arrow from B (below)
%% change line-free radius of P to 2cm
point*(P){P}[radius=2]
drawArrow(SP)           %% draw arrow from S (side)
text($S$){S, shift(-0.4,0)}
text($B$){B, shift(-0.4,0)}
text(\textsc{p}){P, shift(0.3,0)}
\newcommand{\textbox}{\fbox{text\hspace{17mm}box}}%
text(\textbox){P}
\endpicture
\end{Verbatim}
Of course, sometimes it is  convenient just to draw
the arrows a certain length from one point towards another point.
For example, in order to draw an arrow  1 unit long from point~A  towards point~B we could use the following two commands
\begin{Verbatim}
point(Z){pointonline(AB,1)} % Z is point 1 unit from A towards B
drawArrow(AZ)
\end{Verbatim}


%%----
\subsection{Order of points}

The order of points in {\mathsPIC} commands is sometimes significant.
For example, the command \verb!point(D){PointOnLine(AB,23)}!
defines the point $D$ as being  23~units
\textit{from $A$ in the direction of $B$}.


%-----------------
\section{Lines}
\label{sec:lines}

{\mathsPIC} draws lines  using
its \texttt{drawLine} and \verb!drawThickline! commands.
For example, a line from ${P_1}$ to ${P_2}$ is drawn with the
command \texttt{drawLine(P1P2)}.
   If a line is to be drawn through several points
(say, $J_1, J_2, J_3, J_4, J_5$)
and can be drawn without `lifting the pen', then this can
be achieved using the single {\mathsPIC}
command \texttt{drawLine(J1J2J3J4J5)}.
   Several unconnected lines can also be drawn using one command
by separating each line sequence with a comma; for example,
\texttt{drawLine(J1J2,J3J4J5,J1J3)}.

A line can also be drawn a specified distance from one point
towards (or away from) another point, using the following two-step approach.
For example, the following commands draws a line a distance $d$
units from point~$A$ \textit{towards} point~$B$.
\begin{verbatim}
point(Z){pointonline(AB,d)}
drawline(AZ)
\end{verbatim}
Note that the order of the points $AB$ and the sign of the
distance \verb!d!  are important. For example, the following
commands will draw a  line a distance $d$
units from point $B$ \textit{away from}  point $A$.
\begin{verbatim}
point(Z){pointonline(BA,-d)}
drawline(BZ)
\end{verbatim}
Since the  {\PiCTeX} \verb!\putrule! command for drawing horizontal or
vertical lines is much more memory efficient than the
\verb!\plot! command, {\mathsPIC} automatically invokes the
\verb!\putrule! command  for horizontal and vertical lines.

%-------------
\subsection{Line thickness}
\label{sec:linethickness}

\subsubsection{\mathsPIC}
\mathsPIC\ uses the \texttt{linethickness()} command. For example, to switch to a linethickness of \texttt{2pt} we would use the \mathsPIC\ command
\begin{verbatim}
linethickness(2pt)
\end{verbatim}
The default value is $0.4$pt, and resetting to this value is achieved by the following command
\begin{verbatim}
linethickness(default)
\end{verbatim}
Sometimes when drawing thick lines it is useful to be able to manipulate the line ends (e.g.~when drawing shapes with horizontal and vertical lines). Consequently it is useful to be able to access the numeric value of the current linethickness (in the units defined by the \verb!paper! command), and this  can be done  using the var command as follows.
\begin{verbatim}
var t = _linethickness_
\end{verbatim}


The {\mathsPIC} \verb!drawLine()! command uses the current dot
size.  However, the {\mathsPIC}
\verb!drawThickline()! command uses the \verb!\large! dot size,
but then resets the dot size to the default \verb!\tiny!.
For example, the commands
\begin{verbatim}
point(A){5,5}
point(B){10,10}
drawThickline(AB)
\end{verbatim}
will result in the following code in the output-file.
\begin{verbatim}
%% point(A){5,5}     (5,5)
%% point(B){10,10}   (10, 10)
%% drawThickline(AB)
\setplotsymbol  ({\usefont{OT1}{cmr}{m}{n}\large .})%
{\setbox1=\hbox{\usefont{OT1}{cmr}{m}{n}\large .}%
 \global\linethickness=0.31\wd1}%
\plot 5.00000 5.00000	10.00000 10.00000 / %% PQ
\setlength{\linethickness}{0.4pt}%
\setplotsymbol  ({\usefont{OT1}{cmr}{m}{n}\tiny .})%
\end{verbatim}




%-----------------------
\subsubsection{\PiCTeX\protect\footnote{See also Chapter~\ref{ch:pictex} on {\PiCTeX}.}}

{\PiCTeX} draws lines using two different methods depending
on whether the lines are (a) horizontal or vertical, (b) any
other orientation. Furthermore these two groups use different
commands for controlling line-thickness, as follows.


\textbf{Horizontal and vertical lines (rules)}: \
Horizontal and vertical lines are drawn using the {\PiCTeX}
\verb!\putrule!
command\footnote{Note that the {\PiCTeX} \texttt{$\backslash$putrule}
    command employs the {\TeX} and {\LaTeX} \texttt{$\backslash$rule}
    command, and so is only used for horizontal and vertical lines.}
and consequently the thickness of such lines is controlled
by the {\PiCTeX}
{\newline}\verb!\linethickness!
command (the default line-thickness is $0.4$pt).
 For example, the following {\PiCTeX} command changes the
 thickness to 1pt.
\begin{verbatim}
\linethickness=1pt
\end{verbatim}
Note also that the {\PiCTeX} \verb!\linethickness! command can also
be reset to its default value ($0.4$pt) by the {\PiCTeX}
\verb!\normalgraphs! command (see chapter on \PiCTeX\ commands), which  resets all {\PiCTeX} graph-drawing parameters to their  default values, including \verb!\linethickness!.

Since the graph axes are drawn using horizontal and vertical lines
\PiCTeX\ draws them using the \verb!\putrule! command, i.e.~using the
\verb!\linethickness! command.
For example, the following commands can be  used to draw
thick axes.
\begin{verbatim}
\linethickness=2pt
paper{units(1mm),xrange(0,50),yrange(0,50),axes(XY)}
\linethickness=0.4pt    %% reset to default
\end{verbatim}

\textbf{Other lines and curves}: \
\PiCTeX\ draws all  other lines (non-horizontal non-vertical) and curves are drawn using the {\PiCTeX} \verb!\plot! command
 which draws a
continuous line of dots. Consequently
the thickness of these lines is controlled by
the size of the dot, which  is defined using the
{\PiCTeX} \verb!\setplotsymbol! command,
the default size of dot being \verb!{\tiny .}!.
Larger dots therefore generate thicker lines.
 For example, the following {\PiCTeX} command sets the dot to a
 larger size.
\begin{verbatim}
\setplotsymbol({\Large .})
\end{verbatim}


%%------------------------
\subsection{Recommendations}
In general it is recommended that the \mathsPIC\  \texttt{linethickness()}
command
is used as this automatically sets both  the \PiCTeX\ \verb!\putrule! and \verb!\setplotsymbol()! commands\footnote{See Section~\ref{sec:lines}}.
However, under certain circumstances it may be  convenient to set the \PiCTeX\ commands directly, as described below.

If you do use \PiCTeX\ commands for drawing lines you need to remember that since {\PiCTeX} uses two groups of commands for controlling
the thickness of lines (i.e.\ \verb!\linethickness! and
\verb!\setplotsymbol!)
it is important to use pairs of equivalent commands for
`rules' (horizontal and vertical lines) and dots (all other
lines) when changing line-thickness.
These are shown in Table~\ref{tab:linethickness}
for a 10-point font (note that the default sizes are $0.4$-point and
\verb!\tiny!).


%----table~2  line thickness commands-----------------------------------
%\newcommand{\tstrut}{\rule{0pt}{12pt}}  % for top line
%\newcommand{\mstrut}{\rule{0pt}{12pt}}  % middle lines
%\newcommand{\bstrut}{\rule{0pt}{12pt}}  % bottom lines

% small table for line-free radius
\begin{table}[hbt]
\begin{center}
\caption{Equivalent {\PiCTeX} commands for a 10-point font}
\label{tab:linethickness}
{\vspace{0.5\baselineskip}}   %% line between caption and table
\begin{tabular}{|l|l|}
\hline
\multicolumn{1}{|c|}{{\tstrut}rules (horizontal/vertical)}
	       & \multicolumn{1}{|c|}{all other lines}\\
\hline
\verb!\linethickness=1.35pt! & \verb!\setplotsymbol({\Large .})! {\mstrut} \\
\verb!\linethickness=1.1pt! & \verb!\setplotsymbol({\large .})! {\mstrut} \\
\verb!\linethickness=0.9pt! & \verb!\setplotsymbol({\normalsize .})! {\mstrut} \\
\verb!\linethickness=0.4pt! & \verb!\setplotsymbol({\tiny .})! {\mstrut} \\
\hline
\end{tabular}
\end{center}
\end{table}
%%----------------------------------------------------------

If macros are required, then this can be done easily with a \TeX\ macro using the \PiCTeX\ commands directly.
For example, the following code draws a medium-thick
line $AB$ by invoking the command \verb!\mediumthickline!.
\begin{Verbatim}
\newcommand{\mediumthickline}{%
	    \linethickness=1.1pt%
	    \setplotsymbol({\large .})}%
...
\mediumthickline%
drawline(AB)
\end{Verbatim}


%---------------
\section{Text}

Text is typeset using the \texttt{text} command and, by default, is
centered both horizontally and vertically at a defined point.
    For example,  the words  `point Z'  would be placed at the
point $Z$ using the command \verb!text(point $Z$){Z}!.

Text can be located relative to a point-location using the
\texttt{shift($dx$,$dy$)} or \texttt{polar($r$,$\theta$)}
commands. For example, points ${P_1}{P_2}{P_3}$ could have
their labels located 4 units from each point as follows.
\begin{verbatim}
var d = 4
text($P_1$){P1,shift(-d,0)}
text($P_2$){P2,polar(d,10 deg)}
text($P_3$){P3,polar(d,0.29088 rad)}
\end{verbatim}
    Optionally, text can be positioned relative to a
given point using appropriate combinations of the
\textit{case sensitive} {\PiCTeX}  options \verb! l t r B b! to
align the \textbf{l}eft edge, \textbf{r}ight edge, \textbf{t}op edge,
\textbf{B}aseline, \textbf{b}ottom edge
 of the text respectively, as
described in the {\PiCTeX} manual.
    For example in the diagram below (Figure~\ref{fig:nicebox})
    the text box \framebox{\texttt{a nice box}}
    is aligned such that the right edge of the text box
    is centered vertically at the point $P$ using the
    \verb![r]! option as follows.
\begin{verbatim}
point(P){25,5}
text(\fbox{a nice box}){P}[r]
\end{verbatim}

%%------------Figure 3-----------------
%% rectangular box
\begin{figure}[hbt]
\centering
   %% a nice box
    \ifpdf
  \includegraphics[width=6cm]{mpicpm03-3.pdf}
  \else
  \includegraphics[width=6cm]{mpicpm03-3.eps}
  \fi
   \caption{\ }
   \label{fig:nicebox}
\end{figure}
%----------------------

%%------------------------------
The \mathsPIC\ code for Figure~\ref{fig:nicebox} is as follows.

\begin{Verbatim}
%% mpicpm03-3.m (Figure 3.3)
\usepackage{mathspic}
\framebox{\vbox{
%---------------------------
\beginpicture
paper{units(1mm),xrange(0,28),yrange(0,10)}
point(P){25,5}[symbol=$\bullet$,radius=2]
text(\fbox{a nice box}){P}[r]
drawpoint(P)
point(J){P,polar(15,-20deg)}[radius=2]
text(this is point P){J}[l]
drawarrow(JP)
\endpicture
%---------------------------
\  }}  %% end of framebox
\end{Verbatim}
Text can also be placed at a point-location (using a
\verb!DrawPoint! command), if the
text is defined as the optional point-symbol (in square brackets)
associated with a \verb!point! command. Although this is useful
in certain circumstances, this method is somewhat less flexible
than the \verb!text! command, since the \verb!drawPoint! command
centers the point-symbol vertically and horizontally over the
point-location.



%%----
\section{Variables and constants}

\subsection{Scalar variables}

Numeric scalar variables are defined using the
\verb!var! \textit{name} \verb!=! \textit{value} command as for example
\begin{verbatim}
var r=6
\end{verbatim}
The name requirement is the same as that for points; an initial (single) letter optionally followed by a maximum of 3 digits.
Sometimes the \verb!var! command too restrictive as regards the  variable-name, in which case a more intuitive variable-name can be allocated by using a  \mathsPIC\ macro (see Section~\ref{sec:macros}). For example, we can allocate the name \verb!WeightInKg! to some value, say $22.6$~$Kg$, using
the following macro definition (see also Section~\ref{sec:maths} for other examples).
\begin{verbatim}
%def WeightInKg()22.6
\end{verbatim}
However, you have to then remember to use the macro with the \verb!&! prefix (see Section~\ref{sec:macros}).

The \textit{value} can be either a number (e.g.~$4.32$ or $63$), an existing variable name (e.g.~\texttt{r3}), a pair of point names
e.g.~\texttt{AB} (i.e.~representing the Pythagorean distance between the two points), or a numerical expression(e.g.~\verb!3*k/2!).
Thus the command
\verb!var r3=20!  allocates 20 to the  variable name
\texttt{r3}, which could then be used, for example, as the
radius in the circle command \verb!drawcircle(C3,r3)!.

New values can be re-allocated to  existing variable-names
using the  same \verb!var! command.

If it is necessary to use the same letter for a point and a variable (or constant), then a convenient strategy  to to consider using
 upper case for points and
lower case for variables and constants.

Note that several variables can be allocated in a single statement, as follows:
\begin{verbatim}
var r=6, j22=r*6/5, d=180
\end{verbatim}



%%----
\subsection{Scalar constants}

Constants can be allocated using the \verb!const! command as follows.
A constant can be any numerical expression.
\begin{verbatim}
const j26=23.653
\end{verbatim}
If you subsequently try and change the value of a constant, then \mathsPIC\ will issue an appropriate error message.


\subsection{Mathematics}
All the usual mathematical operations can used with variables (see Section~4.1), both  when defining a variable, and in places where variables can be used as parameters.
When using `scientific' notation \mathsPIC\ allows either \verb!e! or \verb!E!;
for example, \verb!var j25=7E-2! and \verb!point(P){3, 2.34e2}!.
The constants $\pi$ and $e$  are available as \verb!_Pi_! and \verb!_e_!. The following are examples of valid commands.
\begin{verbatim}
var r = 6, j = r*tan(0.34)/27, d3=AB
point(C){5,5}
drawCircle(C,r/3)
var e=_e_, p1=_Pi_
var j25=7E-2
var t = _linethickness_
text($P$){P, shift(-5.564e-1,0)}
\end{verbatim}



%--------------------------------
\subsection{Scientific notation}

While \mathsPIC\ \textit{does} allow the use of the  `\texttt{E}'  or `\texttt{e}' format of so-called `scientific' notation (see above) it is important to remember that \TeX\ does not, and consequently this influences how \mathsPIC\ displays small numbers when they  appear in the output file.

One of the curious anomalies of \TeX\ is that it cannot manipulate
 numeric values in scientific notation,
and will generate an error message whenever it finds the letter \verb!E!
or \verb!e! as part of a number.
  Consequently {\mathsPIC} automatically  converts all numbers  destined to appear within  a \PiCTeX\ command in the output-file into
`true' decimal format (i.e.~not \verb!E! notation).
\mathsPIC\ also reduces such numbers to  only five decimal places, and consequently quantities with an absolute value less than $0.00001$ are therefore effectively reduced to zero ($0.00000$).

This is demonstrated in the following example, where the coordinates $s_i$ appear  in the output file in scientific
notation when in commented lines, but in decimal notation
in the \PiCTeX\ \verb!\put...! commands.
Note also that in this example the $y$-coordinate  of $J_{45}$
appears as zero
in the \verb!\put...! command  but as \verb!2.32857142857143e-06!  when shown as the value \verb!s5!.
\begin{verbatim}
var r = 163/7, s1=r/1E3, s2=r/1E4, s3=r/1E5, s4=r/1E6, s5=r/1E7
point(J12){s1,s2}
point(J23){s2,s3}
point(J34){s3,s4}
point(J45){s4,s5}
drawpoint(J12 J23 J34 J45)
\end{verbatim}
appears in the output file as
\begin{verbatim}
%% var r=163/7, s1=r/1E3,s2=r/1E4,s3=r/1E5,s4=r/1E6,s5=r/1E7
%% r = 23.2857142857143
%% s1 = 0.0232857142857143
%% s2 = 0.00232857142857143
%% s3 = 0.000232857142857143
%% s4 = 2.32857142857143e-05
%% s5 = 2.32857142857143e-06
%% point(J12){s1,s2} 	J12 = (0.02329, 0.00233)
%% point(J23){s2,s3} 	J23 = (0.00233, 0.00023)
%% point(J34){s3,s4} 	J34 = (0.00023, 0.00002)
%% point(J45){s4,s5} 	J45 = (0.00002, 0.00000)
%% drawpoint(J12 J23 J34 J45)
\put {$\bullet$} at 0.02329 0.00233 %% J12
\put {$\bullet$} at 0.00233 0.00023 %% J23
\put {$\bullet$} at 0.00023 0.00002 %% J34
\put {$\bullet$} at 0.00002 0.00000 %% J45
\end{verbatim}

Note that in practice one could write a Perl subroutine to check and filter out occurrences of unwanted \verb!E! characters. For example, as when out-putting graph data in the form of $(x,y)$ data-pairs to a file.


%%-----------------------------
\section{The LOOP environment}

This operates as a simple `\textsc{do...loop}' allowing  a chunk of code to be input multiple times. It takes a single argument, namely the loop number. The commands for this environment are as follows.

\medskip
\syntax{beginloop} \ab{expr}

\syntax{...}

\syntax{endloop}

\medskip

When using a `\textsc{do-loop}' one usually has to initialise some parameters, and then increment the parameters with each passage of the loop. In particular, it is often convenient to use a loop counter so that one can see in the output file which particular loop  is being processed at any stage. It is also useful to include an obvious marker at the beginning and end of the repeated section. All these are included in the following code which produces Figure~\ref{fig:fold} by inputting a section of the code 40 times.

%\pagebreak

\begin{Verbatim}
%% mpicpm03-4.m (Figure 3.4)
\usepackage{mathspic}
%---------------------------
\beginpicture
paper{units(1mm), xrange(0,60), yrange(0,60) axes(LB), ticks(10,10)}
point(S){7,55}   % Start position
drawpoint(S)
%% initialise parameters
var n=0     % initialise mathspic counter
var a=-180  % start angle degrees
var d=50    % start length
beginLOOP 40   % loop 40 times
   var n=n+1, a = a+90, d = d-1 %% increment counter, angle, length
   point*(P){S,polar(d,a deg)} % generate new point P
   drawline(SP) % draw line from OLD S to NEW P
   point*(S){P} %% reallocate S <-- P
endLOOP
drawpoint(P)
\endpicture
\end{Verbatim}

%%------------Figure 03-4-----------------
%% fold figure
\begin{figure}[hbt]
\centering
   %% fold
    \ifpdf
  \includegraphics[width=10cm]{mpicpm03-4.pdf}
  \else
  \includegraphics[width=10cm]{mpicpm03-4.eps}
  \fi
   \caption{\ }
   \label{fig:fold}
\end{figure}
%----------------------



\end{document}
