%% mpicp-run.tex
%% mathsPIC manual
%% May 2011  RWD Nickalls


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

%%----------------------------
\chapter{Running \mathsPIC$_{Perl}$}


\MathsPICperl\ is a Perl program and will therefore run on any platform on which Perl is installed. Apart from  minor platform differences regarding filename conventions, commands for creating, editing and deleting ASCII files and so on, the practicalities of running and using \mathsPIC\ will be essentially the same whichever platform is being used.

\MathsPIC\ was developed using both   GNU Linux and a Solaris x86 box, and 
consequently some of the command-line codes  may reflect this perspective. For example, the following \mathsPIC\ command to delete the file \verb!temp.txt!
\begin{verbatim}
system("rm temp.txt")
\end{verbatim}
uses the Unix\footnote{The term ``Unix'' here is used as a synonym for both Unix systems (e.g.,~Solaris, TrueUnix) and Unix-like systems (e.g.,~Linux, FreeBSD).} `remove' command \verb!rm!. Clearly this particular command will differ between platforms but it is assumed that users are familiar with  their own local system commands.
MS-Windows users may wish to look at Appendix~D in which we address installing Perl on a MS-Windows platform. The authors  welcome any relevant platform-related information so we can include it in updates to this manual.








%=========================
\section{Installation}

If you have a recent \TeXlive\ installation (2009 or later) then both \mathsPIC\ and \PiCTeX\ will already be installed. However,  \mathsPIC\ may not be immediately runnable from the command-line as this depends  on the status and location of the Perl program \texttt{mathspicX.pl} and the associated  BASH file \texttt{mathspic.sh}.



%--------------------------------
\subsection{The \mathsPIC\ package}

The latest version of \mathsPICperl\ can  be
 downloaded from the following directory in CTAN.

\begin{verbatim}
CTAN: /tex-archive/graphics/mathspic/perl/
\end{verbatim}


\subsection*{List of files}
\begin{Verbatim}
grabtexdata.pl        % program used in Chapter 8 
HELP.TXT              % text version of the Unix manpage
mathspicX.pl          % mathsPIC program version X (perl)
mathspic.sty          % style option
mathspic.1            % unix/Linux manpage file
mathspic.sh           % example BASH file for running mathsPIC
MATHSPIC.BAT          % example batch file (MS-Windows)
mathsPICmanual.pdf    % manual 
mathsPICmanual.zip    % manual--all the LaTeX and figure files
mathsPICfigures.zip   % all the .m and .pl files described in the manual
mathspic.lib          % example library file of macros
README.txt            % this file
sourcecode.pdf        % source code
sourcecode.html       % source code
sourcecode.nw         % source code (noweb format)
\end{Verbatim}




%-----------------------
\subsection{Unix/Linux platform}


Note that {\TeX}Live  generally places non-executable \mathsPIC\ scripts and programs (e.g.,~\texttt{mathspic113.pl} and \texttt{mathspic.sh}) in a `scripts' directory, for example
\newline\verb!/usr/local/texlive/2010/texmf-dist/scripts/mathspic/!
{\newline}and executable ones into
\newline\verb!/usr/local/texlive/2010/bin/i386-linux/!
{\newline}Consequently, this last directory needs to be included in the \$PATH.



