diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/mathspic/dos/mpicm21.tex |
Initial commit
Diffstat (limited to 'graphics/mathspic/dos/mpicm21.tex')
-rw-r--r-- | graphics/mathspic/dos/mpicm21.tex | 4373 |
1 files changed, 4373 insertions, 0 deletions
diff --git a/graphics/mathspic/dos/mpicm21.tex b/graphics/mathspic/dos/mpicm21.tex new file mode 100644 index 0000000000..4ece3dfe02 --- /dev/null +++ b/graphics/mathspic/dos/mpicm21.tex @@ -0,0 +1,4373 @@ + +%%----------------------------- +%% File name = mPICm21.tex +%% manual for mathsPIC 2.1 (PowerBASIC/DOS version) +%% +%% Copyright (c) RWD Nickalls November 5th, 2000 +%% RWD Nickalls, +%% Department of Anaesthesia, +%% City Hospital, Nottingham, UK. +%% email: dicknickalls@compuserve.com +%% +%% The mathsPIC program is released under the terms of the +%% General Public License as published by +%% the Free Software Foundation; either version 2 +%% of the license or later. +%% +%% MathsPIC is distributed without any warranty or +%% implied warranty of merchantability or fitness for a +%% particular purpose. See the General Public License +%% for more details. +%% +%%---------------------------------------------- +\documentclass[a4paper]{article} +\usepackage{geometry} \geometry{hscale=0.75,vscale=0.85} +\usepackage{pictexwd} % new pictex style option by Andreas Schrell (1994) +\usepackage{amssymb} % for symbols in Table 1 +\usepackage{fancyhdr} +%% pictexwd is available from CTAN\tex-archive\graphics\pictex\addon + +%%------ mathsPIC and PiCTeX macros ----------- +\newcommand{\mathsPIC}{\textsf{mathsPIC}} +\newcommand{\MathsPIC}{\textsf{MathsPIC}} +\newcommand{\bs}{$\backslash$} +\newcommand{\gap}{\protect\texttt{\char'40}\protect} %% the <space> symbol + +%%---------some table macros------------- +\newcommand{\tstrut}{\rule{0pt}{12pt}} % for top line +\newcommand{\mstrut}{\rule{0pt}{12pt}} % middle lines +\newcommand{\bstrut}{\rule{0pt}{12pt}} % bottom lines +%%-------------------- start of document ------------------- + +\begin{document} +\thispagestyle{empty} + +\vspace*{1cm} +\bigskip\bigskip\bigskip +\hrule \medskip +\begin{flushleft} + \hspace*{3cm}{\huge \mathsPIC\Large\ 2.1} \\ + \end{flushleft} + +\medskip +\hrule + +\vspace{3cm} + +\begin{flushright} +\large + Richard W.\ D.\ Nickalls,\\ + Department of Anaesthesia,\\ + City Hospital, Nottingham, UK. \\ + \textit{dicknickalls@compuserve.com}\\ + Tel: +44-(0)115-9691169\\ + Fax: +44-(0)115-9627713\\ + + {\ } \\ + November 5th, 2000 + \end{flushright} +%%-------------------------- + \vspace{4cm} + + +\newpage %{\ }\cleardoublepage +\vspace*{7cm} + + +\begin{center} + Copyright {\copyright} RWD Nickalls 1999--2000 +\end{center} + +\begin{center} +\begin{minipage}{10cm} + {\mathsPIC} is released under the terms of the + General Public License as published by + the Free Software Foundation; either version~2 + of the license or later. + {\MathsPIC} is distributed without any warranty or + implied warranty of merchantability or fitness for a + particular purpose. See the General Public License + for more details. +\end{minipage} +\end{center} + +\newpage + +%--------------------------- +\tableofcontents + +\cleardoublepage + +%%------------------------------------ +\pagestyle{fancy} +\fancyfoot{} +\fancyhead{} +\fancyhead[L]{\Large\mathsPIC\large\ 2.1} +\fancyhead[R]{\thepage} +%%----------------------------------- + +\section{Introduction} + +{\MathsPIC}\footnote{{\mathsPIC} +(\texttt{CTAN:/tex-archive/graphics/pictex/mathspic/}) +was first presented at the +Euro{\TeX}'99 conference in Heidelberg, Germany. It is a free MS-DOS +program (150 KB) compatible with MS-Windows 9x, 2000, NT.} + is a small filter program for use with the excellent free +{\PiCTeX} drawing +engine\footnote{\texttt{CTAN:/tex-archive/graphics/pictex/addon/}. +The files input using \texttt{pictexwd.sty} total only 138 KB. +See Section~9 for details.} +(Nickalls, 1999a, 1999b; Syropoulos and Nickalls, 2000). + {\MathsPIC} parses a plain text input-file (the {\mathsPIC} file), + and generates a plain text output-file + containing {\PiCTeX} and \TeX\ commands + which can then be {\TeX}ed (or {\LaTeX}ed) in the usual way. + Spaces and the comment \texttt{\%} symbol are used in the same way as + \TeX, although unlike \TeX, {\mathsPIC} commands +are \textit{not} case-sensitive. {\PiCTeX}, \TeX\ and \LaTeX\ +commands can all be freely used in the {mathsPIC} 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 motivation for {\mathsPIC} stems from the fact that, while +{\PiCTeX} is an extremely versatile system for drawing +figures, and offers the convenience and advantages of +having the graphics code within the \TeX\ + document itself (e.g.\ printer-independence), +it does require you to specify the coordinates +of most points. This can make {\PiCTeX} quite +awkward to use with 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~1, and the +{\PiCTeX} commands for drawing it are as follows +(the units are in cm). + + +%%------------Figure 1----------------- +%% triangle with incircle +\begin{figure}[hbt] +\begin{center} + %% small triangle with incircle + \strut\input{mPICm01.pic} + \vspace{-4mm} %% raise position of caption %% + \caption{\ } +\end{center} +\end{figure} +%----------------------- + +\vspace{-5mm} + +\begin{verbatim} +\put {$\bullet$} at 0 0 % draw point A +\put {$\bullet$} at 4.924039 0.8682409 % draw point B +\put {$\bullet$} at 1.928363 2.298133 % draw point C +\plot 0 0 4.924039 0.8682409 1.928363 2.298133 0 0/ % draw triangle +\circulararc 360 degrees from 3.008607 1.245238 center at 2.156815 1.245238 +\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 it is then necessary to resort to geometry +and a calculator to determine points $B$ and $C$, +since $AB$, $AC$, and the included angle are 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 +scalar variables, +which has the effect of making even complicated + mathematical diagrams very easy to create. + For example, the equivalent {\mathsPIC} +commands for drawing Figure~1 are as follows (the units are in +cm as before). + + +\begin{verbatim} +point(A){0,0} % point A at origin +point(B){A,polar(5,10 deg)} % point B 5 cm from A; AB slope 10 deg +point(C){A,polar(3,50 deg)} % point C 3 cm from A; BAC = 40 deg +drawPoint(ABC) % put $\bullet$ at points A B C +drawTriangle(ABC) +drawIncircle(ABC) +variable(d){0.5} % d = 0.5 cm +text($A$){A, shift(-d,0)} % label for A +text($B$){B, shift(d,0)} % label for B +text($C$){C, shift(-d,0)} % label for C +\end{verbatim} + + +{\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 (see Section~4.5). +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~7.5). +Files can also be input recursively (see Section~7.6). +A significant feature of {\mathsPIC} is that it +allows TeX macros to be easily used within the {\mathsPIC} file. + +Note that {\mathsPIC} can also be viewed as a handy tool +for exploring elementary geometry since its \texttt{show} commands +return the values of various parameters; +for example, angles, the distance between points, +coordinates of derived points, areas of triangles etc. + + +A PERL version of {\mathsPIC} is currently being developed +(Syropoulos and Nickalls, 2000), and should be available in 2001 +(see Section~11). + + + +%%--------------------------- +\section{Installing {\mathsPIC}} + +\texttt{CTAN:/tex-archive/graphics/pictex/mathspic/} + +{\mathsPIC} can be downloaded from the above directory at CTAN +(Comprehensive \TeX\ Archive Network). +See the file \texttt{readme.txt}. + When installing \PiCTeX\ (see Section~9) I would recommend using +the new \PiCTeX\ files by Andreas Schrell (1994), namely +\verb!pictexwd.sty! (for \LaTeX\ users) and \verb!pictexwd.tex! +(for plain \TeX\ users). + +%----- +\subsection{The program} + +\begin{verbatim} +mpic21.exe (rename to mathspic.exe) +\end{verbatim} + +The executable program \verb!mpic21.exe! was compiled +on an MS-DOS 6.2 platform. It is compatible with +WINDOWS 9x, 2000, NT. +For the purposes of this manual it is suggested that +\verb!mpic21.exe! be renamed to +\verb!mathspic.exe!. The executable program +must be either in the same directory as the {\mathsPIC} input-file, +or in the directory path. + + + +%------ +\subsection{Optional utilities} + +\begin{verbatim} +show.com (a DOS textviewer) +clean.exe (a DOS tool for deleting comment lines) +\end{verbatim} + + + These two files should be placed in the same directory as + \verb!mathspic.exe!. +\verb!clean.exe! is a program for removing all the +commented lines from the output-file (see +Section~3.2 for details). \verb!show.com! is a simple +textviewer which can be invoked using the /s switch (see +Section~3.1.2 for details). + +%------- +\subsection{The manual} + +\begin{verbatim} +mpicm21.tex +mpicm21.dvi +mpicm21.ps +mpicm21.pdf +mpicm01.pic - mpicm16.pic +\end{verbatim} + +The 16 figure files \texttt{mpicm01.pic}---\texttt{mpicm16.pic} +are input by \verb!mpicm21.tex!. +Note that all the {\mathsPIC} files for these figures +(\texttt{mpicm01.m}---\texttt{mpicm16.m}) +are also included in the package---users are free to experiment +with them as they wish. + + + +%--------- +\subsection{Examples} + +The file \texttt{examples} is a collection of +example figures and corresponding {\mathsPIC} code. + + +%%---------------------------- +\section{Running {\mathsPIC}} +\subsection{Command-line syntax} + +Assuming the \verb!.exe! file has been renamed +to \verb!mathspic.exe!, then +the minimum command-line instruction requires only the name of +an input-file as follows. + +\begin{verbatim} +mathspic inputfile +\end{verbatim} + +This will result in \verb!mathspic! generating an output-file (in +the same directory) with +the same filename but with a \verb!.mt! filename extension (see +below for options), and a log-file (\verb!.mlg!). + +While {\mathsPIC} is running, its progress is documented on the +screen by a series of dots (one dot per program line). If an +error is encounted then this is shown as an E instead of a +dot, as follows. + +\begin{verbatim} +.................E....EE.......... +\end{verbatim} + + +\subsubsection{Files} +{\MathsPIC} actions only the first two filenames (any additional +filenames are ignored). + Each filename must be isolated by at +least one space. The order is important; the first filename is +actioned as the \verb!inputfile! (the {\mathsPIC} file); +the second filename (if present) is actioned as the \verb!outputfile!. + + +\begin{verbatim} +mathspic inputfile 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 myoutfile.xyz +\end{verbatim} + + In practice, I find it convenient to use the filename +extension \verb!.m! for {\mathsPIC} files (input-files), +since I can then easily +distinguish between the various files. Thus \verb!.m!\ files +are {\mathsPIC} files (input-files), while +\verb!.mt!\ files are output {\TeX} files containing {\PiCTeX} +commands ready for {\TeX}ing, and \verb!.mlg! files are +{\mathsPIC} log-files. + + +\subsubsection{Switches} + +Five switches are currently used (\verb!/? /h /help /b /s!). +Switches are \emph{not} case-sensitive; +they can be run together without intervening spaces; and they can be +positioned anywhere, provided that they are separated by at +least one space from any filenames. +The switches are as follows. + +\smallskip + +\hspace{1cm}\verb!/?!\hspace{1cm}Help---shows all commands +(also \verb!/h /help!). + +\smallskip + +\hspace{1cm}\verb!/b!\hspace{1cm}Error-beep. A beep is sounded if +{\mathsPIC} detects an error. + +\smallskip + +\hspace{1cm}\verb!/s!\hspace{1cm}Screen view. +Automatically shows the output-file using the free +text-viewer \texttt{show.com}. + +\medskip + +For example, the following command invokes both the error-beep +and automatic viewing of the output-file by the default file-viewer + \texttt{show.com}. +\begin{verbatim} +mathspic /b /s inputfile outputfile +\end{verbatim} + +%--------- +\subsection{Removing comment lines from the output-file} + +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 included \textsc{clean.exe} +utility, which will strip out all lines starting with the +double comment symbol \verb!%%!. The /s switch can also be used +with \textsc{clean.exe}. + Examples of the syntax are as follows. + +\begin{verbatim} +clean.exe /? +clean.exe inputfilename +clean.exe /s inputfilename +clean.exe /s inputfilename outputfilename +\end{verbatim} + +If no output filename is supplied, then \textsc{clean.exe} will +use the same filename but add the filename extension +\verb!.mtc!. +For example, the following command will clean the +output-file \verb!myfile.mt!, generating the file \verb!myfile.mtc! +as the cleaned file, and then view the `cleaned' output-file +using \verb!show.com!. + +\begin{verbatim} +clean.exe /s myfile.mt +\end{verbatim} + +%--------- +\subsection{Batch processing} + +In addition to running the program from the command-line, +{\mathsPIC} can also be run from a batch-file (some familiarity +with the MS-DOS batch-file language is assumed; note that the +batch-files need to be tailored to the particular command-line +sequence.) + For example, the following command line with five parameters + (two switches and three filenames) + +\begin{verbatim} +mathspic /b /s testpic.m testpic.mt testpic.dvi +\end{verbatim} + + +{\noindent}will be executed by the following MS-DOS batch-file (written +for the {Em\TeX}\footnote{The Em\TeX\ screen viewer +is \texttt{dviscrs.exe} and is usually called via +the batch-file \texttt{vs.bat}.} +implementation of \LaTeX\ for PCs using MS-DOS), +which first runs {\mathsPIC} on the input-file +\verb!testpic.m!; then calls \LaTeXe\ to process the output-file; +and finally calls the Em\TeX\ screen viewer \texttt{dviscrs.exe} +(via \verb!vs.bat!) to view +the file \verb!testpic.dvi! (\verb!%5!). + + + +\begin{verbatim} +REM mathsPIC.bat (MS-DOS 6.0 and greater) +@ECHO OFF +mathspic.exe %1 %2 %3 %4 %5 +CALL latex2e %4 +CALL vs.bat /s3 %5 +\end{verbatim} + + + +Note that care needs to be taken to make sure that the +parameters used in the batch-file +correspond to the command-line parameters. + For example, if the two switches are +run together without a space (e.g.\ \verb!/b/s!) + they will be perceived by MS-DOS as a single entity, in which case +the \verb!.dvi! file would be represented by \verb!%4! in the +batch-file instead of \verb!%5!. +For example, the following four-parameter command-line + +\begin{verbatim} +mathspic /b/s testpic.m testpic.mt testpic.dvi +\end{verbatim} + + +{\noindent}would require the following MS-DOS batch-file. + + +\begin{verbatim} +@ECHO OFF +mathspic.exe %1 %2 %3 %4 +CALL latex2e.bat %3 +CALL vs.bat /s3 %4 +\end{verbatim} + + +As a final example (again based on the {Em\TeX} implementation), +suppose you wish to use your own text-viewer (say, +\verb!myTextViewer.exe!) to view the output-file, +with the \verb!/b! switch (enables error-beep), and have +conditional branching---i.e.\ have the option to either (a) quit +(select the `\verb!N!' option) and return to the text-editor +after viewing the output-file, or (b) proceed (select the `\verb!Y!' option) +and process the output-file \verb!testpic.mt! (\verb!%3!) and +then view the \verb!.dvi! file (\verb!%4!). +In this example, the following four-parameter command-line + + +\begin{verbatim} +mathspic /b testpic.m testpic.mt testpic.dvi +\end{verbatim} + +{\noindent}could be run using the following batch-file. + + +\begin{verbatim} +REM mPIC.bat (MS-DOS 6.0 and greater) +@ECHO OFF +mathspic.exe %1 %2 %3 %4 +CALL myTextViewer.exe %3 +CHOICE /C:YN View figure?: +IF ERRORLEVEL 1 IF NOT ERRORLEVEL 2 GOTO yes +GOTO no +:yes +CALL latex2e %3 +CALL vs.bat /s3 %4 +:no +\end{verbatim} + + +%%-------------------------------- +\section{The {\mathsPIC} file and script} + +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\ 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(a1a22a34a4)} +can be made easier to read by writing it as + \texttt{drawpoint(a1 a22 a34 a4)}. + + + +\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 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!showPoint(A)! +\newline + Braces contain required supporting arguments; + e.g.\ \verb!point(A){5,6}! +\newline + Square brackets contain optional arguments; + e.g.\ \verb!point(p3){a,shift(1,2)}[circle,5]! + + +\item +Logically distinct groups within brackets must be separated +by commas. +{\newline}e.g.\ \verb!point(B2){A,polar(3,40deg)}[circle,5]! + + +\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 \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 (see Sections~4.1 and 4.2). + + + +\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)---see example in +Section~7.6.1 + +\end{itemize} + + +%------------------------------- +\subsection{\PiCTeX\ commands} + +Note that \PiCTeX\ commands can \textit{only} be used within the +\verb!\beginpicture! ... \verb!\endpicture! environment, + as described in the \PiCTeX\ Manual\footnote{See Section~9.5 for + information regarding the {\PiCTeX} manual.} (Wichura, 1992). + + + +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 {\PiCTeX} \verb!\setdashes! command, and this would be +expressed in the {\mathsPIC} file as follows. + +\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. + +\begin{verbatim} +\setquadratic +\plot 1.15 -0.67 +\ 1.25 0.02 +\ 1.35 1.24 +\ 1.45 3.13 / +\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 + 1.45 3.13 / +\setlinear +\end{verbatim} + + +%%------------------------------------ +\subsection{\TeX\ and \LaTeX\ commands} + +\subsubsection{Headers and footers} + +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, when using \LaTeX\ a typical +format for a {\mathsPIC} file might be as follows (note that +in this example Andreas Schrell's style option \verb!pictexwd.sty! is +used---see Section~9.2). + + +\begin{verbatim} +\documentclass[a4paper]{article} +\usepackage{pictexwd} +\begin{document} +\beginpicture +... +... +\endpicture +\end{document} +\end{verbatim} + + +For users of plain \TeX\ a typical format might be as +follows (see Section~9). + +\begin{verbatim} +\input latexpic.tex +\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 simply 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 (see Section~4.1) +unless a line actually starts with a \TeX\ command. +A typical example is the following macro (used in Figure~9) +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} + +Note that when using {\TeX} or {\LaTeX} commands \textit{within} +the {\PiCTeX} picture environment, it is very important +to include the comment \verb!%! symbol at the end of such lines, +to prevent {\PiCTeX} accumulating additional 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. + + + +%%--------------------------- +\subsubsection{Other \TeX\ commands} + +A very useful command is the \verb!\typeout{}! command, +which will make \TeX\ print comments to the screen while the +output-file is being processed. +For example, the following commands in the {\mathsPIC} file +will print a message to the +screen just before processing a data-file for a curve. + +\begin{verbatim} +\typeout{processing the data-file now}% +inputfile*(curve.dat) +\end{verbatim} + +This command is also useful is when a file is +\verb!input! several times in a loop using the +{\mathsPIC} \verb!inputFile{..}[]! +command. In such cases it is quite useful to include +the line \verb!\typeout{...}%! at the beginning of the file +being input, as this results in \TeX\ printing \verb!...! +to the screen each time the file is input. + +Note the importance of including the comment \verb!%! symbol +at the end of the line when the \verb!\typeout{}%! command +is used within the {\PiCTeX} picture environment. + +%%-------------------------------- +\subsection{The plotting area} + +\subsubsection{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 x 5 cm with a ruled frame on +four sides as shown in Figure~2a. + +\begin{verbatim} +paper{units(mm),xrange(0,50),yrange(0,50),axes(LRTB),ticks(10,10)} +\end{verbatim} + +This particular \verb!paper! command 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} + + + +%%------------Figure 2----------------- +%% the plotting area +\begin{figure}[hbt] +\begin{center} +\noindent +%\framebox{ + % box picture +\begin{minipage}{6cm} + %\vspace{2cm} %% controls space above picture + \input{mPICm02a.pic} + \vspace{5mm} %% controls space between pict and caption + \begin{center} + a. Using \texttt{...axes(LRTB)} + \end{center} +\end{minipage} +%} % end of framebox +%----------------------- +\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 %% use this to place vertically +%%---------------------- +%\framebox{ +\begin{minipage}{5cm} + \vspace{3mm} %% controls space between pict and caption + \input{mPICm02b.pic} + \vspace{10mm} %% controls space between pict and caption + \begin{center} + b. Using \texttt{...axes(XY)} + \end{center} +\end{minipage} +%} % end of framebox +\end{center} +\caption{\ } +\end{figure} +%----------------------- + +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~2b was generated +using the following \verb!paper! command, + + + +\begin{verbatim} +paper{units(cm),xrange(-2,3),yrange(-2,3),axes(XY),ticks(1,1)} +\end{verbatim} + +{\noindent}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). + +%%\clearpage %% need to flush the floats. + +The line-thickness of axes and tick-marks is controlled by +the {\PiCTeX}\verb! \linethickness! command (see Section~4.6.1, +and also Figure~14). + +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~14). +If complicated or more demanding axis configurations are +required, then the {\PiCTeX} Manual (see Section~9.5) +will need to be consulted. +See also Section~8 for details on positioning figures within +\LaTeX\ documents. + + +\subsubsection{Units} + +In addition to the usual units \verb!mm!, \verb!cm!, and +\verb!pt!, {\PiCTeX} accomodates the other six units used by +{\TeX}\footnote{These are described in Chapter~10 of the +\textit{The {\TeX}book} by D.\ Knuth.}, +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 enbrace the Metric system (mm, +cm), the Didot system (didot, cicero), and the UK system +(point, big point, pica, inch). + +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(mm)! in the +\texttt{paper} command is translated by {\mathsPIC} into +the following {\PiCTeX} command in the output-file. + +\begin{verbatim} +\setcoordinatesystem units <1mm,1mm> +\end{verbatim} + +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} +variable(u){1.5} +paper{units(u mm), xrange(0,100), yrange(0,100)} +... +variable(r){2} +variable*(r){r, divide(u)} +point(A){30,20}[circle,r] +variable(s){4} +variable*(s){s, divide(u) +text($A$){A, shift(-s,s)} +\end{verbatim} + + + +If different scales are required (most commonly when drawing +curves and equations---see Figure~14) +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. + + + +\subsubsection{Tick-marks} + +It is recommended that integers are used with the \verb!ticks! +option, since {\PiCTeX} sometimes gives unpredictable results +if decimals are used with the \verb!xrange! and +\verb!yrange! options in conjunction with the \verb!ticks! +option. +In general {\PiCTeX} gives more pleasing axes if integers are +used throughout the \verb!paper! command. + + + + %------------------ +\subsection{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 the length of line $AB$. +A group of three points represents either a triangle, an angle, +or a line, depending on the circumstances. + +%----- +\subsubsection{Point-name} + + +A point-name \textit{must} begin +with a \textit{single} letter, +and may have up to a \textit{maximum} of two following +digits. The following are valid point-names: {$A, B, C3, d45$}. +Since {\mathsPIC} is not case sensitive the points {$d45$} +and {$D45$} are regarded as being the same point. +Point-names can be either separated by spaces, or simply run +together. + + +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. + +\medskip + +\noindent\verb!point*(A){A, shift(5,0)}! + + +%%--------------- +\subsubsection{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 including 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. + +\medskip + +\noindent\verb!point(A){5,10}[$\triangle$]! + +\medskip + + The default point-symbol can also be changed to any \TeX\ character +or string of characters by using the +{\mathsPIC} \verb!PointSymbol! command, and putting this +command \textit{before} any relevant \verb!point! commands, +since 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 +reinstituted (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 be positioned symmetrically over a point-location. +Most characters are therefore not ideal for use as point-symbols, +as they generally require some slight adjustment in order to +position them symmetrically. +In view of this, Table~1 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 with \PiCTeX. + +%%--------------------------- +\subsubsection{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}[$\triangle$,5] +\end{verbatim} + +If only the line-free radius is to be specified + then a preceding comma must be used (e.g.\ \verb![,10]!). +For example the following {\mathsPIC} command would change the line-free +radius associated with point $A$ to 10 units. + +\begin{verbatim} +point*(A){A}[,10] +\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{Useful point-symbols and their radii for 10--12pt fonts.} +{\ } \\ %% 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} +%%---------------------------------------------------------- + + + +Table~1 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 Harald 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/}.}. + 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} +point(A){1,1}[$\odot$,1.2] +point(B){2,2}[$\odot$,1.2] +point(C){1,3}[$\odot$,1.2] +drawline(ABC) +\end{verbatim} + + 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}[,2] +\end{verbatim} + + +By way of illustration, this command is used in +drawing Figure~3 +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{mpicm03a.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. + + +%%------------Figure 3----------------- +%% rectangular text box +\begin{figure}[hbt] +\begin{center} + %% rectangular text box + \strut\input{mPICm03.pic} + \caption{\ } +\end{center} +\end{figure} +%----------------------- + +\begin{verbatim} +%% mpicm03a.m (Figure 3) +\beginpicture +paper{units(cm),xrange(0,6),yrange(0,3),axes(LBT*R*),ticks(1,1)} +point(P){4,2}[$\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 +point*(P){P}[,1] %% set line-free radius of P to 1 cm +drawArrow(BP) %% draw arrow from B (below) +point*(P){P}[,2] %% change line-free radius of P to 2 cm +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 Figure~3, the two \verb!point*! commands and the +two \verb!drawArrow! commands could all be replaced by the +following two commands using the \hbox{[\ ]} option to indicate the +length of the arrow. + +\begin{verbatim} +drawArrow(SP)[1] %% draw arrow 1 unit from point A towards P +drawArrow(BP)[1.5] %% draw arrow 1.5 units from point B towards P +\end{verbatim} + + +%%---- +\subsubsection{Order of points} + +The order of points in {\mathsPIC} commands is sometimes significant. +For example, the command +\newline\verb!point(D){PointOnLine(AB,23)}! +defines the point $D$ as being 23 units +\textit{from $A$ in the direction of $B$}. + + +%%--- +\subsubsection{Number of points} + +The maximum combined number of named points and variables +which can be used +is currently set by default at 50. The total array space for +points and variables can be increased +by using the {\mathsPIC} \verb!PointNumber()! +command. For example, array space for a total of 75 +points/variables would be allocated by the command +\verb!PointNumber(75)!. + + +If the combined point/variable allocation is exceeded, then a so-called +`fatal error' arises and the program terminates. +The following example (from an output-file) documents a fatal error +which occured while the program was trying to define a new point $Z_3$. + +\begin{verbatim} +%% *** point(Z3){P,shift(2,5)} +%% ... FATAL ERROR: points used exceed allocation +%% ... use the PointNumber() command to increase allocation +\end{verbatim} + +%%---- +\subsection{Scalar variables} + +Numeric scalar variables are defined using the +\verb!variable(!\textit{name}\verb!){!\textit{value}\verb!}! command. +The \textit{value} in the braces can be either a numeric (e.g.\ +4.32; 2.6E-2), a variable name (e.g.\ r3), or two points (e.g.\ +AB---meaning the Pythagorean distance between the two points +$A,B$). +Thus the command +\verb!variable(r3){20}! allocates 20 to the variable +\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 \verb!variable*! command. + +However, one must be careful not to mistake +variables for points, and vice versa, since they both +have the same name structure. When both are necessary, + using upper case for points and +lower case for variables is a convenient strategy. +If you inadvertently use a point instead of a variable +{\mathsPIC} will generate an appropriate error message +(see the last example in Section~5.1). + + +\subsubsection{Arithmetic} + +Variables can be manipulated using the commands +\verb!advance!, \verb!multiply!, \verb!divide! and \verb!mod!. +The format is similar to that of the \verb!point! commands. +Thus the command \verb!variable(a1){a,advance(-r3)}! makes +the variable \verb!a1! assume the value \verb!a-r3! (i.e.\ +$a_1 = a - r_3$). +Note that although {\mathsPIC} allows the use of the negative +sign with variables (e.g.\ \verb!-5.34!, \verb!-r3!), +the positive sign is \textit{not} allowed. +Examples of valid \verb!variable! commands are given in Section~6. + + +\subsubsection{Scientific notation} + +When numbers are either very small or very big they are +generally written using the usual computer `E' format of + so-called `scientific notation', for example, 1.243E--9 etc. +{\mathsPIC} allows the use of scientific notation in commands +wherever decimals are normally allowed, as follows. + + +\begin{verbatim} +variable(p2){3.78E3} +point(Z3){J,shift(1.3E-1,6)} +\end{verbatim} + + +Unfortunately, \TeX\ does not process numeric values in scientific notation, +and will generate an error message whenever it finds the letter \verb!E! +as part of a number. + Consequently {\mathsPIC} converts all numbers which appear +within \PiCTeX\ commands in the output-file into conventional +decimal format (place-value notation). +If the value is less than 1.0E--7 (0.0000001) then {\mathsPIC} +simply converts the value to zero. + +However, since this convertion requires additional checking, +{\mathsPIC} does not bother to do this when it outputs data to the +end of a commented line. +For example, in the following extract from an output-file +the variables $s_4$ and $s_5$ appear in scientific +notation when in commented lines, but in decimal notation +in the \PiCTeX\ \verb!\put...! commands (see the line for +point $J_{45}$). +Note also that in this example the $y$-coordinate of $J_{45}$ +appears as zero +in the \verb!\put...! command (since \verb!s5! is less than +0.0000001), but as \verb!2.3E-8! in the +\verb!%%variable(s5){...! line. + +\begin{verbatim} +%% variable(r){23} ( 23 ) +%% variable(s1){r,divide(100000)} ( .00023 ) +%% variable(s2){r,divide(1000000)} ( .000023 ) +%% variable(s3){r,divide(10000000)} ( .0000023 ) +%% variable(s4){r,divide(100000000)} ( 2.3E-7 ) +%% variable(s5){r,divide(1000000000)} ( 2.3E-8 ) +%% point(J12){s1,s2} +%% point(J23){s2,s3} +%% point(J34){s3,s4} +%% point(J45){s4,s5} +%% drawpoint(J12 J23 J34 J45) +\put {$\bullet$} at .00023 .000023 %% J12 +\put {$\bullet$} at .000023 .0000023 %% J23 +\put {$\bullet$} at .0000023 .00000023 %% J34 +\put {$\bullet$} at .00000023 0 %% J45 +\end{verbatim} + + +%----------------- +\subsection{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 segment 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 square-bracket option. +For example, the following command draws a line a distance $d$ +units from point $A$ \textit{towards} point $B$. + +\begin{verbatim} +drawline(AB)[d] +\end{verbatim} + +Note that in this particular command +the order of the points $AB$ and the sign of the +distance \verb![d]! are important. For example, the following +command will draw a line a distance $d$ +units from point $B$ \textit{away from} point $A$. + + +\begin{verbatim} +drawline(BA)[-d] +\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 +(see also \texttt{Pictex2.sty} in Section~9.3). + +However, there are some occasions when it is necessary to draw using +the \verb!\plot! command even for horizontal and vertical +lines (eg.\ when using \verb!\setdots! with larger than usual +dots), in which case the \verb!drawline*! command (disables the +use of \verb!\putrule!) should be used. + + +%------------- +\subsubsection{Line thickness} + +{\PiCTeX} draws lines using two different methods depending +on whether the lines are (a) horizontal or vertical, (b) any +other orientation. These two groups use different +commands for controlling line-thickness, as follows. + + +\subsubsection*{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} \verb!\linethickness! +command (the default line-thickness is 0.4pt). + For example, the following {\PiCTeX} command changes the + thickness to 1pt. + +\begin{verbatim} +\linethickness=1pt +\end{verbatim} + +The \verb!\linethickness! command is also useful +for adjusting the thickness of graph axes, tick marks. +For example, the following commands are used in the code for +Figure~14 to draw thick axes. + +\begin{verbatim} +\linethickness=2pt +paper{units(mm),xrange(0,50),yrange(0,50),axes(XY)} +\linethickness=0.4pt %% reset to default +\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, which resets all +{\PiCTeX} graph-drawing parameters to their default values +including \verb!\linethickness! (see Section~6.3). + + +\subsubsection*{Other lines and curves} + +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} + +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 \verb!\tiny!. +For example, the commands + +\begin{verbatim} +point(A){5,5} +point(B){10,10} +drawThickline(AB) +\end{verbatim} + + +{\noindent}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({\large .}) +\plot 5 5 10 10 / %% AB +\setplotsymbol({\tiny .}) +\end{verbatim} + +\subsubsection*{Recommendations} + +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~2 +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} +{\ } \\ %% 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} +%%---------------------------------------------------------- + +The author's experience is that although {\mathsPIC} +does have commands for drawing thick lines and thick arrows, it +is generally better to control the line-thickness separately +using the two {\PiCTeX} commands shown in Table~2, and to +make separate macros where necessary. +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} + + +%--------------- +\subsection{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 triangle symbol $\triangle$ would be placed at the +point $Z$ using the command \verb!text($\triangle$){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} +variable(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 (see Section~9.5). + For example in the diagram below, + 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} + + +%----------------small diagram-------- +%% A2test.m +%% mathsPIC 2.0k +\begin{center} +\framebox{\vbox{ +\beginpicture +%% paper{units(mm),xrange(0,28),yrange(0,10)} +\setcoordinatesystem units < 1mm, 1mm> +\setplotarea x from 0 to 28, y from 0 to 10 +%% point(P){25,5}[$\bullet$,2] ( 25 , 5 ) +%% text(\fbox{a nice box}){P}[r] +\put {\fbox{a nice box}} [r] at 25 5 +%% drawpoint(P) +\put {$\bullet$} at 25 5 %% P +%% point(J){P,polar(15,-20deg)}[,2] ( 39.09539 ,-.130302 ) +%% text(this is point P){J}[l] +\put {this is point P} [l] at 39.09539 -.130302 +%% drawarrow(JP) +\arrow < 2mm> [ .2679492, .7279404] from 37.216 .5537382 to 26.87938 4.31596 +\endpicture +}} +\end{center} +%%------------------------------ + +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{Error-messages} +A certain amount of syntax checking is performed by {\mathsPIC}. +Error-messages appear in the output-file (\verb!.mt! file) +and also in the log-file (\verb!.mlg! file). + + +\subsection{Output-file} + + A line containing an error is prefixed by \texttt{***}; +the associated error-message appears on the next line and is +prefixed by dots (\texttt{...}). +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 are +where the {\mathsPIC} commands are written incorrectly (e.g.\ +missing bracket). + A typical example might be in a \texttt{draw} command if +a point has not been previously defined +resulting in a `point-name' error as follows. + + +\begin{verbatim} +%% *** drawTriangle(T1T6T3) +%% ... ?syntax error: point T6 is not defined +\end{verbatim} + + +If the maximum point/variable allocation (default is 50) +is exceeded, then a so-called +`fatal error' arises and the program terminates. +In the following example, a fatal error occured while +the program was trying to define a new point $Z_3$. + +\begin{verbatim} +%% *** point(Z3){P,shift(2,5)} +%% ... FATAL ERROR: points used exceed allocation +%% ... use the PointNumber() command to increase allocation +\end{verbatim} + + +Some other examples of error-messages are as follows. + + +\begin{verbatim} +%% *** point(a2{5,6} +%% ... syntax error: extra or missing () +%% +%% *** point(B2){A,shift(,6)} +%% ... syntax error: missing X coordinate in shift() +%% +%% *** point(z2){} +%% ... runtime error: ?syntax error +%% +%% *** pointt(z4){2,3} +%% ... ?syntax error: statement not recognised +%% +%% *** drawLine(AB) +%% ... ?syntax error: points A and B are the same +%% +%% *** variable(d){j, advance(4)} +%% ... ?syntax error: j is a Point not a Variable + +\end{verbatim} + + +\subsection{Log-file} +{\mathsPIC} outputs a log-file (\verb!.mlg! file) +which contains details of all errors, relevant line numbers +and file names (e.g.\ $<$myfile.m$>$). +The format was designed to match that of a standard \TeX\ log-file +in order to be compatible with commonly used +error-checking utilities. +Part of a typical log-file is as follows. + +\begin{verbatim} +mathsPIC log-file = myfile.mlg +mathsPIC input-file = myfile.m +mathsPIC output-file = myfile.mt + +! syntax error: extra or missing () bracket +l.9 point(A{10,5} +<myfile.m> + +! ?syntax error: point A is not defined +l.13 drawpoint(ABC) +<myfile.m> + +! syntax error: point A is not defined +l.22 point(P){A,shift(5,0)} +<myfile.m> + +! start of inputfile <newfile.dat> + +! syntax error: point X is not defined +l.7 point(Q){X,shift(5,0)} +<newfile.dat> +... +... +\end{verbatim} + + +%%----------------------- +\section{Commands} + +\subsection{\MathsPIC\ commands} +Although {\mathsPIC} commands are \textit{not} case sensitive, +it is recommended (to avoid confusion) that +points are represented using upper case +letters, and variables are represented using lower case +letters. + +The parameters of {\mathsPIC} commands are either strings +(any legitimate {\TeX} or {\LaTeX} commands or characters which +are suitable for an \verb!\hbox! are allowed), +point-names (e.g.\ A,B,C), or scalar quantities. +Where appropriate, {\MathsPIC} allows scalar quantities in +commands to be represented by either a +numeric value (e.g.\ 0.432, or 4.32E-1 ), +a variable name (e.g.\ r2), or the Pythagorean distance between +two points (e.g.\ $AB$). + For example, the structure of a + \texttt{DrawCircle(\textit{center,radius})} command is + quite flexible, as follows. + +\begin{verbatim} +drawCircle(C,4.32) +drawCircle(C,3.6E-1) +drawCircle(C,r2) +drawcircle(C,AB) +\end{verbatim} + +The various parameters which control the thickness of lines, +arrows and curves drawn by {\PiCTeX} are described in +Section~4.6.1. + + +%----------------------------- +\begin{itemize} +%----------------------------- +\item \framebox{\texttt{$\backslash$...}\ } \hspace{5mm} + \framebox{\texttt{$\backslash$\gap...}\ } + +A line having a \textit{leading} backslash is processed (copied +verbatim) slightly differently depending on whether the character +following the backslash is a space or not. + +A leading backslash \textit{followed by a non-space character} +tells {\mathsPIC} to copy the +whole line verbatim (\textit{including} the backslash) through to the +output-file (thus a line leading with the {\LaTeX} command +\verb!\begin{document}! will be copied unchanged). + +However, a leading backslash \textit{followed by one +or more spaces}, (e.g.\ \texttt{$\backslash$\gap\ldots}) + tells {\mathsPIC} to copy the rest of the line +verbatim through to the output-file, but \textit{without} the +leading backslash. + + +%------------------------- +\item \framebox{\tt Arrowshape(\textit{L, B, C})} + +This command defines the shape of an arrowhead, and allows +different arrowheads to be customised (see Section~7.3 for details). +The default arrow shape is equivalent to the +command \verb!Arrowshape(2,30,40)!. +This default arrowhead shape can be reset using +\verb!default! as the argument, as shown in the following example. + + +\begin{verbatim} +Arrowshape(4,30,60) +drawArrow(AB) +ArrowShape(default) +\end{verbatim} + + + + +%----------------------------- +\item \framebox{\tt DrawAngleArc{\{}angle(), radius(), internal, clockwise{\}}} + +This command draws an arc in the specified angle, a distance +\textit{radius} from the angle. The angle is either +\textit{internal} ($\leq 180^{\circ}$) or +\textit{external} ($\geq 180^{\circ}$). +The direction of the arc is +either \textit{clockwise} or \textit{anticlockwise}, and this +direction must correspond with the letter sequence specified +for the angle. +Strange and unexpected results will be produced if +the four parameters are not internally consistent. + + +For example, the following command draws a clockwise arc, +radius 3 units, in the external angle $ABC$, from line $AB$ +to line $BC$. + + + +\begin{verbatim} +DrawAngleArc{angle(ABC), radius(3), external, clockwise} +\end{verbatim} + +%---------- +\item \framebox{\tt DrawAngleArrow{\{}angle(), radius(), internal, clockwise{\}}} + +This command draws an arrow in the specified angle, a distance +\textit{radius} from the angle. The angle is either +\textit{internal} ($\leq 180^{\circ}$) or +\textit{external} ($\geq 180^{\circ}$). +The direction of the arrow is +either \textit{clockwise} or \textit{anticlockwise}, and this +direction must correspond with the letter sequence specified +for the angle. +Strange and unexpected results will be produced if +the four parameters are not internally consistent. +The arrow shape for the angleArrow is currently fixed, +and cannot be changed using the \verb!ArrowShape! command for +straight arrows (the author is happy to make this more flexible +if necessary). + + +For example, the following command draws a clockwise arrow, +radius 3 units, in the internal angle $ABC$ from line $AB$ +to line $BC$. + + + +\begin{verbatim} +drawAngleArrow{angle(ABC), radius(3), internal, clockwise} +\end{verbatim} + + + +%------------------------- +\item \framebox{\tt drawArrow(\textit{AB})} \hspace{5mm} + \framebox{\tt drawArrow(\textit{AB})[d]} \hspace{5mm} + \framebox{\tt drawThickarrow(\textit{AB,CD,FG, ...})} + +These commands draw arrows (or thick arrows) joining +two points. +The direction of the arrow is in the point order specified. +The shape of the arrowhead is controlled by the +\verb!ArrowShape! command (see Section~7.3). +Parameters which control line-thickness +are described in Section~4.6.1 + + +\begin{verbatim} +drawArrow(AB) +drawArrow(FG, HJ) +drawThickarrow(BC) +drawThickarrow(PQ, RS) +\end{verbatim} + + +An arrow can also be drawn a specified distance from one point +towards another point, using a square-bracket option. For +example, the following command draws an arrow a distance $d$ +units from point $A$ towards point $B$. + + +\begin{verbatim} +drawArrow(AB)[d] +\end{verbatim} + + +%----------------------------- +\item \framebox{\tt DrawCircle(\textit{center, radius})} + +This command draws a circle defined by its radius and the +point-name of its centre. The radius argument can be either a +decimal, a variable, or the Pythagorean length of a line (e.g.\ AB). +The following example draws a circle centre $C_2$, and radius 5 +units. + + +\begin{verbatim} +drawCircle(C2,5) +\end{verbatim} + + +In the following example, the radius argument +is the variable \verb!r2!. + + +\begin{verbatim} +drawCircle(C2,r2) +\end{verbatim} + + + +In the following example, the radius argument +is the Pythagorean length of the line $AB$. + + +\begin{verbatim} +drawCircle(C2,AB) +\end{verbatim} + + +Note that \PiCTeX\ draws circles with the +\verb!\circulararc! command, using a radius +equivalent to the distance from the center to the point at +which it starts drawing the arc. +Consequently, if the units of the $x$ and $y$ axes are +different, circles may be drawn strangely. {\MathsPIC} +therefore generates a message to this effect in the output-file + if different units are selected for the two axes in the +\verb!units! command (see Section~4.3.2). + + +%----------------------------- +\item \framebox{\tt DrawCircumcircle($ABC$)} + +This command draws the circumcircle of the triangle defined +by the points A, B, C. + + +%----------------------------- +\item \framebox{\tt DrawCurve(\textit{ABC})} + +This command draws a smooth quadratic curve through three points +$A,B,C$ in the point order specified. +At present it uses the {\PiCTeX} \verb!\plot! command, and +so it is only recommended for three points (for more than +three points the resulting curve is unlikely to be `smooth'). +This command will be upgraded in the next version to give a smooth +curve for more than three points. + + +Note that curves drawn using this command + do \textit{not} break to +avoid line-free zones associated with + the points (the \verb!drawLine! command for straight lines +\textit{does} acknowledge line-free zones). + +%----------------------------- +\item \framebox{\tt DrawExcircle($ABC$, $AB$)[${\delta}r$]} + + +This command draws the excircle touching side $AB$ of the +triangle $ABC$. +The optional argument [${\delta}r$] is a fine adjustment +to the radius of the excircle circle to facilitate drawing +the figure in certain circumstances. + + +In the following two examples, the first draws the true +excircle, while the second draws the excircle with its +radius reduced by 0.2 units. + + +\begin{verbatim} +drawExcircle(T1T2T3, T1T2) +drawExcircle(T1T2T3, T1T2)[-0.2] +\end{verbatim} + + +%----------------------------- +\item \framebox{\tt DrawIncircle($ABC$)[${\delta}r$]} + +This command draws the incircle of a triangle. +The optional argument [${\delta}r$] is a fine adjustment +to the radius of the incircle circle to facilitate drawing the figure. + +In the following two examples, the first draws the true +incircle, while the second draws the incircle with its +radius reduced by 0.2 units. + +\begin{verbatim} +drawIncircle(T1T2T3) +drawIncircle(T1T2T3)[-0.2] +\end{verbatim} + + + +%------------------------- +\item \framebox{\tt drawline(\textit{ABCD...})} \hspace{5mm} + \framebox{\tt drawline(\textit{AB})[6]} \hspace{5mm} + \framebox{\tt drawline(\textit{AB,CD,EFG, ...})} + + +\framebox{\tt drawline*(\textit{ABCD...})} + +This command draws a line joining +two or more points. +Lines are drawn in the order specified. +Lines are not drawn within line-free zones of points. + +Parameters which control line-thickness +are described in Section~4.6.1. + +\begin{verbatim} +drawline(AB) +drawline(BCDE) +drawline(FG, HJK, PQRST) +\end{verbatim} + + +A line can also be drawn a specified distance from one point +towards another point, using a square-bracket option. For +example, the following command draws a line a distance $d$ +units from point $A$ towards point $B$. + + +\begin{verbatim} +drawline(AB)[d] +\end{verbatim} + +Note that some restrictions are associated with the square +bracket option: (a) it can only be used when +drawing a \textit{single} line; (b) a line-free zone associated with the +second point will be ignored, (c) the order of the points $AB$ is +important---the line is drawn from the first point +\textit{towards} the second point (see Figure~11). + +Note that the \verb!drawline! command uses the {\PiCTeX} +\verb!\putrule! +command for horizontal and vertical lines, and the \verb!\plot! +command for all other lines. +However, the use of the \verb!\putrule! command is disabled +when using the {\mathsPIC} \verb!drawline*! command, which uses only +the \verb!\plot! command for all lines. +Since the \verb!\plot! command should be used when using +larger than normal dots (\verb!\setdots!) for horizontal or +vertical lines, then this is achieved with the \verb!drawline*! +command. + + + +%----------------------------- +\item \framebox{\tt DrawPerpendicular(\textit{point,line})[foot]} + + +This command draws the perpendicular from \textit{point} to +the \textit{line}. + If the option [foot] is specified, +then this command also draws the current \verb!pointsymbol()! +character (default point-symbol is \verb!$\bullet$!) + at the point where the perpendicular joins the line. +The following example draws the perpendicular from the + point $P$ to the line $AB$. + + + +\begin{verbatim} +drawPerpendicular(P,AB) +\end{verbatim} + + + +%-------------------------- +\item \framebox{\tt drawpoint(\textit{name})} \hspace{5mm} + \framebox{\tt drawpoint(\textit{name1 name2 ... })} + + +This command draws the point-symbol at the point-location. +Commas must not be used to separate points. + The default point-symbol is \verb!$\bullet$!, unless +an optional point-symbol (or string of characters) was +specified in the associated +\verb!point! command. If the \verb![circle]! option was used +with the \verb!point! command \textit{without} a radius parameter, +then the \verb!$\circ$! symbol will be used (see +the \verb!point! command). + + +\begin{verbatim} +drawpoint(T4) +drawpoint(ABCDEF) +drawpoint(P1 P2 P3 P4) +\end{verbatim} + + +%----------------------------- +\item \framebox{\tt DrawRightangle(\textit{angle,symbolsize})} + + +This command draws the standard right-angle symbol in the +internal angle specified. + The following example draws a right-angle symbol (side +3 units) in the internal angle ABC. + + +\begin{verbatim} +drawRightangle(ABC,3) +\end{verbatim} + +%------------------------- +\item \framebox{\tt drawThickline(\textit{ABCD...})} \hspace{5mm} + \framebox{\tt drawThickline(\textit{AB})[d]} \hspace{5mm} + \framebox{\tt drawThickline(\textit{AB,CD,EFG, ...})} + +This command draws a thick line joining +two or more points in the point-order specified. +Lines are not draw within line-free zones associated with points. + +Parameters which control line-thickness +are described in Section~4.6.1. + +\begin{verbatim} +drawThickline(AB) +drawThickline(BCDE) +drawThickline(FG, HIJ) +\end{verbatim} + + +An arrow can also be drawn a specified distance from one point +towards another point, using a square-bracket option. For +example, the following command draws an arrow a distance $d$ +units from point $A$ towards point$B$. + + +\begin{verbatim} +drawThickArrow(AB)[d] +\end{verbatim} + + + %----------------------------- +\item \framebox{\tt DrawTriangle($ABC$)} + +This command draws the triangle defined by the points $A, B, C$. +Note that \verb!drawTriangle(ABC)! is equivalent to \verb!drawLine(ABCA)!. +The \verb!drawTriangle! command checks +that the area is not zero, and generates an error-message if it +is (note that this area check +is \textit{not} made when using the equivalent +\verb!drawLine(ABCA)! command to draw a triangle). + + +%----------------------------- +\item \framebox{\tt inputFile($mathspic.doc$)[$loop$]} {\hspace{5mm}} + \framebox{\tt inputFile*($pictex.doc$)} + +The \verb!inputFile! command inputs a plain text file +containing {\mathsPIC} commands. Optionally, the file can be input +[\textit{loop}] times, in which case this command functions like a +DO--LOOP. +For example, the following command inputs the file +\verb!newfile.dat! 4 times in succession. + +\begin{verbatim} +inputFile(newfile.dat)[4] +\end{verbatim} + +The \verb!inputfile*! command is used to input a file in +\textit{verbatim}, +i.e.\ a file with \textit{no} {\mathsPIC} commands. For example, a file +containing only \PiCTeX\ commands or data-points +for plotting etc. A typical example might be the following file +(curve-A.dat) which would be input verbatim +using the command \verb!inputfile*(curve-A.dat)!. + +\begin{verbatim} +%% curve-A.dat +\setquadratic +\plot 0 0 + 3.56 4.87 + 8.45 9.45 + 5 7 + 2.34 3.23 / +\setlinear +\end{verbatim} + +Note that the \verb!inputfile*! command has no +[$loop$] option. + +%-------------------------- +\item +\framebox{\tt paper{\{}units(\ ),xrange(\ ),yrange(\ ),axes(\ ),ticks(\ ){\}}} + +\smallskip + +\texttt{units({\it unit})}\ \ or\ \ \texttt{units({\it xunit,yunit})} + +\texttt{xrange({\it xlow,xhigh})} + +\texttt{yrange({\it ylow,yhigh})} + +\texttt{axes({\it XYLRTB})} + +\texttt{ticks({\it x,y})} + + +The \verb!paper{..}! command defines a plot area with +optional axes and tick-marks (see Section~4.3.1). + +For example, the following statement sets up a rectangular drawing area +50mm x 50mm with axes on the \verb!L!eft (y-axis) and \verb!B!ottom +(x-axis), and tick marks at 10mm intervals. + + +\begin{verbatim} +paper{units(mm),xrange(0,50),yrange(0,50),axes(LB),ticks(10,10)} +\end{verbatim} + + +All combinations of the axis-codes (XYLRTB) are allowed, and a * +following an axis-code (e.g.\ L*) stops ticks being drawn on +the specified axis. + +If it is necessary to have \emph{different} unit scales +for the $x$ and $y$ +axes, say 1 cm and 2 mm respectively, then this is implemented +by \verb!units(1cm,2mm)!, or \verb!units(cm,2mm)!. If there is +no digit associated with a unit (e.g.\ mm), then {\mathsPIC} +actions the command as \verb!1mm!. +If only a single unit is specified (e.g.\ \verb!units(cm)!) +then {\mathsPIC} automatically makes this the unit scale for +\textit{both} axes. +If the \verb!unit! option is omitted {\PiCTeX} will use +the last defined units (within the same picture environment), +the default units being \textit{xunit}=1pt and \textit{yunit}=1pt +(see the {\PiCTeX} Manual, page~3; Wichura, 1992). + + + +%----------------------- +\item \framebox{\tt +point(\textit{name}){\{}...{\}}[\textit{symbol, linefree radius}]} + + +\framebox{\tt +point*(\textit{name}){\{}...{\}}[\textit{symbol, linefree radius}]} + + +The \verb!point! command is used to define points. + Note that a point-name \textit{must} begin +with a \textit{single} letter (either upper or lower case), +and may have up to a \textit{maximum} of two following digits. + +The default point-symbol is the \verb!$\bullet$!. +An optional alternative point-symbol (or string of characters) +can be specified within square +brackets e.g.\ \verb![$\triangle$]! (see Section~4.4). + +By default lines are drawn to the point location. However, the +radius of an optional line-free zone can be specified within an +optional square bracket e.g.\ \verb![$\triangle$,4]! +(see Section~4.4). +If a line-free radius is specified without a point-symbol, then +the preceding comma must still be included; for example +\verb![,5]!. + +An optional `{\verb!circle!}' can also be used +as the \textit{symbol}. If a radius value is also +included, e.g.\ \verb![circle, 5]! then +a circle will be drawn having the specified radius (the radius +value will also be assumed to be the line-free radius). +If no radius value is specified, +e.g.\ \verb![circle]!, then the +small circle symbol (\verb!$\circ$!) is used instead (and +line-free radius set to zero). + + +Points can also be defined relative to \emph{previously defined} +points. For example, as the intersection +of two existing lines, or as a $+$ve or $-$ve extension (in the +direction indicated by the letters) between two previously +defined points, etc. + +The \verb!point*! command re-allocates new parameters (e.g.\ +coordinates, point-symbol, or line-free radius) +to a previously defined point-name. + +Some examples of valid point commands are as follows. + + +\begin{verbatim} +point(A){5,5} +point(B2){22,46}[circle] +point(B2){22,46}[circle,5] +point(C32){3,8}[$\Box$] +point(D1){20,2}[$\Box$,4] +point(D10){20,5}[,4] +point(D2){B2, shift(5,5)} +point(D3){D2, polar(6,32 deg)} +point(D4){D2, polar(6,1.2 rad)} +point(D2){intersection(AB,CD)} +point(F){PointOnLine(AB,5.3)} +point(G){perpendicular(P,AB)} +point(G2){Q, rotate(P, 23 deg)} +point(H){circumcircleCenter(ABC)} +point(J){incircleCenter(ABC)} +point(K){excircleCenter(ABC,BC)} +point*(A){6,3} +point*(B){B, shift(5,0)} +point*(C){C}[,6] +\end{verbatim} + + +%-------------------------- +\item \framebox{\tt PointNumber(n)} + +This command allows the array space +used for holding the total number of points and variables +(combined) to be increased (or decreased). + This statement must therefore be placed before +any \verb!point! statements, and so is best used right at +the beginning of the {\mathsPIC} file. +The default number is set at 50 points. + + +\begin{verbatim} +PointNumber(55) +\end{verbatim} + + +If the total number of points and variables combined exceeds +the allocated number then +a `fatal error' is triggered, and the program terminates (see +Section~4.4.5). + + + +%-------------------------- +\item \framebox{\tt PointSymbol(\textit{symbol, linefree radius})} + +This command allows the default point-symbol (\verb!$\bullet$!, +line-free radius zero) to be changed. +The syntax of this command mirrors exactly that of the +square-bracket option associated with the \texttt{point} command. +The PointSymbol command is particularly useful where a set of +points uses the same point-symbol (Figure~16), and also +when drawing graphs (Figure~15). + + +For example, the following command changes the +point-symbol to $\odot$ (\verb!$\odot$!) +having a line-free radius of 0.7 units. + +\begin{verbatim} +PointSymbol($\odot$, 0.7) +\end{verbatim} + +Note that the \verb!PointSymbol! command only influences +subsequent \verb!point! commands. +For example, the following commands will make points $A$ and $B$ +be drawn as circles having radius of 5 units. + +\begin{verbatim} +variable(r){5} +PointSymbol(circle,r) +point(A){5,5} +point(B){10,12} +\end{verbatim} + +Note that the optional square bracket of the \verb!point! command +overrides the PointSymbol command. +The point-symbol can be reset to the default $\bullet$ +(\verb!$\bullet$!) using the command \verb!PointSymbol(default)!. + + +%%-------- +\item \framebox{\tt show ...} + +This command forces {\mathsPIC} to + return the value of a calculation or specified parameter; for + example, the value of a particular angle, or the length of a line. +The result is shown in the output-file as a commented line. + This allows {\mathsPIC} commands to be + adjusted in the light of calculations. + +\begin{verbatim} +show(B) %% for both Points and Variables +show(r) %% for both Points and Variables +showLength(AB) +showIntersection(AB,CD) +showAngle(ABC) +showArea(ABC) +\end{verbatim} + +When the above examples are processed, the results appear +as commented lines in the output-file as follows. + +\begin{verbatim} +%% show(B) Point (22.12432, 18.96723) +%% show(r) Variable (8.25367) +%% showLength(AB) 25.35746 +%% showIntersection(AB,CD) (15.13245, 22.74723) +%% showAngle(ABC) 39.35746 degrees (0.68691 radians) +%% showArea(ABC) 54.54267 +\end{verbatim} + + +%-------------------------- +\item \framebox{\tt text({\it string}){\{}{\it x,y}{\}}[{\it position}]} + +\framebox{\tt text({\it string}){\{}{\it pointname, + adjustment}{\}}[{\it position}]} + +\smallskip +where the \textit{adjustment} option is either {\tt shift($dx$,$dy$)} +or {\tt polar($r$,$\theta$)}. + +This command puts the given text-string either at the named +point, or with a displacement specified by the +optional \texttt{shift($dx$,$dy$)} or +\texttt{polar($r$,$\theta$)} parameters. +By default the text is centered vertically and +horizontally at the specified point. + + Optionally, text can be placed relative to a +point using appropriate combinations of the + {\PiCTeX} \textit{position} 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 +respectively of the text box with the point-location +(see the {\PiCTeX} Manual, page~5; Wichura, 1992). + For example, the text box \framebox{\texttt{This is point P}} + would be aligned such that the right edge of the text box would be +centered vertically at the point $P$, +using \verb!text(This is point P){P}[r]!. + +The \verb!text! command can be used to label points, or to simply +position text in a diagram, as shown in the following examples. + +\begin{verbatim} +text(A){5,6} +text($A_1$){A1, shift(2, 2)} +text($Z2$){Z2, shift(5, -5)}[tr] +text($Z3$){Z2, polar(5, 20 deg)}[Br] +text($Z4$){Z2, polar(5, 1.34 rad)} +text(\framebox{$Z5$}){Z3} +\end{verbatim} + + +%----------------------- +\item +\framebox{\tt variable(\textit{name}){\{}\textit{value}{\}}} + +\framebox{\tt variable*(\textit{name}){\{}\textit{value}{\}}} + + +The \verb!variable! command is used to define scalar variables +(see Section~4.5). + Note that a variable-name \textit{must} begin +with a \textit{single} letter (either upper or lower case), +and may have up to a \textit{maximum} of two following digits. +Variables and points have the same name structure, and a +variable cannot have the same name as a point. +The scalar argument in the braces can be either a numeric value, + another variable, or two points (implying the distance +between the two points). + +New values can be re-allocated to existing variable-names using +the equivalent \verb!variable*! command; thus the variable +\verb!r3! can be re-allocated the value 15 using the command +\verb!variable*(r3){15}! (if the variable-name has not been used +before then {\mathsPIC} will generate an error message). + +Variables can be manipulated using the commands +\verb!advance!, \verb!multiply!, \verb!divide! and \verb!mod!. + + +The following are examples of valid \verb!variable! commands. + +\begin{verbatim} +variable(r3){20} +variable(z3){3.46E-2} +variable(r4){r1} +variable(r5){AB} +variable*(r5){6} +variable(x1){w, advance(-6)} +variable(x2){w2, divide(-p)} +variable(x3){AB, multiply(2)} +variable*(x1){x1, mod(3)} +variable(g){angle(ABC)} +variable(g2){area(ABC)} +variable(x3){Xpoint(P3)} % gets the x-coordinate of a point +variable(y3){Ypoint(P3)} % gets the y-coordinate of a point +variable(p1){3.14159} % use p1 to represent Pi +variable(e){2.71828} +\end{verbatim} + + +\end{itemize} +%----------------------------- + + +\subsection{Summary of \mathsPIC\ commands} + +The following list shows the format and typical usage +of all {\mathsPIC} commands. +Although {\mathsPIC} commands are \textit{not} case sensitive, +in this summary of commands points are represented using upper case +letters, and variables are represented using lower case +letters. Note that a leading +\texttt{$\backslash$\gap} is used for copying \TeX\ or \PiCTeX\ +lines verbatim, for example with macros or coordinates of data +points etc. + +\begin{verbatim} +\ 4.5 6.3 +\setdashes +\typeout{drawing circle C2 now}% +arrowShape(4,30,40) +arrowShape(default) +drawAngleArc{angle(ABC), radius(3), internal, clockwise} +drawAngleArrow{angle(ABC), radius(3), internal, clockwise} +drawArrow(AB) +drawArrow(AB)[d] %% draw arrow distance d from A towards B +drawArrow(AB,CD) +drawCircle(J,12) +drawCircle(C,r2) +drawCircle(C,AB) %% the radius is length of line AB +drawCircumcircle(ABC) +drawCurve(ABC) %% best for only three points +drawExcircle(ABC)[-0.2] +drawIncircle(ABC)[-0.3] +drawLine(AB) +drawline*(AB, CDEF) %% the * option disables use of \putrule +drawLine(AB)[d] %% draw line distance d from A towards B +drawLine(ABCDE) +drawPerpendicular(P,AB) +drawPerpendicular(P,AB)[foot] %% draws pointSymbol at the foot +drawPoint(B) +drawPoint(ABP1P2) +drawRightAngle(ABC, 4) +drawThickArrow(AB) +drawThickArrow(AB)[d] %% draw thickarrow distance d from A towards B +drawThickArrow(AB,CD) +drawThickLine(PQ) +drawThickLine(RS,TU) +drawTriangle(ABC) +inputFile(mathspic.dat) +inputFile(mathspic.dat)[4] +inputfile*(fig2.dat) %% disables mathsPIC processing of file +paper{units(1mm,3mm),xrange(-5,50),yrange(-5,50),axes(LR)} +paper{units(cm),xrange(0,5),yrange(0,9),axes(X*Y),ticks(1,1)} +point(D1){20,2} +point(D4){6.3,8.9534E-1} +point(P){x1,y1} +point(P){AB,PQ} +point(D2){20,2}[circle] +point(D3){20,3}[circle,5] +point(D4){20,4}[$\Box$,4] +point(D5){20,7}[,4] %% set the line-free radius +point(E1){D1, shift(5,6)}[$\Box$] +point(E5){D1, shift(r2,6)} +point(E2){D2, polar(8,45)} %% deg is the default +point(E2){D2, polar(8,45 deg)} +point(E6){D2, polar(r4,45 deg)} +point(E5){D2, polar(AB,45 deg)}[,5] +point(D32){midpoint(AB)} +point(D2){intersection(AB,CD)} +point(F){PointOnLine(AB,5.3)} +point(G){perpendicular(P,AB)} +point(G){perpendicular(P,AB)} +point(G2){Q, rotate(P, 23 deg)} %% rotate Q about P by 23 deg +point(H){circumcircleCenter(ABC)} +point(J){incircleCenter(ABC)} +point(K){excircleCenter(ABC,BC)} +point*(D1){20,3} +point*(E1){D1, shift(3,0)} +point*(E1){E1}[,6] %% change the line-free radius +pointNumber(67) %% default is 50 points +pointSymbol($\odot$) +pointSymbol($\odot$,3) +pointSymbol(,4) +pointSymbol(default) +show(P3) +show(m) +showAngle(ABC) +showArea(ABC) +showIntersection(AB,CD) +showLength(AB) +text(P){5,7} +text($A$){A} +text($K$){K}[r] +text($B$){B, shift(5,5)} +text(\framebox{$C$}){C, polar(5,62 deg)}[Br] +variable(r1){15} +variable(z3){4.875E-2} +variable(d){AB} +variable(d2){d1} +variable(x1){w, advance(6)} +variable(x1){w, advance(-23.55)} +variable(x2){w2, divide(-p)} +variable(x3){AB, multiply(2)} +variable(g){angle(ABC)} +variable(g2){area(ABC)} +variable(x3{Xpoint(P3)} % gets the x-coordinate of a point +variable(y3){Ypoint(P3)} % gets the y-coordinate of a point +variable(p1){3.14159} % use p1 to represent Pi +variable(e){2.71828} +variable*(r1){20} +variable*(x1){x1, mod(3)} +\end{verbatim} + + +Note that the old \verb!latex{...}! \verb!pictex{...}! and +\verb!tex{...}! `wrapper' commands (for copying their argument +unchanged into the output file) have been superseded by the +more convenient +\texttt{$\backslash$} and \texttt{$\backslash$\gap} commands, +but are still available to allow downwards +compatibility with earlier versions of {\mathsPIC}. + + +\subsection{Useful \PiCTeX\ commands} + + The following is a 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. + Note that there is a section on {\PiCTeX} in Alan +Hoenig's recent book \textsl{\TeX\ Unbound}\footnote{Hoenig A +(1998). \textsl{\TeX\ Unbound: \LaTeX\ and \TeX\ strategies for fonts, +graphics, \& more.} (Oxford University Press, UK) pp 580. +\textsc{isbn}: 0-19-509685-1 (hardback), 0-19-509686-X +(paperback); see pages 377--389.} + which also includes a brief list of commands. + Note that where small angle brackets are shown (e.g.\ \verb!<!) then + these must be used exactly as shown. + + +\begin{verbatim} +\grid {cols} {rows} %% eg \grid {5} {10} +\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 curve} +\headingtoplotskip=1cm %% separation between plotheading and 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 30 5 %% corners at Top-left Bottom-right +\inboundscheckon %% restricts plotting to plotting area +\inboundscheckoff %% +\normalgraphs %% restores default values for graph parameters +\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, ie a:b) +\end{verbatim} + +Note that {\PiCTeX} also has an excellent rotation facility. +{\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 the 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} + +A {\PiCTeX} error-bar facility is also available by loading +the file \verb!errorbar.tex! (see Section~9.4). +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~9.5), and are +currently outside the scope of {\mathsPIC}. + +%%--------------------------- +\section{Examples} + +This section describes some practical examples of figures drawn +using {\mathsPIC}, together with the associated code. +A collection of more complicated examples +can be found in the the companion document \verb!examples.tex! +which is included in the {\mathsPIC} package. + +When drawing a new figure or diagram, the author finds it best +to start with a graduated coordinate frame (see Figure~1) 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. +Finally (if the frame is not required), the frame should +be moved close to the edge of the figure +by adjusting the \verb!xrange! and \verb!yrange! parameters, in +order to remove unnecessary surrounding white space, after which the +the \verb!axes! and \verb!ticks! options of the +\verb!paper! command can be removed, ready for inserting into +the document. The code can then be either pasted into the +document directly, or kept as a separate file and then +\verb!\input! as required. + +As regards scales and units, the author finds it most +convenient to use the mm units and to keep the $x$ and $y$ scales +the same whenever possible (i.e.\ use \verb!paper{units(mm)...}!), +since this allows easy scaling up and down after the figure has +been finished (see Section~4.3.2 for details regarding the use of +variables to control the units). + +The appropriate \LaTeX\ commands to \verb!\input! the file and +position the graphic on the page are described in Section~8. + + + +%----- +\subsection{Input- and output-files} + +The following example {\mathsPIC} file (input-file) +illustrates how some of these commands are used +to draw Figure~4. Note that the dashed line $AD$ 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 +(Section~4.4.3). + +\bigskip + +%%------------Figure 4----------------- +%% the triangle +%% testing importing a small fig (works OK) + \begin{figure}[hbt] + \begin{center} + %\framebox{ + \strut\vbox{ + %% triangle + \input{mPICm04.pic} + } + % } + \caption{\ } + \end{center} +\end{figure} +%----------------------- + +\begin{verbatim} +% mPICm04.m (Figure 4) +\documentclass[a4paper]{article} +\usepackage{pictexwd} +\begin{document} +%------------------- +\beginpicture +\setdashes +paper{units(mm),xrange(0,70),yrange(0,50),axes(LRTB),ticks(10,10)} +\setsolid +point(A){10,10}[$\odot$,1.2] %% anchor point +point(B){A, polar(40, 50 deg)}[$\odot$,1.2] +point(C){A, polar(50, 10 deg)}[$\odot$,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) +\endpicture +%------------------ +\end{document} +\end{verbatim} + + +When the above 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 added (e.g.\ the +coordinates of a derived point---see the +line \verb!%% point(D)...!\ ). +Being able to compare the {\mathsPIC} and resulting {\PiCTeX} +commands in the output-file is particularly useful when +debugging. +Note also how the \texttt{show} commands +return the lengths AD, BC, and the area ABC. + +\begin{verbatim} +% mPICm04.m (Figure 4) +\documentclass[a4paper]{article} +\usepackage{pictexwd} +\begin{document} +%------------------- +\beginpicture +%% paper{units(mm),xrange(0,70),yrange(0,50),axes(LB),ticks(10,10)} +\setcoordinatesystem units <1mm, 1mm> +\setplotarea x from 0 to 70, y from 0 to 50 +\axis left ticks numbered from 0 to 50 by 10 / +\axis bottom ticks numbered from 0 to 70 by 10 / +%% point(A){10,10}[$\odot$,1.2] ( 10 , 10 ) %% anchor point +%% point(B){A,polar(40,50deg)}[$\odot$,1.2] ( 35.7115 , 40.64178 ) +%% point(C){A,polar(50,10deg)}[$\odot$,1.2] ( 59.24039 , 18.68241 ) +%% point(D){perpendicular(B,AC)} ( 40.17626 , 15.32089 ) +%% drawPoint(ABCD) +\put {$\odot$} at 10 10 %% A +\put {$\odot$} at 35.7115 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.94016 39.72252 / %% AB +\plot 36.58879 39.82301 58.3631 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.7115 44.64178 +%% text($A$){A,shift(-4,-2)} +\put {$A$} at 6 8 +%% text($C$){C,shift(4,-1)} +\put {$C$} at 63.24039 17.68241 +%% text($D$){D,shift(1,-4)} +\put {$D$} at 41.17626 11.32089 +%% showLength(BD) 25.7115 +%% showLength(AC) 50 +%% showArea(ABC) 642.7875 +\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 removing +all the \verb!%%! comment lines (using the +\textsc{clean.exe} utility---see Section~3.2), as well as +some of the header and footer lines which are not now required, +as follows. + +\begin{verbatim} +% mPICm04.pic (Figure 4) +%------------ +\beginpicture +\setcoordinatesystem units < 1mm, 1mm> +\setplotarea x from 0 to 70, y from 0 to 50 +\axis left ticks numbered from 0 to 50 by 10 / +\axis bottom ticks numbered from 0 to 70 by 10 / +\put {$\odot$} at 10 10 %% A +\put {$\odot$} at 35.7115 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.94016 39.72252 / %% AB +\plot 36.58879 39.82301 58.3631 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.7115 44.64178 +\put {$A$} at 6 8 +\put {$C$} at 63.24039 17.68241 +\put {$D$} at 41.17626 11.32089 +\endpicture +%---------- +\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 \textsc{clean.exe} utility only removes lines +having a leading \verb!%%! pair of characters, so comment lines +prefixed with only a single \verb!%! character will remain. + + +%--------------------- +\subsection{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! (see Section~6.3), +as in the following code for drawing the rectangular box +shown in Figure~5. + +The default \verb!\setdashes! gives alternating lines and +spaces, each of width 5pt. +More fancy dash-patterns (see Figure~5) can be easily generated using +the {\PiCTeX} \verb!\setdashpattern! command which defines +the pattern cycle, and hence takes an even number of +parameters. If a particular +dash-pattern is to be used several times in a figure, +then a defining macro may be useful, as follows. + +\begin{verbatim} +\def\fancydashes{\setdashpattern <6pt, 2pt, 1pt, 2pt>} +... +\fancydashes +\end{verbatim} + + +Note that in Figure~5 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 +\begin{center} + \strut\input{mPICm05.pic} + \caption{\ } +\end{center} +\end{figure} +%%---------------------- + +\begin{verbatim} +%% mPICm05.m (Figure 5) +\beginpicture +paper{units(mm), xrange(0,50), yrange(0,62)} +variable(s){20} % Sides front & back +variable(L){34} % Length +variable(a2){56.6} % Angle degrees +\def\fancydashes{\setdashpattern <6pt, 2pt, 1pt, 2pt>} +point(A){5,7} +point(B){A, polar(s,90)} +point(C){B, polar(s,0)} +point(D){A, polar(s,0 )} +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=0.4pt \fancydashes +drawline(AH, BG, CF, DE) +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{verbatim} + +%------------------ +\subsection{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 +standard {\PiCTeX} commands, +the {\mathsPIC} \texttt{Arrowshape} command makes this +easier by allowing you to define 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(2,30,40) +\end{verbatim} + + +%%--------BOX with arrow diagram----Figure 6---- + +\begin{figure}[hbt] +\begin{center} + \strut\input{mPICm06.pic} + \caption{\ } +\end{center} +\end{figure} +%%--------------------------------------- + + +If the arrowshape has been altered, it can be reset using the +command \verb!ArrowShape(default)!. + 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~7 and~8). + + +%% ? keep this next triangle fig & code together + +\begin{figure}[hbt] +\noindent +\begin{minipage}{4cm} +%----------------- +\begin{verbatim} +% mPICm07.m (Figure 7) +\beginpicture +paper{units(mm),xrange(5,45),yrange(5,45)} +point(A){30,30} +point(P){10,10} +point(B){30,10} +drawPoint(APB) +drawLine(APBA) +text($A$){A,shift(1,5)} +text($B$){B,shift(5,0)} +text($P$){P,shift(-5,0)} +drawAngleArrow{angle(BPA),radius(11),anticlockwise,internal} +text($\psi$){P,polar(7,22.5 deg)} +drawRightangle(ABP,2.5) +\endpicture +\end{verbatim} +\end{minipage} +%%----------- + \hspace{3cm} +%%----------- +\begin{minipage}{4cm} +%% arrow1 + \vspace{.1mm} + %% small triangle with angle arrow (arrow1) + \strut\input{mPICm07.pic} + \vspace{-12mm} %%to adjust the position of the caption%% + \caption{\ } + \vspace{2.5cm} +\end{minipage} +%---------- +\hfill +\end{figure} + + +Arrows can also be used to link elements in a diagram, + as shown in Figure~8. 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 \texttt{mpicm08b.m}). The arrows +are easily `stretched' to accommodate their labels + simply by adjusting the separation of the nodes using the + \texttt{polar($r$,$\theta$)} commands (cf.\ Feruglio, 1994). + + +\bigskip + +%%------------Figure 8----------------- +%% the plotting area +\begin{figure}[hbt] +\begin{center} +\noindent +%\framebox{ +\begin{minipage}{3cm} + \begin{center} + %\vspace{2cm} %% controls top space + \input{mPICm08a.pic} + %\vspace{5mm} %% controls space between pict and caption + a. Circular arrows + \end{center} +\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} + \begin{center} + %\vspace{3mm} %% controls top space + \input{mPICm08b.pic} + %\vspace{5mm} %% controls space between pict and caption + b. Straight arrows + \end{center} +\end{minipage} +%} % end of framebox +\caption{\hspace{7mm} } +\end{center} +\end{figure} +%----------------------- + + +\begin{verbatim} +%% mpicm08a.m (Figure 8a) +\beginpicture +paper{units(mm),xrange(10,40),yrange(0,45)} +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),clockwise,internal} +point(N1){N,shift(2,1)} +point(S1){S,shift(-2,1)} +point(Z1){Z,shift(0,-3)} +drawAngleArrow{angle(N1Z1S1),radius(N1Z1),clockwise,internal} +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),clockwise,internal} +\endpicture +\end{verbatim} + +\bigskip + +\begin{verbatim} +%% mpicm08b.m (Figure 8b) +\beginpicture +paper{units(mm),xrange(0,45),yrange(0,45)} +point(P){5,10}[$P$,5] +point(Q){P,polar(30,90 deg)}[$Q$,5] +point(R){Q,polar(40,0 deg)}[$R$,5] +point(T){P,polar(30,0 deg)}[$T$,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 macro for the label +\newcommand{\q}{$q \star q \star q \star q \star q$} +text(\q){Q1,shift(-1,3)} +\endpicture +\end{verbatim} + + +%%------------------- +\subsection{Circles} + +{\MathsPIC} allows the point-symbol to be designated as a +circle using the \verb![circle,r]! option 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~9. +This construction greatly simplifies the drawing of directed +graphs, trees and equivalent structures. + +\bigskip + +%-------------figure 9---------- +\begin{figure}[hbt] +\begin{center} + %% 4 circles + \strut\input{mPICm09.pic} + \caption{\ } +\end{center} +\end{figure} +%----------------------- + + +\begin{verbatim} +%% mPICm09.m (Figure 9) +\beginpicture +paper{units(mm),xrange(0,70),yrange(0,60)} +point(A){30,11}[circle,8] +point(B){A,shift(-10,30)}[circle,15] %% big circle +point(C){A,polar(30,20 deg)}[circle,5] +point(D){A,polar(45,50 deg)}[circle,7] +drawPoint(ABCD) +drawLine(AB,AC,BC,BD,CD) +\setdashes +drawLine(AD) +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{verbatim} + +Note that in this particular case it is necessary to define the +maths formula using \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~10. +Notice the use of the variable \verb!r! for the radius of the +circle (allocated using the command \verb!variable(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] +\begin{center} + %% circle and chord with two angles + \strut\input{mPICm10.pic} + \caption{\ } + \end{center} +\end{figure} +%%-------------------------- + +\begin{verbatim} +%% mPICm10.m (Figure 10) +\beginpicture +paper{units(mm), xrange(5,55), yrange(5,55)} +point(C){30,30}[$\odot$,1.2] %% center +variable(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) anticlockwise internal} +text($\beta$){C, polar(5,285 deg)} +drawAngleArrow{angle(PQS), radius(12) anticlockwise internal} +text($\alpha$){Q, polar(8,-65 deg)} +show angle(PQS) % alpha +show angle(PCS) % beta +\endpicture +\end{verbatim} + + + +Note that the returned values in the output-file +from the \texttt{showAngle} commands (see below) +for Figure~10 indicate that $\beta$ is twice $\alpha$, +as one would expect. + + +\begin{verbatim} +%% showAngle(PQS) 40 degrees / radians 0.6981316 % alpha +%% showAngle(PCS) 79.99999 degrees / radians 1.396263 % beta +\end{verbatim} + +%--------- + + +{\MathsPIC} offers a range of other circle commands +(\texttt{drawIncircle}, +\texttt{drawExcircle}, +\texttt{drawCircumcircle}), + specifically for geometry diagrams + (cf.\ Cameron, 1992), as shown in Figure~11. + +\bigskip + +%%--------------------------- +\begin{figure}[hbt] +\begin{center} +%% the incircles + \strut\input{mPICm11.pic} + \caption{\ } + \end{center} +\end{figure} +%%----------------------------- + + +\begin{verbatim} +%% mpicm11.m (Figure 11) +\beginpicture +\setdashes +paper{units(mm),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) +point(I){IncircleCenter(AJK)}[$\odot$] +point(E){ExcircleCenter(AJK,JK)}[$\odot$,1.2] +point(P1){perpendicular(E,AC)} +variable(r){EP1} %% radius of excircle +variable(d){72} %% angle of pentagon (deg) +variable(a1){-90} +variable(a2){a1, advance(d)} +variable(a3){a2, advance(d)} +variable(a4){a3, advance(d)} +variable(a5){a4, advance(d)} +point(P2){E, polar(r,a2)} +point(P3){E, polar(r,a3)} +point(P4){E, polar(r,a4)} +point(P5){E, polar(r,a5)} +drawPoint(ABCJKIEP1P2P3P4P5) +\setplotsymbol({\tiny .}) +\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} +variable(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)} +text($P_2$){P2,polar(s, a2)} +text($P_3$){P3,polar(s, a3)} +\endpicture +\end{verbatim} + + +%---------------------------------------- +\subsection{Functionally connected diagrams} + +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. +This is demonstrated in Figure~12, where 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] + \begin{center} + %% dynamic figure + \strut \input{mPICm12.pic} + \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{mPICm12.m}).} + \end{center} +\end{figure} +%----------------------- + +\begin{verbatim} +%% mPICm12.m (Figure 12) +\beginpicture +paper{units(mm),xrange(5,120),yrange(0,45)} +point(A){15,5}[$\odots$,1.2] +point(P){A,shift(10,30)}[$\odots$,1.2] +point(B){A,polar(45,60 deg)} +point(Q){perpendicular(P,AB)} % from P to line 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} +%% now draw vertical line and angle +point(N){A,shift(0,12)} +\setdashes +drawLine(AN) +\setsolid +drawAngleArrow{angle(NAB),radius(7),clockwise,internal} +\endpicture +\end{verbatim} + +Note that in Figure~12 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 line AB +in-line with the points PQ, using the command +\verb!point(S){pointOnLine(QP,-5)}!. + +%%------------------------------------------- +\subsection{Inputting files and recursion} + +{\mathsPIC} allows the recursive input of blocks of {\mathsPIC} +commands as files, using the \verb!inputfile! command. +In practice, this functions as a `DO--LOOP' in a +program. +For example, the file \texttt{myfile.dat} would be input six +times sequentially using the command +\verb!inputfile(myfile.dat)[6]!. + +\bigskip + +%%---------figure 13----------- +\begin{figure}[hbt] +\begin{center} + %% spiral + \strut\input{mPICm13.pic} + \caption{\ } +\end{center} +\end{figure} +%----------------------- + + Figure~13 was produced by the following +code which inputs a small file of {\mathsPIC} +code (\verb!mpicm13.dat!) recursively 30 times using the +command \verb!inputfile(mpicm13.dat)[30]!. +Note the use of the \verb!variable*! and \verb!point*! commands +and the \verb!advance! operator in order to +re-allocate variables and points recursively. + + +\begin{verbatim} +%% mpicm13.m (Figure 13) +%% spiral +\beginpicture +paper{units(mm), xrange(0,60), yrange(0,60)}% axes(LB), ticks(10,10)} +point(C){30,30} % circle center +drawcircle(C,25) +variable(a){315} % angle deg +variable(r){20} % radius of spiral +variable(s){5} % square, semi-diagonal +point(T){C,polar(r,330 deg)} +inputfile(mpicm13.dat)[30] +\endpicture + + %% mpicm13.dat (Figure 13) + %% spiral routine + variable*(r){r,advance(-0.5)} % let r = r - 0.5 + variable*(a){a,advance(15)} % let a = a + 15 deg + point*(P){C,polar(r,a deg)} + drawpoint(P) + drawline(TP) + point*(T){P} % let T = P + %% make a square centered on P + point*(Q1){P,polar(s,0)} + point*(Q2){P,polar(s,90)} + point*(Q3){P,polar(s,180)} + point*(Q4){P,polar(s,270)} + drawline(Q1Q2Q3Q4Q1) +\end{verbatim} + + +\subsubsection{Plotting graphs} + +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 (see Section~6). +For example, the following {\mathsPIC} code (\texttt{mpicm14.m}) +draws the quartic curve shown in Figure~14, by inputting +in \textit{verbatim} a datafile (\texttt{mpicm14.dat}) 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] +\begin{center} + %% quartic equation + \strut\input{mPICm14.pic} + \caption{\ } +\end{center} +\end{figure} +%----------------------- + +\begin{verbatim} +%% mpicm14.m (Figure 14) +\beginpicture +\linethickness=1pt %% use a thick line for the axes +paper{units(3cm,cm),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}} +inputfile*(mpicm14.dat) %% input file containing data points for curve +variable(r){0.3} %% define a line-free radius r = 0.3 +point(E1){1,3.5}[,r] +text($f(x)=6x^4 - 8x^3 + 1$){E1} % center the equation at E1 +point(E2){1.4,2}[,r] +drawArrow(E1E2) +point(J1){0.55,2}[,r] +text(inflection points){J1} %% center inflection text at J1 +point(J2){0,1}[,r] +point(J3){0.6,0}[,r] +drawArrow(J1J2,J1J3) +\endpicture +\end{verbatim} + + +The datafile for the curve is as follows. +Note 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).} + + +\begin{verbatim} +%% mpicm14.dat (Figure 14) +%% 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 + \end{verbatim} + + +However, when there are only a few data points, it is somtimes +more convenient just to plot the points separately and then +draw connecting lines, as shown in Figure~15. + + +\bigskip + +%%---------figure 15----------- +\begin{figure}[hbt] +\begin{center} + %% diet graph + \strut\input{mPICm15.pic} + \caption{\ } +\end{center} +\end{figure} +%----------------------- + +\begin{verbatim} +%% mpicm15.m (Figure 15) +\beginpicture +paper{units(cm),xrange(0,6),yrange(73,77),axes(LBT*R*),ticks(1,1)} +variable(r){0.2} %% line-free radius +pointsymbol($\odot$,r) +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$,r) +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 Days}){3,72} +\endpicture +\end{verbatim} + + +The \verb!drawcurve! command can also be used for drawing smooth +curves linking a number of points or touching lines. +For example, Figure~16 shows a smooth curve touching +a piecewise linear closed +line\footnote{Figure~16 was constructed and drawn by Frantisek Chvala.}, + some of the points being constructed using a Bezier +technique\footnote{see \textit{The Metafont book} by DE Knuth, +chapter~3 for details regarding Bezier curves.}. +The smooth curve is drawn using the \verb!drawcurve! command for +successive three-point sequences. + + + +%%---------figure 16----------- +\begin{figure}[hbt] +\begin{center} + %% smooth curve from Frantisek + \strut\input{mPICm16.pic} + \caption{A smooth curve inscribed in the intersecting + closed line $ABCDEFGA$} +\end{center} +\end{figure} +%----------------------- + + + +\begin{verbatim} +%% mpicm16.m (Figure 16) +\beginpicture +variable(u){12} %% units = 12 mm +paper{units(u mm),xRange(0,9),yRange(-1,6)} +variable(r){0.7} %% line-free radius of \circ = 0.7mm +variable*(r){r, divide(u)} %% scale line-free radius 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$ symbol for points +% +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)} +% +DrawPoints(ABCDEFG) +DrawPoints(A1B1C1D1E1F1G1) +DrawPoints(A2B2C2D2E2F2G2) +% +DrawLine(ABCDEFGA) +\setplotsymbol ({\Large.}) +DrawCurve(A1B2B1) +DrawCurve(B1C2C1) +DrawCurve(C1D2D1) +DrawCurve(D1E2E1) +DrawCurve(E1F2F1) +DrawCurve(F1G2G1) +DrawCurve(G1A2A1) +% +Text($A$){A,shift(-.2,0)} +Text($B$){B,shift(-.2,.1)} +Text($C$){C,shift(0,.25)} +Text($D$){D,shift(0,-.25)} +Text($E$){E,shift(.2,0)} +Text($F$){F,shift(0,.25)} +Text($G$){G,shift(0,-.25)} +\scriptsize +Text($A_1$){A1,shift(.25,0)} +Text($B_1$){B1,shift(0,-.2)} +Text($C_1$){C1,shift(.25,0)} +Text($D_1$){D1,shift(-.2,.15)} +Text($E_1$){E1,shift(-.2,0)} +Text($F_1$){F1,shift(.15,-.15)} +Text($G_1$){G1,shift(.1,.2)} +Text($A_2$){A2,shift(.25,0)} +Text($B_2$){B2,shift(.1,-.2)} +Text($C_2$){C2,shift(-.1,-.15)} +Text($D_2$){D2,shift(.1,.2)} +Text($E_2$){E2,shift(-.25,.05)} +Text($F_2$){F2,shift(.05,-.2)} +Text($G_2$){G2,shift(0,.25)} +\endpicture +\end{verbatim} + + + +Note the technique used in the code for Figure~16, 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 (see also Section~4.3.2). + +\begin{verbatim} +variable(u){12} %% units = 12 mm +paper{units(u mm),xRange(0,9),yRange(-1,6)} +variable(r){0.7} %% line-free radius of \circ = 0.7mm +variable*(r){r, divide(u)} %% scaled linefree radius for u mm +pointsymbol($\circ$, r) +point(A){1,1} +\end{verbatim} + +This technique can be very useful if it will be necessary to +scale the figure markedly after having designed the figure, in +order, say, to make it fit into a particular space in a document. + + + +%%------------------------------------------- +\section{Positioning figures in a document} + +Once a diagram or figure has been finished it can be easily +placed in a document either by including the {\PiCTeX} code +directly in +the main document within the \verb!\begin{figure}...\end{figure}! +environment, or by \verb!\input!ting the code as a separate +file. +For example, if the {\mathsPIC} file was called \verb!myPIC.m! +and this generated the output-file \verb!myPIC.mt!, then one would +comment-out the \LaTeX\ headers and footers from the \verb!.mt! +file, keeping just the part of the file within the +\verb!\beginpicture!\ldots\verb!\endpicture! environment (renaming +it, say, \verb!myPIC.pic!) as follows. + + +\begin{verbatim} +%% this is file myPIC.pic +\beginpicture +... +... +\endpicture +\end{verbatim} + +The \verb!myPIC.pic! file can then be \verb!\input! into +a document as a centered Figure as follows. + + +\begin{verbatim} +\begin{figure}[hbt] +\begin{center} + \strut\input{myPIC.pic} + \caption{...} + \label{...} +\end{center} +\end{figure} +\end{verbatim} + +It is often useful when adjusting +its position on the page, +to initially place the Figure inside a frame +in order to see the exact extent of the Figure, in which case replace the +\verb!\input! line above with the following: + + +\begin{verbatim} +\strut\framebox{\input{myPIC.pic}} +\end{verbatim} + + +Sometimes more flexibility is needed regarding positioning +the \verb!\caption!, in which case a \verb!\parbox! is useful, +as follows: + +\begin{verbatim} +\begin{figure}[hbt] +\begin{center} + \strut\input{myPIC.pic} + \parbox{10cm}{ + \vspace{5mm} + \caption{...} + \label{...} + } +\end{center} +\end{figure} +\end{verbatim} + + +When typesetting text and a figure side-by-side the following +format for using two adjacent minipages works well---this was the +construction used for displaying the program code +and the associated Figure~7. + +\begin{verbatim} +\begin{figure}[hbt] +\noindent +\begin{minipage}{4cm} +%% put some text or a figure here +... +... +\end{minipage} +%%----------- +\hspace{3cm} %% controls the horizontal space between Figures +%%----------- +\begin{minipage}{4cm} + \vspace{3mm} + \strut\hspace*{...}\input{circle.pic} + \vspace{...} % adjusts vertical position of caption + \caption{...} + \label{...} +\end{minipage} +%----- +\hfill +\end{figure} +\end{verbatim} + + +Finally, it is often necessary to have two figures side-by-side, +each with separate sub-captions, in which case the following +rather similar format is useful---this was the +construction used for displaying the two figures of Figure~8. +Note the commented-out \verb!\framebox{}! commands; these are +very useful for revealing the full extent of any white-space +surrounding the separate figures, since such unwanted white-space is +probably the most common cause of difficulty when trying to +position and center figures in a document. + + +\begin{verbatim} +\begin{figure}[hbt] +\begin{center} + %------- + \noindent %\framebox{ + \begin{minipage}{3cm} + \begin{center} + %\vspace{...} %% controls space above picture + \input{mPICm08a.pic} + %\vspace{...} %% controls space between pict and caption + a. Circular arrows + \end{center} + \end{minipage} + %} %end of framebox + %----------------------- + \hspace{12mm} %% controls horiz space between figs + % \bigskip\bigskip %% use this to place figs vertically + %---------------------- + %\framebox{ + \begin{minipage}{5cm} + \begin{center} + %\vspace{...} %% controls space between pict and caption + \input{mPICm08b.pic} + %\vspace{...} %% controls space between pict and caption + b. Straight arrows + \end{center} + \end{minipage} + %} %end of framebox + %--------- + \caption{.....\hspace{7mm}} % add \hspace{} to adjust horiz possn +\end{center} +\end{figure} +\end{verbatim} + + +%%----------------------------------------- +\section{Downloading and installing \PiCTeX} + +{\PiCTeX} is an excellent small graphics package, freely available +from CTAN and the usual \TeX\ CD-ROM +discs\footnote{Available from \TeX\ user groups. +Note that a particularly good 3-disk CTAN archive is published +annually by the German \TeX\ users group DANTE +(\textit{dante@dante.de}, \texttt{http://www.dante.de}).}. + Download all the files in the following two +directories, and place them where your \TeX\ system can +find them\footnote{For EmTeX, this would be the directory +\texttt{c:{\bs}emtex{\bs}texinput{\bs}pictex{\bs}}}. +\begin{itemize} + \item \verb!CTAN/tex-archive/graphics/pictex/! + \item \verb!CTAN/tex-archive/graphics/pictex/addon/! +\end{itemize} +If you are a \LaTeX\ user, then use \verb!\usepackage{pictexwd}!. +If you are a plain \TeX\ user, then use \verb!\input pictexwd.tex! +(see Section~4.2.1 and Section~9.2 for details). + + + Unfortunately, the {\PiCTeX} documentation is not available +from CTAN---the {\PiCTeX} +manual has to be purchased separately (see Section~9.5). +However, {\mathsPIC} users will mostly find this +unnecessary, since those \PiCTeX\ commands +which are particularly useful in conjunction with {\mathsPIC} +are described in the {\mathsPIC} manual (Section~6.3), together +with examples in the code for the various Figures. + + + +%%%-------------------- +\subsection{The original files (1986)} + +\noindent\texttt{CTAN/tex-archive/graphics/pictex/} + +\medskip + +The original {\PiCTeX} package by Michael Wichura (21/09/1987) +originally consisted of the 4 files listed below. +On the left is the MS-DOS name (truncated to 8 characters), and +on the right is the full UNIX name). + +The file \texttt{latexpic.tex} gives Plain \TeX\ users the +option of using the \LaTeX\ Picture macros \verb!\line!, \verb!\vector!, +\verb!\circle!, \verb!\oval!, \verb!\thicklines! and +\verb!\thinlines! (for syntax and use with \PiCTeX\ see +Wichura, 1992). + +Note that only two of the files are required for +using with plain {\TeX}, while three files are + required when running \LaTeX. + +\begin{verbatim} +latexpic.tex 11243 bytes (latexpicobjs.tex --for plain TeX only) +prepicte.tex 1293 bytes (prepictex.tex --for LaTeX) +pictex.tex 133388 bytes (pictex.tex --for LaTeX and plain TeX) +postpict.tex 1614 bytes (postpictex.tex --for LaTeX) +\end{verbatim} + + +The three files required for use with \LaTeX\ +need to be loaded (input) \textit{in the order +shown above}. + Note that when using {\PiCTeX} with \LaTeXe\ +it is necessary to redefine the \LaTeX\ 2.09 command \verb!\fiverm! +(because {\PiCTeX} was originally written for \LaTeX\ 2.09). +This is most easily done as follows. + +\begin{verbatim} +\newcommand{\fiverm}{\rmfamily\tiny} +\end{verbatim} + +Alternatively you can use the more robust method (i.e.\ for +\textit{wizards}) suggested +by Michael J Downes as follows (I believe +Michael Downes suggested this originally on the +\textsl{comp.text.tex} usenet group---see also +the file \texttt{fntguide.tex} among the \LaTeXe\ documents). + +\begin{verbatim} +\declarefixedfont{\fiverm}{\encodingdefault}{\rmdefault}{m}{n}{5} +\end{verbatim} + +A significant problem with the original \PiCTeX\ package was +that it was very memory hungry. However, in 1994 +this problem was overcome by a significant rewrite by Andreas +Schrell (see Section~9.2). + +%%-------------------- +\subsection{The new updated files (1994)} + +\begin{verbatim} +CTAN/tex-archive/graphics/pictex/addon/ +\end{verbatim} + +In 1994 Andreas Schrell uploaded a set of updated \PiCTeX\ files into the +\verb!CTAN: .../pictex/addon/! directory. One of these additional files +(\verb!pictexwd.tex!) is a replacement for the original +(\verb!pictex.tex!), and is extremely +economic in its use of {\TeX}'s dimension registers, + allowing significantly better memory usage + with exactly the same functionality. +The other files correct some errors (\verb!piccorr.sty!), +and add new functionality (\verb!picmore.tex!). + +\begin{verbatim} +pictexwd.sty 416 bytes +pictexwd.tex 133232 bytes +picmore.tex 2952 bytes +piccorr.sty 4608 bytes +pictex.sty 311 bytes +\end{verbatim} + + +%-------- +\begin{itemize} + + \item \verb!pictexwd.sty! + +For \LaTeX\ users. This replaces \verb!pictex.sty!. It inputs +\verb!prepictex.tex!, \verb!pictexwd.tex!, and +\verb!postpictex.tex!, as well as inputting \verb!piccorr.sty! +and \verb!picmore.tex! if these are available. + + \item \verb!pictexwd.tex! + +For \TeX\ users. + + \item \verb!picmore.tex! + +An extension for drawing impulse diagrams. + + \item \verb!piccorr.sty! + +A correction for the +original \PiCTeX\ \verb!\betweenarrows! command. + +\item \verb!pictex.sty! + +The \LaTeX\ style-option for loading the \textit{original} +\PiCTeX\ files. Note that it also inputs \verb!piccorr.sty! +and \verb!picmore.tex! if these are available. + + + \end{itemize} +%------ + + + All the necessary files required for +running \PiCTeX\ are automatically input in +the correct order by \verb!pictexwd.sty! (\LaTeX\ users), or by +\verb!pictexwd.tex! (\TeX\ users). +Users of {\LaTeXe} should include the following command in the +preamble. + +\begin{verbatim} +\usepackage{pictexwd} +\end{verbatim} + +Users of plain {\TeX} need to include the following. + +\begin{verbatim} +\input latexpic.tex +\input pictexwd.tex +\end{verbatim} + +Note that it is still necessary to download all the original +\PiCTeX\ files even when using Andreas Schrell's new files, as +some of the original files are still required. + + +%%---------------------- +\subsection{Pictex2.sty} + + +\begin{verbatim} +CTAN/tex-archive/macros/latex/contrib/supported/pictex2.sty +16418 bytes 09/05/1999 +\end{verbatim} + + +William Park\footnote{\texttt{parkw@better.net}} +has written a style option (\texttt{pictex2.sty}) +which adds two useful commands to standard {\PiCTeX}, +which force the use of the \verb!\putrule! command where lines are +either horizontal or vertical, thus saving on memory (note that +{\mathsPIC} automatically implements the use of \verb!\putrule! +in these circumstances---see Section~4.6). +These two commands are as follows. + +\begin{itemize} +\item \texttt{$\backslash$putanyline} command + +This command invokes the {\PiCTeX} \verb!\putrule! command +(instead of \verb!\plot!) in cases where lines are either +vertical or horizontal. + + +\item \texttt{$\backslash$setanyline} command + +This is a line-drawing mode (similar to \verb!\setlinear!) which +forces subsequent \verb!\plot! commands to invoke \verb!\putrule! +whenever the line is either horizontal or vertical. + +\end{itemize} + + +%%---------------------- +\subsection{Errorbar.tex} + + +\begin{verbatim} +CTAN/tex-archive/graphics/pictex/errorbar.tex +3041 bytes 20/04/1988 +\end{verbatim} + +In 1988 Dirk Grunwald implemented the following errorbar command +for \PiCTeX\ which draws error bars using +a modified \verb!\plot! command as follows. + + +\begin{itemize} +\item \texttt{$\backslash$plotWithErrorBars} command + +This command, which is case sensitive, has the format + +\begin{verbatim} +\plotWithErrorBars mark M at + x1 y1 e1 + ... + xn yn en / +\end{verbatim} + +where \verb!M! is a \TeX\ character (e.g.\ \verb!$\bullet$!), +and \verb!e! is the size of vertical error bars which are +plotted above and below the point. The default cross-bar length +is 5pt, but can be changed, say to 7pt, using the command +\verb!\crossbarlength=7pt!. + +To use this command, input the file \verb!errorbar.tex! after +all the \PiCTeX\ files. + +\end{itemize} + + + +%%------------------------------------------ +\subsection{The \PiCTeX\ Manual} + +You may wish to purchase \textsl{The {\PiCTeX} Manual} +by Michael J.\ Wichura (The University of Chicago, Chicago, +Illinois, USA; \textit{wichur@galton.uchicago.edu}). +This excellent booklet (version 1.1, third printing, March 1992; 85 pages) +used to be available from TUG as Publication No.\ 6 in +the TUG {\TeX}niques series. +Unfortunately, TUG (\texttt{http://www.tug.org/}) +has now stopped publishing the manual, and +\textsl{The {\PiCTeX} Manual} +is currently only available from \textsl{Personal \TeX\ +Inc.} (\textit{texsales@pctex.com}\ \texttt{http://www.pctex.com/}) +at approximately {\$}59 plus postage. + +When you buy a copy of the manual you also receive a floppy disk +containing {\PiCTeX} files. Unfortunately these are only +the original 1986 files, and do not as yet include any of Andreas Schrell's +1994 files. + +%%------------------- + +\section{Bug reports} +The author would be grateful for any bug reports, +constructive comments, and any ideas for improving this program. +The author is grateful to Apostolos Syropoulos, Bob Schumacher, +Frantisek Chvala, Orlando Rodriguez, Boris Kuselj, and others +for testing this program, and for their many ideas and +suggestions. + +\section{Perl version of {\mathsPIC}} +A Perl version of {\mathsPIC} is currently in progress +(Syropoulos and Nickalls, 2000). It will have a number +of enhanced features, particularly with regard to handling of +variables. The authors expect it to be first released in the Autumn of +2001. + +%%---------------- +\section{History} + +\begin{itemize} + +\item 2.1 (November, 2000): + +Revised the documentation; fixed numerous bugs; introduced the +\texttt{$\backslash$} and \texttt{$\backslash$\gap...} commands +to facilitate the use of \TeX\ and \LaTeX\ commands and for +copying lines verbatim. The following +commands have also been added/extended. + +\begin{verbatim} +drawCurve(ABC) +drawline(AB)[d] %% added the [] option +drawline*(AB) %% disables use of \putrule +point(S){Q, rotate(P, 23 deg)} %% added the rotate() option +pointsymbol(char,lineFreeRadius) %% added the line-free radius option +\end{verbatim} + + +\item 1.9b (May 2000): + +Fixed a bug associated with the +\verb!drawAngleArc! and \verb!drawAngleArrow! commands. + + +\item 1.9a (January 2000): + +Added the options X and Y to the \texttt{axes} option in the +\texttt{paper} command, which allows X and Y axes to be drawn. +Also added +the option of following any of the \texttt{axes} options by a * which +prevents ticks being drawn on that particular axis. + +\item 1.8f (October 1999): + +Fixed problem with scientific +notation; added current loop number indicator; added the +following new commands: + +\begin{verbatim} +variable(){area()} +variable(){angle()} +variable(){Xpoint()} +variable(){Ypoint()} +inputfile*() +PointSymbol(default) +\end{verbatim} + + +\item 1.7u (September 1999): First release. + +\end{itemize} + +%%------------------- +\section{References} + +\begin{itemize} + +\item Cameron P.\ J.\ (1992). Geometric diagrams in \LaTeX. +\textit{TUGboat} \textbf{13} (No.~2), 215--216. + +\item Feruglio G.\ V.\ (1994). Typesetting commutative diagrams. +\textit{TUGboat} \textbf{15} (No.~4), 466--484. + +\item Nickalls RWD (1999a). +{\MathsPIC}: a filter program for use with {\PiCTeX}. +{\newline}\textit{Euro{\TeX}'99 Proceedings}; 197--210. +(Heidelberg, Germany; August 1999). + +\item Nickalls RWD (1999b). +{\MathsPIC}: a filter program for use with {\PiCTeX}. +{\newline}\textit{Eutupon}\footnote{The editor is Apostolos +Syropoulos (email: \textit{apostolo@obelix.ee.duth.gr}).} +[the Greek \TeX\ Friends' journal]; +No.~3 (October, 1999), 33--49 (English). +{\newline} [This is an updated version of Nickalls (1999a)]. + + +\item Salomon D.\ (1992). Arrows for technical drawing. +\textit{TUGboat} \textbf{13} (No.~2), 146--149. + +\item Syropoulos A.\ and Nickalls R.\ W.\ D.\ (2000). +A PERL porting of the {\mathsPIC} graphics package. +{\newline}\textit{TUG2000 Conference} (Oxford, UK); August +13--16, 2000. + +\item Wichura M.\ J.\ (1992). The {\PiCTeX} manual. +Pub: Personal \TeX\ Inc., 12~Madrona Avenue, Mill Valley, CA +94941, USA. \textit{texsales@pctex.com}\ \ +\texttt{http://www.pctex.com}. + +\end{itemize} + + +\begin{center} +------------ +\end{center} + +\end{document} |