%% mpicp-comm-pictex.tex
%% mathsPIC manual

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

%%-----------------------------------------
\chapter[PiCTeX commands]{\PiCTeX\ commands}
\label{chap:pictex}
%-------------------------------


In this section we present a list of \PiCTeX\ commands for use with \mathsPIC\ which is adequate for most purposes.  For a more extensive listing see the excellent 8-page summary  by  by  Duggan (1990). A 3-page  German summary is available from Siart (2008).
Alternatively,  there is a nice section on {\PiCTeX} in Hoenig (1998),
 which  includes a brief list of  commands.

The complete list of \PiCTeX\ commands is long and detailed, and is, unfortunately, only available currently by purchasing the small \textit{The \PiCTeX\ Manual} by Wichura (1992)\footnote{Available from \textsl{Personal \TeX\ Inc.} (\textit{texsales@pctex.com}, \texttt{http://www.pctex.com/books.html}}.
See Chapter~\ref{ch:pictex} for full details on \PiCTeX\ itself and  Wichura's manual (Section~\ref{sec:pictexmanual}). 
Wichura's manual is well worth obtaining if you intend to be adventurous with \PiCTeX.


\PiCTeX\ commands can \textit{only} be used within  the
\verb!\beginpicture! ... \verb!\endpicture! environment.
Most \PiCTeX\ commands are short one-line commands starting
with a leading backslash.
 Such commands can be used in the normal way
 as {\mathsPIC} will automatically
copy lines starting with a backslash command unchanged through into
the output-file (\verb!.mt!~file).
For example, drawing with dashed lines is enabled  using
the  following {\PiCTeX} command 
\begin{verbatim}
\setdashes
\end{verbatim}
However, some {\PiCTeX} commands are very long.
It is therefore sometimes necessary to have the initial part of a
{\PiCTeX} command on one line, with the rest of the command
continuing onto the next line, such that the second
 and subsequent lines may well not have a leading backslash command.
In order to protect such subsequent lines
 from being processed as  {\mathsPIC}
commands, they must be protected by a leading
backslash \textit{followed by one or more spaces}
(e.g.\ \verb!\!{\gap\ldots}) as this instruction tells {\mathsPIC} to
copy the rest of the line unchanged (\textit{without} the leading
backslash) through into the output-file.
For example, the {\PiCTeX} code for plotting data-points for a
curve  could be spread across several lines in the {\mathsPIC}
file as follows (an important point to note is that the \PiCTeX\ algorithm requires that the number of such points is odd---see Section~\ref{sec:plotting}).
\begin{verbatim}
\setquadratic
\plot  1.15    -0.67
\      1.25     0.02
\      1.35     1.24 /
\setlinear
\end{verbatim}
When these commands are processed by {\mathsPIC}, they will
appear in the output {\TeX} file (\verb!.mt! file) as follows.
\begin{verbatim}
\setquadratic
\plot  1.15    -0.67
       1.25     0.02
       1.35     1.24 /
\setlinear
\end{verbatim}



%------------------------------------
\section[Useful PiCTeX commands]{Useful \PiCTeX\ commands}

 The following is a small list of {\PiCTeX} commands which are
particularly useful for including in the  {\mathsPIC} file, mainly for
 controlling the thickness of lines and axes, customising dash
 patterns and symbol spacing, and for plotting and rotation.

 Some care needs to be taken with  the syntax of \PiCTeX\ commands, which uses spaces, angle brackets and commas.
For example, where small angle brackets are shown (e.g.~\gap\verb!<...>!\gap) then
 these must be used exactly as shown below, including spaces (shown here as \gap). Thus, if you wish to use a following comment (\% ...) on the same line as a \PiCTeX\ command, then you must ensure there is a trailing space (\gap) after the command.
For example, you would implement a dash pattern of dash (4pt) alternating with  a gap of 2pt using the following command.

\medskip
\noindent\verb!\setdashpattern!{\gap}\verb!<4pt,!{\gap}\verb!2pt>!{\gap}\% this command sets the pattern

\medskip
The more extensive summary of  \PiCTeX\ commands (\texttt{pictexsum.pdf}) by Duggan (1990) mentioned above will certainly suffice for most people's use.
%%% ***use Verbatim here to make sure of the leading spaces 
%%% (better than v for large distances)
\begin{Verbatim}
\grid {cols} {rows}  %% eg. \grid {5} {10}
\nogridlines
\plot
\setdashpattern <4pt, 2pt>
\setdashes <7pt>  %% equivalent to  \setdashpattern <7pt, 7pt>
\setdashes        %% default is  \setdashes <5pt>
\setdots <4pt>
\setdots          %% default is  \setdots <5pt>
\setsolid         %% sets solid-line mode (ie not dashes/dots)
\setlinear        %% sets straight-line plotting mode
		  %% (ie not quadratic)
\setquadratic     %% sets curved plotting for graphs etc
\setplotsymbol({\large .})
\setplotsymbol({\tiny .})   %% default size for curves
			    %% (used by \plot)
\plotsymbolspacing=2pt  %% sets spacing between plot symbols
			%% (used by \plot)
\plotheading{..}        %% eg \plotheading{This is a quadratic}
\plot  x1  y1  x2  y2  ...  /  %% the <space>/ is the list terminator
\headingtoplotskip=1cm  %% separation between plotheading & graph
\linethickness=2pt      %% for horiz & vert lines: default 0.4pt
\frame <sep> {text}           %% eg  \frame <5pt> {Hello}
\rectangle <width> <height>   %% eg  \rectangle <2cm> <1cm>
\putrectangle corners at 5 10 and 30 5   %% corners at Top-left
				      %% and Bottom-right
\inboundscheckon        %% restricts plotting to plotting area
\inboundscheckoff       %%
\normalgraphs           %% restores default values for
                        %% graph parameters (see Section 4.6.1)
\ticksin
\ticksout
\visibleaxes
\invisibleaxes
\circulararc 30 degrees from 3.5  4.5 center at 5 5
\ellipticalarc axes ratio 2:1  360 degrees from 3 3 center at 5 5
                %%(axes ratio is  major-axis:minor-axis, i.e. a:b)
\end{Verbatim}

Note that {\PiCTeX} also has an excellent rotation facility (but only in conjunction with \PiCTeX\ function commands, e.g.,~\verb!\ellipticalarc! as shown below, and so will not rotate points input by \mathsPIC\ via a data-file).
{\PiCTeX} will rotate about a given point, by a given angle, all
picture elements (but not text) which
are detailed between its \verb!\startrotation...! and
\verb!\stoprotation! commands.  However the decimal value of
the Sine and Cosine angle must be supplied (see below).
If a rotation point is not specified then
rotation is performed about the origin. The format is as follows.
\begin{verbatim}
\startrotation by cos(t) sin(t) [about x y]
...
\stoprotation
\end{verbatim}
This command is particularly useful for rotating curves.
For example, to rotate an ellipse by 30 degrees about the
point (5,5) one would write
\begin{verbatim}
\startrotation  by  0.86602  0.5  about  5  5
\ellipticalarc.....
\stoprotation
\end{verbatim}
Note that the \PiCTeX\ \verb!\startrotation! command would be easily amenable to
being rewritten as a \mathsPIC\ macro (to avoid calculating the radian values etc).


A {\PiCTeX} error-bar facility  is also available by loading
the file \verb!errorbars.tex! (see Section~\ref{sec:errorbar}).
Note that {\PiCTeX} does allow more sophisticated graph axes and
tick-marks to be setup, as well as shading of enclosed areas.
However, these are complicated and require access
to the {\PiCTeX} Manual (see Section~\ref{sec:pictexmanual}), and are
currently outside the scope of {\mathsPIC}.


%%===============
\section[Using the \$ symbol with PiCTeX]{Using the \$ symbol with \PiCTeX}

Because \PiCTeX\ was originally written for Plain \TeX\  there is a difficulty when using the \$ symbol in the labels for axes.
The `work-around'  fix for this is to re-encode it as, say, \verb!\dollar!, and  express {\$2} as \verb!{\dollar}2!,
 as shown in the following example which has dollars on the y-axis
 (note the \%  at the end of the first line to stop unwanted horizontal space being grabbed by \PiCTeX and pushing the Y-axis slightly to the right).

\begin{verbatim}
\newcommand{\dollar}{\char'44}%
\setcoordinatesystem units <1mm, 1mm>
\setplotarea x from 0 to 50, y from 0 to 50
\axis bottom ticks numbered from 0 to 50 by 10 /
\axis left ticks withvalues {\dollar}1  {\dollar}2 / at 10  20 /  /
\plotheading{A nice picture costing \$25}
\end{verbatim}



\end{document}