When installing \mathsPIC\ manually, place the files as follows (and then update your system's \TeX-file index, by invoking the \verb!texhash! command, so the new files can be found by the system).
\begin{itemize}


\item  \textbf{\LaTeX\ package} (\texttt{mathspic.sty})

This file needs to be  placed either (a)~with the \TeX\  style-options (typically in  the directory \verb!/usr/share/texlive/20XX/texmf-dist/tex/latex/mathspic/!)
or possibly (b)~among your  `local'  packages
(for example in: \newline\verb!/usr/local/texlive/texmf-local/tex/latex/local/mathspic/!).


\item \textbf{The \mathsPIC\ program} (\texttt{mathspicX.pl})

This file should be placed where your shell can find it (typically in the directory \verb!/usr/local/bin/!). 



\item \textbf{The \mathsPIC\ BASH script} (\texttt{mathspic.sh})

This file should be placed where your shell can find it (typically in the directory \verb!/usr/local/bin/!).



\item \textbf{Unix man page} (\texttt{mathspic.1})

This useful quick-reference file should be placed in the directory where the man pages of your  installation reside (typically in \verb!/usr/share/man/man1/!).
Following this, you will be able to access the \mathsPIC\ man page by typing the command
\begin{verbatim}
$ man mathspic
\end{verbatim}
\end{itemize}
%\enlargethispage*{\baselineskip}\pagebreak




%========================-
\subsection{MS-Windows platform}

Since \mathsPIC\ is a Perl program, if Perl is not already installed then see Appendix~D   for directions on how to install a free version of Perl.


\subsection{\texttt{mathspic.sty}}
Locate the  directory containing all the \LaTeX\ packages, and create a
mathspic subdirectory.
Copy  into this new directory the file \texttt{mathspic.sty}.

%-------------------
\subsection{\texttt{mathspicX.pl}}
Locate the  directory containing all the Perl \texttt{.pl} programs (typically the directory \texttt{c:{\bs}perl{\bs}bin{\bs}} for the  ActivePerl implementation of Perl)  and
copy  into this directory the file \texttt{mathspic.pl}
(see Appendix for details regarding  installing Perl on MS-Windows platforms).





%--------------------------------
\section{Command-line syntax}

 The general command-line syntax is as follows.


%%% note that \ab{}  is my macro for anglebrackets (in the .tex file}
\medskip
\noindent\fbox{\$ perl [\ab{perl switches}] mathspic.pl  [\ab{mathspic switches}] \ab{inputfile} [-o \ab{outputfile}] }

\medskip
By default \mathsPIC\ writes the output to a file having the same filename as the input file, but with the filename extension \verb!.mt!.
If you forget to type an input filename, then \mathsPIC\ writes the following line to the screen.
\begin{verbatim}
mathspic version 1.13 Apr 26, 2010
Usage: mathspic [-h] [-b] [-c] [-o <out file>] <in file>
\end{verbatim}
If you type \verb!$ mathspic -h! you get all the switches information as well
\begin{Verbatim}
This is mathspic version 1.13 Apr 26, 2010
Type "man mathspic" for detailed help
Usage:  mathspic  [-h] [-b] [-c] [-o <out file>] <in file>
        where,
        [-b]    enables bell sound if error exists
        [-c]    disables comments in output file
        [-h]    gives this help listing
        [-o]    creates specified output file
\end{Verbatim}

There are several ways of running \mathsPIC\ from the commandline, as follows (at the time of writing the current version of the program is \texttt{mathspic113.pl}):

%--------------------
\subsubsection{\fbox{a}---Invoking the Perl interpreter}
The minimum command required to  process the script file \verb!myfile.m! is
\begin{verbatim}
$ perl mathspic113.pl  myfile.m
\end{verbatim}

%-----------------------
\subsubsection{\fbox{b}---Making the mathspicX.pl program executable}
This is probably the  most efficient approach, and is therefore the recommended method.
\begin{itemize}
\item [1] Rename the \mathsPIC\ program  (\verb!mathspic113.pl!)
to just \ab{mathspic}; 
\begin{verbatim}
$ mv mathspic113.pl  mathspic
\end{verbatim}
\item [2] Now make the file executable, by  typing the command:
\begin{verbatim}
$ chmod 755 mathspic
\end{verbatim}
 and then copy it to where the shell can find it (typically \verb!/usr/local/bin/!).
 Now mathsPIC can be run from any directory by typing
\begin{verbatim}
$ mathspic  myfile.m
\end{verbatim}
\end{itemize}
Note that this is the approach adopted by {\texlive}, which 
places  executable files in the directory,
\begin{verbatim}
 /usr/local/texlive/2010/bin/i386-linux/
\end{verbatim}
which therefore needs to be included in the \$PATH.

%-----------------------
\subsubsection{\fbox{c}---Using a batch file}

Alternatively, \mathsPIC\ can   be run via a batch file, and an example BASH file  is included in the package (\verb!mathspic.sh!). Rename the BASH file
to \verb!mathspic!; make it executable; and then copy it to where the shell can find it (typically \verb!/usr/local/bin/!).
 Now mathsPIC can be run from any directory just by typing
\begin{verbatim}
$ mathspic  myfile.m
\end{verbatim}






%====================
\section{Files}


%--------------------------------
\subsection{Filename extensions}

Throughout this manual we  use the filename
extension \verb!.m! to denote a  {\mathsPIC} script file (input-file),
purely in order to distinguish them from the other files which are generated by \mathsPIC. In practice, though, the \mathsPIC\ program will accept \textit{any} filename-extension preferred by the user\footnote{For example, there is an obvious clash with the extension used by the program \textit{Mathematica}, so in this case a user could consider, perhaps, the alternative extension \texttt{.mp} for a \mathsPIC\ script file.}.
However, \mathsPIC\ by default uses the extension \texttt{.mt} for the \TeX\ output-file (a   {\TeX} file containing  {\PiCTeX} commands  ready for  {\TeX}ing), and the extension \verb!.mlg!   for the log-file.



The {\mathsPIC} command-line actions one input file
and (optionally) one  output filename (prefixed by the  \texttt{-o} switch).
 Each command or switch must be separated by at least one space, as in the following example.
\begin{verbatim}
$ mathspic inputfile   -o outputfile
\end{verbatim}


If the \texttt{outputfile} is not specified then {\mathsPIC} will
create an output-file having the same filename as the
\verb!inputfile! but with the filename extension \verb!.mt!.
For example, if you want an input-file called
\verb!myinfile.abc! to generate an output-file called
\verb!myoutfile.xyz! then use the following command.
\begin{verbatim}
$ mathspic myinfile.abc   -o myoutfile.xyz
\end{verbatim}
\MathsPIC\ also writes to a log file (the \texttt{.mlg} file). This has the same filename as the input filename.

 

%%-----------------------
\section{Switches}

There are four command-line switches (\verb!-h -c -b -o!)
which are case-sensitive. 
If more than one switch is used then
they must be separated by at least one space. The switches are as follows (this information is also given by typing \verb!$ mathspic -h!).

\begin{itemize}

\item [-h] Help---gives basic information
\item [-b] Beep---a beep is sounded if
     \mathsPIC\ detects an error. If an  audible beep does not sound in the presence of an error, then check the PC configuration to see if the
PC beep is disabled.

\item [-c] Disables comment line generation in the output file.
\item [-o] Output file name
\end{itemize}


%---------
\section{Removing comment lines}

Once a diagram has been finalised, it is sometimes convenient to
remove all the various commented lines from the final
output-file, particularly if the file is a large one.
This can be easily done using the \texttt{-c} switch, which will stop \mathsPIC\ writing any comments to the output \texttt{.mt} file.
For example, the following command  disables the writing of  comment lines to the output \texttt{.mt} file.
\begin{verbatim}
$ mathspic   -c inputfilename
\end{verbatim}


%-------------------------
\section{Online help}

In Unix systems typing the command
\begin{verbatim}
$ man  mathspic
\end{verbatim}
will open the manpage help file. If this fails, then check that the man page file (\texttt{mathspic.1}) has been placed in the correct directory (typically \texttt{/usr/share/man/man1/}.
\hbox{MS-Windows} users can read the equivalent file HELP.TXT.


%--------------------------------
\section{The \mathsPIC\ style-option}
\label{sec:sty}

Since some \PiCTeX\  commands  are redefined  by \mathsPIC\ it is \textit{always} necessary  to use the \mathsPIC\ style-option by using the following command in the preamble of the
\LaTeX\ document.
\begin{verbatim}
\usepackage{mathspic}
\end{verbatim}
If the \texttt{color} package is used, then it must be loaded \textit{after} the \texttt{mathspic} package, as follows:
\begin{verbatim}
\usepackage{mathspic, color}
\end{verbatim}


Since \mathsPIC\ is only used  to generate figures and diagrams, the style-option also  includes the \LaTeX\ command  \verb!\thispagestyle{empty}! in order to stop page numbers appearing in a figure.
Note also  that if page numbering is not disabled when creating a diagram, then the page number will prevent the DVIPS  BBox  \texttt{-E} option (see Section~\ref{sec:epsandjpg})  from removing all the white space from between the figure and the number.
However, there are instances when it may be useful to comment out the \verb!\thispagestyle{empty}! command, as detailed in Section~\ref{sec:pictexfigs}.

The style-option also defines the macros for various forms of the logo (e.g.,~\mathsPIC, \mathsPICp, \mathsPICperl).

The style-option is as follows:
\begin{verbatim}
%%
%% This is file `mathspic.sty',
%% April 26, 2010
%%
%%  (c) copyright 2004-2010  A Syropoulos & RWD Nickalls
%%  This program can be redistributed and/or modified under the terms
%%  of the LaTeX Project Public License Distributed from CTAN
%%  archives in directory macros/latex/base/lppl.txt; either
%%  version 1 of the License, or any later version.
%%
%%  Please report errors or suggestions for improvement to
%%
%%     Apostolos Syropoulos          Dick Nickalls
%%     apostolo@yahoo.com         dick@nickalls.org
%%
\wlog{Package `mathspic' A Syropoulos & RWD Nickalls (April 2010)}%
\typeout{Loading mathsPIC package (c) RWD Nickalls & A Syropoulos%
         April 2010}%
\ProvidesFile{mathspic.sty}%
  [2010/04/26 v1.13 Package `mathspic.sty']%
\def\fileversion{1.13}
\def\filedate{2010/04/26}
\ifx\fiverm\undefined
        \newfont\fiverm{cmr5}
\fi
\let\Linethickness\linethickness%
%%----------mathsPIC logos---------------------
\newcommand{\mathsPIC}{\textsf{mathsPIC}}
\newcommand{\MathsPIC}{\textsf{MathsPIC}}
\newcommand{\mathsPICp}{\textsf{mathsPIC}%
                    \kern-0.08em\raisebox{-0.15em}{\textit{\tiny P}}}
\newcommand{\MathsPICp}{\textsf{MathsPIC}%
                    \kern-0.08em\raisebox{-0.15em}{\textit{\tiny P}}}
\newcommand{\mathsPICperl}{\textsf{mathsPIC}%
                    \kern-0.08em\raisebox{-0.15em}{\textit{\tiny Perl}}}
\newcommand{\MathsPICperl}{\textsf{MathsPIC}%
                    \kern-0.08em\raisebox{-0.15em}{\textit{\tiny Perl}}}
%%-----------PICTEX stuff-----------------------------
\input prepictex
\input pictexwd
\input postpictex
%%-------------------------------------
\thispagestyle{empty}% stop page numbers 
\endinput
%%
%% End of file `mathspic.sty'.
\end{verbatim}
 
%-------------------------
\section{Error-messages}

A certain amount of syntax checking is performed by {\mathsPIC}, and error-messages are written to the main output-file (\verb!.mt! file)
and also to the log-file (\verb!.mlg! file).

  A copy of the  line containing an error is prefixed by \texttt{\%\%~***};
the associated error-message appears on the next line and is
prefixed  by dots (\texttt{\%\%~...}).
Note that if the \texttt{-c} switch (clean) is used (see above), then error-messages appear only in the log file.
If the \texttt{-b} switch is used then a beep is  sounded if
an error occurs during processing.


Runtime errors most commonly arise  when an argument has been
omitted, or division by zero has been attempted.
  Syntax errors arise when {\mathsPIC} commands are written incorrectly (e.g.~missing bracket, or a command being spelled incorrectly).
    
The following lines  show some typical examples with respect to a \texttt{draw} command if
a point has not been previously defined resulting in a `point-name' error:


\begin{verbatim}
%% drawline(AB)
%% *** Line 15: drawline(AB
%% ***                   )
%% ... Error: Undefined point  B
\end{verbatim}
Some other examples of error-messages are as follows.
\begin{verbatim}
%% drawline()
%% *** Line 22: drawline(
%% ***                 )
%% ... Error: Wrong number of points
\end{verbatim}

\medskip
\begin{verbatim}
%% *** Line 49:
%% ***          pointt(K2){4,6}
%% ... Error: command not recognized
\end{verbatim}

\medskip
\begin{verbatim}
%% drawline(PQ)
%% *** Line 52 : drawline(PQ
%% ***                     )
%% ... Error: points P and Q are the same
\end{verbatim}

Since  an error often has an effect on the processing of
 later commands in the script (\mathsPIC\ file), a single error can result in a cascade of  error messages. In other words, the number of error messages is not a good guide to the number of errors---there may only be one small typo causing all the error messages.

%%--------------------
\section{Log-file}
{\mathsPIC} outputs a log-file (\verb!.mlg! file)
which contains details of all errors, relevant line numbers
and file names.
The format was designed to match that of a standard \TeX\ log-file
in order to be compatible with commonly used
error-checking utilities.

For example, in the following code the errors in the 2nd, 3rd and 4th lines
(combined with the fact that point B has not been defined) generate the error messages found in the associated log file (\verb!.mlg! file) below.

\begin{verbatim}
%% test.m
point(A){5,5}
var d=
drawline(AB
var j=
text($B$){B, shift(d,0)}
\end{verbatim}

The log file (\verb!.mlg! file) shows the following:
\begin{verbatim}
----
2011/05/29    14:42:41
mathspic (Perl version 1.13 Apr 26, 2010)
Copyright (c) 2005-2010 A Syropoulos & RWD Nickalls 
Input file  = test.m
Output file = test.mt
Log file    = test.mlg
----
Line 3: var d=
               ***Error: Unexpected token
Line 4: drawline(AB
                    ***Error: Undefined point B
Line 4: drawline(AB
                    ***Error: Wrong number of points
Line 4: drawline(AB
                    ***Error: Missing ) after arguments of 
Line 5: var j=
               ***Error: Unexpected token
Line 6: text($B$){B
                   , shift(d,0)}
***Error: undefined point/var
\end{verbatim}



%%----------------------
\end{document}
