diff --git a/books/bookvol7.1.pamphlet b/books/bookvol7.1.pamphlet
index d76b336..9f6e885 100644
--- a/books/bookvol7.1.pamphlet
+++ b/books/bookvol7.1.pamphlet
@@ -33,38 +33,45 @@ The Blue Bayou image Copyright (c) 2004 Jocelyn Guidry
 
 Portions Copyright (c) 2004 Martin Dunstan
 
-Portions Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
+Portions Copyright (c) 1991-2002, 
+The Numerical ALgorithms Group Ltd.
 All rights reserved.
 
 This book and the Axiom software is licensed as follows:
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
+Redistribution and use in source and binary forms, with or 
+without modification, are permitted provided that the following 
+conditions are
 met:
 
-    - Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-
-    - Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in
-      the documentation and/or other materials provided with the
-      distribution.
-
-    - Neither the name of The Numerical ALgorithms Group Ltd. nor the
-      names of its contributors may be used to endorse or promote products
-      derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
-OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+    - Redistributions of source code must retain the above 
+      copyright notice, this list of conditions and the 
+      following disclaimer.
+
+    - Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the 
+      following disclaimer in the documentation and/or other 
+      materials provided with the distribution.
+
+    - Neither the name of The Numerical ALgorithms Group Ltd. 
+      nor the names of its contributors may be used to endorse 
+      or promote products derived from this software without 
+      specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
+SUCH DAMAGE.
 
 \end{verbatim}
 
@@ -200,6 +207,8 @@ November 10, 2003 ((iHy))
 \label{releaseNotes}
 \includegraphics[scale=.5]{ps/v71releasenotes.eps}
 \index{images!releasenotes}
+
+Called from ``Root Page'' (RootPage) \ref{RootPage} on page~\pageref{RootPage}
 \begin{itemize}
 \item ``Online information'' (onlineInformation) \ref{onlineInformation}
 on page~\pageref{onlineInformation}
@@ -892,7 +901,8 @@ individual .ht files that are of a local nature.
 All unix commands should be done as macros defined here so we don't
 have to go hunting when moving between Unix versions.
 <<util.ht>>=
-\newcommand{\newspadclient}[1]{xterm -n "#1" -e \$SPAD/bin/clef \$SPAD/bin/server/spadclient}
+\newcommand{\newspadclient}[1]
+{xterm -n "#1" -e \$SPAD/bin/clef \$SPAD/bin/server/spadclient}
 \newcommand{\searchwindow}[2]{\unixwindow{#1}{\$SPAD/lib/htsearch "#2"}}
 \newcommand{\unixwindow}[2]{\unixlink{#1}{#2}}
 \newcommand{\menuunixlink}[2]{\item\unixlink{\menuitemstyle{#1}}{#2}}
@@ -932,15 +942,21 @@ have to go hunting when moving between Unix versions.
 \newcommand{\menuwindowlink}[2]    {\item\windowlink{\menuitemstyle{#1}}{#2}}
 
 %   These execute lisp commands in various flavors
-\newcommand{\menulispcommand}[2] {\item\lispcommand{\menuitemstyle{#1}}{#2}}
-\newcommand{\menulispdownlink}[2]{\item\lispdownlink{\menuitemstyle{#1}}{#2}}
-\newcommand{\menulispmemolink}[2]{\item\lispmemolink{\menuitemstyle{#1}}{#2}}
-\newcommand{\menulispwindowlink}[2]{\item\lispwindowlink{\menuitemstyle{#1}}{#2}}
+\newcommand{\menulispcommand}[2]
+{\item\lispcommand{\menuitemstyle{#1}}{#2}}
+\newcommand{\menulispdownlink}[2]
+{\item\lispdownlink{\menuitemstyle{#1}}{#2}}
+\newcommand{\menulispmemolink}[2]
+{\item\lispmemolink{\menuitemstyle{#1}}{#2}}
+\newcommand{\menulispwindowlink}[2]
+{\item\lispwindowlink{\menuitemstyle{#1}}{#2}}
 
 %   This executes a unix command
-\newcommand{\menuunixcmd}[2]     {\item\unixcommand{\menuitemstyle{#1}}{#2}}
-\newcommand{\searchresultentry}[3]{\tab{3}\item#3\tab{8}\downlink{\menuitemstyle{#1}}{#2}\newline}
-\newcommand{\newsearchresultentry}[3]{\tab{3}\item#1\tab{8}\downlink{\menuitemstyle{#2}}{#3}\newline}
+\newcommand{\menuunixcmd}[2]{\item\unixcommand{\menuitemstyle{#1}}{#2}}
+\newcommand{\searchresultentry}[3]
+{\tab{3}\item#3\tab{8}\downlink{\menuitemstyle{#1}}{#2}\newline}
+\newcommand{\newsearchresultentry}[3]
+{\tab{3}\item#1\tab{8}\downlink{\menuitemstyle{#2}}{#3}\newline}
 
 @
 \subsection{Bitmaps and bitmap manipulation macros}
@@ -963,7 +979,8 @@ have to go hunting when moving between Unix versions.
 
 % Including control panel pixmaps for help pages:
 
-\newcommand{\helpbit}[1]{\centerline{\inputpixmap{\env{AXIOM}/doc/hypertex/pixmaps/{#1}}}}
+\newcommand{\helpbit}[1]
+{\centerline{\inputpixmap{\env{AXIOM}/doc/hypertex/pixmaps/{#1}}}}
 
 @
 \subsection{HyperDoc button objects}
@@ -993,7 +1010,8 @@ have to go hunting when moving between Unix versions.
 
 % Macro for downward compatibility (?).
 
-\newcommand{\simplebox}[2]{\inputbox[#1]{#2}{\htbitmap{xbox}}{\htbitmap{xopenbox}}}
+\newcommand{\simplebox}[2]
+{\inputbox[#1]{#2}{\htbitmap{xbox}}{\htbitmap{xopenbox}}}
 
 @
 \subsection{HyperDoc graphics macros}
@@ -1001,19 +1019,24 @@ have to go hunting when moving between Unix versions.
 % Including viewport bitmaps within \HyperName pages:
 
 \newcommand{\viewport}[1]{\inputimage{{#1}.view/image}}
-\newcommand{\axiomViewport}[1]{\inputimage{\env{AXIOM}/doc/viewports/{#1}.view/image}}
+\newcommand{\axiomViewport}[1]
+{\inputimage{\env{AXIOM}/doc/viewports/{#1}.view/image}}
 \newcommand{\spadviewport}[1]{\axiomViewport{#1}}
 
 % Creating a real live viewport:
 
 \newcommand{\viewportbutton}[2]{\unixcommand{#1}{viewalone #2}}
-\newcommand{\axiomViewportbutton}[2]{\unixcommand{#1}{viewalone \$AXIOM/doc/viewports/{#2}}}
+\newcommand{\axiomViewportbutton}[2]
+{\unixcommand{#1}{viewalone \$AXIOM/doc/viewports/{#2}}}
 \newcommand{\spadviewportbutton}[2]{\axiomViewportbutton{#1}{#2}}
 
 % Making active viewport buttons:
 
-\newcommand{\viewportasbutton}[1]{\unixcommand{\inputimage{{#1}.view/image}}{viewalone {#1}}}
-\newcommand{\axiomViewportasbutton}[1]{\unixcommand{\inputimage{\env{AXIOM}/doc/viewports/{#1}.view/image}}{viewalone \$AXIOM/doc/viewports/{#1}}}
+\newcommand{\viewportasbutton}[1]
+{\unixcommand{\inputimage{{#1}.view/image}}{viewalone {#1}}}
+\newcommand{\axiomViewportasbutton}[1]
+{\unixcommand{\inputimage{\env{AXIOM}/doc/viewports/{#1}.view/image}}
+{viewalone \$AXIOM/doc/viewports/{#1}}}
 \newcommand{\spadviewportasbutton}[1]{\axiomViewportasbutton{#1}}
 
 @
@@ -1146,15 +1169,21 @@ have to go hunting when moving between Unix versions.
 \newcommand{\mathOrSpad}[1]{{\spad{#1}}}
 \newcommand{\menuspadref}[2]{\menudownlink{#1}{#2Page}}
 \newcommand{\menuxmpref}[1]{\menudownlink{`#1'}{#1XmpPage}}
-\newcommand{\noOutputXtc}[2]{\xtc{#1}{#2}}  % comment and then \spadcommand or spadsrc
+% comment and then \spadcommand or spadsrc
+\newcommand{\noOutputXtc}[2]{\xtc{#1}{#2}}  
 \newcommand{\not=}{\inputbitmap{\htbmdir{}/not=.bitmap}}
 \newcommand{\notequal}{\inputbitmap{\htbmdir{}/notequal.bitmap}}
-\newcommand{\nullXtc}[2]{\xtc{#1}{#2}}      % comment and then \spadcommand or spadsrc
+% comment and then \spadcommand or spadsrc
+\newcommand{\nullXtc}[2]{\xtc{#1}{#2}}      
 \newcommand{\nullspadcommand}[1]{\spadcommand}
-\newcommand{\pp}{\newline}              % Use this instead of \par for now.
-\newcommand{\psXtc}[3]{\xtc{#1}{#2}}        % comment and then \spadcommand or spadsrc
+% Use this instead of \par for now.
+\newcommand{\pp}{\newline}
+% comment and then \spadcommand or spadsrc
+\newcommand{\psXtc}[3]{\xtc{#1}{#2}}        
 \newcommand{\ref}[1]{(see the graph)}
-\newcommand{\showBlurb}[1]{Issue the system command \spadcmd{)show #1} to display the full list of operations defined by \spadtype{#1}.}
+\newcommand{\showBlurb}[1]
+{Issue the system command \spadcmd{)show #1} to display the full list 
+of operations defined by \spadtype{#1}.}
 \newcommand{\smath}[1]{\mathOrSpad{#1}}
 \newcommand{\spadFileExt}{.spad}
 \newcommand{\spadkey}[1]{}
@@ -1172,7 +1201,8 @@ have to go hunting when moving between Unix versions.
 \newcommand{\xdefault}[1]{The default value is {\tt "#1"}.}
 \newcommand{\xmpLine}[2]{{\tt #1}\newline}   % have to improve someday
 \newcommand{\xmpref}[1]{\downlink{`#1'}{#1XmpPage}}
-\newcommand{\xtc}[2]{#1 #2}                 % comment and then \spadcommand or spadsrc
+% comment and then \spadcommand or spadsrc
+\newcommand{\xtc}[2]{#1 #2} 
 
 % glossary terms
 \newcommand{\axiomGloss}[1]{\lispdownlink{#1}{(|htGloss| '|#1|)}}
@@ -1187,12 +1217,14 @@ have to go hunting when moving between Unix versions.
 % constructors
 \newcommand{\axiomType}[1]{\lispdownlink{#1}{(|spadType| '|#1|)}}
 \newcommand{\spadtype}[1]{\axiomType{#1}}
-\newcommand{\nonLibAxiomType}[1]{{\it #1}}       % things that browse can't handle
+% things that browse can't handle
+\newcommand{\nonLibAxiomType}[1]{{\it #1}}
 \newcommand{\pspadtype}[1]{\nonLibAxiomType{#1}}
 
-\newcommand{\axiom}   [1]{{\tt #1}}              % note font
+\newcommand{\axiom}   [1]{{\tt #1}} % note font
 \newcommand{\spad}    [1]{\axiom{#1}}
-\newcommand{\spadvar} [1]{\axiom{#1}}            % exists in ++ comments; to be removed
+% exists in ++ comments; to be removed
+\newcommand{\spadvar} [1]{\axiom{#1}}
 \newcommand{\s}       [1]{\axiom{#1}}
 
 \newcommand{\httex}[2]{#1}
@@ -1205,14 +1237,14 @@ have to go hunting when moving between Unix versions.
 %
 % Example: \spadfunFromX{reverse}{List} prints as   reverse!
 %
-% In the "From" versions, the first arg is function name, second is constructor
-% where exported.
+% In the "From" versions, the first arg is function name,
+% second is constructor where exported.
 %
 % Use the "op" flavors of "-", "+", "*" etc, otherwise the "fun" flavors
 
-\newcommand{\userfun} [1]{{\bf #1}}              % example, non-library function names
+\newcommand{\userfun} [1]{{\bf #1}} % example, non-library function names
 
-\newcommand{\fakeAxiomFun}[1]{{\bf #1}}          % not really a library function
+\newcommand{\fakeAxiomFun}[1]{{\bf #1}} % not really a library function
 \newcommand{\pspadfun} [1]{\fakeAxiomFun{#1}}
 
 \newcommand{\axiomFun} [1]{\lispdownlink{#1}{(|oPage| '|#1|)}}
@@ -1269,10 +1301,12 @@ have to go hunting when moving between Unix versions.
 
 \newcommand{\dlink}[2]{\downlink{#2}{#1}}
 \newcommand{\dom}[1]{\lispdownlink{#1}{(|conPage| '|#1|)}}
-\newcommand{\example}[1]{\newline\indent{5}\spadcommand{#1}\indent{0}\newline}
+\newcommand{\example}[1]
+{\newline\indent{5}\spadcommand{#1}\indent{0}\newline}
 \newcommand{\lisp}[2]{\lispdownlink{#2}{#1}}
 \newcommand{\spadatt} [1]{{\it #1}}
-\newcommand{\indented}[2]{\indentrel{#1}\newline #2\indentrel{-#1}\newline}
+\newcommand{\indented}[2]
+{\indentrel{#1}\newline #2\indentrel{-#1}\newline}
 \newcommand{\keyword}[1]{\lispdownlink{#1}{(|htsn| '|#1|)}}
 \newcommand{\op}[1]{\lispdownlink{#1}{(|htsn| '|#1|)}}
 \newcommand{\spadignore}[1]{#1}
@@ -1290,7 +1324,8 @@ have to go hunting when moving between Unix versions.
 \newcommand{\hidepaste}{\htbitmap{sup3d}}
 \newcommand{\spadpaste}[1]{
   \newline
-  \begin{paste}{\pagename Empty \examplenumber}{\pagename Patch \examplenumber}
+  \begin{paste}{\pagename Empty \examplenumber}
+{\pagename Patch \examplenumber}
   \pastebutton{\pagename Empty \examplenumber}{\showpaste}
   \tab{5}\spadcommand{#1}
   \end{paste}
@@ -1298,7 +1333,8 @@ have to go hunting when moving between Unix versions.
 
 \newcommand{\graphpaste}[1]{
   \newline
-  \begin{paste}{\pagename Empty \examplenumber}{\pagename Patch \examplenumber}
+  \begin{paste}{\pagename Empty \examplenumber}
+{\pagename Patch \examplenumber}
   \pastebutton{\pagename Empty \examplenumber}{\showpaste}
   \tab{5}\spadgraph{#1}
   \end{paste}
@@ -1312,6 +1348,7 @@ have to go hunting when moving between Unix versions.
 @
 \section{Special Hyperdoc pages}
 \subsection{Not Connected to Axiom}
+\label{SpadNotConnectedPage}
 \index{pages!SpadNotConnectedPage!util.ht}
 \index{util.ht!pages!SpadNotConnectedPage}
 \index{SpadNotConnectedPage!util.ht!pages}
@@ -1327,6 +1364,7 @@ the button you pressed.
 
 @
 \subsection{Do You Really Want to Exit?}
+\label{ProtectedQuitPage}
 \index{pages!ProtectedQuitPage!util.ht}
 \index{util.ht!pages!ProtectedQuitPage}
 \index{ProtectedQuitPage!util.ht!pages}
@@ -1343,6 +1381,7 @@ the button you pressed.
 
 @
 \subsection{Missing Page}
+\label{UnknownPage}
 \index{pages!UnknownPage!util.ht}
 \index{util.ht!pages!UnknownPage}
 \index{UnknownPage!util.ht!pages}
@@ -1357,6 +1396,7 @@ The page you requested was not found in the \HyperName{} database.
 
 @
 \subsection{Something is Wrong}
+\label{ErrorPage}
 \index{pages!ErrorPage!util.ht}
 \index{util.ht!pages!ErrorPage}
 \index{ErrorPage!util.ht!pages}
@@ -1371,6 +1411,7 @@ The page you requested was not found in the \HyperName{} database.
 
 @
 \subsection{Sorry!}
+\label{Unlinked}
 \index{pages!Unlinked!util.ht}
 \index{util.ht!pages!Unlinked}
 \index{Unlinked!util.ht!pages}
@@ -1471,6 +1512,9 @@ What would you like to do?
 \label{RootPageLogo}
 \includegraphics[scale=.5]{ps/v71rootpagelogo.eps}
 \index{images!rootpagelogo}
+
+Called from ``Root Page'' (RootPage) 
+\ref{RootPage} on page~\pageref{RootPage}
 \index{pages!RootPageLogo!rootpage.ht}
 \index{rootpage.ht!pages!RootPageLogo}
 \index{RootPageLogo!rootpage.ht!pages}
@@ -1484,12 +1528,13 @@ BSD license. For further information visit
 http://axiom.axiom-developer.org
 \newline
 Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997 by
-the Numerical Algorithms Group Limited, which is also the proprietor of the
-trademarks Axiom and the Axiom logo and of the registered
-trademarks NAG and the NAG logo.
+the Numerical Algorithms Group Limited, which is also the 
+proprietor of the trademarks Axiom and the Axiom logo and 
+of the registered trademarks NAG and the NAG logo.
 \newline
-Axiom was originally developed by the Research Division of the International
-Business Machines Corporation, Yorktown Heights, New York, USA.
+Axiom was originally developed by the Research Division of 
+the International Business Machines Corporation, Yorktown 
+Heights, New York, USA.
 \endscroll
 \end{page}
 
@@ -1499,6 +1544,9 @@ Business Machines Corporation, Yorktown Heights, New York, USA.
 \includegraphics[scale=.5]{ps/v71topsettingspage.eps}
 \index{images!topsettingspage}
 
+Called from ``Root Page'' (RootPage) \ref{RootPage} on 
+page~\pageref{RootPage}
+
 See ``Commands'' (ugSysCmdPage) 
 \ref{ugSysCmdPage} on page~\pageref{ugSysCmdPage}
 
@@ -1527,6 +1575,9 @@ management and change Axiom system variables.
 \label{TopExamplePage}
 \includegraphics[scale=.5]{ps/v71topexamplepage.eps}
 \index{images!topexamplepage}
+
+Called from ``Root Page'' (RootPage) \ref{RootPage} on 
+page~\pageref{RootPage}
 \begin{itemize}
 \item ``Graphics'' (GraphicsExamplePage) \ref{GraphicsExamplePage} on 
 page~\pageref{GraphicsExamplePage}.
@@ -1571,6 +1622,9 @@ What would you like to see?
 \label{TopReferencePage}
 \includegraphics[scale=.5]{ps/v71topreferencepage.eps}
 \index{images!topreferencepage}
+
+Called from ``Root Page'' (RootPage) \ref{RootPage} on 
+page~\pageref{RootPage}
 \begin{itemize}
 \item ``this font'' (YouTriedIt) \ref{YouTriedIt} on 
 page~\pageref{YouTriedIt}
@@ -1659,16 +1713,19 @@ A glossary of Axiom terms.
 \begin{scroll}
 
 \beginitems
-\item\downlink{\menuitemstyle{Essential Introduction to the NAG Foundation Library}}{manpageXXintro}
+\item\downlink{\menuitemstyle
+{Essential Introduction to the NAG Foundation Library}}{manpageXXintro}
 \item Foundation Library Chapter Manual Pages
 \beginitems
-\item\downlink{\menuitemstyle{C02}}{manpageXXc02}\tab{8} Zeros of Polynomials
+\item\downlink{\menuitemstyle{C02}}
+{manpageXXc02}\tab{8} Zeros of Polynomials
 \indentrel{8}\newline
 \table{
 {\downlink{c02aff}{manpageXXc02aff}}
 {\downlink{c02agf}{manpageXXc02agf}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{C05}}{manpageXXc05}\tab{8} Roots of One or More Transcendental Equations
+\item\downlink{\menuitemstyle{C05}}
+{manpageXXc05}\tab{8} Roots of One or More Transcendental Equations
 \indentrel{8}\newline
 \table{
 {\downlink{c05adf}{manpageXXc05adf}}
@@ -1676,7 +1733,8 @@ A glossary of Axiom terms.
 {\downlink{c05pbf}{manpageXXc05pbf}}
 {\downlink{c05zaf}{manpageXXc05zaf}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{C06}}{manpageXXc06}\tab{8} Summation of Series
+\item\downlink{\menuitemstyle{C06}}
+{manpageXXc06}\tab{8} Summation of Series
 \indentrel{8}\newline
 \table{
 {\downlink{c06eaf}{manpageXXc06eaf}}
@@ -1708,7 +1766,8 @@ A glossary of Axiom terms.
 {\downlink{d01gaf}{manpageXXd01gaf}}
 {\downlink{d01gbf}{manpageXXd01gbf}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{D02}}{manpageXXd02}\tab{8} Ordinary Differential Equations
+\item\downlink{\menuitemstyle{D02}}
+{manpageXXd02}\tab{8} Ordinary Differential Equations
 \indentrel{8}\newline
 \table{
 {\downlink{d02bbf}{manpageXXd02bbf}}
@@ -1720,7 +1779,8 @@ A glossary of Axiom terms.
 {\downlink{d02kef}{manpageXXd02kef}}
 {\downlink{d02raf}{manpageXXd02raf}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{D03}}{manpageXXd03}\tab{8} Partial Differential Equations
+\item\downlink{\menuitemstyle{D03}}
+{manpageXXd03}\tab{8} Partial Differential Equations
 \indentrel{8}\newline
 \table{
 {\downlink{d03edf}{manpageXXd03edf}}
@@ -1741,7 +1801,8 @@ A glossary of Axiom terms.
 {\downlink{e01sef}{manpageXXe01sef}}
 {\downlink{e01sff}{manpageXXe01sff}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{E02}}{manpageXXe02}\tab{8} Curve and Surface Fitting
+\item\downlink{\menuitemstyle{E02}}
+{manpageXXe02}\tab{8} Curve and Surface Fitting
 \indentrel{8}\newline
 \table{
 {\downlink{e02adf}{manpageXXe02adf}}
@@ -1763,7 +1824,8 @@ A glossary of Axiom terms.
 {\downlink{e02gaf}{manpageXXe02gaf}}
 {\downlink{e02zaf}{manpageXXe02zaf}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{E04}}{manpageXXe04}\tab{8} Minimizing or Maximizing a Function
+\item\downlink{\menuitemstyle{E04}}
+{manpageXXe04}\tab{8} Minimizing or Maximizing a Function
 \indentrel{8}\newline
 \table{
 {\downlink{e04dgf}{manpageXXe04dgf}}
@@ -1780,7 +1842,8 @@ A glossary of Axiom terms.
 {\downlink{e04ycf}{manpageXXe04ycf}}
 }\indentrel{-8}
 \item\downlink{\menuitemstyle{F}}{manpageXXf}\tab{8} Linear Algebra
-\item\downlink{\menuitemstyle{F01}}{manpageXXf01}\tab{8} Matrix Operations, Including Inversion
+\item\downlink{\menuitemstyle{F01}}
+{manpageXXf01}\tab{8} Matrix Operations, Including Inversion
 \indentrel{8}\newline
 \table{
 {\downlink{f01brf}{manpageXXf01brf}}
@@ -1794,7 +1857,8 @@ A glossary of Axiom terms.
 {\downlink{f01rdf}{manpageXXf01rdf}}
 {\downlink{f01ref}{manpageXXf01ref}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{F02}}{manpageXXf02}\tab{8} Eigenvalues and Eigenvectors
+\item\downlink{\menuitemstyle{F02}}
+{manpageXXf02}\tab{8} Eigenvalues and Eigenvectors
 \indentrel{8}\newline
 \table{
 {\downlink{f02aaf}{manpageXXf02aaf}}
@@ -1813,7 +1877,8 @@ A glossary of Axiom terms.
 {\downlink{f02wef}{manpageXXf02wef}}
 {\downlink{f02xef}{manpageXXf02xef}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{F04}}{manpageXXf04}\tab{8} Simultaneous Linear Equations
+\item\downlink{\menuitemstyle{F04}}
+{manpageXXf04}\tab{8} Simultaneous Linear Equations
 \indentrel{8}\newline
 \table{
 {\downlink{f04adf}{manpageXXf04adf}}
@@ -1828,7 +1893,8 @@ A glossary of Axiom terms.
 {\downlink{f04mcf}{manpageXXf04mcf}}
 {\downlink{f04qaf}{manpageXXf04qaf}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{F07}}{manpageXXf07}\tab{8} Linear Equations (LAPACK)
+\item\downlink{\menuitemstyle{F07}}
+{manpageXXf07}\tab{8} Linear Equations (LAPACK)
 \indentrel{8}\newline
 \table{
 {\downlink{f07adf}{manpageXXf07adf}}
@@ -1836,7 +1902,8 @@ A glossary of Axiom terms.
 {\downlink{f07fdf}{manpageXXf07fdf}}
 {\downlink{f07fef}{manpageXXf07fef}}
 }\indentrel{-8}
-\item\downlink{\menuitemstyle{S}}{manpageXXs}\tab{8} Approximations of Special Functions
+\item\downlink{\menuitemstyle{S}}
+{manpageXXs}\tab{8} Approximations of Special Functions
 \indentrel{8}\newline
 \table{
 {\downlink{s01eaf}{manpageXXs01eaf}}
@@ -1879,10 +1946,13 @@ A glossary of Axiom terms.
 {\downlink{s21bdf}{manpageXXs21bdf}}
 }\indentrel{-8}
 \enditems
-\item\downlink{\menuitemstyle{Introduction to NAG On-Line Documentation}}{manpageXXonline}
+\item\downlink{\menuitemstyle
+{Introduction to NAG On-Line Documentation}}{manpageXXonline}
 \item\downlink{\menuitemstyle{Keywords in Context}}{manpageXXkwic}
-\item\downlink{\menuitemstyle{List of all \naglib{} Routines}}{manpageXXsummary}
-\item\downlink{\menuitemstyle{Converting from the Workstation Library}}{manpageXXconvert}
+\item\downlink{\menuitemstyle{List of all \naglib{} Routines}}
+{manpageXXsummary}
+\item\downlink{\menuitemstyle
+{Converting from the Workstation Library}}{manpageXXconvert}
 \enditems
 \end{scroll}
 \end{page}
@@ -1892,11 +1962,16 @@ A glossary of Axiom terms.
 @
 \subsection{Abstract Algebra}
 \label{AlgebraPage}
+\includegraphics[scale=.5]{ps/v71algebrapage.eps}
+\index{images!algebrapage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on 
+page~\pageref{TopicPage}
 \begin{itemize}
-\item NumberTheoryPage \ref{NumberTheoryPage} on
-page~pageref{NumberTheoryPage}
-\item GroupTheoryPage \ref{GroupTheoryPage} on
-page~pageref{GroupTheoryPage}
+\item ``Number Theory'' (NumberTheoryPage)\\
+\ref{NumberTheoryPage} on page~pageref{NumberTheoryPage}
+\item ``Group Theory'' (GroupTheoryPage)\\
+\ref{GroupTheoryPage} on page~pageref{GroupTheoryPage}
 \end{itemize}
 \index{pages!AlgebraPage!algebra.ht}
 \index{algebra.ht!pages!AlgebraPage}
@@ -1925,8 +2000,8 @@ Permutation groups; representation theory.
 \begin{itemize}
 \item ugProblemGaloisPage \ref{ugProblemGaloisPage} on
 page~pageref{ugProblemGaloisPage}
-\item IntegerNumberTheoryFunctionsXmpPage 
-\ref{IntegerNumberTheoryFunctionsXmpPage} on
+\item IntegerNumberTheoryFunctionsXmpPage \\
+\ref{IntegerNumberTheoryFunctionsXmpPage} on\\
 page~pageref{IntegerNumberTheoryFunctionsXmpPage}
 \end{itemize}
 \index{pages!NumberTheoryPage!algebra.ht}
@@ -1940,7 +2015,8 @@ facilities.
 \beginmenu
 \menulink{Galois Groups}{ugProblemGaloisPage} \newline
 Computation of Galois groups using factorizations over number fields.
-\menulink{Number Theory Functions}{IntegerNumberTheoryFunctionsXmpPage}\newline
+\menulink{Number Theory Functions}
+{IntegerNumberTheoryFunctionsXmpPage}\newline
 Some functions of interest to number theorists.
 \endmenu
 \endscroll
@@ -1967,18 +2043,17 @@ Some functions of interest to number theorists.
 \begin{page}{AssociationListXmpPage}{AssociationList}
 \beginscroll
 
-The \spadtype{AssociationList} constructor provides a general structure for
-associative storage.
-This type provides association lists in which data objects can be saved
-according to keys of any type.
-For a given association list, specific types must be chosen for the keys and
-entries.
-You can think of the representation of an association list as a list
-of records with key and entry fields.
+The \spadtype{AssociationList} constructor provides a general
+structure for associative storage.  This type provides association
+lists in which data objects can be saved according to keys of any
+type.  For a given association list, specific types must be chosen for
+the keys and entries.  You can think of the representation of an
+association list as a list of records with key and entry fields.
 
-Association lists are a form of table and so most of the operations available
-for \spadtype{Table} are also available for \spadtype{AssociationList}.
-They can also be viewed as lists and can be manipulated accordingly.
+Association lists are a form of table and so most of the operations
+available for \spadtype{Table} are also available for
+\spadtype{AssociationList}.  They can also be viewed as lists and can
+be manipulated accordingly.
 
 \xtc{
 This is a \pspadtype{Record} type with age and gender fields.
@@ -2036,856 +2111,16 @@ The second argument is the index of the element to delete.
 \spadpaste{delete!(al,1) \free{al6}\bound{al7}}
 }
 
-For more information about tables, see \downlink{`Table'}{TableXmpPage}\ignore{Table}.
-For more information about lists, see \downlink{`List'}{ListXmpPage}\ignore{List}.
+For more information about tables, 
+see \downlink{`Table'}{TableXmpPage}\ignore{Table}.
+For more information about lists, 
+see \downlink{`List'}{ListXmpPage}\ignore{List}.
 \showBlurb{AssociationList}
 \endscroll
 \autobuttons
 \end{page}
 
 @
-\section{annaex.ht}
-\subsection{Axiom/NAG Expert System}
-\label{UXANNA}
-\index{pages!UXANNA!annaex.ht}
-\index{annaex.ht!pages!UXANNA}
-\index{UXANNA!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNA}{Axiom/NAG Expert System}
-\centerline{\tt{\inputbitmap{\htbmdir{}/anna_logo.xbm}}\rm}
-\newline
-\centerline{This expert system chooses, and uses, NAG numerical routines.}
-\begin{scroll}
-\blankline
-\indent{2}
-\beginmenu
-\menumemolink{Integration}{UXANNAInt}
-\blankline
-\menumemolink{Ordinary Differential Equations}{UXANNAOde}
-\blankline
-\menumemolink{Partial Differential Equations}{UXANNAPde}
-\blankline
-\menumemolink{Optimization}{UXANNAOpt}
-\vspace{10}
-\menumemolink{About the Axiom/NAG Expert System}{UXANNATxt}
-%\unixcommand{(Postscript)}{ghostview \ \htbmdir{}/anna.ps}
-%\blankline
-%\menumemolink{How to use the NAGLINK}{nagLinkIntroPage}
-%\blankline
-%\menumemolink{Tutorial}{tutorialIntroPage}
-%\blankline
-%\item \menulispdownlink{Interpolation}{(|interp1|}
-\endmenu
-\indent{0}
-\end{scroll}
-%\unixcommand{Netscape}{netscape \ http:\/\/www.bath.ac.uk\/\~masbjd\/anna.html}
-\autobutt{HelpContents}
-\end{page}
-
-@
-\subsection{Integration}
-\label{UXANNAInt}
-\index{pages!UXANNAInt!annaex.ht}
-\index{annaex.ht!pages!UXANNAInt}
-\index{UXANNAInt!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAInt}{Integration}
-Welcome to the Integration section of {\tt
-\inputbitmap{\htbmdir{}/anna.xbm.tiny}}, the {\em Axiom/NAG Expert
-System}.  This system chooses, and uses, NAG numerical routines.
-\begin{scroll}
-\blankline
-\indent{2}
-\beginmenu
-\item \menulispdownlink{Integration}{(|annaInt|)}\space{}\newline
-\indent{5} Integrating a function over a finite or infinite range.
-\blankline
-\item \menulispdownlink{Multiple Integration}{(|annaMInt|)}\space{}\newline
-\indent{5} Integrating a multivariate function over a finite space.  
-The dimensions of the space need to be 2 <= n <= 15.
-\blankline
-\menudownlink{Examples}{UXANNAIntEx}\space{}\newline
-\indent{5} Examples of integration.  These examples cover all of the major 
-methods.  Parameters can be changed to investigate the effect 
-on the choice of method.
-\endmenu
-\indent{0}
-\end{scroll}
-\autobutt{MainHelp}
-\end{page}
-
-@
-\subsection{Ordinary Differential Equations}
-\label{UXANNAOde}
-\index{pages!UXANNAOde!annaex.ht}
-\index{annaex.ht!pages!UXANNAOde}
-\index{UXANNAOde!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAOde}{Ordinary Differential Equations}
-Welcome to the Ordinary Differential Equations section of {\tt
-\inputbitmap{\htbmdir{}/anna.xbm.tiny}}, the 
-{\em Axiom/NAG Expert System}.  
-This system chooses, and uses, NAG numerical routines.
-\begin{scroll}
-\blankline
-\blankline
-\indent{2}
-\beginmenu
-\item \menulispdownlink{Ordinary Differential Equations}{(|annaOde|)}\space{}\newline
-\indent{5} Finding a solution to an Initial Value Problem of a set of Ordinary Differential Equations.
-\blankline
-\menudownlink{Examples}{UXANNAOdeEx}\newline
-\indent{5} Examples of ODE problems with various features using both stiff
-and non-stiff methods.  Parameters can be changed to investigate the effect 
-on the choice of method.
-\autobutt{MainHelp}
-\endmenu
-\indent{0}
-\end{scroll}
-\end{page}
-
-@
-\subsection{Optimization}
-\label{UXANNAOpt}
-\index{pages!UXANNAOpt!annaex.ht}
-\index{annaex.ht!pages!UXANNAOpt}
-\index{UXANNAOpt!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAOpt}{Optimization}
-Welcome to the Optimization section of {\tt
-\inputbitmap{\htbmdir{}/anna.xbm.tiny}}, the {\em Axiom/NAG Expert System}.  
-This system chooses, and uses, NAG numerical routines.
-\begin{scroll}
-\blankline
-\indent{2}
-\beginmenu
-\item \menulispdownlink{Optimization of a Single Multivariate Function}
-{(|annaOpt|)}\space{}\newline
-\indent{6} Finding the minimum of a function in n variables. 
-\newline
-\indent{6} Linear Programming and Quadratic Programming problems.
-\blankline
-\indent{4} 
-\beginmenu
-\menudownlink{Examples}{UXANNAOptEx}\newline
-\indent{8} Examples of optimization problems with various constraint features.
-\endmenu
-\blankline
-\item \menulispdownlink{Optimization of a set of observations of a data set}
-{(|annaOpt2|)}\space{}\newline
-\indent{6} Least-squares problems.
-\newline
-\indent{6} Checking the goodness of fit of a least-squares model.
-\blankline
-\indent{4} 
-\beginmenu
-\menudownlink{Examples}{UXANNAOpt2Ex}\newline
-\indent{8} Examples of least squares problems.
-\endmenu
-\endmenu
-\indent{0}
-\end{scroll}
-\autobutt{MainHelp}
-\end{page}
-
-@
-\subsection{Partial Differential Equations}
-\label{UXANNAPde}
-\index{pages!UXANNAPde!annaex.ht}
-\index{annaex.ht!pages!UXANNAPde}
-\index{UXANNAPde!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAPde}{Partial Differential Equations}
-Welcome to the Partial Differential Equations section of {\tt
-\inputbitmap{\htbmdir{}/anna.xbm.tiny}}, the
-{\em Axiom/NAG Expert System}.  
-\begin{scroll}
-\indent{2}
-\beginmenu
-\menulispdownlink{Second Order Elliptic Partial Differential Equation}{(|annaPDESolve|)}
-\newline
-\indent{4} Discretizing the PDE:
-\newline
-\centerline{\inputbitmap{\htbmdir{}/d03eef.xbm}}
-defined on a rectangular region with boundary conditions of the form 
-\centerline{\inputbitmap{\htbmdir{}/d03eef1.bitmap}} 
-and solving the resulting
-seven-diagonal finite difference equations using a multigrid technique.
-\blankline
-%\menulispdownlink{Helmholtz Equation in 3-D, Cartesian Coordinates}{(|d03fafVars|)}
-%\newline
-%\indent{4} Descretizing the PDE:
-%\newline
-%\centerline{\inputbitmap{\htbmdir{}/d03faf.xbm}}
-%and solving the resulting
-%seven-diagonal finite difference equations using a method based on the Fast
-%Fourier Transform.
-\endmenu
-\end{scroll}
-\autobutt{MainHelp}
-\end{page}
-
-@
-\subsection{Examples Using the Axiom/NAG Expert System}
-\label{UXANNAOptEx}
-\index{pages!UXANNAOptEx!annaex.ht}
-\index{annaex.ht!pages!UXANNAOptEx}
-\index{UXANNAOptEx!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAOptEx}{Examples Using the Axiom/NAG Expert System}
-\begin{scroll}
-Select any of these examples and you will be presented with a page which
-contains active areas for the function and its parameters.
-\blankline
-These parameters can be altered by selecting the area and replacing the
-default parameters by the new values. 
-\blankline
-\beginmenu
-\item \menulispdownlink{Example 1: \newline 
-\indent{2} Minimize the function: 
-\centerline{\inputbitmap{\htbmdir{}/opt1.xbm}}}{(|annaOptDefaultSolve1|)}\space{}
-\blankline
-\item \menulispdownlink{Example 2: \newline 
-\indent{2} Minimize the function: 
-\centerline{\inputbitmap{\htbmdir{}/opt2.xbm}}}{(|annaOptDefaultSolve2|)}\space{}
-\newline \indent{3} With conditions: 
-\centerline{\inputbitmap{\htbmdir{}/opt2c.xbm}}
-\blankline
-\item \menulispdownlink{Example 3: \newline 
-\indent{2} Minimize the function: 
-\centerline{\inputbitmap{\htbmdir{}/opt3.xbm}}}{(|annaOptDefaultSolve3|)}\space{}
-\newline \indent{3} With conditions: 
-\centerline{\inputbitmap{\htbmdir{}/opt3c1.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt3c2.xbm}}
-\blankline
-\item \menulispdownlink{Example 4: \newline 
-\indent{2} Minimize the function: 
-\centerline{\inputbitmap{\htbmdir{}/opt4.xbm}}
-}{(|annaOptDefaultSolve4|)}\space{}
-\newline \indent{3} With conditions: 
-\centerline{\inputbitmap{\htbmdir{}/opt4c1.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt4c2.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt4c3.xbm}}
-\blankline
-\item \menulispdownlink{Example 5: \newline 
-\indent{2} Minimize the function: 
-\centerline{\inputbitmap{\htbmdir{}/opt5.xbm}}
-}{(|annaOptDefaultSolve5|)}\space{}
-\newline \indent{3} With conditions: 
-\centerline{\inputbitmap{\htbmdir{}/opt4c1.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt4c2.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt4c3.xbm}}
-\blankline
-\endmenu
-\end{scroll}
-\autobutt{Mainhelp}
-\end{page}
-
-@
-\subsection{Examples Using the Axiom/NAG Expert System}
-\label{UXANNAOpt2Ex}
-\index{pages!UXANNAOpt2Ex!annaex.ht}
-\index{annaex.ht!pages!UXANNAOpt2Ex}
-\index{UXANNAOpt2Ex!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAOpt2Ex}{Examples Using the Axiom/NAG Expert System}
-\begin{scroll}
-Select this example and you will be presented with a page which
-contains active areas for the function and its parameters.
-\blankline
-These parameters can be altered by selecting the area and replacing the
-default parameters by the new values. 
-\blankline
-\beginmenu
-\blankline
-\item \menulispdownlink{Example 1: \newline 
-\indent{2} Calculate a least-squares minimization of the following functions: 
-\centerline{\inputbitmap{\htbmdir{}/opt61.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt62.xbm}}
-\centerline{\inputbitmap{\htbmdir{}/opt63.xbm}}}
-{(|annaOpt2DefaultSolve|)}\space{}
-\endmenu
-\end{scroll}
-\autobutt{MainHelp}
-\end{page}
-
-
-@
-\subsection{Examples Using the Axiom/NAG Expert System}
-\label{UXANNAIntEx}
-\index{pages!UXANNAIntEx!annaex.ht}
-\index{annaex.ht!pages!UXANNAIntEx}
-\index{UXANNAIntEx!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAIntEx}{Examples Using the Axiom/NAG Expert System}
-\begin{scroll}
-Select any of these examples and you will be presented with a page which
-contains active areas for the function and its parameters.
-\blankline
-These parameters can be altered by selecting the area and replacing the
-default parameters by the new values.  In this way you can investigate the
-effect of the new parameters on the choice of method.
-\blankline
-\beginmenu
-\item \menulispdownlink{Example 1: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int1.xbm}}}{(|annaFoo|)}\space{}
-\blankline
-\item \menulispdownlink{Example 2: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int2.xbm}}}{(|annaBar|)}\space{}
-\blankline
-\item \menulispdownlink{Example 3: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int3.xbm}}}{(|annaJoe|)}\space{}
-\blankline
-\item \menulispdownlink{Example 4: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int4.xbm}}}{(|annaSue|)}\space{}
-\blankline
-\item \menulispdownlink{Example 5: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int5.xbm}}}{(|annaAnn|)}\space{}
-\blankline
-\item \menulispdownlink{Example 6: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int6.xbm}}}{(|annaBab|)}\space{}
-\blankline
-\item \menulispdownlink{Example 7: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int7.xbm}}}{(|annaFnar|)}\space{}
-\blankline
-\item \menulispdownlink{Example 8: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int8.xbm}}}{(|annaDan|)}\space{}
-\blankline
-\item \menulispdownlink{Example 9: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int9.xbm}}}{(|annaBlah|)}\space{}
-\blankline
-\item \menulispdownlink{Example 10: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int10.xbm}}}{(|annaTub|)}\space{}
-\blankline
-\item \menulispdownlink{Example 11: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int13.xbm}}}{(|annaRats|)}\space{}
-\blankline
-\item \menulispdownlink{Example 12: \newline 
-\centerline{\inputbitmap{\htbmdir{}/int11.xbm}}}{(|annaMInt|)}\space{}
-\endmenu
-\end{scroll}
-\autobutt{MainHelp}
-\end{page}
-
-@
-\subsection{Examples Using the Axiom/NAG Expert System}
-\label{UXANNAOdeEx}
-\index{pages!UXANNAOdeEx!annaex.ht}
-\index{annaex.ht!pages!UXANNAOdeEx}
-\index{UXANNAOdeEx!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAOdeEx}{Examples Using the Axiom/NAG Expert System}
-\begin{scroll}
-Analyses the function for various attributes, chooses and 
-then uses a suitable ODE solver to provide a 
-solution to the system of n ODEs \center{\htbitmap{d02gaf},}
-for i = 1,2,...,n.
-\blankline
-Select either of these examples and you will be presented with a page which
-contains active areas for the function and its parameters.
-\blankline
-These parameters can be altered by selecting the area and replacing the
-default parameters by the new values.  In this way you can investigate the
-effect of the new parameters on the choice of method.
-\blankline
-\beginmenu
-\item \menulispdownlink{Example 1: \tab{12}
-\inputbitmap{\htbmdir{}/ode1.xbm}}{(|annaOdeDefaultSolve1|)}
-\blankline with initial conditions: \newline
-\tab{12}\inputbitmap{\htbmdir{}/y1.xbm} \space{1} and \space{1}
-\inputbitmap{\htbmdir{}/x1.xbm}
-\blankline
-\blankline
-\blankline
-\item \menulispdownlink{Example 2: \tab{12}
-\inputbitmap{\htbmdir{}/ode2.xbm}}{(|annaOdeDefaultSolve2|)}
-\blankline with initial conditions: \newline
-\tab{12}\inputbitmap{\htbmdir{}/y2.xbm} \space{1} and \space{1}
-\inputbitmap{\htbmdir{}/x1.xbm}
-\blankline
-\blankline
-\blankline
-\endmenu
-\end{scroll}
-\autobutt{MainHelp}
-\end{page}
-
-@
-\subsection{About the Axiom/NAG Expert System}
-\label{UXANNATxt}
-\begin{itemize}
-\item UXANNAEx \ref{UXANNAEx} on page~\pageref{UXANNAEx}
-\item UXANNAIntro \ref{UXANNAIntro} on page~\pageref{UXANNAIntro}
-\item UXANNADec \ref{UXANNADec} on page~\pageref{UXANNADec}
-\item UXANNAInfer \ref{UXANNAInfer} on page~\pageref{UXANNAInfer}
-\item UXANNAMeas \ref{UXANNAMeas} on page~\pageref{UXANNAMeas}
-\end{itemize}
-\index{pages!UXANNATxt!annaex.ht}
-\index{annaex.ht!pages!UXANNATxt}
-\index{UXANNATxt!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNATxt}{About the Axiom/NAG Expert System}
-\begin{scroll}
-\centerline{\tt\inputbitmap{\htbmdir{}/anna_logo.xbm}\rm} 
-\vspace{-30}\horizontalline
-In applied mathematics, electronic and chemical engineering, the modelling
-process can produce a number of mathematical problems which require numerical
-solutions for which symbolic methods are either not possible or not obvious. 
-With the plethora of numerical library routines for the solution of these
-problems often the numerical analyst has to answer the question {\em Which
-routine to choose?} 
-\blankline
-Some analysis needs to be carried out before the
-appropriate routine can be identified i.e. {\em How stiff is this ODE?} and
-{\em Is this function continuous?}  It may well be the case that more than
-one routine is applicable to the problem.  So the question may become {\em
-Which is likely to be the best?}  Such a choice may be critical for both
-accuracy and efficiency.
-\blankline
-An expert system is thus required to make this choice based on the result of
-its own analysis of the problem, call the routine and act on the outcome. 
-This may be to put the answer in a relevant form or react to an apparent
-failure of the chosen routine and thus choose and call an alternative.  
-It should also have sufficient explanation mechanisms to inform on the choice
-of routine and the reasons for that choice.
-\blankline
-\end{scroll}
-\downlink{ Examples }{UXANNAEx}
-\downlink{ Introduction }{UXANNAIntro}
-\downlink{ Decision Agents }{UXANNADec}
-\downlink{ Inference Mechanisms }{UXANNAInfer}
-\downlink{ Measure Functions }{UXANNAMeas}
-\end{page}
-
-@
-\subsection{Introduction to the Axiom/NAG Expert System}
-\label{UXANNAIntro}
-\begin{itemize}
-\item UXANNADec \ref{UXANNADec} on page~\pageref{UXANNADec}
-\item UXANNAInfer \ref{UXANNAInfer} on page~\pageref{UXANNAInfer}
-\item UXANNAMeth \ref{UXANNAMeth} on page~\pageref{UXANNAMeth}
-\item UXANNAMeas \ref{UXANNAMeas} on page~\pageref{UXANNAMeas}
-\end{itemize}
-\index{pages!UXANNAIntro!annaex.ht}
-\index{annaex.ht!pages!UXANNAIntro}
-\index{UXANNAIntro!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAIntro}{Introduction to the Axiom/NAG Expert System}
-\begin{scroll}
-\centerline{\tt\inputbitmap{\htbmdir{}/anna_logo.xbm}\rm}
-\vspace{-30}\horizontalline
-Deciding amongst, and then implementing, several possible approaches to
-solving a numerical problem can be daunting for a novice user, or tedious for
-an expert.  Different attributes of the problem need to be
-identified and their possible interactions weighed up before a final decision
-about which method to use can be made. 
-\blankline
-The implementation is then largely an
-automatic, if laborious, process of writing, compiling and linking usually
-Fortran code.  The aim is to build an expert system which will use computer
-algebra to analyse such features of a problem, inference mechanisms and a
-knowledge base to choose a numerical method appropriate to the solution of a
-given problem.  
-\blankline
-Any interactive system is constrained by the need to provide a reasonable
-response time for the user.  Given the complexity of some of the analysis our
-system will need to do, it is clear that we should only aim to select a good
-method, rather than try to identify the best one available.  The overall goal
-is to provide a ``black-box'' interface to numerical software which allows
-non-experts access to its full potential.  It will also provide explanation
-mechanisms commensurate with its role as a teaching aid.
-\blankline
-Given, say, an integration to perform (which may or may not be able to be
-handled symbolically), the system should choose and apply an appropriate
-method, thus mirroring as closely as possible the way that an experienced
-numerical analyst would think so, for example, given an integration to
-perform:\newline
-{\it \centerline{\inputbitmap{\htbmdir{}/int1.xbm}}}
-\newline
-the experienced analyst would see that the integral is semi-infinite and
-transform it by splitting the range and transforming the integral over {\it
-[1,\inputbitmap{\htbmdir{}/infty.xbm}]} into an integral over 
-{\it [0,1] } using the transformation {\it x -> 1/t}.  
-A different numerical routine might be used over each
-sub-region and the results added to give the final answer. 
-\blankline
-It then requires
-the translation of the problem into Fortran code which may be extensive.
-Even with this simple example, the process is quite involved.
-\blankline
-\end{scroll}
-\autobuttons
-\downlink{ Decision Agents }{UXANNADec}
-\downlink{ Inference Mechanisms }{UXANNAInfer}
-\downlink{ Method Domains }{UXANNAMeth}
-\downlink{ Measure Functions }{UXANNAMeas}
-\end{page}
-
-@
-\subsection{Example using the Axiom/NAG Expert System}
-\label{UXANNAEx}
-See UXANNAEx2 \ref{UXANNAEx2} on page~\pageref{UXANNAEx2}
-\index{pages!UXANNAEx!annaex.ht}
-\index{annaex.ht!pages!UXANNAEx}
-\index{UXANNAEx!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAEx}{Example using the Axiom/NAG Expert System}
-\begin{scroll}
-\xtc{
-{\bf Example 1}: The integral
-{\centerline{\inputbitmap{\htbmdir{}/int1.xbm}}}
-\newline
-is performed as follows:
-\blankline
-}{}
-\xtc{
-}{
-\spadpaste{ans := integrate((exp(-X^3)+exp(-3*X^2))/sqrt(X),0.0..\%plusInfinity)\bound{ans} }
-}
-\blankline
-\xtc{
-It creates a composite structure for which the field containing the result can be 
-expanded as required.\blankline
-}{
-\spadpaste{ans . 'result\free{ans}}
-}
-\blankline
-\xtc{
-}{
-\spadpaste{ans . 'abserr\free{ans}}
-}
-\blankline
-This system has performed the analysis described above, done the necessary
-problem transformation, written any necessary Fortran, called two different
-numerical routines, and amalgamated their
-results.  This whole process was transparent to the user.
-\end{scroll}
-\autobuttons
-\downlink{Example 2}{UXANNAEx2}
-%\downlink{Decision Agents}{UXANNADec}
-\end{page}
-
-@
-\subsection{Example using the Axiom/NAG Expert System}
-\label{UXANNAEx2}
-See UXANNAEx3 \ref{UXANNAEx3} on page~\pageref{UXANNAEx3}
-\index{pages!UXANNAEx2!annaex.ht}
-\index{annaex.ht!pages!UXANNAEx2}
-\index{UXANNAEx2!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAEx2}{Example using the Axiom/NAG Expert System}
-\begin{scroll}
-\xtc{
-{\bf Example 2}: The ODE
-{\centerline{\inputbitmap{\htbmdir{}/ode3.xbm}\space{1}with
-\space{1}
-{\inputbitmap{\htbmdir{}/y3.xbm}}}}
-\newline
-could be solved as follows:
-\blankline
-}{}
-\xtc{
-}{
-\spadpaste{ans2 := solve([Y[2],-1001*Y[2]-1000*Y[1]], 0.0, 10.0,
-[1.0,-1.0], [2,4,6,8], 1.0e-4)\bound{ans2} }
-}
-\blankline
-\xtc{
-It creates a composite structure for which the field containing the result can be 
-expanded as required.\blankline
-}{
-\spadpaste{ans2 . 'result\free{ans2}}
-}
-\blankline
-\xtc{
-}{
-\spadpaste{ans2 . 'y\free{ans2}}
-}
-\blankline
-\end{scroll}
-\autobuttons
-\downlink{Example 3}{UXANNAEx3}
-%\downlink{Decision Agents}{UXANNADec}
-\end{page}
-
-@
-\subsection{Example using the Axiom/NAG Expert System}
-\label{UXANNAEx3}
-See UXANNADec \ref{UXANNADec} on page~\pageref{UXANNADec}
-\index{pages!UXANNAEx3!annaex.ht}
-\index{annaex.ht!pages!UXANNAEx3}
-\index{UXANNAEx3!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAEx3}{Example using the Axiom/NAG Expert System}
-\begin{scroll}
-\xtc{
-{\bf Example 3}: The function
-{\centerline{\inputbitmap{\htbmdir{}/opt2.xbm}}}
-with simple bounds
-{\centerline{\inputbitmap{\htbmdir{}/opt2c.xbm}}}
-\newline
-could be minimized as follows:
-\blankline
-}{}
-\xtc{
-}{
-\spadpaste{ans3 := optimize((X[1]+10*X[2])**2 + 5*(X[3]-X[4])**2 + 
-(X[2]-2*X[3])**4 + 10*(X[1]-X[4])**4, [3,-1,0,1], [1,-2,\%minusInfinity,1], 
-[3,0,\%plusInfinity,3])\bound{ans3} }
-}
-\blankline
-\xtc{
-It creates a composite structure for which the field containing the minimum can be 
-expanded as required.\blankline
-}{
-\spadpaste{ans3 . objf\free{ans3}}
-}
-\blankline
-\xtc{
-}{
-\spadpaste{ans3 . x\free{ans3}}
-}
-\blankline
-\xtc{
-}{
-\spadpaste{ans3 . attributes\free{ans3}}
-}
-\blankline
-\end{scroll}
-\autobuttons
-\downlink{Decision Agents}{UXANNADec}
-\end{page}
-
-@
-\subsection{Decision Agents}
-\label{UXANNADec}
-\begin{itemize}
-\item UXANNAInfer \ref{UXANNAInfer} on page~\pageref{UXANNAInfer}
-\item UXANNAMeth \ref{UXANNAMeth} on page~\pageref{UXANNAMeth}
-\item UXANNAMeas \ref{UXANNAMeas} on page~\pageref{UXANNAMeas}
-\item UXANNAAgent \ref{UXANNAAgent} on page~\pageref{UXANNAAgent}
-\end{itemize}
-\index{pages!UXANNADec!annaex.ht}
-\index{annaex.ht!pages!UXANNADec}
-\index{UXANNADec!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNADec}{Decision Agents}
-\begin{scroll}
-\blankline
-Some features are either present or absent in a problem.  Examples of such
-binary decisions include {\em is a matrix symmetric?} and {\em is a
-function continuous?}  However in practice many questions are about the {\em
-degree} to which a problem exhibits a property: {\em how much does a
-function oscillate?}, or {\em how stiff are these differential equations?}
-\blankline
-We have therefore created decision agents of two types, reflecting their
-property --- {\em Binary Agents} are Boolean functions returning either true
-or false and {\em Intensity Functions} are quantitative and return a range of
-different values, either numerical or structured types. The framework we are
-developing is able to deal with both these forms of information.  
-\blankline
-
-In any given problem area (for example solving ordinary differential
-equations, optimization etc.) we have a selection of {\em methods}.  These
-might be to use a particular NAG routine, or they might involve employing a
-higher-level strategy such as transforming the problem into an equivalent,
-but easier to solve, form.  
-\blankline
-Associated with every method we define a {\em
-measure function} which assesses the suitability of that method to a
-particular problem.  Each measure function has access to a range of symbolic
-{\em agents} which can answer questions about the various properties of the
-problem in hand.
-\blankline
-\end{scroll}
-\downlink{ Inference Mechanisms }{UXANNAInfer}
-\downlink{ Method Domains }{UXANNAMeth}
-\downlink{ Measure Functions }{UXANNAMeas}
-\downlink{ Computational Agents }{UXANNAAgent}
-
-\end{page}
-
-@
-\subsection{Inference Mechanisms}
-\label{UXANNAInfer}
-\begin{itemize}
-\item UXANNAMeth \ref{UXANNAMeth} on page~\pageref{UXANNAMeth}
-\item UXANNAMeas \ref{UXANNAMeas} on page~\pageref{UXANNAMeas}
-\item UXANNAAgent \ref{UXANNAAgent} on page~\pageref{UXANNAAgent}
-\item UXANNAEx \ref{UXANNAEx} on page~\pageref{UXANNAEx}
-\end{itemize}
-\index{pages!UXANNAInfer!annaex.ht}
-\index{annaex.ht!pages!UXANNAInfer}
-\index{UXANNAInfer!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAInfer}{Inference Mechanisms}
-\begin{scroll}
-\blankline
-The inference machine will take the problem description as provided by the
-user and perform an initial analysis to verify its validity.  It will
-consider, in turn, all of the available methods within its knowledge base
-which might solve that problem.  In doing so it analyses the input problem to
-find out about any attributes that could affect the ability of the methods
-under consideration to perform effectively.  
-\blankline
-Some of these
-measures may use lazy evaluation in the sense that, if a method already
-assessed is believed to be a good candidate, and if evaluating the current
-measure will be relatively expensive, then that measure will not be evaluated
-unless later evidence shows that the selected method is not, in fact, a
-successful strategy, for example if it has failed.
-\end{scroll}
-\downlink{ Method Domains }{UXANNAMeth}
-\downlink{ Measure Functions }{UXANNAMeas}
-\downlink{ Computational Agents }{UXANNAAgent}
-\downlink{ Examples }{UXANNAEx}
-\end{page}
-
-@
-\subsection{Method Domains}
-\label{UXANNAMeth}
-\begin{itemize}
-\item UXANNAMeas \ref{UXANNAMeas} on page~\pageref{UXANNAMeas}
-\item UXANNAAgent \ref{UXANNAAgent} on page~\pageref{UXANNAAgent}
-\item UXANNAEx \ref{UXANNAEx} on page~\pageref{UXANNAEx}
-\end{itemize}
-\index{pages!UXANNAMeth!annaex.ht}
-\index{annaex.ht!pages!UXANNAMeth}
-\index{UXANNAMeth!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAMeth}{Method Domains}
-\begin{scroll}
-\blankline
-An Axiom {\em domain} has been created for each method or strategy for
-solving the problem.  These method domains each implement two functions with
-a uniform (method independant) interface.
-\blankline {\bf measure:} A function which calculates an estimate of suitability of
-this particular method to the problem if there is a possibility that the
-method under consideration is more appropriate than one already investigated.
-\blankline
-If it may be possible to improve on the current favourite method, the function
-will call computational agents to analyse the problem for specific features
-and calculate the measure from the results these agents return, 
-using a variation on the Lucks/Gladwell intensity and compatibility
-model if conflict between attributes, as investigated by these computational
-agents, may be present.
-\blankline
-{\bf implementation:} A function which may be one of two distinct kinds. 
-The first kind uses the interface to the NAG Library to call a particular 
-routine with the required parameters.  Some of the parameters may need to be
-calculated from the data provided before the external function call.  
-\blankline
-The other kind will apply a ``high level'' strategy to try to solve the
-problem e.g.~a transformation of an expression from one that is difficult to
-solve to one which is easier, or a splitting of the problem into several more
-easily solvable parts.  For example, for a solution of the equation above,
-since the integral is semi-infinite we might wish to transform the range by,
-say, using the mapping {\it y -> 1/x} on the section {\it 1
-< x < \inputbitmap{\htbmdir{}/infty.xbm}}) and
-adding the result to the unmapped section {\it 0 < x < 1}.
-\blankline
-\end{scroll}
-\downlink{ Measure Functions }{UXANNAMeas}
-\downlink{ Computational Agents }{UXANNAAgent}
-\downlink{ Examples }{UXANNAEx}
-\end{page}
-
-@
-\subsection{Measure Functions}
-\label{UXANNAMeas}
-\begin{itemize}
-\item UXANNAAgent \ref{UXANNAAgent} on page~\pageref{UXANNAAgent}
-\item UXANNAEx \ref{UXANNAEx} on page~\pageref{UXANNAEx}
-\end{itemize}
-\index{pages!UXANNAMeas!annaex.ht}
-\index{annaex.ht!pages!UXANNAMeas}
-\index{UXANNAMeas!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAMeas}{Measure Functions}
-\begin{scroll}
-\blankline
-Each measure function will estimate the ability of a particular method to
-solve a problem.  It will consult whichever agents are needed to perform
-analysis on the problem in order to calculate the measure.  There is a
-parameter which would contain the best compatibility
-value found so far.  
-\blankline
-However, the interpretation we give to the results of some tests is not
-always clear-cut.  If a set of tests give
-conflicting advice as to the appropriateness of a particular method, it
-becomes important to decide not only {\it whether} certain properties are
-present but also their {\it degree}.  This gives us a basis for estimating the
-compatibility of each property.  
-\blankline
-We have taken for our model the system recommended by Lucks and Gladwell
-which uses a system of measurement of compatibility allowing for interaction
-and conflict between a number of attributes.  All of these processes may not
-be required if the choice is clear-cut e.g. we have an integral to calculate
-which has a particular singularity structure for which one particular method
-has been specifically constructed.  However, for more difficult cases a
-composite picture should be built up to calculate a true measurement. 
-\blankline
-How the compatibility functions interpret the measurements of various
-attributes is up to them and may vary between differing methods.  It is this
-area that takes as its basis the {\it judgement} of Numerical Analysis
-`experts' whether that be from the documentation (which may be deficient in
-certain respects) or from alternative sources.  However, its assessment of
-the suitability or otherwise of a particular method is reflected in a single
-normalised value facilitating the direct comparison of the suitability of a
-number of possible methods.
-\blankline
-\end{scroll}
-\downlink{ Computational Agents }{UXANNAAgent}
-\downlink{ Examples }{UXANNAEx}
-\end{page}
-
-@
-\subsection{Computational Agents}
-\label{UXANNAAgent}
-See UXANNAEx \ref{UXANNAEx} on page~\pageref{UXANNAEx}
-\index{pages!UXANNAAgent!annaex.ht}
-\index{annaex.ht!pages!UXANNAAgent}
-\index{UXANNAAgent!annaex.ht!pages}
-<<annaex.ht>>=
-\begin{page}{UXANNAAgent}{Computational Agents}
-\begin{scroll}
-\blankline
-Computational Agents are those program segments which investigate the
-attributes of the input function or functions, such as 
-{\bf stiffnessAndStabilityOfODEIF}
-(the {\em IF} indicates that it is an {\em Intensity Function} i.e. one that
-returns a normalised real number or a set of normalised real numbers).  They
-are usually functions or programs written completely in the Axiom
-language and implemented using computer algebra.
-\blankline
-Some agents will be common to more than one problem domain whereas others
-will be specific to a single domain.  They also vary greatly in their
-complexity.  It is a fairly simple task to return details about the range of
-a function since this information will have been included in the problem
-specification.  It is a different order of complexity to return details of
-its singularity structure.
-\blankline
-\xtc{
-As an example, here is a call to the computational agent {\bf
-singularitiesOf} to obtain the list of singularities of the function 
-{\it tan x} which are in the range 
-{\it 0..12\inputbitmap{\htbmdir{}/pi.xbm}}:
-\blankline
-}{
-}
-\xtc{
-}{
-\spadpaste{s := singularitiesOf(tan x,[x],0..12*\%pi)$ESCONT \free{lib3} }
-}
-\blankline
-Each of these computational agents which may be called by a number of method
-domains retain their output in a dynamic hash-table, so speeding the process
-and retaining efficiency.
-\end{scroll}
-\downlink{ Examples }{UXANNAEx}
-\end{page}
-
-@
 \section{array1.ht}
 <<array1.ht>>=
 \newcommand{\OneDimensionalArrayXmpTitle}{OneDimensionalArray}
@@ -2926,7 +2161,8 @@ operation \spadfun{oneDimensionalArray} to a list.
 \xtc{
 Another approach is to first create \spad{a}, a one-dimensional 
 array of 10 \spad{0}'s.
-\spadtype{OneDimensionalArray} has the convenient abbreviation \spadtype{ARRAY1}.
+\spadtype{OneDimensionalArray} has the convenient 
+abbreviation \spadtype{ARRAY1}.
 }{
 \spadpaste{a : ARRAY1 INT := new(10,0)\bound{a}}
 }
@@ -2957,7 +2193,8 @@ Sort the elements in place.
 \spadpaste{sort! a \bound{a6}\free{a5}}
 }
 \xtc{
-Create a new one-dimensional array \spad{b} containing the last 5 elements of \spad{a}.
+Create a new one-dimensional array \spad{b} containing the 
+last 5 elements of \spad{a}.
 }{
 \spadpaste{b := a(6..10)\bound{b}\free{a6}}
 }
@@ -2995,26 +2232,24 @@ page~pageref{OneDimensionalArrayXmpPage}
 \begin{page}{TwoDimensionalArrayXmpPage}{TwoDimensionalArray}
 \beginscroll
 
-The \spadtype{TwoDimensionalArray} domain is used for storing data in a
-\twodim{} data structure indexed by row and by column.
-Such an array is a homogeneous data structure in that all the entries of
-the array must belong to the same Axiom domain (although see
-\downlink{``\ugTypesAnyNoneTitle''}{ugTypesAnyNonePage} in 
-Section \ugTypesAnyNoneNumber\ignore{ugTypesAnyNone}).
-Each array has a fixed number of rows and columns specified by the user
-and arrays are not extensible.
-In Axiom, the indexing of two-dimensional arrays is one-based.
-This means that both the ``first'' row of an array and the ``first''
-column of an array are given the index \spad{1}.
-Thus, the entry in the upper left corner of an array is in position
+The \spadtype{TwoDimensionalArray} domain is used for storing data in
+a \twodim{} data structure indexed by row and by column.  Such an
+array is a homogeneous data structure in that all the entries of the
+array must belong to the same Axiom domain (although see
+\downlink{``\ugTypesAnyNoneTitle''}{ugTypesAnyNonePage} in Section
+\ugTypesAnyNoneNumber\ignore{ugTypesAnyNone}).  Each array has a fixed
+number of rows and columns specified by the user and arrays are not
+extensible.  In Axiom, the indexing of two-dimensional arrays is
+one-based.  This means that both the ``first'' row of an array and the
+``first'' column of an array are given the index \spad{1}.  Thus, the
+entry in the upper left corner of an array is in position
 \spad{(1,1)}.
 
 
-The operation \spadfunFrom{new}{TwoDimensionalArray} creates
-an array with a specified number of rows and columns and fills the components
-of that array with a specified entry.
-The arguments of this operation specify the number of rows, the number
-of columns, and the entry.
+The operation \spadfunFrom{new}{TwoDimensionalArray} creates an array
+with a specified number of rows and columns and fills the components
+of that array with a specified entry.  The arguments of this operation
+specify the number of rows, the number of columns, and the entry.
 \xtc{
 This creates a five-by-four array of integers, all of whose entries are
 zero.
@@ -3158,1030 +2393,14 @@ For information on related topics, see
 %
 
 @
-\section{aspex.ht}
-\subsection{Asp1 Example Code}
-\label{Asp1ExampleCode}
-\index{pages!Asp1ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp1ExampleCode}
-\index{Asp1ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp1ExampleCode}{Asp1 Example Code}
-\begin{verbatim}
-      DOUBLE PRECISION FUNCTION F(X)
-      DOUBLE PRECISION X
-      F=DSIN(X)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp10 Example Code}
-\label{Asp10ExampleCode}
-\index{pages!Asp10ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp10ExampleCode}
-\index{Asp10ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp10ExampleCode}{Asp10 Example Code}
-\begin{verbatim}
-      SUBROUTINE COEFFN(P,Q,DQDL,X,ELAM,JINT)
-      DOUBLE PRECISION ELAM,P,Q,X,DQDL
-      INTEGER JINT
-      P=1.0D0
-      Q=((-1.0D0*X**3)+ELAM*X*X-2.0D0)/(X*X)
-      DQDL=1.0D0
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-
-@
-\subsection{Asp12 Example Code}
-\label{Asp12ExampleCode}
-\index{pages!Asp12ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp12ExampleCode}
-\index{Asp12ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp12ExampleCode}{Asp12 Example Code}
-\begin{verbatim}
-      SUBROUTINE MONIT (MAXIT,IFLAG,ELAM,FINFO)
-      DOUBLE PRECISION ELAM,FINFO(15)
-      INTEGER MAXIT,IFLAG
-      IF(MAXIT.EQ.-1)THEN
-        PRINT*,"Output from Monit"
-      ENDIF
-      PRINT*,MAXIT,IFLAG,ELAM,(FINFO(I),I=1,4)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp19 Example Code}
-\label{Asp19ExampleCode}
-\index{pages!Asp19ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp19ExampleCode}
-\index{Asp19ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp19ExampleCode}{Asp19 Example Code}
-\begin{verbatim}
-      SUBROUTINE LSFUN2(M,N,XC,FVECC,FJACC,LJC)
-      DOUBLE PRECISION FVECC(M),FJACC(LJC,N),XC(N)
-      INTEGER M,N,LJC
-      INTEGER I,J
-      DO 25003 I=1,LJC
-        DO 25004 J=1,N
-          FJACC(I,J)=0.0D0
-25004   CONTINUE
-25003 CONTINUE
-      FVECC(1)=((XC(1)-0.14D0)*XC(3)+(15.0D0*XC(1)-2.1D0)*XC(2)+1.0D0)/(
-     &XC(3)+15.0D0*XC(2))
-      FVECC(2)=((XC(1)-0.18D0)*XC(3)+(7.0D0*XC(1)-1.26D0)*XC(2)+1.0D0)/(
-     &XC(3)+7.0D0*XC(2))
-      FVECC(3)=((XC(1)-0.22D0)*XC(3)+(4.333333333333333D0*XC(1)-0.953333
-     &3333333333D0)*XC(2)+1.0D0)/(XC(3)+4.333333333333333D0*XC(2))
-      FVECC(4)=((XC(1)-0.25D0)*XC(3)+(3.0D0*XC(1)-0.75D0)*XC(2)+1.0D0)/(
-     &XC(3)+3.0D0*XC(2))
-      FVECC(5)=((XC(1)-0.29D0)*XC(3)+(2.2D0*XC(1)-0.6379999999999999D0)*
-     &XC(2)+1.0D0)/(XC(3)+2.2D0*XC(2))
-      FVECC(6)=((XC(1)-0.32D0)*XC(3)+(1.666666666666667D0*XC(1)-0.533333
-     &3333333333D0)*XC(2)+1.0D0)/(XC(3)+1.666666666666667D0*XC(2))
-      FVECC(7)=((XC(1)-0.35D0)*XC(3)+(1.285714285714286D0*XC(1)-0.45D0)*
-     &XC(2)+1.0D0)/(XC(3)+1.285714285714286D0*XC(2))
-      FVECC(8)=((XC(1)-0.39D0)*XC(3)+(XC(1)-0.39D0)*XC(2)+1.0D0)/(XC(3)+
-     &XC(2))
-      FVECC(9)=((XC(1)-0.37D0)*XC(3)+(XC(1)-0.37D0)*XC(2)+1.285714285714
-     &286D0)/(XC(3)+XC(2))
-      FVECC(10)=((XC(1)-0.58D0)*XC(3)+(XC(1)-0.58D0)*XC(2)+1.66666666666
-     &6667D0)/(XC(3)+XC(2))
-      FVECC(11)=((XC(1)-0.73D0)*XC(3)+(XC(1)-0.73D0)*XC(2)+2.2D0)/(XC(3)
-     &+XC(2))
-      FVECC(12)=((XC(1)-0.96D0)*XC(3)+(XC(1)-0.96D0)*XC(2)+3.0D0)/(XC(3)
-     &+XC(2))
-      FVECC(13)=((XC(1)-1.34D0)*XC(3)+(XC(1)-1.34D0)*XC(2)+4.33333333333
-     &3333D0)/(XC(3)+XC(2))
-      FVECC(14)=((XC(1)-2.1D0)*XC(3)+(XC(1)-2.1D0)*XC(2)+7.0D0)/(XC(3)+X
-     &C(2))
-      FVECC(15)=((XC(1)-4.39D0)*XC(3)+(XC(1)-4.39D0)*XC(2)+15.0D0)/(XC(3
-     &)+XC(2))
-      FJACC(1,1)=1.0D0
-      FJACC(1,2)=-15.0D0/(XC(3)**2+30.0D0*XC(2)*XC(3)+225.0D0*XC(2)**2)
-      FJACC(1,3)=-1.0D0/(XC(3)**2+30.0D0*XC(2)*XC(3)+225.0D0*XC(2)**2)
-      FJACC(2,1)=1.0D0
-      FJACC(2,2)=-7.0D0/(XC(3)**2+14.0D0*XC(2)*XC(3)+49.0D0*XC(2)**2)
-      FJACC(2,3)=-1.0D0/(XC(3)**2+14.0D0*XC(2)*XC(3)+49.0D0*XC(2)**2)
-      FJACC(3,1)=1.0D0
-      FJACC(3,2)=((-0.1110223024625157D-15*XC(3))-4.333333333333333D0)/(
-     &XC(3)**2+8.666666666666666D0*XC(2)*XC(3)+18.77777777777778D0*XC(2)
-     &**2)
-      FJACC(3,3)=(0.1110223024625157D-15*XC(2)-1.0D0)/(XC(3)**2+8.666666
-     &666666666D0*XC(2)*XC(3)+18.77777777777778D0*XC(2)**2)
-      FJACC(4,1)=1.0D0
-      FJACC(4,2)=-3.0D0/(XC(3)**2+6.0D0*XC(2)*XC(3)+9.0D0*XC(2)**2)
-      FJACC(4,3)=-1.0D0/(XC(3)**2+6.0D0*XC(2)*XC(3)+9.0D0*XC(2)**2)
-      FJACC(5,1)=1.0D0
-      FJACC(5,2)=((-0.1110223024625157D-15*XC(3))-2.2D0)/(XC(3)**2+4.399
-     &999999999999D0*XC(2)*XC(3)+4.839999999999998D0*XC(2)**2)
-      FJACC(5,3)=(0.1110223024625157D-15*XC(2)-1.0D0)/(XC(3)**2+4.399999
-     &999999999D0*XC(2)*XC(3)+4.839999999999998D0*XC(2)**2)
-      FJACC(6,1)=1.0D0
-      FJACC(6,2)=((-0.2220446049250313D-15*XC(3))-1.666666666666667D0)/(
-     &XC(3)**2+3.333333333333333D0*XC(2)*XC(3)+2.777777777777777D0*XC(2)
-     &**2)
-      FJACC(6,3)=(0.2220446049250313D-15*XC(2)-1.0D0)/(XC(3)**2+3.333333
-     &333333333D0*XC(2)*XC(3)+2.777777777777777D0*XC(2)**2)
-      FJACC(7,1)=1.0D0
-      FJACC(7,2)=((-0.5551115123125783D-16*XC(3))-1.285714285714286D0)/(
-     &XC(3)**2+2.571428571428571D0*XC(2)*XC(3)+1.653061224489796D0*XC(2)
-     &**2)
-      FJACC(7,3)=(0.5551115123125783D-16*XC(2)-1.0D0)/(XC(3)**2+2.571428
-     &571428571D0*XC(2)*XC(3)+1.653061224489796D0*XC(2)**2)
-      FJACC(8,1)=1.0D0
-      FJACC(8,2)=-1.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(8,3)=-1.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(9,1)=1.0D0
-      FJACC(9,2)=-1.285714285714286D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)*
-     &*2)
-      FJACC(9,3)=-1.285714285714286D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)*
-     &*2)
-      FJACC(10,1)=1.0D0
-      FJACC(10,2)=-1.666666666666667D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)
-     &**2)
-      FJACC(10,3)=-1.666666666666667D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)
-     &**2)
-      FJACC(11,1)=1.0D0
-      FJACC(11,2)=-2.2D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(11,3)=-2.2D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(12,1)=1.0D0
-      FJACC(12,2)=-3.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(12,3)=-3.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(13,1)=1.0D0
-      FJACC(13,2)=-4.333333333333333D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)
-     &**2)
-      FJACC(13,3)=-4.333333333333333D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)
-     &**2)
-      FJACC(14,1)=1.0D0
-      FJACC(14,2)=-7.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(14,3)=-7.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(15,1)=1.0D0
-      FJACC(15,2)=-15.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      FJACC(15,3)=-15.0D0/(XC(3)**2+2.0D0*XC(2)*XC(3)+XC(2)**2)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp20 Example Code}
-\label{Asp20ExampleCode}
-\index{pages!Asp20ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp20ExampleCode}
-\index{Asp20ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp20ExampleCode}{Asp20 Example Code}
-\begin{verbatim}
-      SUBROUTINE QPHESS(N,NROWH,NCOLH,JTHCOL,HESS,X,HX)
-      DOUBLE PRECISION HX(N),X(N),HESS(NROWH,NCOLH)
-      INTEGER JTHCOL,N,NROWH,NCOLH
-      HX(1)=2.0D0*X(1)
-      HX(2)=2.0D0*X(2)
-      HX(3)=2.0D0*X(4)+2.0D0*X(3)
-      HX(4)=2.0D0*X(4)+2.0D0*X(3)
-      HX(5)=2.0D0*X(5)
-      HX(6)=(-2.0D0*X(7))+(-2.0D0*X(6))
-      HX(7)=(-2.0D0*X(7))+(-2.0D0*X(6))
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp24 Example Code}
-\label{Asp24ExampleCode}
-\index{pages!Asp24ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp24ExampleCode}
-\index{Asp24ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp24ExampleCode}{Asp24 Example Code}
-\begin{verbatim}
-      SUBROUTINE FUNCT1(N,XC,FC)
-      DOUBLE PRECISION FC,XC(N)
-      INTEGER N
-      FC=10.0D0*XC(4)**4+(-40.0D0*XC(1)*XC(4)**3)+(60.0D0*XC(1)**2+5
-     &.0D0)*XC(4)**2+((-10.0D0*XC(3))+(-40.0D0*XC(1)**3))*XC(4)+16.0D0*X
-     &C(3)**4+(-32.0D0*XC(2)*XC(3)**3)+(24.0D0*XC(2)**2+5.0D0)*XC(3)**2+
-     &(-8.0D0*XC(2)**3*XC(3))+XC(2)**4+100.0D0*XC(2)**2+20.0D0*XC(1)*XC(
-     &2)+10.0D0*XC(1)**4+XC(1)**2
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp27 Example Code}
-\label{Asp27ExampleCode}
-\index{pages!Asp27ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp27ExampleCode}
-\index{Asp27ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp27ExampleCode}{Asp27 Example Code}
-\begin{verbatim}
-      FUNCTION DOT(IFLAG,N,Z,W,RWORK,LRWORK,IWORK,LIWORK)
-      DOUBLE PRECISION W(N),Z(N),RWORK(LRWORK)
-      INTEGER N,LIWORK,IFLAG,LRWORK,IWORK(LIWORK)
-      DOT=(W(16)+(-0.5D0*W(15)))*Z(16)+((-0.5D0*W(16))+W(15)+(-0.5D0*W(1
-     &4)))*Z(15)+((-0.5D0*W(15))+W(14)+(-0.5D0*W(13)))*Z(14)+((-0.5D0*W(
-     &14))+W(13)+(-0.5D0*W(12)))*Z(13)+((-0.5D0*W(13))+W(12)+(-0.5D0*W(1
-     &1)))*Z(12)+((-0.5D0*W(12))+W(11)+(-0.5D0*W(10)))*Z(11)+((-0.5D0*W(
-     &11))+W(10)+(-0.5D0*W(9)))*Z(10)+((-0.5D0*W(10))+W(9)+(-0.5D0*W(8))
-     &)*Z(9)+((-0.5D0*W(9))+W(8)+(-0.5D0*W(7)))*Z(8)+((-0.5D0*W(8))+W(7)
-     &+(-0.5D0*W(6)))*Z(7)+((-0.5D0*W(7))+W(6)+(-0.5D0*W(5)))*Z(6)+((-0.
-     &5D0*W(6))+W(5)+(-0.5D0*W(4)))*Z(5)+((-0.5D0*W(5))+W(4)+(-0.5D0*W(3
-     &)))*Z(4)+((-0.5D0*W(4))+W(3)+(-0.5D0*W(2)))*Z(3)+((-0.5D0*W(3))+W(
-     &2)+(-0.5D0*W(1)))*Z(2)+((-0.5D0*W(2))+W(1))*Z(1)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp28 Example Code}
-\label{Asp28ExampleCode}
-\index{pages!Asp28ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp28ExampleCode}
-\index{Asp28ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp28ExampleCode}{Asp28 Example Code}
-\begin{verbatim}
-      SUBROUTINE IMAGE(IFLAG,N,Z,W,RWORK,LRWORK,IWORK,LIWORK)
-      DOUBLE PRECISION Z(N),W(N),IWORK(LRWORK),RWORK(LRWORK)
-      INTEGER N,LIWORK,IFLAG,LRWORK
-      W(1)=0.01707454969713436D0*Z(16)+0.001747395874954051D0*Z(15)+0.00
-     &2106973900813502D0*Z(14)+0.002957434991769087D0*Z(13)+(-0.00700554
-     &0882865317D0*Z(12))+(-0.01219194009813166D0*Z(11))+0.0037230647365
-     &3087D0*Z(10)+0.04932374658377151D0*Z(9)+(-0.03586220812223305D0*Z(
-     &8))+(-0.04723268012114625D0*Z(7))+(-0.02434652144032987D0*Z(6))+0.
-     &2264766947290192D0*Z(5)+(-0.1385343580686922D0*Z(4))+(-0.116530050
-     &8238904D0*Z(3))+(-0.2803531651057233D0*Z(2))+1.019463911841327D0*Z
-     &(1)
-      W(2)=0.0227345011107737D0*Z(16)+0.008812321197398072D0*Z(15)+0.010
-     &94012210519586D0*Z(14)+(-0.01764072463999744D0*Z(13))+(-0.01357136
-     &72105995D0*Z(12))+0.00157466157362272D0*Z(11)+0.05258889186338282D
-     &0*Z(10)+(-0.01981532388243379D0*Z(9))+(-0.06095390688679697D0*Z(8)
-     &)+(-0.04153119955569051D0*Z(7))+0.2176561076571465D0*Z(6)+(-0.0532
-     &5555586632358D0*Z(5))+(-0.1688977368984641D0*Z(4))+(-0.32440166056
-     &67343D0*Z(3))+0.9128222941872173D0*Z(2)+(-0.2419652703415429D0*Z(1
-     &))
-      W(3)=0.03371198197190302D0*Z(16)+0.02021603150122265D0*Z(15)+(-0.0
-     &06607305534689702D0*Z(14))+(-0.03032392238968179D0*Z(13))+0.002033
-     &305231024948D0*Z(12)+0.05375944956767728D0*Z(11)+(-0.0163213312502
-     &9967D0*Z(10))+(-0.05483186562035512D0*Z(9))+(-0.04901428822579872D
-     &0*Z(8))+0.2091097927887612D0*Z(7)+(-0.05760560341383113D0*Z(6))+(-
-     &0.1236679206156403D0*Z(5))+(-0.3523683853026259D0*Z(4))+0.88929961
-     &32269974D0*Z(3)+(-0.2995429545781457D0*Z(2))+(-0.02986582812574917
-     &D0*Z(1))
-      W(4)=0.05141563713660119D0*Z(16)+0.005239165960779299D0*Z(15)+(-0.
-     &01623427735779699D0*Z(14))+(-0.01965809746040371D0*Z(13))+0.054688
-     &97337339577D0*Z(12)+(-0.014224695935687D0*Z(11))+(-0.0505181779315
-     &6355D0*Z(10))+(-0.04353074206076491D0*Z(9))+0.2012230497530726D0*Z
-     &(8)+(-0.06630874514535952D0*Z(7))+(-0.1280829963720053D0*Z(6))+(-0
-     &.305169742604165D0*Z(5))+0.8600427128450191D0*Z(4)+(-0.32415033802
-     &68184D0*Z(3))+(-0.09033531980693314D0*Z(2))+0.09089205517109111D0*
-     &Z(1)
-      W(5)=0.04556369767776375D0*Z(16)+(-0.001822737697581869D0*Z(15))+(
-     &-0.002512226501941856D0*Z(14))+0.02947046460707379D0*Z(13)+(-0.014
-     &45079632086177D0*Z(12))+(-0.05034242196614937D0*Z(11))+(-0.0376966
-     &3291725935D0*Z(10))+0.2171103102175198D0*Z(9)+(-0.0824949256021352
-     &4D0*Z(8))+(-0.1473995209288945D0*Z(7))+(-0.315042193418466D0*Z(6))
-     &+0.9591623347824002D0*Z(5)+(-0.3852396953763045D0*Z(4))+(-0.141718
-     &5427288274D0*Z(3))+(-0.03423495461011043D0*Z(2))+0.319820917706851
-     &6D0*Z(1)
-      W(6)=0.04015147277405744D0*Z(16)+0.01328585741341559D0*Z(15)+0.048
-     &26082005465965D0*Z(14)+(-0.04319641116207706D0*Z(13))+(-0.04931323
-     &319055762D0*Z(12))+(-0.03526886317505474D0*Z(11))+0.22295383396730
-     &01D0*Z(10)+(-0.07375317649315155D0*Z(9))+(-0.1589391311991561D0*Z(
-     &8))+(-0.328001910890377D0*Z(7))+0.952576555482747D0*Z(6)+(-0.31583
-     &09975786731D0*Z(5))+(-0.1846882042225383D0*Z(4))+(-0.0703762046700
-     &4427D0*Z(3))+0.2311852964327382D0*Z(2)+0.04254083491825025D0*Z(1)
-      W(7)=0.06069778964023718D0*Z(16)+0.06681263884671322D0*Z(15)+(-0.0
-     &2113506688615768D0*Z(14))+(-0.083996867458326D0*Z(13))+(-0.0329843
-     &8523869648D0*Z(12))+0.2276878326327734D0*Z(11)+(-0.067356038933017
-     &95D0*Z(10))+(-0.1559813965382218D0*Z(9))+(-0.3363262957694705D0*Z(
-     &8))+0.9442791158560948D0*Z(7)+(-0.3199955249404657D0*Z(6))+(-0.136
-     &2463839920727D0*Z(5))+(-0.1006185171570586D0*Z(4))+0.2057504515015
-     &423D0*Z(3)+(-0.02065879269286707D0*Z(2))+0.03160990266745513D0*Z(1
-     &)
-      W(8)=0.126386868896738D0*Z(16)+0.002563370039476418D0*Z(15)+(-0.05
-     &581757739455641D0*Z(14))+(-0.07777893205900685D0*Z(13))+0.23117338
-     &45834199D0*Z(12)+(-0.06031581134427592D0*Z(11))+(-0.14805474755869
-     &52D0*Z(10))+(-0.3364014128402243D0*Z(9))+0.9364014128402244D0*Z(8)
-     &+(-0.3269452524413048D0*Z(7))+(-0.1396841886557241D0*Z(6))+(-0.056
-     &1733845834199D0*Z(5))+0.1777789320590069D0*Z(4)+(-0.04418242260544
-     &359D0*Z(3))+(-0.02756337003947642D0*Z(2))+0.07361313110326199D0*Z(
-     &1)
-      W(9)=0.07361313110326199D0*Z(16)+(-0.02756337003947642D0*Z(15))+(-
-     &0.04418242260544359D0*Z(14))+0.1777789320590069D0*Z(13)+(-0.056173
-     &3845834199D0*Z(12))+(-0.1396841886557241D0*Z(11))+(-0.326945252441
-     &3048D0*Z(10))+0.9364014128402244D0*Z(9)+(-0.3364014128402243D0*Z(8
-     &))+(-0.1480547475586952D0*Z(7))+(-0.06031581134427592D0*Z(6))+0.23
-     &11733845834199D0*Z(5)+(-0.07777893205900685D0*Z(4))+(-0.0558175773
-     &9455641D0*Z(3))+0.002563370039476418D0*Z(2)+0.126386868896738D0*Z(
-     &1)
-      W(10)=0.03160990266745513D0*Z(16)+(-0.02065879269286707D0*Z(15))+0
-     &.2057504515015423D0*Z(14)+(-0.1006185171570586D0*Z(13))+(-0.136246
-     &3839920727D0*Z(12))+(-0.3199955249404657D0*Z(11))+0.94427911585609
-     &48D0*Z(10)+(-0.3363262957694705D0*Z(9))+(-0.1559813965382218D0*Z(8
-     &))+(-0.06735603893301795D0*Z(7))+0.2276878326327734D0*Z(6)+(-0.032
-     &98438523869648D0*Z(5))+(-0.083996867458326D0*Z(4))+(-0.02113506688
-     &615768D0*Z(3))+0.06681263884671322D0*Z(2)+0.06069778964023718D0*Z(
-     &1)
-      W(11)=0.04254083491825025D0*Z(16)+0.2311852964327382D0*Z(15)+(-0.0
-     &7037620467004427D0*Z(14))+(-0.1846882042225383D0*Z(13))+(-0.315830
-     &9975786731D0*Z(12))+0.952576555482747D0*Z(11)+(-0.328001910890377D
-     &0*Z(10))+(-0.1589391311991561D0*Z(9))+(-0.07375317649315155D0*Z(8)
-     &)+0.2229538339673001D0*Z(7)+(-0.03526886317505474D0*Z(6))+(-0.0493
-     &1323319055762D0*Z(5))+(-0.04319641116207706D0*Z(4))+0.048260820054
-     &65965D0*Z(3)+0.01328585741341559D0*Z(2)+0.04015147277405744D0*Z(1)
-      W(12)=0.3198209177068516D0*Z(16)+(-0.03423495461011043D0*Z(15))+(-
-     &0.1417185427288274D0*Z(14))+(-0.3852396953763045D0*Z(13))+0.959162
-     &3347824002D0*Z(12)+(-0.315042193418466D0*Z(11))+(-0.14739952092889
-     &45D0*Z(10))+(-0.08249492560213524D0*Z(9))+0.2171103102175198D0*Z(8
-     &)+(-0.03769663291725935D0*Z(7))+(-0.05034242196614937D0*Z(6))+(-0.
-     &01445079632086177D0*Z(5))+0.02947046460707379D0*Z(4)+(-0.002512226
-     &501941856D0*Z(3))+(-0.001822737697581869D0*Z(2))+0.045563697677763
-     &75D0*Z(1)
-      W(13)=0.09089205517109111D0*Z(16)+(-0.09033531980693314D0*Z(15))+(
-     &-0.3241503380268184D0*Z(14))+0.8600427128450191D0*Z(13)+(-0.305169
-     &742604165D0*Z(12))+(-0.1280829963720053D0*Z(11))+(-0.0663087451453
-     &5952D0*Z(10))+0.2012230497530726D0*Z(9)+(-0.04353074206076491D0*Z(
-     &8))+(-0.05051817793156355D0*Z(7))+(-0.014224695935687D0*Z(6))+0.05
-     &468897337339577D0*Z(5)+(-0.01965809746040371D0*Z(4))+(-0.016234277
-     &35779699D0*Z(3))+0.005239165960779299D0*Z(2)+0.05141563713660119D0
-     &*Z(1)
-      W(14)=(-0.02986582812574917D0*Z(16))+(-0.2995429545781457D0*Z(15))
-     &+0.8892996132269974D0*Z(14)+(-0.3523683853026259D0*Z(13))+(-0.1236
-     &679206156403D0*Z(12))+(-0.05760560341383113D0*Z(11))+0.20910979278
-     &87612D0*Z(10)+(-0.04901428822579872D0*Z(9))+(-0.05483186562035512D
-     &0*Z(8))+(-0.01632133125029967D0*Z(7))+0.05375944956767728D0*Z(6)+0
-     &.002033305231024948D0*Z(5)+(-0.03032392238968179D0*Z(4))+(-0.00660
-     &7305534689702D0*Z(3))+0.02021603150122265D0*Z(2)+0.033711981971903
-     &02D0*Z(1)
-      W(15)=(-0.2419652703415429D0*Z(16))+0.9128222941872173D0*Z(15)+(-0
-     &.3244016605667343D0*Z(14))+(-0.1688977368984641D0*Z(13))+(-0.05325
-     &555586632358D0*Z(12))+0.2176561076571465D0*Z(11)+(-0.0415311995556
-     &9051D0*Z(10))+(-0.06095390688679697D0*Z(9))+(-0.01981532388243379D
-     &0*Z(8))+0.05258889186338282D0*Z(7)+0.00157466157362272D0*Z(6)+(-0.
-     &0135713672105995D0*Z(5))+(-0.01764072463999744D0*Z(4))+0.010940122
-     &10519586D0*Z(3)+0.008812321197398072D0*Z(2)+0.0227345011107737D0*Z
-     &(1)
-      W(16)=1.019463911841327D0*Z(16)+(-0.2803531651057233D0*Z(15))+(-0.
-     &1165300508238904D0*Z(14))+(-0.1385343580686922D0*Z(13))+0.22647669
-     &47290192D0*Z(12)+(-0.02434652144032987D0*Z(11))+(-0.04723268012114
-     &625D0*Z(10))+(-0.03586220812223305D0*Z(9))+0.04932374658377151D0*Z
-     &(8)+0.00372306473653087D0*Z(7)+(-0.01219194009813166D0*Z(6))+(-0.0
-     &07005540882865317D0*Z(5))+0.002957434991769087D0*Z(4)+0.0021069739
-     &00813502D0*Z(3)+0.001747395874954051D0*Z(2)+0.01707454969713436D0*
-     &Z(1)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp29 Example Code}
-\label{Asp29ExampleCode}
-\index{pages!Asp29ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp29ExampleCode}
-\index{Asp29ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp29ExampleCode}{Asp29 Example Code}
-\begin{verbatim}
-      SUBROUTINE MONIT(ISTATE,NEXTIT,NEVALS,NEVECS,K,F,D)
-      DOUBLE PRECISION D(K),F(K)
-      INTEGER K,NEXTIT,NEVALS,NVECS,ISTATE
-      CALL F02FJZ(ISTATE,NEXTIT,NEVALS,NEVECS,K,F,D)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp30 Example Code}
-\label{Asp30ExampleCode}
-\index{pages!Asp30ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp30ExampleCode}
-\index{Asp30ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp30ExampleCode}{Asp30 Example Code}
-\begin{verbatim}
-      SUBROUTINE APROD(MODE,M,N,X,Y,RWORK,LRWORK,IWORK,LIWORK)
-      DOUBLE PRECISION X(N),Y(M),RWORK(LRWORK)
-      INTEGER M,N,LIWORK,IFAIL,LRWORK,IWORK(LIWORK),MODE
-      DOUBLE PRECISION A(5,5)
-      EXTERNAL F06PAF
-      A(1,1)=1.0D0
-      A(1,2)=0.0D0
-      A(1,3)=0.0D0
-      A(1,4)=-1.0D0
-      A(1,5)=0.0D0
-      A(2,1)=0.0D0
-      A(2,2)=1.0D0
-      A(2,3)=0.0D0
-      A(2,4)=0.0D0
-      A(2,5)=-1.0D0
-      A(3,1)=0.0D0
-      A(3,2)=0.0D0
-      A(3,3)=1.0D0
-      A(3,4)=-1.0D0
-      A(3,5)=0.0D0
-      A(4,1)=-1.0D0
-      A(4,2)=0.0D0
-      A(4,3)=-1.0D0
-      A(4,4)=4.0D0
-      A(4,5)=-1.0D0
-      A(5,1)=0.0D0
-      A(5,2)=-1.0D0
-      A(5,3)=0.0D0
-      A(5,4)=-1.0D0
-      A(5,5)=4.0D0
-      IF(MODE.EQ.1)THEN
-        CALL F06PAF('N',M,N,1.0D0,A,M,X,1,1.0D0,Y,1)
-      ELSEIF(MODE.EQ.2)THEN
-        CALL F06PAF('T',M,N,1.0D0,A,M,Y,1,1.0D0,X,1)
-      ENDIF
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp31 Example Code}
-\label{Asp31ExampleCode}
-\index{pages!Asp31ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp31ExampleCode}
-\index{Asp31ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp31ExampleCode}{Asp31 Example Code}
-\begin{verbatim}
-      SUBROUTINE PEDERV(X,Y,PW)
-      DOUBLE PRECISION X,Y(*)
-      DOUBLE PRECISION PW(3,3)
-      PW(1,1)=-0.03999999999999999D0
-      PW(1,2)=10000.0D0*Y(3)
-      PW(1,3)=10000.0D0*Y(2)
-      PW(2,1)=0.03999999999999999D0
-      PW(2,2)=(-10000.0D0*Y(3))+(-60000000.0D0*Y(2))
-      PW(2,3)=-10000.0D0*Y(2)
-      PW(3,1)=0.0D0
-      PW(3,2)=60000000.0D0*Y(2)
-      PW(3,3)=0.0D0
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp33 Example Code}
-\label{Asp33ExampleCode}
-\index{pages!Asp33ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp33ExampleCode}
-\index{Asp33ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp33ExampleCode}{Asp33 Example Code}
-\begin{verbatim}
-      SUBROUTINE REPORT(X,V,JINT)
-      DOUBLE PRECISION V(3),X
-      INTEGER JINT
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp34 Example Code}
-\label{Asp34ExampleCode}
-\index{pages!Asp34ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp34ExampleCode}
-\index{Asp34ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp34ExampleCode}{Asp34 Example Code}
-\begin{verbatim}
-      SUBROUTINE MSOLVE(IFLAG,N,X,Y,RWORK,LRWORK,IWORK,LIWORK)
-      DOUBLE PRECISION RWORK(LRWORK),X(N),Y(N)
-      INTEGER I,J,N,LIWORK,IFLAG,LRWORK,IWORK(LIWORK)
-      DOUBLE PRECISION W1(3),W2(3),MS(3,3)
-      IFLAG=-1
-      MS(1,1)=2.0D0
-      MS(1,2)=1.0D0
-      MS(1,3)=0.0D0
-      MS(2,1)=1.0D0
-      MS(2,2)=2.0D0
-      MS(2,3)=1.0D0
-      MS(3,1)=0.0D0
-      MS(3,2)=1.0D0
-      MS(3,3)=2.0D0
-      CALL F04ASF(MS,N,X,N,Y,W1,W2,IFLAG)
-      IFLAG=-IFLAG
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp35 Example Code}
-\label{Asp35ExampleCode}
-\index{pages!Asp35ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp35ExampleCode}
-\index{Asp35ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp35ExampleCode}{Asp35 Example Code}
-\begin{verbatim}
-      SUBROUTINE FCN(N,X,FVEC,FJAC,LDFJAC,IFLAG)
-      DOUBLE PRECISION X(N),FVEC(N),FJAC(LDFJAC,N)
-      INTEGER LDFJAC,N,IFLAG
-      IF(IFLAG.EQ.1)THEN
-        FVEC(1)=(-1.0D0*X(2))+X(1)
-        FVEC(2)=(-1.0D0*X(3))+2.0D0*X(2)
-        FVEC(3)=3.0D0*X(3)
-      ELSEIF(IFLAG.EQ.2)THEN
-        FJAC(1,1)=1.0D0
-        FJAC(1,2)=-1.0D0
-        FJAC(1,3)=0.0D0
-        FJAC(2,1)=0.0D0
-        FJAC(2,2)=2.0D0
-        FJAC(2,3)=-1.0D0
-        FJAC(3,1)=0.0D0
-        FJAC(3,2)=0.0D0
-        FJAC(3,3)=3.0D0
-      ENDIF
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp4 Example Code}
-\label{Asp4ExampleCode}
-\index{pages!Asp4ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp4ExampleCode}
-\index{Asp4ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp4ExampleCode}{Asp4 Example Code}
-\begin{verbatim}
-      DOUBLE PRECISION FUNCTION FUNCTN(NDIM,X)
-      DOUBLE PRECISION X(NDIM)
-      INTEGER NDIM
-      FUNCTN=(4.0D0*X(1)*X(3)**2*DEXP(2.0D0*X(1)*X(3)))/(X(4)**2+(2.0D0*
-     &X(2)+2.0D0)*X(4)+X(2)**2+2.0D0*X(2)+1.0D0)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp41 Example Code}
-\label{Asp41ExampleCode}
-\index{pages!Asp41ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp41ExampleCode}
-\index{Asp41ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp41ExampleCode}{Asp41 Example Code}
-\begin{verbatim}
-      SUBROUTINE FCN(X,EPS,Y,F,N)
-      DOUBLE PRECISION EPS,F(N),X,Y(N)
-      INTEGER N
-      F(1)=Y(2)
-      F(2)=Y(3)
-      F(3)=(-1.0D0*Y(1)*Y(3))+2.0D0*EPS*Y(2)**2+(-2.0D0*EPS)
-      RETURN
-      END
-      SUBROUTINE JACOBF(X,EPS,Y,F,N)
-      DOUBLE PRECISION EPS,F(N,N),X,Y(N)
-      INTEGER N
-      F(1,1)=0.0D0
-      F(1,2)=1.0D0
-      F(1,3)=0.0D0
-      F(2,1)=0.0D0
-      F(2,2)=0.0D0
-      F(2,3)=1.0D0
-      F(3,1)=-1.0D0*Y(3)
-      F(3,2)=4.0D0*EPS*Y(2)
-      F(3,3)=-1.0D0*Y(1)
-      RETURN
-      END
-      SUBROUTINE JACEPS(X,EPS,Y,F,N)
-      DOUBLE PRECISION EPS,F(N),X,Y(N)
-      INTEGER N
-      F(1)=0.0D0
-      F(2)=0.0D0
-      F(3)=2.0D0*Y(2)**2-2.0D0
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp42 Example Code}
-\label{Asp42ExampleCode}
-\index{pages!Asp42ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp42ExampleCode}
-\index{Asp42ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp42ExampleCode}{Asp42 Example Code}
-\begin{verbatim}
-      SUBROUTINE G(EPS,YA,YB,BC,N)
-      DOUBLE PRECISION EPS,YA(N),YB(N),BC(N)
-      INTEGER N
-      BC(1)=YA(1)
-      BC(2)=YA(2)
-      BC(3)=YB(2)-1.0D0
-      RETURN
-      END
-      SUBROUTINE JACOBG(EPS,YA,YB,AJ,BJ,N)
-      DOUBLE PRECISION EPS,YA(N),AJ(N,N),BJ(N,N),YB(N)
-      INTEGER N
-      AJ(1,1)=1.0D0
-      AJ(1,2)=0.0D0
-      AJ(1,3)=0.0D0
-      AJ(2,1)=0.0D0
-      AJ(2,2)=1.0D0
-      AJ(2,3)=0.0D0
-      AJ(3,1)=0.0D0
-      AJ(3,2)=0.0D0
-      AJ(3,3)=0.0D0
-      BJ(1,1)=0.0D0
-      BJ(1,2)=0.0D0
-      BJ(1,3)=0.0D0
-      BJ(2,1)=0.0D0
-      BJ(2,2)=0.0D0
-      BJ(2,3)=0.0D0
-      BJ(3,1)=0.0D0
-      BJ(3,2)=1.0D0
-      BJ(3,3)=0.0D0
-      RETURN
-      END
-      SUBROUTINE JACGEP(EPS,YA,YB,BCEP,N)
-      DOUBLE PRECISION EPS,YA(N),YB(N),BCEP(N)
-      INTEGER N
-      BCEP(1)=0.0D0
-      BCEP(2)=0.0D0
-      BCEP(3)=0.0D0
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp49 Example Code}
-\label{Asp49ExampleCode}
-\index{pages!Asp49ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp49ExampleCode}
-\index{Asp49ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp49ExampleCode}{Asp49 Example Code}
-\begin{verbatim}
-      SUBROUTINE OBJFUN(MODE,N,X,OBJF,OBJGRD,NSTATE,IUSER,USER)
-      DOUBLE PRECISION X(N),OBJF,OBJGRD(N),USER(*)
-      INTEGER N,IUSER(*),MODE,NSTATE
-      OBJF=X(4)*X(9)+((-1.0D0*X(5))+X(3))*X(8)+((-1.0D0*X(3))+X(1))*X(7)
-     &+(-1.0D0*X(2)*X(6))
-      OBJGRD(1)=X(7)
-      OBJGRD(2)=-1.0D0*X(6)
-      OBJGRD(3)=X(8)+(-1.0D0*X(7))
-      OBJGRD(4)=X(9)
-      OBJGRD(5)=-1.0D0*X(8)
-      OBJGRD(6)=-1.0D0*X(2)
-      OBJGRD(7)=(-1.0D0*X(3))+X(1)
-      OBJGRD(8)=(-1.0D0*X(5))+X(3)
-      OBJGRD(9)=X(4)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp50 Example Code}
-\label{Asp50ExampleCode}
-\index{pages!Asp50ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp50ExampleCode}
-\index{Asp50ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp50ExampleCode}{Asp50 Example Code}
-\begin{verbatim}
-      SUBROUTINE LSFUN1(M,N,XC,FVECC)
-      DOUBLE PRECISION FVECC(M),XC(N)
-      INTEGER I,M,N
-      FVECC(1)=((XC(1)-2.4D0)*XC(3)+(15.0D0*XC(1)-36.0D0)*XC(2)+1.0D0)/(
-     &XC(3)+15.0D0*XC(2))
-      FVECC(2)=((XC(1)-2.8D0)*XC(3)+(7.0D0*XC(1)-19.6D0)*XC(2)+1.0D0)/(X
-     &C(3)+7.0D0*XC(2))
-      FVECC(3)=((XC(1)-3.2D0)*XC(3)+(4.333333333333333D0*XC(1)-13.866666
-     &66666667D0)*XC(2)+1.0D0)/(XC(3)+4.333333333333333D0*XC(2))
-      FVECC(4)=((XC(1)-3.5D0)*XC(3)+(3.0D0*XC(1)-10.5D0)*XC(2)+1.0D0)/(X
-     &C(3)+3.0D0*XC(2))
-      FVECC(5)=((XC(1)-3.9D0)*XC(3)+(2.2D0*XC(1)-8.579999999999998D0)*XC
-     &(2)+1.0D0)/(XC(3)+2.2D0*XC(2))
-      FVECC(6)=((XC(1)-4.199999999999999D0)*XC(3)+(1.666666666666667D0*X
-     &C(1)-7.0D0)*XC(2)+1.0D0)/(XC(3)+1.666666666666667D0*XC(2))
-      FVECC(7)=((XC(1)-4.5D0)*XC(3)+(1.285714285714286D0*XC(1)-5.7857142
-     &85714286D0)*XC(2)+1.0D0)/(XC(3)+1.285714285714286D0*XC(2))
-      FVECC(8)=((XC(1)-4.899999999999999D0)*XC(3)+(XC(1)-4.8999999999999
-     &99D0)*XC(2)+1.0D0)/(XC(3)+XC(2))
-      FVECC(9)=((XC(1)-4.699999999999999D0)*XC(3)+(XC(1)-4.6999999999999
-     &99D0)*XC(2)+1.285714285714286D0)/(XC(3)+XC(2))
-      FVECC(10)=((XC(1)-6.8D0)*XC(3)+(XC(1)-6.8D0)*XC(2)+1.6666666666666
-     &67D0)/(XC(3)+XC(2))
-      FVECC(11)=((XC(1)-8.299999999999999D0)*XC(3)+(XC(1)-8.299999999999
-     &999D0)*XC(2)+2.2D0)/(XC(3)+XC(2))
-      FVECC(12)=((XC(1)-10.6D0)*XC(3)+(XC(1)-10.6D0)*XC(2)+3.0D0)/(XC(3)
-     &+XC(2))
-      FVECC(13)=((XC(1)-1.34D0)*XC(3)+(XC(1)-1.34D0)*XC(2)+4.33333333333
-     &3333D0)/(XC(3)+XC(2))
-      FVECC(14)=((XC(1)-2.1D0)*XC(3)+(XC(1)-2.1D0)*XC(2)+7.0D0)/(XC(3)+X
-     &C(2))
-      FVECC(15)=((XC(1)-4.39D0)*XC(3)+(XC(1)-4.39D0)*XC(2)+15.0D0)/(XC(3
-     &)+XC(2))
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp55 Example Code}
-\label{Asp55ExampleCode}
-\index{pages!Asp55ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp55ExampleCode}
-\index{Asp55ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp55ExampleCode}{Asp55 Example Code}
-\begin{verbatim}
-      SUBROUTINE CONFUN(MODE,NCNLN,N,NROWJ,NEEDC,X,C,CJAC,NSTATE,IUSER
-     &,USER)
-      DOUBLE PRECISION C(NCNLN),X(N),CJAC(NROWJ,N),USER(*)
-      INTEGER N,IUSER(*),NEEDC(NCNLN),NROWJ,MODE,NCNLN,NSTATE
-      IF(NEEDC(1).GT.0)THEN
-        C(1)=X(6)**2+X(1)**2
-        CJAC(1,1)=2.0D0*X(1)
-        CJAC(1,2)=0.0D0
-        CJAC(1,3)=0.0D0
-        CJAC(1,4)=0.0D0
-        CJAC(1,5)=0.0D0
-        CJAC(1,6)=2.0D0*X(6)
-      ENDIF
-      IF(NEEDC(2).GT.0)THEN
-        C(2)=X(2)**2+(-2.0D0*X(1)*X(2))+X(1)**2
-        CJAC(2,1)=(-2.0D0*X(2))+2.0D0*X(1)
-        CJAC(2,2)=2.0D0*X(2)+(-2.0D0*X(1))
-        CJAC(2,3)=0.0D0
-        CJAC(2,4)=0.0D0
-        CJAC(2,5)=0.0D0
-        CJAC(2,6)=0.0D0
-      ENDIF
-      IF(NEEDC(3).GT.0)THEN
-        C(3)=X(3)**2+(-2.0D0*X(1)*X(3))+X(2)**2+X(1)**2
-        CJAC(3,1)=(-2.0D0*X(3))+2.0D0*X(1)
-        CJAC(3,2)=2.0D0*X(2)
-        CJAC(3,3)=2.0D0*X(3)+(-2.0D0*X(1))
-        CJAC(3,4)=0.0D0
-        CJAC(3,5)=0.0D0
-        CJAC(3,6)=0.0D0
-      ENDIF
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp6 Example Code}
-\label{Asp6ExampleCode}
-\index{pages!Asp6ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp6ExampleCode}
-\index{Asp6ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp6ExampleCode}{Asp6 Example Code}
-\begin{verbatim}
-      SUBROUTINE FCN(N,X,FVEC,IFLAG)
-      DOUBLE PRECISION X(N),FVEC(N)
-      INTEGER N,IFLAG
-      FVEC(1)=(-2.0D0*X(2))+(-2.0D0*X(1)**2)+3.0D0*X(1)+1.0D0
-      FVEC(2)=(-2.0D0*X(3))+(-2.0D0*X(2)**2)+3.0D0*X(2)+(-1.0D0*X(1))+1.
-     &0D0
-      FVEC(3)=(-2.0D0*X(4))+(-2.0D0*X(3)**2)+3.0D0*X(3)+(-1.0D0*X(2))+1.
-     &0D0
-      FVEC(4)=(-2.0D0*X(5))+(-2.0D0*X(4)**2)+3.0D0*X(4)+(-1.0D0*X(3))+1.
-     &0D0
-      FVEC(5)=(-2.0D0*X(6))+(-2.0D0*X(5)**2)+3.0D0*X(5)+(-1.0D0*X(4))+1.
-     &0D0
-      FVEC(6)=(-2.0D0*X(7))+(-2.0D0*X(6)**2)+3.0D0*X(6)+(-1.0D0*X(5))+1.
-     &0D0
-      FVEC(7)=(-2.0D0*X(8))+(-2.0D0*X(7)**2)+3.0D0*X(7)+(-1.0D0*X(6))+1.
-     &0D0
-      FVEC(8)=(-2.0D0*X(9))+(-2.0D0*X(8)**2)+3.0D0*X(8)+(-1.0D0*X(7))+1.
-     &0D0
-      FVEC(9)=(-2.0D0*X(9)**2)+3.0D0*X(9)+(-1.0D0*X(8))+1.0D0
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp7 Example Code}
-\label{Asp7ExampleCode}
-\index{pages!Asp7ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp7ExampleCode}
-\index{Asp7ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp7ExampleCode}{Asp7 Example Code}
-\begin{verbatim}
-      SUBROUTINE FCN(X,Z,F)
-      DOUBLE PRECISION F(*),X,Z(*)
-      F(1)=DTAN(Z(3))
-      F(2)=((-0.03199999999999999D0*DCOS(Z(3))*DTAN(Z(3)))+(-0.02D0*Z(2)
-     &**2))/(Z(2)*DCOS(Z(3)))
-      F(3)=-0.03199999999999999D0/(X*Z(2)**2)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp73 Example Code}
-\label{Asp73ExampleCode}
-\index{pages!Asp73ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp73ExampleCode}
-\index{Asp73ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp73ExampleCode}{Asp73 Example Code}
-\begin{verbatim}
-      SUBROUTINE PDEF(X,Y,ALPHA,BETA,GAMMA,DELTA,EPSOLN,PHI,PSI)
-      DOUBLE PRECISION ALPHA,EPSOLN,PHI,X,Y,BETA,DELTA,GAMMA,PSI
-      ALPHA=DSIN(X)
-      BETA=Y
-      GAMMA=X*Y
-      DELTA=DCOS(X)*DSIN(Y)
-      EPSOLN=Y+X
-      PHI=X
-      PSI=Y
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp74 Example Code}
-\label{Asp74ExampleCode}
-\index{pages!Asp74ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp74ExampleCode}
-\index{Asp74ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp74ExampleCode}{Asp74 Example Code}
-\begin{verbatim}
-      SUBROUTINE BNDY(X,Y,A,B,C,IBND)
-      DOUBLE PRECISION A,B,C,X,Y
-      INTEGER IBND
-      IF(IBND.EQ.0)THEN
-        A=0.0D0
-        B=1.0D0
-        C=-1.0D0*DSIN(X)
-      ELSEIF(IBND.EQ.1)THEN
-        A=1.0D0
-        B=0.0D0
-        C=DSIN(X)*DSIN(Y)
-      ELSEIF(IBND.EQ.2)THEN
-        A=1.0D0
-        B=0.0D0
-        C=DSIN(X)*DSIN(Y)
-      ELSEIF(IBND.EQ.3)THEN
-        A=0.0D0
-        B=1.0D0
-        C=-1.0D0*DSIN(Y)
-      ENDIF
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp77 Example Code}
-\label{Asp77ExampleCode}
-\index{pages!Asp77ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp77ExampleCode}
-\index{Asp77ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp77ExampleCode}{Asp77 Example Code}
-\begin{verbatim}
-      SUBROUTINE FCNF(X,F)
-      DOUBLE PRECISION X
-      DOUBLE PRECISION F(2,2)
-      F(1,1)=0.0D0
-      F(1,2)=1.0D0
-      F(2,1)=0.0D0
-      F(2,2)=-10.0D0
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp78 Example Code}
-\label{Asp78ExampleCode}
-\index{pages!Asp78ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp78ExampleCode}
-\index{Asp78ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp78ExampleCode}{Asp78 Example Code}
-\begin{verbatim}
-      SUBROUTINE FCNG(X,G)
-      DOUBLE PRECISION G(*),X
-      G(1)=0.0D0
-      G(2)=0.0D0
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp8 Example Code}
-\label{Asp8ExampleCode}
-\index{pages!Asp8ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp8ExampleCode}
-\index{Asp8ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp8ExampleCode}{Asp8 Example Code}
-\begin{verbatim}
-      SUBROUTINE OUTPUT(XSOL,Y,COUNT,M,N,RESULT,FORWRD)
-      DOUBLE PRECISION Y(N),RESULT(M,N),XSOL
-      INTEGER M,N,COUNT
-      LOGICAL FORWRD
-      DOUBLE PRECISION X02ALF,POINTS(8)
-      EXTERNAL X02ALF
-      INTEGER I
-      POINTS(1)=1.0D0
-      POINTS(2)=2.0D0
-      POINTS(3)=3.0D0
-      POINTS(4)=4.0D0
-      POINTS(5)=5.0D0
-      POINTS(6)=6.0D0
-      POINTS(7)=7.0D0
-      POINTS(8)=8.0D0
-      COUNT=COUNT+1
-      DO 25001 I=1,N
-        RESULT(COUNT,I)=Y(I)
-25001 CONTINUE
-      IF(COUNT.EQ.M)THEN
-        IF(FORWRD)THEN
-          XSOL=X02ALF()
-        ELSE
-          XSOL=-X02ALF()
-        ENDIF
-      ELSE
-        XSOL=POINTS(COUNT)
-      ENDIF
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp80 Example Code}
-\label{Asp80ExampleCode}
-\index{pages!Asp80ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp80ExampleCode}
-\index{Asp80ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp80ExampleCode}{Asp80 Example Code}
-\begin{verbatim}
-      SUBROUTINE BDYVAL(XL,XR,ELAM,YL,YR)
-      DOUBLE PRECISION ELAM,XL,YL(3),XR,YR(3)
-      YL(1)=XL
-      YL(2)=2.0D0
-      YR(1)=1.0D0
-      YR(2)=-1.0D0*DSQRT(XR+(-1.0D0*ELAM))
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
-\subsection{Asp9 Example Code}
-\label{Asp9ExampleCode}
-\index{pages!Asp9ExampleCode!aspex.ht}
-\index{aspex.ht!pages!Asp9ExampleCode}
-\index{Asp9ExampleCode!aspex.ht!pages}
-<<aspex.ht>>=
-\begin{page}{Asp9ExampleCode}{Asp9 Example Code}
-\begin{verbatim}
-      DOUBLE PRECISION FUNCTION G(X,Y)
-      DOUBLE PRECISION X,Y(*)
-      G=X+Y(1)
-      RETURN
-      END
-\end{verbatim}
-\end{page}
-
-@
 \section{basic.ht}
 \subsection{Basic Commands}
 \label{BasicCommand}
 \includegraphics[scale=.5]{ps/v71basiccommand.eps}
 \index{images!basiccommand}
 
+Called from ``Root Page'' (RootPage) \ref{RootPage} on page~\pageref{RootPage}
+
 See Calculus \ref{Calculus} on page~\pageref{Calculus}.
 
 The other links on the page call lisp code. 
@@ -4222,6 +2441,11 @@ The other links on the page call lisp code.
 @
 \subsection{Calculus}
 \label{Calculus}
+\includegraphics[scale=.5]{ps/v71calculus.eps}
+\index{images!calculus}
+
+Called from ``Basic Commands'' \ref{BasicCommand} on 
+page~\pageref{BasicCommand}
 \index{pages!Calculus!basic.ht}
 \index{basic.ht!pages!Calculus}
 \index{Calculus!basic.ht!pages}
@@ -4243,7 +2467,8 @@ The other links on the page call lisp code.
 What would you like to do?
 \beginmenu
 \menulispdownlink{Differentiate}{(|bcDifferentiate|)}\space{}
-\menulispdownlink{Do an Indefinite Integral}{(|bcIndefiniteIntegrate|)}\space{}
+\menulispdownlink{Do an Indefinite Integral}
+{(|bcIndefiniteIntegrate|)}\space{}
 \menulispdownlink{Do a Definite Integral}{(|bcDefiniteIntegrate|)}\space{}
 \menulispdownlink{Find a limit}{(|bcLimit|)}\space{}
 \menulispdownlink{Do a summation}{(|bcSum|)}\space{}
@@ -4280,29 +2505,24 @@ the \spadfun{left} and \spadfun{right}
 branch of every interior node is identical in shape.
 
 Balanced binary trees are useful in algebraic computation for
-so-called ``divide-and-conquer'' algorithms.
-Conceptually, the data for a problem is initially placed at the
-root of the tree.
-The original data is then split into two subproblems, one for each
-subtree.
-And so on.
-Eventually, the problem is solved at the leaves of the tree.
-A solution to the original problem is obtained by some mechanism
-that can reassemble the pieces.
-In fact, an implementation of the Chinese Remainder Algorithm
-using balanced binary trees was first proposed by David Y. Y.
-Yun at the IBM T. J.
-Watson Research Center in Yorktown Heights, New York, in 1978.
-It served as the prototype for polymorphic algorithms in
-Axiom.
+so-called ``divide-and-conquer'' algorithms.  Conceptually, the data
+for a problem is initially placed at the root of the tree.  The
+original data is then split into two subproblems, one for each
+subtree.  And so on.  Eventually, the problem is solved at the leaves
+of the tree.  A solution to the original problem is obtained by some
+mechanism that can reassemble the pieces.  In fact, an implementation
+of the Chinese Remainder Algorithm using balanced binary trees was
+first proposed by David Y. Y.  Yun at the IBM T. J.  Watson Research
+Center in Yorktown Heights, New York, in 1978.  It served as the
+prototype for polymorphic algorithms in Axiom.
 
 In what follows, rather than perform a series of computations with
 a single expression, the expression is reduced modulo a number of
 integer primes, a computation is done with modular arithmetic for
 each prime, and the Chinese Remainder Algorithm is used to obtain
 the answer to the original problem.
-We illustrate this principle with the computation of \texht{$12^2
-= 144$}{12 ** 2 = 144}.
+We illustrate this principle with the computation of 
+\texht{$12^2 = 144$}{12 ** 2 = 144}.
 
 \xtc{
 A list of moduli.
@@ -4382,10 +2602,10 @@ answer for \texht{$12^2$}{12**2}.
 \subsection{BinaryExpansion}
 \label{BinaryExpansionXmpPage}
 \begin{itemize}
-\item DecimalExpansionXmpPage \ref{DecimalExpansionXmpPage} on
-page~pageref{DecimalExpansionXmpPage}
-\item RadixExpansionXmpPage \ref{RadixExpansionXmpPage} on
-page~pageref{RadixExpansionXmpPage}
+\item DecimalExpansionXmpPage\\
+\ref{DecimalExpansionXmpPage} on page~pageref{DecimalExpansionXmpPage}
+\item RadixExpansionXmpPage\\ 
+\ref{RadixExpansionXmpPage} on page~pageref{RadixExpansionXmpPage}
 \end{itemize}
 \index{pages!BinaryExpansionXmpPage!binary.ht}
 \index{binary.ht!pages!BinaryExpansionXmpPage}
@@ -4398,8 +2618,10 @@ All rational numbers have repeating binary expansions.
 Operations to access the individual bits of a binary expansion can
 be obtained by converting the value to \spadtype{RadixExpansion(2)}.
 More examples of expansions are available in
-\downlink{`DecimalExpansion'}{DecimalExpansionXmpPage}\ignore{DecimalExpansion},
-\downlink{`HexadecimalExpansion'}{HexadecimalExpansionXmpPage}\ignore{HexadecimalExpansion}, and
+\downlink{`DecimalExpansion'}{DecimalExpansionXmpPage}
+\ignore{DecimalExpansion},
+\downlink{`HexadecimalExpansion'}{HexadecimalExpansionXmpPage}
+\ignore{HexadecimalExpansion}, and
 \downlink{`RadixExpansion'}{RadixExpansionXmpPage}\ignore{RadixExpansion}.
  
 \xtc{
@@ -4450,40 +2672,6 @@ These numbers are bona fide algebraic objects.
 <<bmcat.ht>>=
 \begin{page}{BitMaps}{Bit Map Catalog}
 \beginscroll
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/1x1}}   1x1
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/2x2}}   2x2
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/black}}   black
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/boxes}}   boxes
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/cntr_ptr}}   cntr_ptr
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/cntr_ptrmsk}}   cntr_ptrmsk
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/cross_weave}}   cross_weave
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/dimple1}}   dimple1
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/dimple3}}   dimple3
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/dot}}   dot
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/flipped_gray}}   flipped_gray
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/gray}}   gray
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/gray1}}   gray1
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/gray3}}   gray3
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/icon}}   icon
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/left_ptr}}   left_ptr
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/left_ptrmsk}}   left_ptrmsk
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/light_gray}}   light_gray
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/opendot}}   opendot
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/opendotMask}}   opendotMask
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/right_ptr}}   right_ptr
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/right_ptrmsk}}   right_ptrmsk
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/root_weave}}   root_weave
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/scales}}   scales
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/sipb}}   sipb
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/star}}   star
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/starMask}}   starMask
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/stipple}}   stipple
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/target}}   target
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/tie_fighter}}   tie_fighter
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/wide_weave}}   wide_weave
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/wierd_size}}   wierd_size
-%\space{} {\inputbitmap{/usr/include/X11/bitmaps/wingdogs}}   wingdogs
-%\horizontalline
 \space{} {\inputbitmap{\htbmdir{}/xfbox.bitmap}}      xfbox    \space{4}
 \space{} {\inputbitmap{\htbmdir{}/xfcirc.bitmap}}     xfcirc   \space{4}
 \space{} {\inputbitmap{\htbmdir{}/xnobox.bitmap}}     Xnobox   \space{2}
@@ -4564,8 +2752,10 @@ These numbers are bona fide algebraic objects.
 A basic operator is an object that can be symbolically
 applied to a list of arguments from a set, the result being
 a kernel over that set or an expression.
-In addition to this section, please see \downlink{`Expression'}{ExpressionXmpPage}\ignore{Expression}
-and \downlink{`Kernel'}{KernelXmpPage}\ignore{Kernel} for additional information and examples.
+In addition to this section, please see 
+\downlink{`Expression'}{ExpressionXmpPage}\ignore{Expression}
+and \downlink{`Kernel'}{KernelXmpPage}\ignore{Kernel} 
+for additional information and examples.
 
 You create an object of type \axiomType{BasicOperator} by using the
 \axiomFunFrom{operator}{BasicOperator} operation.
@@ -4596,7 +2786,8 @@ To solve the above equation, enter this.
 }{
 \spadpaste{solve(deq, y, x) \free{e1}\free{y}}
 }
-See \downlink{``\ugProblemDEQTitle''}{ugProblemDEQPage} in Section \ugProblemDEQNumber\ignore{ugProblemDEQ}
+See \downlink{``\ugProblemDEQTitle''}{ugProblemDEQPage} 
+in Section \ugProblemDEQNumber\ignore{ugProblemDEQ}
 for this kind of use of \axiomType{BasicOperator}.
 
 Use the single argument form of
@@ -4669,7 +2860,8 @@ because the property values are stored as values of type
 \xtc{
 Attach a property by using \axiomFunFrom{setProperty}{BasicOperator}.
 }{
-\spadpaste{setProperty(y, "use", "unknown function" :: None ) \free{y}\bound{spy}}
+\spadpaste{setProperty(y, "use", "unknown function" :: None ) 
+\free{y}\bound{spy}}
 }
 \xtc{
 }{
@@ -4709,12 +2901,12 @@ remove a property.
 <<bstree.ht>>=
 \begin{page}{BinarySearchTreeXmpPage}{BinarySearchTree}
 \beginscroll
+
 \spadtype{BinarySearchTree(R)} is the domain of binary trees with
-elements of type \spad{R}, ordered across the nodes of the tree.
-A non-empty binary search tree has a value
-of type \spad{R}, and \spadfun{right} and \spadfun{left}
-binary search subtrees.
-If a subtree is empty, it is displayed as a period (``.'').
+elements of type \spad{R}, ordered across the nodes of the tree.  A
+non-empty binary search tree has a value of type \spad{R}, and
+\spadfun{right} and \spadfun{left} binary search subtrees.  If a
+subtree is empty, it is displayed as a period (``.'').
 
 \xtc{
 Define a list of values to be placed across the tree.
@@ -4786,7 +2978,8 @@ Function \userfun{buildFromRoot} builds
 a binary search tree from a list of elements \spad{ls}
 and the empty tree \spad{emptybst}.
 }{
-\spadpaste{buildFromRoot ls == reduce(insertRoot,ls,emptybst)\bound{x2}\free{x1 e}}
+\spadpaste{buildFromRoot ls == reduce(insertRoot,ls,emptybst)
+\bound{x2}\free{x1 e}}
 }
 \xtc{
 Apply this to the reverse of the list \spad{lv}.
@@ -4885,10 +3078,14 @@ Arithmetic operations are defined on cardinal numbers as follows:
 If \spad{x = \#X}  and  \spad{y = \#Y} then
 
 \indent{0}
-\spad{x+y  = \#(X+Y)} \tab{20} cardinality of the disjoint union \newline
-\spad{x-y  = \#(X-Y)} \tab{20} cardinality of the relative complement \newline
-\spad{x*y  = \#(X*Y)} \tab{20} cardinality of the Cartesian product \newline
-\spad{x**y = \#(X**Y)}\tab{20} cardinality of the set of maps from \spad{Y} to \spad{X} \newline
+\spad{x+y  = \#(X+Y)} 
+\tab{20} cardinality of the disjoint union \newline
+\spad{x-y  = \#(X-Y)} 
+\tab{20} cardinality of the relative complement \newline
+\spad{x*y  = \#(X*Y)} 
+\tab{20} cardinality of the Cartesian product \newline
+\spad{x**y = \#(X**Y)}
+\tab{20} cardinality of the set of maps from \spad{Y} to \spad{X} \newline
 
 \xtc{
 Here are some arithmetic examples.
@@ -4897,18 +3094,21 @@ Here are some arithmetic examples.
 }
 \xtc{
 }{
-\spadpaste{[c0*c2, c1*c2, c2*c2, c0*A1, c1*A1, c2*A1, A0*A1] \free{c0,c1,c2,A0,A1}}
+\spadpaste{[c0*c2, c1*c2, c2*c2, c0*A1, c1*A1, c2*A1, A0*A1] 
+\free{c0,c1,c2,A0,A1}}
 }
 \xtc{
 }{
-\spadpaste{[c2**c0, c2**c1, c2**c2, A1**c0, A1**c1, A1**c2] \free{c0,c1,c2,A1}}
+\spadpaste{[c2**c0, c2**c1, c2**c2, A1**c0, A1**c1, A1**c2] 
+\free{c0,c1,c2,A1}}
 }
 \xtc{
 Subtraction is a partial operation: it is not defined
 when subtracting a larger cardinal from a smaller one, nor
 when subtracting two equal infinite cardinals.
 }{
-\spadpaste{[c2-c1, c2-c2, c2-c3, A1-c2, A1-A0, A1-A1] \free{c1,c2,c3,A0,A1}}
+\spadpaste{[c2-c1, c2-c2, c2-c3, A1-c2, A1-A0, A1-A1] 
+\free{c1,c2,c3,A0,A1}}
 }
 The generalized continuum hypothesis asserts that
 \begin{verbatim}
@@ -4927,7 +3127,8 @@ whether the hypothesis is to be assumed.
 When the generalized continuum hypothesis
 is assumed, exponentiation to a transfinite power is allowed.
 }{
-\spadpaste{[c0**A0, c1**A0, c2**A0, A0**A0, A0**A1, A1**A0, A1**A1] \free{c0,c1,c2,A0,A1,GCH}}
+\spadpaste{[c0**A0, c1**A0, c2**A0, A0**A0, A0**A1, A1**A0, A1**A1] 
+\free{c0,c1,c2,A0,A1,GCH}}
 }
 
 Three commonly encountered cardinal numbers are
@@ -5398,7 +3599,9 @@ defined and manipulated efficiently.
 Character classes can be created by giving either a string or a list
 of characters.
 }{
-\spadpaste{cl1 := charClass [char "a", char "e", char "i", char "o", char "u", char "y"] \bound{cl1}}
+\spadpaste{cl1 := 
+charClass [char "a", char "e", char "i", char "o", char "u", char "y"] 
+\bound{cl1}}
 }
 \xtc{
 }{
@@ -5771,7 +3974,8 @@ We use Hamilton's notation for \spad{i},\spad{j},\spad{k}.
 \spadpaste{x * y \free{x y}}
 }
 \xtc{
-See \downlink{`Quaternion'}{QuaternionXmpPage}\ignore{Quaternion} for examples of Axiom's constructor
+See \downlink{`Quaternion'}{QuaternionXmpPage}
+\ignore{Quaternion} for examples of Axiom's constructor
 implementing quaternions.
 }{
 \spadpaste{y * x \free{x y}}
@@ -5845,7 +4049,8 @@ On an \spad{n} space, a grade \spad{p} form has a dual \spad{n-p} form.
 In particular, in three space the dual of a grade two element identifies
 \spad{e1*e2->e3, e2*e3->e1, e3*e1->e2}.
 }{
-\spadpaste{dual2 a == coefficient(a,[2,3]) * i + coefficient(a,[3,1]) * j + coefficient(a,[1,2]) * k \free{i j k}\bound{dual2}}
+\spadpaste{dual2 a == coefficient(a,[2,3]) * i + coefficient(a,[3,1]) * 
+j + coefficient(a,[1,2]) * k \free{i j k}\bound{dual2}}
 }
 \xtc{
 The vector cross product is then given by this.
@@ -5913,11 +4118,15 @@ Verify this identity for particular values of \spad{m,n,r,s}.
 }
 \xtc{
 }{
-\spadpaste{lhs := reduce(+, [reduce(+, [ g(l,t)*gam(l)*gam(m)*gam(n)*gam(r)*gam(s)*gam(t) for l in 1..4]) for t in 1..4]) \bound{lhs}\free{g gam m n r s}}
+\spadpaste{lhs := 
+reduce(+, [reduce(+, 
+[ g(l,t)*gam(l)*gam(m)*gam(n)*gam(r)*gam(s)*gam(t) for l in 1..4]) 
+for t in 1..4]) \bound{lhs}\free{g gam m n r s}}
 }
 \xtc{
 }{
-\spadpaste{rhs := 2*(gam s * gam m*gam n*gam r + gam r*gam n*gam m*gam s) \bound{rhs}\free{lhs g gam m n r s}}
+\spadpaste{rhs := 2*(gam s * gam m*gam n*gam r + gam r*gam n*gam m*gam s)
+\bound{rhs}\free{lhs g gam m n r s}}
 }
 \endscroll
 \autobuttons
@@ -5983,7 +4192,8 @@ If \spad{R} is a field, you can also divide the complex objects.
 \spadpaste{a / b \free{a b}\bound{adb}}
 }
 \xtc{
-Use a conversion (\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} in Section \ugTypesConvertNumber\ignore{ugTypesConvert}) to view the last
+Use a conversion (\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} 
+in Section \ugTypesConvertNumber\ignore{ugTypesConvert}) to view the last
 object as a fraction of complex integers.
 }{
 \spadpaste{\% :: Fraction Complex Integer \free{adb}}
@@ -6766,7 +4976,7 @@ The smallest is
 DO NOT EDIT! Created by ex2ht.
 \begin{itemize}
 \item Menuexdiff \ref{Menuexdiff} on page~\pageref{Menuexdiff}
-\item menuexint \ref{menuexint} on page~\pageref{menuexint}
+\item Menuexint \ref{Menuexint} on page~\pageref{Menuexint}
 \item Menuexlap \ref{Menuexlap} on page~\pageref{Menuexlap}
 \item Menuexlimit \ref{Menuexlimit} on page~\pageref{Menuexlimit}
 \item Menuexmatrix \ref{Menuexmatrix} on page~\pageref{Menuexmatrix}
@@ -7152,8 +5362,8 @@ page~\pageref{ExSumGeneralFunction}
 page~pageref{BinaryExpansionXmpPage}
 \item HexadecimalExpansionXmpPage \ref{HexadecimalExpansionXmpPage} on
 page~pageref{HexadecimalExpansionXmpPage}
-\item RadicExpansionPage \ref{RadicExpansionPage} on
-page~pageref{RadicExpansionPage}
+\item RadixExpansionXmpPage \ref{RadixExpansionXmpPage} on
+page~pageref{RadixExpansionXmpPage}
 \end{itemize}
 \index{pages!DecimalExpansionXmpPage!decimal.ht}
 \index{decimal.ht!pages!DecimalExpansionXmpPage}
@@ -7555,8 +5765,8 @@ facilities, see
 \begin{itemize}
 \item ugIntroVariablesPage \ref{ugIntroVariablesPage} on
 page~pageref{ugIntroVariablesPage}
-\item utTypesConvertPage \ref{utTypesConvertPage} on
-page~pageref{utTypesConvertPage}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~pageref{ugTypesConvertPage}
 \item PolynomialXmpPage \ref{PolynomialXmpPage} on
 page~pageref{PolynomialXmpPage}
 \item UnivariatePolynomialXmpPage \ref{UnivariatePolynomialXmpPage} on
@@ -9061,11 +7271,11 @@ Here is the {\em twisted cubic curve}:
 
 @
 \section{expose.ht}
-\subsection{TITLE}
-\label{TPD}
-\index{pages!TPD!expose.ht}
-\index{expose.ht!pages!TPD}
-\index{TPD!expose.ht!pages}
+\subsection{Exposure}
+\label{helpExpose}
+\index{pages!helpExpose!expose.ht}
+\index{expose.ht!pages!helpExpose}
+\index{helpExpose!expose.ht!pages}
 <<expose.ht>>=
 \begin{page}{helpExpose}{Exposure}
 \beginscroll
@@ -9725,10 +7935,10 @@ page~pageref{ugGraphPage}
 page~pageref{ugProblemNumericPage}
 \item DoubleFloatXmpPage \ref{DoubleFloatXmpPage} on
 page~pageref{DoubleFloatXmpPage}
-\item ugFloatIntroPage \ref{ugFloatIntroPage} on
-page~pageref{ugFloatIntroPage}
-\item ugFloatConvertPage \ref{ugFloatConvertPage} on
-page~pageref{ugFloatConvertPage}
+\item ugxFloatIntroPage \ref{ugxFloatIntroPage} on
+page~pageref{ugxFloatIntroPage}
+\item ugxFloatConvertPage \ref{ugxFloatConvertPage} on
+page~pageref{ugxFloatConvertPage}
 \item ugxFloatOutputPage \ref{ugxFloatOutputPage} on
 page~pageref{ugxFloatOutputPage}
 \item ugxFloatHilbertPage \ref{ugxFloatHilbertPage} on
@@ -10905,15 +9115,23 @@ decompositions.
 \section{function.ht}
 \subsection{Functions in Axiom}
 \label{FunctionPage}
+\includegraphics[scale=.5]{ps/v71functionpage.eps}
+\index{images!functionpage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
 \begin{itemize}
-\item RationalFunctionPage \ref{RationalFunctionPage} on
-page~\pageref{RationalFunctionPage}
-\item AlgebraicFunctionPage \ref{AlgebraicFunctionPage} on
-page~\pageref{AlgebraicFunctionPage}
-\item ElementaryFunctionPage \ref{ElementaryFunctionPage} on
-page~\pageref{ElementaryFunctionPage}
-\item FunctionSimplificationPage \ref{FunctionSimplificationPage} on
-page~\pageref{FunctionSimplificationPage}
+\item ``Rational Functions'' (RationalFunctionPage) 
+\ref{RationalFunctionPage} on page~\pageref{RationalFunctionPage}
+\item ``Algebraic Functions'' (AlgebraicFunctionPage) 
+\ref{AlgebraicFunctionPage} on page~\pageref{AlgebraicFunctionPage}
+\item ``Elementary Functions'' (ElementaryFunctionPage) 
+\ref{ElementaryFunctionPage} on page~\pageref{ElementaryFunctionPage}
+\item ``Simplification'' (FunctionSimplificationPage) 
+\ref{FunctionSimplificationPage} on page~\pageref{FunctionSimplificationPage}
+\item ``Pattern Matching'' (ugUserRulesPage) 
+\ref{ugUserRulesPage} on page~\pageref{ugUserRulesPage}
+\item ``Operator Algebra'' (OperatorXmpPage)
+\ref{OperatorXmpPage} on page~\pageref{OperatorXmpPage}
 \end{itemize}
 \index{pages!FunctionPage!function.ht}
 \index{function.ht!pages!FunctionPage}
@@ -10927,7 +9145,7 @@ You can also define a function by rules or use a built-in function
 Axiom lets you convert expressions to compiled functions.
 \beginscroll
 \beginmenu
-\menulink{Rational Functions}{RationatFunctionPage} \tab{22}
+\menulink{Rational Functions}{RationalFunctionPage} \tab{22}
 Quotients of polynomials.
 
 \menulink{Algebraic Functions}{AlgebraicFunctionPage} \tab{22}
@@ -10955,12 +9173,12 @@ The operator algebra facility.
 
 @
 \subsection{Rational Functions}
-\label{RationatFunctionPage}
-\index{pages!RationatFunctionPage!function.ht}
-\index{function.ht!pages!RationatFunctionPage}
-\index{RationatFunctionPage!function.ht!pages}
+\label{RationalFunctionPage}
+\index{pages!RationalFunctionPage!function.ht}
+\index{function.ht!pages!RationalFunctionPage}
+\index{RationalFunctionPage!function.ht!pages}
 <<function.ht>>=
-\begin{page}{RationatFunctionPage}{Rational Functions}
+\begin{page}{RationalFunctionPage}{Rational Functions}
 \beginscroll
 To create a rational function, just compute the
 quotient of two polynomials:
@@ -12262,16 +10480,22 @@ for glossary entry matching \inputstring{pattern}{24}{*}\end{page}
 @
 \section{graphics.ht}
 \subsection{Graphics}
+\label{GraphicsPage}
+\includegraphics[scale=.5]{ps/v71graphicspage.eps}
+\index{images!graphicspage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
 \begin{itemize}
-\item GraphicsExamplePage \ref{GraphicsExamplePage} on 
-page~\pageref{GraphicsExamplePage}
-\item TwoDimensionalGraphicsPage \ref{TwoDimensionalGraphicsPage} on 
-page~\pageref{TwoDimensionalGraphicsPage}
-\item ThreeDimensionalGraphicsPage \ref{ThreeDimensionalGraphicsPage} on 
+\item ``Examples'' (GraphicsExamplePage) 
+\ref{GraphicsExamplePage} on page~\pageref{GraphicsExamplePage}
+\item ``2D Graphics'' (TwoDimensionalGraphicsPage) 
+\ref{TwoDimensionalGraphicsPage} on page~\pageref{TwoDimensionalGraphicsPage}
+\item ``3D Graphics'' (ThreeDimensionalGraphicsPage) 
+\ref{ThreeDimensionalGraphicsPage} on 
 page~\pageref{ThreeDimensionalGraphicsPage}
-\item ViewportPage \ref{ViewportPage} on page~\pageref{ViewportPage}
+\item ``Viewports'' (ViewportPage) 
+\ref{ViewportPage} on page~\pageref{ViewportPage}
 \end{itemize}
-\label{GraphicsPage}
 \index{pages!GraphicsPage!graphics.ht}
 \index{graphics.ht!pages!GraphicsPage}
 \index{GraphicsPage!graphics.ht!pages}
@@ -12868,8 +11092,8 @@ page~\pageref{ParametricCurveGraphicsPage}
 page~\pageref{PolarGraphicsPage}
 \item ImplicitCurveGraphicsPage \ref{ImplicitCurveGraphicsPage} on 
 page~\pageref{ImplicitCurveGraphicsPage}
-\item ListPoinstsGraphicsPage \ref{ListPoinstsGraphicsPage} on 
-page~\pageref{ListPoinstsGraphicsPage}
+\item ListPointsGraphicsPage \ref{ListPointsGraphicsPage} on 
+page~\pageref{ListPointsGraphicsPage}
 \end{itemize}
 \index{pages!TwoDimensionalGraphicsPage!graphics.ht}
 \index{graphics.ht!pages!TwoDimensionalGraphicsPage}
@@ -13589,12 +11813,12 @@ Apply \spadfun{heapsort} to present elements in order.
 \subsection{HexadecimalExpansion}
 \label{HexadecimalExpansionXmpPage}
 \begin{itemize}
-\item DecimalExpansion \ref{DecimalExpansion} on
-page~pageref{DecimalExpansion}
-\item BinaryExpansion \ref{BinaryExpansion} on
-page~pageref{BinaryExpansion}
-\item RadixExpansion \ref{RadixExpansion} on
-page~pageref{RadixExpansion}
+\item DecimalExpansionXmpPage \ref{DecimalExpansionXmpPage} on
+page~pageref{DecimalExpansionXmpPage}
+\item BinaryExpansionXmpPage \ref{BinaryExpansionXmpPage} on
+page~pageref{BinaryExpansionXmpPage}
+\item RadixExpansionXmpPage \ref{RadixExpansionXmpPage} on
+page~pageref{RadixExpansionXmpPage}
 \end{itemize}
 \index{pages!HexadecimalExpansionXmpPage!hexadec.ht}
 \index{hexadec.ht!pages!HexadecimalExpansionXmpPage}
@@ -13653,4164 +11877,6 @@ These numbers are bona fide algebraic objects.
 \end{page}
 
 @
-\section{htxadvpage1.ht}
-\subsection{Input Areas}
-\label{HTXAdvPage1}
-See HTXAdvPage2 \ref{HTXAdvPage2} on page~\pageref{HTXAdvPage2}
-\index{pages!HTXAdvPage1!htxadvpage1.ht}
-\index{htxadvpage1.ht!pages!HTXAdvPage1}
-\index{HTXAdvPage1!htxadvpage1.ht!pages}
-<<htxadvpage1.ht>>=
-\begin{page}{HTXAdvPage1}{Input areas}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-You have probably seen input areas in other \HyperName{}
-pages. They provide {\it dynamic link} capabilities.
-Instead of having a choice between certain actions,
-they allow you to specify an action on--the--fly.
-To use them, you need the following commands:
-\beginImportant
-\newline
-{\tt \\inputstring\{{\it label}\}\{{\it length}\}\{{\it default value}\}}
-\newline
-{\tt \\stringvalue\{{\it label}\}}
-\endImportant
-
-The first command puts up an input area of the {\it length}
-specified. The {\it default value} is placed in it.
-The first argument, {\it label} gives a name to the
-contents of the input area.
-You can refer to those contents by using
-the second command. Never place a {\tt \\stringvalue} command
-in an "exposed" part of the page. It is only meant
-to be used as an argument to an {\it action}.
-Here are some examples.
-
-
-
-
-
-\beginImportant
-\begin{paste}{HTXAdvPage1xPaste1}{HTXAdvPage1xPatch1}
-\pastebutton{HTXAdvPage1xPaste1}{Interpret}
-\newline
-{\tt Page name \\tab\{16\} }
-{\tt \\inputstring\{pagetogo\}\{30\}\{RootPage\}}\newline
-{\tt \\newline}\newline
-{\tt \\downlink\{GO!\}\{\\stringvalue\{pagetogo\}\}}\newline
-\end{paste}
-\endImportant
-
-\beginImportant
-\begin{paste}{HTXAdvPage1xPaste2}{HTXAdvPage1xPatch2}
-\pastebutton{HTXAdvPage1xPaste2}{Interpret}
-\newline
-{\tt File to edit \\tab\{16\}}\newline
-{\tt \\inputstring\{filetoedit\}\{30\}\{/etc/passwd\}}\newline
-{\tt \\newline}\newline
-{\tt \\unixcommand\{Ready!\}\{xterm  -e vi \\stringvalue\{filetoedit\}\}}
-\end{paste}
-\endImportant
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next Page --- Radio boxes}{HTXAdvPage2}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXAdvPage1xPatch1 patch}
-\label{HTXAdvPage1xPatch1}
-\index{patch!HTXAdvPage1xPatch1!htxadvpage1.ht}
-\index{htxadvpage1.ht!patch!HTXAdvPage1xPatch1}
-\index{HTXAdvPage1xPatch1!htxadvpage1.ht!patch}
-<<htxadvpage1.ht>>=
-\begin{patch}{HTXAdvPage1xPatch1}
-\begin{paste}{HTXAdvPage1xPaste1A}{HTXAdvPage1xPatch1A}
-\pastebutton{HTXAdvPage1xPaste1A}{Source}
-\newline
-Page name \tab{16}
-\inputstring{pagetogo}{30}{RootPage}
-\newline
-\downlink{GO!}{\stringvalue{pagetogo}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage1xPatch1A patch}
-\label{HTXAdvPage1xPatch1A}
-\index{patch!HTXAdvPage1xPatch1A!htxadvpage1.ht}
-\index{htxadvpage1.ht!patch!HTXAdvPage1xPatch1A}
-\index{HTXAdvPage1xPatch1A!htxadvpage1.ht!patch}
-<<htxadvpage1.ht>>=
-\begin{patch}{HTXAdvPage1xPatch1A}
-\begin{paste}{HTXAdvPage1xPaste1B}{HTXAdvPage1xPatch1}
-\pastebutton{HTXAdvPage1xPaste1B}{Interpret}
-\newline
-{\tt Page name \\tab\{16\} }
-{\tt \\inputstring\{pagetogo\}\{30\}\{RootPage\}}\newline
-{\tt \\newline}\newline
-{\tt \\downlink\{GO!\}\{\\stringvalue\{pagetogo\}\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage1xPatch2 patch}
-\label{HTXAdvPage1xPatch2}
-\index{patch!HTXAdvPage1xPatch2!htxadvpage1.ht}
-\index{htxadvpage1.ht!patch!HTXAdvPage1xPatch2}
-\index{HTXAdvPage1xPatch2!htxadvpage1.ht!patch}
-<<htxadvpage1.ht>>=
-\begin{patch}{HTXAdvPage1xPatch2}
-\begin{paste}{HTXAdvPage1xPaste2A}{HTXAdvPage1xPatch2A}
-\pastebutton{HTXAdvPage1xPaste2A}{Source}
-\newline
-File to edit \tab{16}
-\inputstring{filetoedit}{30}{/etc/passwd}
-\newline
-\unixcommand{Ready!}{xterm  -e vi \stringvalue{filetoedit}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage1xPatch2A patch}
-\label{HTXAdvPage1xPatch2A}
-\index{patch!HTXAdvPage1xPatch2A!htxadvpage1.ht}
-\index{htxadvpage1.ht!patch!HTXAdvPage1xPatch2A}
-\index{HTXAdvPage1xPatch2A!htxadvpage1.ht!patch}
-<<htxadvpage1.ht>>=
-\begin{patch}{HTXAdvPage1xPatch2A}
-\begin{paste}{HTXAdvPage1xPaste2B}{HTXAdvPage1xPatch2}
-\pastebutton{HTXAdvPage1xPaste2B}{Interpret}
-\newline
-{\tt File to edit \\tab\{16\}}\newline
-{\tt \\inputstring\{filetoedit\}\{30\}\{/etc/passwd\}}\newline
-{\tt \\newline}\newline
-{\tt \\unixcommand\{Ready!\}\{xterm  -e vi \\stringvalue\{filetoedit\}\}}
-\end{paste}
-\end{patch}
-
-@
-\section{htxadvpage2.ht}
-\subsection{Radio buttons}
-\label{HTXAdvPage2}
-See HTXAdvPage3 \ref{HTXAdvPage3} on page~\pageref{HTXAdvPage3}
-\index{pages!HTXAdvPage2!htxadvpage2.ht}
-\index{htxadvpage2.ht!pages!HTXAdvPage2}
-\index{HTXAdvPage2!htxadvpage2.ht!pages}
-<<htxadvpage2.ht>>=
-\begin{page}{HTXAdvPage2}{Radio buttons}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-
-If you just want to make a multiple-choice
-type selection, why not use the {\it radio buttons}.
-
-You need to use bitmaps for the active areas (the buttons) but
-\HyperName{} will keep track of the currently activated button.
-You can use this boolean information somewhere else on your page.
-The commands to use are:
-\beginImportant
-\newline
-{\tt \\radioboxes\{{\it group name}\}\{{\it bitmap file1}\}\{{\it bitmap file0}\}}
-\newline
-{\tt \\radiobox[{\it initial state}]\{{\it label}\}\{{\it group name}\}}
-\newline
-{\tt \\boxvalue\{{\it label}\}}
-\endImportant
-
-The {\tt \\radioboxes} command sets up a group of {\tt \\radiobox}
-buttons. The {\it group name} is a label for the group. The filenames
-for the bitmaps are specified in {\it bitmap file1} and {\it bitmap file0}.
-The first one should denote an activated button and the second
-a de-activated one.
-
-To display each button in a group, use {\tt \\radiobox}.
-The {\it initial state} should be either {\tt 1} or {\tt 0}
-depending on whether the button should first be displayed as activated or not.
-The second {\it label} argument defines the name by which the
-current state of the button can be referred to.
-The third argument specifies which group this button belongs to.
-
-The {\tt \\boxvalue} command can then be used in various
-actions. The value of it will
-be either {\tt t} or {\tt nil}.
-
-In the example below, we use the {\tt \\htbmfile} macro
-defined in {\bf util.ht} so that we do not have to write
-the full bitmap file pathnames.
-
-This is how we set up the group. The {\tt \\radioboxes} command does not display
-anything.
-Note that these commands cannot be included in a {\it patch}.
-This is why we display this time the source and the result
-at the same time.
-\beginImportant
-\newline
-{\tt \\radioboxes\{group\}\{\\htbmfile\{pick\}\}\{\\htbmfile\{unpick\}\}}\newline
-{\tt \\newline \\table\{}\newline
-{\tt \{\\radiobox[1]\{b1\}\{group\}\}}\newline
-{\tt \{\\radiobox[0]\{b2\}\{group\}\}}\newline
-{\tt \{\\radiobox[0]\{b3\}\{group\}\}\}}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{lisp\}\{(pprint (list}\newline
-{\tt \\boxvalue\{b1\} \\boxvalue\{b2\} \\boxvalue\{b3\}))\}}\newline
-{\tt \\newline}\newline
-{\tt \\unixcommand\{unix\}\{echo '\\boxvalue\{b1\}}\newline
-{\tt \\boxvalue\{b2\} \\boxvalue\{b3\}'\}}
-\endImportant
-\radioboxes{group}{\htbmfile{pick}}{\htbmfile{unpick}}
-\table{
-{\radiobox[1]{b1}{group}}
-{\radiobox[0]{b2}{group}}
-{\radiobox[0]{b3}{group}}}
-\newline
-\lispcommand{lisp}{(pprint (list
-\boxvalue{b1} \boxvalue{b2} \boxvalue{b3}))}
-\newline
-\unixcommand{unix}{echo '\boxvalue{b1}
-\boxvalue{b2} \boxvalue{b3}'}
-\endImportant
-
-
-
-
-You can only set one radio button at a time. If you want
-a non--exclusive selection, try {\tt \\inputbox}.
-The syntax for this command is
-\beginImportant
-\newline
-{\tt \\inputbox[{\it initial state}]\{{\it label}\}\{{\it bitmap file1}\}\{{\it bitmap file0}\}}
-\endImportant
-
-There is no group command for these.
-\beginImportant
-\newline
-{\tt \\table\{}\newline
-{\tt \{\\inputbox[1]\{c1\}\{\\htbmfile\{pick\}\}\{\\htbmfile\{unpick\}\}\}}\newline
-{\tt \{\\inputbox\{c2\}\{\\htbmfile\{pick\}\}\{\\htbmfile\{unpick\}\}\}}\newline
-{\tt \{\\inputbox[1]\{c3\}\{\\htbmfile\{pick\}\}\{\\htbmfile\{unpick\}\}\}\}}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{lisp\}\{(pprint (list}\newline
-{\tt \\boxvalue\{c1\} \\boxvalue\{c2\} \\boxvalue\{c3\}))\}}\newline
-{\tt \\newline}\newline
-{\tt \\unixcommand\{unix\}\{echo }\newline
-{\tt '\\boxvalue\{c1\} \\boxvalue\{c2\} \\boxvalue\{c3\}'\}}\newline
-\endImportant
-\table{
-{\inputbox[1]{c1}{\htbmfile{pick}}{\htbmfile{unpick}}}
-{\inputbox{c2}{\htbmfile{pick}}{\htbmfile{unpick}}}
-{\inputbox[1]{c3}{\htbmfile{pick}}{\htbmfile{unpick}}}}
-\newline
-\lispcommand{lisp}{(pprint (list
-\boxvalue{c1} \boxvalue{c2} \boxvalue{c3}))}
-\newline
-\unixcommand{unix}{echo
-'\boxvalue{c1} \boxvalue{c2} \boxvalue{c3}'}
-\endImportant
-
-
-Note that the {\it initial state} is an
-optional argument. If omitted
-the button will initially
-be deactivated.
-
-\end{scroll}
-\beginmenu
-\menulink{Next Page --- Macros}{HTXAdvPage3}
-\endmenu
-
-\end{page}
-
-@
-\section{htxadvpage3.ht}
-\subsection{Macros}
-\label{HTXAdvPage3}
-See HTXAdvPage4 \ref{HTXAdvPage4} on page~\ref{HTXAdvPage4}p
-\index{pages!HTXAdvPage3!htxadvpage3.ht}
-\index{htxadvpage3.ht!pages!HTXAdvPage3}
-\index{HTXAdvPage3!htxadvpage3.ht!pages}
-<<htxadvpage3.ht>>=
-\begin{page}{HTXAdvPage3}{Macros}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-
-Sometimes you may find yourself having to
-write
-almost the same piece of \HyperName{}
-text many times. Thankfully, there is a command to ease
-the work.
-It is the {\tt \\newcommand} command and provides
-a macro facility for \HyperName{}.
-In this way, you can give a short name to a sequence of \HyperName{}
-text and use that name to include the sequence in your pages.
-The way this works is the following
-\beginImportant
-\newline
-\centerline{{\tt \\newcommand\{\\{\it name}\}[{\it number of arguments}]\{{\it \HyperName{} text}\}}}
-\endImportant
-and here is an example from {\bf util.ht}
-\beginImportant
-\newline
-{\tt \\newcommand\{\\axiomSig\}[2]\{\\axiomType\{\#1\} \{\\tt ->\} \\axiomType\{\#2\}\}}
-\newline
-{\tt \\newcommand\{\\axiomType\}[1]\{\\lispdownlink\{\#1\}\{(|spadType| '|\#1|)\}\}}
-\endImportant
-
-You see that a macro's definition can invoke another.
-Don't create a circular definition though!
-Notice how the arguments of the macro are used
-in the definition. The {\tt \#{\it n}} construct
-is the place--holder of the {\it n}'th argument.
-
-To use the macro, just treat it as an ordinary command.
-For instance
-\beginImportant
-\newline
-{\tt \\axiomSig\{Integer\}\{List Integer\}}
-\endImportant
-displays and acts like this
-\beginImportant
-\newline
-\axiomSig{Integer}{List Integer}
-\endImportant
-
-The best way to familiarise yourself to
-macros is to study the macros defined in
-\centerline{
-{\bf \env{AXIOM}/doc/hypertex/pages/util.ht}
-}
-It is highly probable that a good many of them
-will prove useful to you.
-Clever use of macros will allow you to
-create \HyperName{} text that can be
-formatted by other programs (such as TeX).
-The Axiom User Guide was written
-in such a way as to make translation in
-\HyperName{} form and TeX form a mechanical process.
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next Page --- Patch and Paste}{HTXAdvPage4}
-\endmenu
-
-\end{page}
-
-@
-\section{htxadvpage4.ht}
-\subsection{Patch and Paste}
-\label{HTXAdvPage4}
-See HTXAdvPage5 \ref{HTXAdvPage5} on page~\pageref{HTXAdvPage5}
-\index{pages!HTXAdvPage4!htxadvpage4.ht}
-\index{htxadvpage4.ht!pages!HTXAdvPage4}
-\index{HTXAdvPage4!htxadvpage4.ht!pages}
-<<htxadvpage4.ht>>=
-\begin{page}{HTXAdvPage4}{Patch and Paste}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-
-A powerful \HyperName{} feature is
-the ability to {\it replace}
-part of a displayed page with another part
-when an active area is clicked. The group commands
-{\it patch} and {\it paste} offer this facility.
-A {\it paste} region can appear anywhere
-within a page or a {\it patch}. A {\it patch} region must be defined
-outside a page definition.
-
-We need a few  objects to define the {\it paste}
-region. These are a {\it name} with which to
-refer to it, some way of specifying what it
-is to be replaced by and a {\it trigger} for the
-replacement. A {\it patch} is how we specify the
-second of these objects.
-The {\it patch} is generally a sequence of \HyperName{}
-text.
-
-If we want to have the option of returning to the original
-(or ,indeed, proceeding to a {\it third} alternative)
-we clearly must include a {\it paste} in the {\it patch}.
-
-Let us start with a simple example. We wish to
-have the word {\tt initial} somewhere on the page replaced by the
-word {\tt final} at a click of a button.
-Let us first define the {\it patch}. It will just contain
-the word {\tt final}. Here is a definition of a
-patch called {\tt patch1} (note that
-the actual definition must be outside this page's definition).
-\beginImportant
-\newline
-{\tt \\begin\{patch\}\{patch1\}} \newline
-{\tt final}\newline
-{\tt \\end\{patch\}}
-\endImportant
-We now define a {\it paste} region exactly where we
-want the word {\tt initial} to appear.
-\beginImportant
-\newline
-{\tt \\begin\{paste\}\{paste1\}\{patch1\}}\newline
-{\tt initial}\newline
-{\tt \\end\{paste\}}
-\centerline{{\it results in}}
-\begin{paste}{paste1}{patch1}
-initial
-\end{paste}
-\endImportant
-We have specified first the name of the {\it paste} region
-which is {\tt paste1} and then the name of the
-replacement {\it patch} which is {\tt patch1}.
-Something is missing -- the trigger.
-To include a trigger we write
-\beginImportant
-\newline
-{\tt \\pastebutton\{paste1\}\{trigger\}
-\centerline{{\it results in}}
-\pastebutton{paste1}{trigger}
-\endImportant
-This new command {\tt \\pastebutton} displays the second argument
-as an active area. The first argument specifies the {\it paste}
-region it refers to. Clicking on {\tt trigger} above will
-replace the word {\tt initial} with the word {\tt final}.
-
-We can, if we like, include the {\tt \\pastebutton} in the {\it paste}
-region.
-Let us improve on the situation by providing a way
-of going back to the original word {\tt initial} on the page.
-The {\it patch} must itself include a {\it paste}.
-What will the replacement {\it patch} for this new {\it paste}
-be ? Well, we  have to define a second {\it patch}
-that contains all the stuff in the original {\it paste}
-region. Here is the updated {\it patch} for the first replacement.
-The {\tt \\MenuDotBitmap} macro is defined in {\bf util.ht}.
-It displays a button bitmap.
-This time we put the {\tt \\pastebutton}
-inside the {\it paste}.
-\beginImportant
-\newline
-{\tt \\begin\{patch\}\{Patch1\}}\newline
-{\tt \\begin\{paste\}\{Paste2\}\{Patch2\}}\newline
-{\tt \\pastebutton\{Paste2\}\{\\MenuDotBitmap\}}\newline
-{\tt final}\newline
-{\tt \\end\{paste\}}\newline
-{\tt \\end\{patch\}}\newline
-\endImportant
-and the new {\tt Patch2} {\it patch}
-\beginImportant
-\newline
-{\tt \\begin\{patch\}\{Patch2\}}\newline
-{\tt \\begin\{paste\}\{Paste3\}\{Patch1\}}\newline
-{\tt \\pastebutton\{Paste3\}\{\\MenuDotBitmap\}}\newline
-{\tt initial}\newline
-{\tt \\end\{paste\}}\newline
-{\tt \\end\{patch\}}\newline
-\endImportant
-
-Remember that these {\it patch} definitons must
-occur outside a {\tt \\begin\{page\} - \\end\{page\}} group.
-What is left now is to define the starting {\it paste}
-region.
-\beginImportant
-\newline
-{\tt \\begin\{paste\}\{Paste1\}\{Patch1\}}\newline
-{\tt \\pastebutton\{Paste1\}\{\\MenuDotBitmap\}}\newline
-{\tt initial}\newline
-{\tt \\end\{paste\}}
-\centerline{{\it results in}}
-\begin{paste}{Paste1}{Patch1}
-\pastebutton{Paste1}{\MenuDotBitmap}
-initial
-\end{paste}
-\endImportant
-
-Clicking on the button above next to {\tt initial}
-will replace the {\tt Paste1} region with
-{\tt Patch1}. That {\it patch}
-also contains a {\it paste} region ({\tt Paste2}).
-Clicking on {\it its} button will put up
-{\tt Patch2} which has a {\it paste} region ({\tt Paste3}).
-Clicking on {\it its} button will put up {\tt Patch1}
-again. In that way, we close the chain of replacements.
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next Page --- Axiom paste-ins}{HTXAdvPage5}
-\endmenu
-
-\end{page}
-
-@
-\subsection{patch1 patch}
-\label{patch1}
-\index{patch!patch1!htxadvpage4.ht}
-\index{htxadvpage4.ht!patch!patch1}
-\index{patch1!htxadvpage4.ht!patch}
-<<htxadvpage4.ht>>=
-\begin{patch}{patch1}
-final
-\end{patch}
-
-@
-\subsection{Patch1 patch}
-\label{Patch1}
-\index{patch!Patch1!htxadvpage4.ht}
-\index{htxadvpage4.ht!patch!Patch1}
-\index{Patch1!htxadvpage4.ht!patch}
-<<htxadvpage4.ht>>=
-\begin{patch}{Patch1}
-\begin{paste}{Paste2}{Patch2}
-\pastebutton{Paste2}{\MenuDotBitmap}
-final
-\end{paste}
-\end{patch}
-
-@
-\subsection{Patch2 patch}
-\label{Patch2}
-\index{patch!Patch2!htxadvpage4.ht}
-\index{htxadvpage4.ht!patch!Patch2}
-\index{Patch2!htxadvpage4.ht!patch}
-<<htxadvpage4.ht>>=
-\begin{patch}{Patch2}
-\begin{paste}{Paste3}{Patch1}
-\pastebutton{Paste3}{\MenuDotBitmap}
-initial
-\end{paste}
-\end{patch}
-
-@
-\section{htxadvpage5.ht}
-\subsection{Axiom paste-ins}
-\label{HTXAdvPage5}
-See HTXAdvPage6 \ref{HTXAdvPage6} on page~\pageref{HTXAdvPage6}
-\index{pages!HTXAdvPage5!htxadvpage5.ht}
-\index{htxadvpage5.ht!pages!HTXAdvPage5}
-\index{HTXAdvPage5!htxadvpage5.ht!pages}
-<<htxadvpage5.ht>>=
-\begin{page}{HTXAdvPage5}{Axiom paste-ins}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-The {\it paste} and {\it patch} facility (see \downlink{previous page}{HTXAdvPage4})
-is used to display (or hide) the Axiom output
-of an Axiom command ({\tt\\axiomcommand})
-included in a
-\HyperName{} page.
-
-A mechanism has been set up to {\it automatically} generate
-these paste-ins. It amounts to replacing an
-{\tt \\axiomcommand} by a {\tt \\pastecommand} in the
-\HyperName{} page.
-
-In the case of a \axiomOp{draw} Axiom command
-, where the result is to create an interactive viewport,
-the appropriate command to use is {\tt \\pastegraph}.
-The effect of this is to include (as the output)
-the Axiom generated {\it image} of the graph
-as an active area. Clicking on it will put up an
-interactive viewport.
-The {\tt \\pastegraph} command should be used only when
-the result of the associated Axiom operation is
-to {\it create} an interactive viewport. It is {\it not} necessarily
-appropriate for all commands whose result
-is a \axiomType{Two{}Dimensional{}Viewport} or \axiomType{Three{}Dimensional{}Viewport}.
-The {\tt \\pastecommand} and {\tt \\pastegraph}
-are  macros defined in {\bf util.ht}.
-
-
-
-There is no automatic paste-in generation facility
-for Axiom piles (the {\tt \\begin\{axiomsrc\}} command).
-
-
-The automatic paste-in generation mechanism works
-by invoking Axiom with a particular option.
-\HyperName{} is also started automatically. It reads
-the {\tt \\pastecommand} and {\tt \\pastegraph}
-commands in all pages in a specified
-{\bf somefile.ht}  and passes them to
-Axiom for evaluation. \HyperName{}
-captures the output and writes it out (to a
-file called {\bf somefile.pht}) as the body of
-some {\it patch} definitions. The commands
-encountered are written to a file
-{\bf somefile.input} which you can {\tt )read} from an Axiom session.
-It also creates directories for the graphics
-images encountered. Those files and directories
-will be written under the {\it current} directory.
-The idea is that you then include the {\it patch} definitions
-in {\bf somefile.pht} in your local database using {\bf htadd}.
-
-
-You can try this feature now. Edit a file called, say, {\bf trypaste.ht}
-in a directory, say {\bf /tmp}. Put the following \HyperName{} text
-in it.
-\beginImportant
-\newline
-{\tt \\begin\{page\}\{TryPaste\}\{Trying out paste-in generation\}}\newline
-{\tt \\begin\{scroll\}}\newline
-{\tt \\pastecommand\{f z == z**2 \\bound\{f\}\}}\newline
-{\tt \\pastegraph\{draw(f,-1..1) \\free\{f\}\}}\newline
-{\tt \\pastecommand\{x:= f 3 \\free\{f\}\}}\newline
-{\tt \\end\{scroll\}}\newline
-{\tt \\end\{page\}}\newline
-\endImportant
-
-From the directory that contains the {\bf trypaste.ht},
-issue
-\centerline{
-{\tt htadd -l ./trypaste.ht}
-}
-You will get the
-{\bf ht.db} database file.
-Set the environment variable {\tt HTPATH} so that
-it points first to your directory and then the system directory.
-In the {\bf /bin/csh}, you might use
-\centerline{
-{\tt setenv HTPATH /tmp:\$AXIOM/doc/hypertex/pages}
-}
-Make sure that no {\bf trypaste.input} or {\bf trypaste.pht}
-files exist in the directory.
-Then issue
-\centerline{
-{\tt axiom -paste trypaste.ht}
-}
- and wait for
-Axiom to finish.
-
-There is a modification you will wish to make to
-the {\bf trypaste.pht} file.
-This is because the generated \HyperName{} text will assume that
-the {\it viewport} data will be located in the
-{\it system} directory.
-\centerline{{\bf \env{AXIOM}/doc/viewports}}
-You may want to place your images in a different directory,
-say, {\bf /u/sugar/viewports}.
-If so, then change all occurences of
-\beginImportant
-\newline
-{\tt \\env\{AXIOM\}/doc/viewports/}
-\centerline{{\it by}}
-{\tt /u/sugar/viewports/}
-\endImportant
-in the file {\bf trypaste.pht}. The last step
-is to include the {\it patch} definitions
-in {\bf trypaste.pht} to your local database.
-Issue
-\centerline{
-{\tt htadd -l ./trypaste.pht}
-}
-to update the database. If you have provided
-a link to your pages from the {\tt RootPage}
-via the {\tt \\localinfo} macro, you should now
-be able to start Axiom or \HyperName{}
-and see the computed Axiom output whenever you
-click on the buttons to the left of each command.
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next Page --- Miscellaneous}{HTXAdvPage6}
-\endmenu
-
-\end{page}
-
-@
-\section{htxadvpage6.ht}
-\subsection{Miscellaneous}
-\label{HTXAdvPage6}
-See HTXAdvTopPage \ref{HTXAdvTopPage} on page~\pageref{HTXAdvTopPage}
-\index{pages!HTXAdvPage6!htxadvpage6.ht}
-\index{htxadvpage6.ht!pages!HTXAdvPage6}
-\index{HTXAdvPage6!htxadvpage6.ht!pages}
-<<htxadvpage6.ht>>=
-\begin{page}{HTXAdvPage6}{Miscellaneous}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-
-We present here a few commands that may be of some use
-to you.
-You may want to know certain parameters so that you can pass
-them to one of the action {\tt \\command}s.
-
-The {\tt \\thispage} command shows the name of the
-current page.
-
-\beginImportant
-\begin{paste}{HTXAdvPage6xPaste1}{HTXAdvPage6xPatch1}
-\pastebutton{HTXAdvPage6xPaste1}{Interpret}
-\newline
-{\tt \\thispage}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Lisp\}\{(pprint "\\thispage")\}}\newline
-\end{paste}
-\endImportant
-
-
-The {\tt \\windowid} command shows the X Windows
-{\it WindowID} of the current window.
-
-\beginImportant
-\begin{paste}{HTXAdvPage6xPaste2}{HTXAdvPage6xPatch2}
-\pastebutton{HTXAdvPage6xPaste2}{Interpret}
-\newline
-{\tt \\windowid}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Lisp\}\{(pprint \\windowid)\}}\newline
-\end{paste}
-\endImportant
-
-% \examplenumber not documented
-
-The {\tt \\env} command gets the value of an environment
-variable. It is an error to use {\tt \\env} with an undefined
-environment variable.
-
-\beginImportant
-\begin{paste}{HTXAdvPage6xPaste3}{HTXAdvPage6xPatch3}
-\pastebutton{HTXAdvPage6xPaste3}{Interpret}
-\newline
-{\tt \\env\{AXIOM\}}
-\end{paste}
-\endImportant
-
-
-The {\tt \\nolines} command, if included somewhere
-in the page, eliminates the horizontal lines that
-delimit the header and footer regions.
-
-
-% \beep not documented
-
-%\returnbutton{homebutton}{ReturnPage}
-
-%\upbutton{upbutton}{UpPage}
-
-
-\end{scroll}
-\beginmenu
-\menulink{Back to Menu}{HTXAdvTopPage}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXAdvPage6xPatch1 patch}
-\label{HTXAdvPage6xPatch1}
-\index{patch!HTXAdvPage6xPatch1!htxadvpage6.ht}
-\index{htxadvpage6.ht!patch!HTXAdvPage6xPatch1}
-\index{HTXAdvPage6xPatch1!htxadvpage6.ht!patch}
-<<htxadvpage6.ht>>=
-\begin{patch}{HTXAdvPage6xPatch1}
-\begin{paste}{HTXAdvPage6xPaste1A}{HTXAdvPage6xPatch1A}
-\pastebutton{HTXAdvPage6xPaste1A}{Source}
-\newline
-\thispage
-\newline
-\lispcommand{Lisp}{(pprint "\thispage")}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage6xPatch1A patch}
-\label{HTXAdvPage6xPatch1A}
-\index{patch!HTXAdvPage6xPatch1A!htxadvpage6.ht}
-\index{htxadvpage6.ht!patch!HTXAdvPage6xPatch1A}
-\index{HTXAdvPage6xPatch1A!htxadvpage6.ht!patch}
-<<htxadvpage6.ht>>=
-\begin{patch}{HTXAdvPage6xPatch1A}
-\begin{paste}{HTXAdvPage6xPaste1B}{HTXAdvPage6xPatch1}
-\pastebutton{HTXAdvPage6xPaste1B}{Interpret}
-\newline
-{\tt \\thispage}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Lisp\}\{(pprint "\\thispage")\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage6xPatch2 patch}
-\label{HTXAdvPage6xPatch2}
-\index{patch!HTXAdvPage6xPatch2!htxadvpage6.ht}
-\index{htxadvpage6.ht!patch!HTXAdvPage6xPatch2}
-\index{HTXAdvPage6xPatch2!htxadvpage6.ht!patch}
-<<htxadvpage6.ht>>=
-\begin{patch}{HTXAdvPage6xPatch2}
-\begin{paste}{HTXAdvPage6xPaste2A}{HTXAdvPage6xPatch2A}
-\pastebutton{HTXAdvPage6xPaste2A}{Source}
-\newline
-\windowid
-\newline
-\lispcommand{Lisp}{(pprint \windowid)}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage6xPatch2A patch}
-\label{HTXAdvPage6xPatch2A}
-\index{patch!HTXAdvPage6xPatch2A!htxadvpage6.ht}
-\index{htxadvpage6.ht!patch!HTXAdvPage6xPatch2A}
-\index{HTXAdvPage6xPatch2A!htxadvpage6.ht!patch}
-<<htxadvpage6.ht>>=
-\begin{patch}{HTXAdvPage6xPatch2A}
-\begin{paste}{HTXAdvPage6xPaste2B}{HTXAdvPage6xPatch2}
-\pastebutton{HTXAdvPage6xPaste2B}{Interpret}
-\newline
-{\tt \\windowid}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Lisp\}\{(pprint \\windowid)\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage6xPatch3 patch}
-\label{HTXAdvPage6xPatch3}
-\index{patch!HTXAdvPage6xPatch3!htxadvpage6.ht}
-\index{htxadvpage6.ht!patch!HTXAdvPage6xPatch3}
-\index{HTXAdvPage6xPatch3!htxadvpage6.ht!patch}
-<<htxadvpage6.ht>>=
-\begin{patch}{HTXAdvPage6xPatch3}
-\begin{paste}{HTXAdvPage6xPaste3A}{HTXAdvPage6xPatch3A}
-\pastebutton{HTXAdvPage6xPaste3A}{Source}
-\newline
-\env{AXIOM}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXAdvPage6xPatch3A patch}
-\label{HTXAdvPage6xPatch3A}
-\index{patch!HTXAdvPage6xPatch3A!htxadvpage6.ht}
-\index{htxadvpage6.ht!patch!HTXAdvPage6xPatch3A}
-\index{HTXAdvPage6xPatch3A!htxadvpage6.ht!patch}
-<<htxadvpage6.ht>>=
-\begin{patch}{HTXAdvPage6xPatch3A}
-\begin{paste}{HTXAdvPage6xPaste3B}{HTXAdvPage6xPatch3}
-\pastebutton{HTXAdvPage6xPaste3B}{Interpret}
-\newline
-{\tt \\env\{AXIOM\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\section{htxadvtoppage.ht}
-\subsection{Advanced features in Hyperdoc}
-\label{HTXAdvTopPage}
-\begin{itemize}
-\item HTXAdvPage1 \ref{HTXAdvPage1} on page~\pageref{HTXAdvPage1}
-\item HTXAdvPage2 \ref{HTXAdvPage2} on page~\pageref{HTXAdvPage2}
-\item HTXAdvPage3 \ref{HTXAdvPage3} on page~\pageref{HTXAdvPage3}
-\item HTXAdvPage4 \ref{HTXAdvPage4} on page~\pageref{HTXAdvPage4}
-\item HTXAdvPage5 \ref{HTXAdvPage5} on page~\pageref{HTXAdvPage5}
-\item HTXAdvPage6 \ref{HTXAdvPage6} on page~\pageref{HTXAdvPage6}
-\end{itemize}
-\index{pages!HTXAdvTopPage!htxadvtoppage.ht}
-\index{htxadvtoppage.ht!pages!HTXAdvTopPage}
-\index{HTXAdvTopPage!htxadvtoppage.ht!pages}
-<<htxadvtoppage.ht>>=
-\begin{page}{HTXAdvTopPage}{Advanced features in Hyperdoc}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\beginscroll
-\beginmenu
-\menudownlink{Creating input areas}{HTXAdvPage1}
-\menudownlink{Creating radio boxes}{HTXAdvPage2}
-\menudownlink{Define new macros     }{HTXAdvPage3}
-\menudownlink{Using patch and paste}{HTXAdvPage4}
-\menudownlink{Generate paste-ins for Axiom commands}{HTXAdvPage5}
-\menudownlink{Miscellaneous}{HTXAdvPage6}
-\endmenu
-\endscroll
-\end{page}
-
-@
-\section{htxformatpage1.ht}
-\subsection{Using the special characters}
-\label{HTXFormatPage1}
-See HTXFormatPage2 \ref{HTXFormatPage2} on page~\pageref{HTXFormatPage2}
-\index{pages!HTXFormatPage1!htxformatpage1.ht}
-\index{htxformatpage1.ht!pages!HTXFormatPage1}
-\index{HTXFormatPage1!htxformatpage1.ht!pages}
-<<htxformatpage1.ht>>=
-\begin{page}{HTXFormatPage1}{Using the special characters}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-You can display the special characters ({\tt \$ \\ \{ \{ \[ \] \% \#})
-by simply inserting the backslash {\tt \\} character just before any 
-one of them. So,
-\beginImportant
-\begin{paste}{HTXFormatPage1xPaste1}{HTXFormatPage1xPatch1}
-\pastebutton{HTXFormatPage1xPaste1}{Interpret}
-\newline
-{\tt the characters \\\$, \\\\, \\\{, \\\}, \\\[, \\\], \\\%, \\\# }
-\end{paste}
-\endImportant
-
-
-The {\tt \%} character is used in \HyperName{} as a comment marker.
-If it is encountered on any line (without being preceded by the {\tt \\}
- character,
-of course), \HyperName{} will ignore all remaining characters on that line.
-\beginImportant
-\begin{paste}{HTXFormatPage1xPaste2}{HTXFormatPage1xPatch2}
-\pastebutton{HTXFormatPage1xPaste2}{Interpret}
-\newline
-{\tt  the latest figures indicate \% GET THE LATEST FIGURES}\newline
-{\tt a steady rise}\indent{0}
-\end{paste}
-\endImportant
-
-Earlier versions of \HyperName{} merged the words "indicate" and "a"
-into one word in the example above. This no longer occurs.
-
-%The two lines below are from Release 1.x
-%Note that you must leave a space at the beginning of the line after the comment,
-%otherwise \HyperName{} would treat "indicate" and "a" as one word.
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Formatting without commands}{HTXFormatPage2}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage1xPatch1 patch}
-\label{HTXFormatPage1xPatch1}
-\index{patch!HTXFormatPage1xPatch1!htxformatpage1.ht}
-\index{htxformatpage1.ht!patch!HTXFormatPage1xPatch1}
-\index{HTXFormatPage1xPatch1!htxformatpage1.ht!patch}
-<<htxformatpage1.ht>>=
-\begin{patch}{HTXFormatPage1xPatch1}
-\begin{paste}{HTXFormatPage1xPaste1A}{HTXFormatPage1xPatch1A}
-\pastebutton{HTXFormatPage1xPaste1A}{Source}
-\newline
-the characters \$, \\, \{, \}, \[, \],  \%, \#
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage1xPatch1A}
-\begin{paste}{HTXFormatPage1xPaste1B}{HTXFormatPage1xPatch1}
-\pastebutton{HTXFormatPage1xPaste1B}{Interpret}
-\newline
-{\tt the characters \\\$, \\\\, \\\{, \\\}, \\\[, \\\], \\\%, \\\# }
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage1xPatch2 patch}
-\label{HTXFormatPage1xPatch2}
-\index{patch!HTXFormatPage1xPatch2!htxformatpage1.ht}
-\index{htxformatpage1.ht!patch!HTXFormatPage1xPatch2}
-\index{HTXFormatPage1xPatch2!htxformatpage1.ht!patch}
-<<htxformatpage1.ht>>=
-\begin{patch}{HTXFormatPage1xPatch2}
-\begin{paste}{HTXFormatPage1xPaste2A}{HTXFormatPage1xPatch2A}
-\pastebutton{HTXFormatPage1xPaste2A}{Source}
-\newline
-the latest figures indicate % GET THE LATEST FIGURES
-a steady rise
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage1xPatch2A}
-\begin{paste}{HTXFormatPage1xPaste2B}{HTXFormatPage1xPatch2}
-\pastebutton{HTXFormatPage1xPaste2B}{Interpret}
-\newline
-{\tt  the latest figures indicate \% GET THE LATEST FIGURES}\newline
-{\tt a steady rise}\indent{0}
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage2.ht}
-\subsection{Formatting without commands}
-\label{HTXFormatPage2}
-\index{pages!HTXFormatPage2!htxformatpage2.ht}
-\index{htxformatpage2.ht!pages!HTXFormatPage2}
-\index{HTXFormatPage2!htxformatpage2.ht!pages}
-<<htxformatpage2.ht>>=
-\begin{page}{HTXFormatPage2}{Formatting without commands}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-\HyperName{} will interpret normal text in a {\em source file}
-according to the following rules. \newline
-\menuitemstyle{\indentrel{4}
-Spaces mark the ends of words. The number of spaces between
-words is {\em not} significant, that is, you cannot control word spacing
-by inserting or removing extra space characters.
-\indentrel{-4}}
-\beginImportant
-\begin{paste}{HTXFormatPage2xxPaste1}{HTXFormatPage2xPatch1}
-\pastebutton{HTXFormatPage2xxPaste1}{Interpret}
-\begin{verbatim}
-word    spacing is       not  important
-\end{verbatim}
-\end{paste}
-\endImportant
-\menuitemstyle{\indentrel{4}
-End-of-line  characters are not significant.
-You can break up lines in the source file as you like. The end-of-line
-will be interpreted as a space. 
-Take advantage of this feature to improve the readability of the
-source file.
-\indentrel{-4}}
-\beginImportant
-\begin{paste}{HTXFormatPage2xxPaste2}{HTXFormatPage2xPatch2}
-\pastebutton{HTXFormatPage2xxPaste2}{Interpret}
-\begin{verbatim}
-This is
-one
-sentence.
-\end{verbatim}
-\end{paste}
-\endImportant
-\menuitemstyle{\indentrel{4}
-A blank line marks the end of a paragraph. 
-Leaving more blank lines that necessary has no effect.
-\indentrel{-4}}
-\beginImportant
-\begin{paste}{HTXFormatPage2xxPaste3}{HTXFormatPage2xPatch3}
-\pastebutton{HTXFormatPage2xxPaste3}{Interpret}
-\begin{verbatim}
-some end.% A COMMENT
-
-
-Start a paragraph
-
-Start another paragraph.
-\end{verbatim}
-\end{paste}
-\endImportant
-\menuitemstyle{\indentrel{4}
-The two-character combination {\tt \{\}} can be used to indicate
-possible breaking of long words. It does not affect the formatting
-in any other way.
-\indentrel{-4}}
-\beginImportant
-\begin{paste}{HTXFormatPage2xxPaste4}{HTXFormatPage2xPatch4}
-\pastebutton{HTXFormatPage2xxPaste4}{Interpret}
-\begin{verbatim}
-Generalized{}Multivariate{}Factorize
-One{}Dimensional{}Array{}Aggregate
-Elementary{}Function{}Definite{}Integration
-Elementary{}Functions{}Univariate{}Puiseux{}Series
-Finite{}Field{}Cyclic{}Group{}Extension{}ByPolynomial
-\end{verbatim}
-\end{paste}
-\endImportant
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Using different fonts}{HTXFormatPage3}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage2xPatch1 patch}
-\label{HTXFormatPage2xPatch1}
-\index{patch!HTXFormatPage2xPatch1!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch1}
-\index{HTXFormatPage2xPatch1!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch1}
-\begin{paste}{HTXFormatPage2xxPaste1A}{HTXFormatPage2xPatch1A}
-\pastebutton{HTXFormatPage2xxPaste1A}{Source}
-\newline
-word    spacing is       not  important
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage2xPatch1A}
-\begin{paste}{HTXFormatPage2xxPaste1B}{HTXFormatPage2xPatch1}
-\pastebutton{HTXFormatPage2xxPaste1B}{Interpret}
-\begin{verbatim}
-word    spacing is       not  important
-\end{verbatim}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage2xPatch2 patch}
-\label{HTXFormatPage2xPatch2}
-\index{patch!HTXFormatPage2xPatch2!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch2}
-\index{HTXFormatPage2xPatch2!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch2}
-\begin{paste}{HTXFormatPage2xxPaste2A}{HTXFormatPage2xPatch2A}
-\pastebutton{HTXFormatPage2xxPaste2A}{Source}
-\newline
-This is
-one
-sentence.
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage2xPatch2A patch}
-\label{HTXFormatPage2xPatch2A}
-\index{patch!HTXFormatPage2xPatch2A!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch2A}
-\index{HTXFormatPage2xPatch2A!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch2A}
-\begin{paste}{HTXFormatPage2xxPaste2B}{HTXFormatPage2xPatch2}
-\pastebutton{HTXFormatPage2xxPaste2B}{Interpret}
-\begin{verbatim}
-This is
-one
-sentence.
-\end{verbatim}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage2xPatch3 patch}
-\label{HTXFormatPage2xPatch3}
-\index{patch!HTXFormatPage2xPatch3!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch3}
-\index{HTXFormatPage2xPatch3!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch3}
-\begin{paste}{HTXFormatPage2xxPaste3A}{HTXFormatPage2xPatch3A}
-\pastebutton{HTXFormatPage2xxPaste3A}{Source}
-\newline
-some end.% A COMMENT
-
-
-Start a paragraph.
-
-Start another paragraph.
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage2xPatch3A patch}
-\label{HTXFormatPage2xPatch3A}
-\index{patch!HTXFormatPage2xPatch3A!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch3A}
-\index{HTXFormatPage2xPatch3A!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch3A}
-\begin{paste}{HTXFormatPage2xxPaste3B}{HTXFormatPage2xPatch3}
-\pastebutton{HTXFormatPage2xxPaste3B}{Interpret}
-\begin{verbatim}
-some end.% A COMMENT
-
-
-Start a paragraph
-
-Start another paragraph.
-\end{verbatim}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage2xPatch4 patch}
-\label{HTXFormatPage2xPatch4}
-\index{patch!HTXFormatPage2xPatch4!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch4}
-\index{HTXFormatPage2xPatch4!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch4}
-\begin{paste}{HTXFormatPage2xxPaste4A}{HTXFormatPage2xPatch4A}
-\pastebutton{HTXFormatPage2xxPaste4A}{Source}
-\newline
-Generalized{}Multivariate{}Factorize
-One{}Dimensional{}Array{}Aggregate
-Elementary{}Function{}Definite{}Integration
-Elementary{}Functions{}Univariate{}Puiseux{}Series
-Finite{}Field{}Cyclic{}Group{}Extension{}ByPolynomial
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage2xPatch4A patch}
-\label{HTXFormatPage2xPatch4A}
-\index{patch!HTXFormatPage2xPatch4A!htxformatpage2.ht}
-\index{htxformatpage2.ht!patch!HTXFormatPage2xPatch4A}
-\index{HTXFormatPage2xPatch4A!htxformatpage2.ht!patch}
-<<htxformatpage2.ht>>=
-\begin{patch}{HTXFormatPage2xPatch4A}
-\begin{paste}{HTXFormatPage2xxPaste4B}{HTXFormatPage2xPatch4}
-\pastebutton{HTXFormatPage2xxPaste4B}{Interpret}
-\begin{verbatim}
-Generalized{}Multivariate{}Factorize
-One{}Dimensional{}Array{}Aggregate
-Elementary{}Function{}Definite{}Integration
-Elementary{}Functions{}Univariate{}Puiseux{}Series
-Finite{}Field{}Cyclic{}Group{}Extension{}ByPolynomial
-\end{verbatim}
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage3.ht}
-\subsection{Using different fonts}
-\label{HTXFormatPage3}
-\index{pages!HTXFormatPage3!htxformatpage3.ht}
-\index{htxformatpage3.ht!pages!HTXFormatPage3}
-\index{HTXFormatPage3!htxformatpage3.ht!pages}
-<<htxformatpage3.ht>>=
-\begin{page}{HTXFormatPage3}{Using different fonts}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-You can use various fonts for the text. \HyperName{} makes
-four {\em logical} fonts available to you: a {\em roman} font, an
-{\em emphasised} font, a {\em bold} font and a
-{\em typewriter} font. The actual font that corresponds to
-each logical font is determined by the end user via a
-defaults file. The colour for each of these fonts can also
-be specified.
-
-Normal text is displayed with the roman font.
-If you want to emphasize some text, use the {\tt \\em}
-command in the following way.
-\beginImportant
-\begin{paste}{HTXFormatPage3xPaste1}{HTXFormatPage3xPatch1}
-\pastebutton{HTXFormatPage3xPaste1}{Interpret}
-\newline
-{\tt this is \{\\em emphasised\} text}
-\end{paste}
-\endImportant
-
-Note the use of the braces to enclose command and "arguments".
-All font commands are specified in the same way. The {\tt \\em} command
-will in fact {\em switch} between roman and emphasised
-font every time it is used.
-\beginImportant
-\begin{paste}{HTXFormatPage3xPaste2}{HTXFormatPage3xPatch2}
-\pastebutton{HTXFormatPage3xPaste2}{Interpret}
-\newline
-{\tt \{\\em this is \{\\em emphasised\} text\}}
-\end{paste}
-\endImportant
-
-If you want to be sure that the emphasized font will be used, specify
-the {\tt \\it} command. Similarly, you can explicitly select the roman font
-with the {\tt \\rm} command.
-\beginImportant
-\begin{paste}{HTXFormatPage3xPaste3}{HTXFormatPage3xPatch3}
-\pastebutton{HTXFormatPage3xPaste3}{Interpret}
-\newline
-{\tt \{\\em this is \{\\it emphasised\} text and this is \{\\rm roman\}\}}
-\end{paste}
-\endImportant
-
-
-The bold font is selected with the {\tt \\bf} command and the typewriter
-font with the {\tt \\tt} command. All these commands can be applied to
-individual characters, words, sentences etc.
-\beginImportant
-\begin{paste}{HTXFormatPage3xPaste4}{HTXFormatPage3xPatch4}
-\pastebutton{HTXFormatPage3xPaste4}{Interpret}
-\newline
-{\tt \{\\bf U\}\{\\tt g\}\{\\it l\}\{\\rm y\}}
-\end{paste}
-\endImportant
-
-
-Currently, \HyperName{} does not adjust its internal spacing rules
-to each font individually. This means that, for consistent results,
-users are encouraged to specify (in the defaults file)
-"character-cell" fonts that are not
-too small or too large for \HyperName{}. Here is the correspondence
-between the above font commands and the defaults names:\newline
-\menuitemstyle{RmFont \tab{26} {\tt \\rm} or {\tt \\em} }\newline
-\menuitemstyle{BoldFont \tab{26} {\tt \\bf} }\newline
-\menuitemstyle{EmphasizeFont \tab{26} {\tt \\it} or {\tt \\em} }\newline
-\menuitemstyle{Ttfont \tab{26} {\tt \\tt} }\newline
-
-\HyperName{} uses two more logical fonts that can be specified by
-the end user : AxiomFont and ActiveFont. However, you cannot
-explicitly use these fonts in your text. The ActiveFont is automatically
-used for active area text and the AxiomFont is reserved for
-active Axiom commands.
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Indentation}{HTXFormatPage4}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage3xPatch1 patch}
-\label{HTXFormatPage3xPatch1}
-\index{patch!HTXFormatPage3xPatch1!htxformatpage3.ht}
-\index{htxformatpage3.ht!patch!HTXFormatPage3xPatch1}
-\index{HTXFormatPage3xPatch1!htxformatpage3.ht!patch}
-<<htxformatpage3.ht>>=
-\begin{patch}{HTXFormatPage3xPatch1}
-\begin{paste}{HTXFormatPage3xPaste1A}{HTXFormatPage3xPatch1A}
-\pastebutton{HTXFormatPage3xPaste1A}{Source}
-\newline
-this is {\em emphasised} text
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage3xPatch1A}
-\begin{paste}{HTXFormatPage3xPaste1B}{HTXFormatPage3xPatch1}
-\pastebutton{HTXFormatPage3xPaste1B}{Interpret}
-\newline
-{\tt this is \{\\em emphasised\} text}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage3xPatch2 patch}
-\label{HTXFormatPage3xPatch2}
-\index{patch!HTXFormatPage3xPatch2!htxformatpage3.ht}
-\index{htxformatpage3.ht!patch!HTXFormatPage3xPatch2}
-\index{HTXFormatPage3xPatch2!htxformatpage3.ht!patch}
-<<htxformatpage3.ht>>=
-\begin{patch}{HTXFormatPage3xPatch2}
-\begin{paste}{HTXFormatPage3xPaste2A}{HTXFormatPage3xPatch2A}
-\pastebutton{HTXFormatPage3xPaste2A}{Source}
-\newline
-{\em this is {\em emphasised} text}
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage3xPatch2A}
-\begin{paste}{HTXFormatPage3xPaste2B}{HTXFormatPage3xPatch2}
-\pastebutton{HTXFormatPage3xPaste2B}{Interpret}
-\newline
-{\tt \{\\em this is \{\\em emphasised\} text\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage3xPatch3 patch}
-\label{HTXFormatPage3xPatch3}
-\index{patch!HTXFormatPage3xPatch3!htxformatpage3.ht}
-\index{htxformatpage3.ht!patch!HTXFormatPage3xPatch3}
-\index{HTXFormatPage3xPatch3!htxformatpage3.ht!patch}
-<<htxformatpage3.ht>>=
-\begin{patch}{HTXFormatPage3xPatch3}
-\begin{paste}{HTXFormatPage3xPaste3A}{HTXFormatPage3xPatch3A}
-\pastebutton{HTXFormatPage3xPaste3A}{Source}
-\newline
-{\em this is {\it emphasised} text and this is {\rm roman}}
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage3xPatch3A}
-\begin{paste}{HTXFormatPage3xPaste3B}{HTXFormatPage3xPatch3}
-\pastebutton{HTXFormatPage3xPaste3B}{Interpret}
-\newline
-{\tt \{\\em this is \{\\it emphasised\} text and this is \{\\rm roman\}\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage3xPatch4 patch}
-\label{HTXFormatPage3xPatch4}
-\index{patch!HTXFormatPage3xPatch4!htxformatpage3.ht}
-\index{htxformatpage3.ht!patch!HTXFormatPage3xPatch4}
-\index{HTXFormatPage3xPatch4!htxformatpage3.ht!patch}
-<<htxformatpage3.ht>>=
-\begin{patch}{HTXFormatPage3xPatch4}
-\begin{paste}{HTXFormatPage3xPaste4A}{HTXFormatPage3xPatch4A}
-\pastebutton{HTXFormatPage3xPaste4A}{Source}
-\newline
-{\bf U}{\tt g}{\it l}{\rm y}
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage3xPatch4A}
-\begin{paste}{HTXFormatPage3xPaste4B}{HTXFormatPage3xPatch4}
-\pastebutton{HTXFormatPage3xPaste4B}{Interpret}
-\newline
-{\tt \{\\bf U\}\{\\tt g\}\{\\it l\}\{\\rm y\}}
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage4.ht}
-\subsection{Indentation}
-\label{HTXFormatPage4}
-\index{pages!HTXFormatPage4!htxformatpage4.ht}
-\index{htxformatpage4.ht!pages!HTXFormatPage4}
-\index{HTXFormatPage4!htxformatpage4.ht!pages}
-<<htxformatpage4.ht>>=
-\begin{page}{HTXFormatPage4}{Indentation}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-You can control the indentation of lines of text in \HyperName{} with
-some useful commands.
-Use the command {\tt \\par} to force a new paragraph if you don't want
-to use the blank-line rule. The first line of a new paragraph
-will normally be indented by a standard small amount. If you
-just want to start on a new line, use the {\tt \\newline}
-command.
-\beginImportant
-\begin{paste}{HTXFormatPage4xPaste1}{HTXFormatPage4xPatch1}
-\pastebutton{HTXFormatPage4xPaste1}{Interpret}
-\newline
-{\tt let us start a new line \\newline here }
-\end{paste}
-\endImportant
-
-The  command {\tt \\indent\{{\it value}\}} will
-set the left-page-margin {\it value} characters
-to the right of the standard left-page-margin.
-The initial (standard) state of a page can be reset by the
-{\tt \\indent\{0\}} command.
-The first lines of paragraphs will be indented
-by the {\it extra} standard  amount. The {\tt \\indent\{{\it value}\}}
-command does {\em not} force a new line or paragraph.
-
-You can also use the {\tt \\indentrel\{{\it value}\}} command.
-Here, the {\it value} argument is a {\em relative} indentation
-which can be positive or negative.
-Otherwise, it behaves in the same way as the {\tt \\indent} command.
-\beginImportant
-\begin{paste}{HTXFormatPage4xPaste2}{HTXFormatPage4xPatch2}
-\pastebutton{HTXFormatPage4xPaste2}{Interpret}
-\newline
-{\tt let us start a new line \\newline \\indent\{10\} here }\newline
-{\tt \\newline \\indentrel\{-5\} there}\newline
-{\tt \\newline \\indentrel\{-5\} back}
-\end{paste}
-\endImportant
-
-The {\tt \\centerline\{{\it some text}\}} command will center its
-argument between the current left and right margins. The argument of
-the command should not be more than a paragraph of text and should not contain
-any commands that change the left margin. The centered text will
-start on a new line.
-\beginImportant
-\begin{paste}{HTXFormatPage4xPaste3}{HTXFormatPage4xPatch3}
-\pastebutton{HTXFormatPage4xPaste3}{Interpret}
-\newline
-{\tt previous text. \\centerline\{This could}\newline
-{\tt be some heading.\} Carry on}
-\end{paste}
-\endImportant
-
-Placing text in vertically aligned columns is easily done with the
-{\tt \\tab\{{\it value}\}} command. The {\tt \\tab} command has the
-immediate effect of placing the next word {\it value} characters to
-the right of the current left margin.
-\beginImportant
-\begin{paste}{HTXFormatPage4xPaste4}{HTXFormatPage4xPatch4}
-\pastebutton{HTXFormatPage4xPaste4}{Interpret}
-\newline
-{\tt \\indent\{5\}\\newline}\newline
-{\tt Team A \\tab\{17\}Score\\tab\{25\}Team B\\tab\{42\}Score\\newline}\newline
-{\tt 012345678901234567890123456789012345678901234567890\\newline}\newline
-{\tt Green-Red\\tab\{17\}4\\tab\{25\}Blue-Black\\tab\{42\}6\\newline}\newline
-{\tt \\indent\{0\}}
-\end{paste}
-\endImportant
-
-If you wish to preserve the indentation of a piece of text
-you can use the {\tt verbatim} group command. Simply place
-a {\tt \\begin\{verbatim\}} and {\tt \\end\{verbatim\}} around
-the text. Note that \HyperName{} commands will
-not be interpreted within the {\tt verbatim} group.
-\beginImportant
-\begin{paste}{HTXFormatPage4xPaste5}{HTXFormatPage4xPatch5}
-\pastebutton{HTXFormatPage4xPaste5}{Interpret}
-\newline
-{\tt \\begin\{verbatim\}}
-\begin{verbatim}
-This    spacing     will be      preserved
-                    {\bf is}     preserved
-\end{verbatim}
-{\tt \\end\{verbatim\}}\newline
-\end{paste}
-
-
-
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Creating Lists and Tables}{HTXFormatPage5}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage4xPatch1 patch}
-\label{HTXFormatPage4xPatch1}
-\index{patch!HTXFormatPage4xPatch1!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch1}
-\index{HTXFormatPage4xPatch1!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch1}
-\begin{paste}{HTXFormatPage4xPaste1A}{HTXFormatPage4xPatch1A}
-\pastebutton{HTXFormatPage4xPaste1A}{Source}
-\newline
-let us start a new line \newline here
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch1A patch}
-\label{HTXFormatPage4xPatch1A}
-\index{patch!HTXFormatPage4xPatch1A!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch1A}
-\index{HTXFormatPage4xPatch1A!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch1A}
-\begin{paste}{HTXFormatPage4xPaste1B}{HTXFormatPage4xPatch1}
-\pastebutton{HTXFormatPage4xPaste1B}{Interpret}
-\newline
-{\tt let us start a new line \\newline here }
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch2 patch}
-\label{HTXFormatPage4xPatch2}
-\index{patch!HTXFormatPage4xPatch2!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch2}
-\index{HTXFormatPage4xPatch2!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch2}
-\begin{paste}{HTXFormatPage4xPaste2A}{HTXFormatPage4xPatch2A}
-\pastebutton{HTXFormatPage4xPaste2A}{Source}
-\newline
-let us start a new line\newline\indent{10} here
-\newline\indentrel{-5} there
-\newline\indentrel{-5} back
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch2A patch}
-\label{HTXFormatPage4xPatch2A}
-\index{patch!HTXFormatPage4xPatch2A!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch2A}
-\index{HTXFormatPage4xPatch2A!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch2A}
-\begin{paste}{HTXFormatPage4xPaste2B}{HTXFormatPage4xPatch2}
-\pastebutton{HTXFormatPage4xPaste2B}{Interpret}
-\newline
-{\tt let us start a new line \\newline \\indent\{10\} here }\newline
-{\tt \\newline \\indentrel\{-5\} there}\newline
-{\tt \\newline \\indentrel\{-5\} back}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch3 patch}
-\label{HTXFormatPage4xPatch3}
-\index{patch!HTXFormatPage4xPatch3!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch3}
-\index{HTXFormatPage4xPatch3!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch3}
-\begin{paste}{HTXFormatPage4xPaste3A}{HTXFormatPage4xPatch3A}
-\pastebutton{HTXFormatPage4xPaste3A}{Source}
-\newline
-previous text. \centerline{This could
-be some heading.} Carry on
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch3A patch}
-\label{HTXFormatPage4xPatch3A}
-\index{patch!HTXFormatPage4xPatch3A!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch3A}
-\index{HTXFormatPage4xPatch3A!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch3A}
-\begin{paste}{HTXFormatPage4xPaste3B}{HTXFormatPage4xPatch3}
-\pastebutton{HTXFormatPage4xPaste3B}{Interpret}
-\newline
-{\tt previous text. \\centerline\{This could}\newline
-{\tt be some heading.\} Carry on}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch4 patch}
-\label{HTXFormatPage4xPatch4}
-\index{patch!HTXFormatPage4xPatch4!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch4}
-\index{HTXFormatPage4xPatch4!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch4}
-\begin{paste}{HTXFormatPage4xPaste4A}{HTXFormatPage4xPatch4A}
-\pastebutton{HTXFormatPage4xPaste4A}{Source}
-\newline
-\indent{5}\newline
-Team A \tab{17}Score\tab{25}Team B\tab{42}Score\newline
-012345678901234567890123456789012345678901234567890\newline
-Green-Red\tab{17}4\tab{25}Blue-Black\tab{42}6\newline
-\indent{0}
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage4xPatch4A}
-\begin{paste}{HTXFormatPage4xPaste4B}{HTXFormatPage4xPatch4}
-\pastebutton{HTXFormatPage4xPaste4B}{Interpret}
-\newline
-{\tt \\indent\{5\}\\newline}\newline
-{\tt Team A \\tab\{17\}Score\\tab\{25\}Team B\\tab\{42\}Score\\newline}\newline
-{\tt 012345678901234567890123456789012345678901234567890\\newline}\newline
-{\tt Green-Red\\tab\{17\}4\\tab\{25\}Blue-Black\\tab\{42\}6\\newline}\newline
-{\tt \\indent\{0\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch5 patch}
-\label{HTXFormatPage4xPatch5}
-\index{patch!HTXFormatPage4xPatch5!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch5}
-\index{HTXFormatPage4xPatch5!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch5}
-\begin{paste}{HTXFormatPage4xPaste5A}{HTXFormatPage4xPatch5A}
-\pastebutton{HTXFormatPage4xPaste5A}{Source}
-\begin{verbatim}
-This    spacing     will be      preserved
-                    {\bf is}     preserved
-\end{verbatim}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage4xPatch5A patch}
-\label{HTXFormatPage4xPatch5A}
-\index{patch!HTXFormatPage4xPatch5A!htxformatpage4.ht}
-\index{htxformatpage4.ht!patch!HTXFormatPage4xPatch5A}
-\index{HTXFormatPage4xPatch5A!htxformatpage4.ht!patch}
-<<htxformatpage4.ht>>=
-\begin{patch}{HTXFormatPage4xPatch5A}
-\begin{paste}{HTXFormatPage4xPaste5B}{HTXFormatPage4xPatch5}
-\pastebutton{HTXFormatPage4xPaste5B}{Interpret}
-\newline
-{\tt \\begin\{verbatim\}}
-\begin{verbatim}
-This    spacing     will be      preserved
-                    {\bf is}     preserved
-\end{verbatim}
-{\tt \\end\{verbatim\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage5.ht}
-\subsection{Creating Lists and Tables}
-\label{HTXFormatPage5}
-See HTXFormatPage6 \ref{HTXFormatPage6} on page~\pageref{HTXFormatPage6}
-\index{pages!HTXFormatPage5!htxformatpage5.ht}
-\index{htxformatpage5.ht!pages!HTXFormatPage5}
-\index{HTXFormatPage5!htxformatpage5.ht!pages}
-<<htxformatpage5.ht>>=
-\begin{page}{HTXFormatPage5}{Creating Lists and Tables}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-The {\tt \\begin\{items\} {\rm -}  \\end\{items\}} 
-group command constructs itemized lists.
-The {\tt \\item} command separates the items in the list.
-The indentation rules for the list group are different from those
-of a paragraph. The first line of an item will
-normally extend further to the left than the rest of the lines.
-Both commands accept {\em optional} arguments.
-Optional arguments are enclosed in square brackets ({\tt \[ \]}) rather
-than braces.
-
-The indentation of subsequent lines in an item is determined by the
-optional argument {\it some text} in the 
-{\tt \\begin\{items\}\[{\it some text}\]}
-command. The optional argument is {\em not} displayed. Its width is calculated
-and used to indent all subsequent lines in the group except from the
-first line of each new item. This indentation rule applies to all text
-{\em before} the first {\tt \\item} command as well.
-
-The {\tt \\item\[{\it some text}\]} command specifies the start of a new item.
-The {\it some text} optional argument will be displayed in {\em bold}
-font at the current left-page-margin. Then, the text following the command
-will be displayed in normal fashion with the above indentation rule.
-\beginImportant
-\begin{paste}{HTXFormatPage5xPaste1}{HTXFormatPage5xPatch1}
-\pastebutton{HTXFormatPage5xPaste1}{Interpret}
-\newline
-{\tt \\indent\{5\}}\newline
-{\tt \\begin\{items\}\[how wide am I\]}\newline
-{\tt Here we carry on but a \\newline} \newline
-{\tt new line will be indented } \newline
-{\tt \\item\[how wide am I\] fits nicely. 
-Here is a \\newline new line in an item.}\newline
-{\tt \\item\[again\] to show another item}\newline
-{\tt \\item\[\\\\tab\]\\tab\{0\} can be used \\tab\{15\} effectively}\newline
-{\tt \\end\{items\}}\newline
-{\tt \\indent\{0\}}\newline
-\end{paste}
-\endImportant
-
-
-Note that the {\tt \\begin\{items\}} command immediately sets the left-
-page-margin to a new value. Subsequent 
-{\tt \\tab} or {\tt \\centerline} commands
-refer to this new margin.
-Any explicit margin setting commands included
-in the group {\em will} have the normal effect.
-The {\tt \\par} command does not produce
-the standard paragraph indentation within a list group --- it behaves
-instead like {\tt \\newline}.
-
-
-You can nest list groups like the following example suggests.
-\beginImportant
-\begin{paste}{HTXFormatPage5xPaste2}{HTXFormatPage5xPatch2}
-\pastebutton{HTXFormatPage5xPaste2}{Interpret}
-\newline
-{\tt \\begin\{items\}\[quitealot\]}\newline
-{\tt A nested list:}\newline
-{\tt \\item\[The first\] item of an itemized list is on this line.}\newline
-{\tt \\item\[The second\] item of the list starts here.  It contains another}\newline
-{\tt list nested inside it.}\newline
-{\tt \\begin\{items\}\[somuchmore\]}\newline
-{\tt \\item \[First\]\\tab\{0\}This is the first item of an enumerated}\newline
-{\tt list that is nested within the itemized list.}\newline
-{\tt \\item \[Second\]\\tab\{0\}This is the second item of the inner list.}\newline
-{\tt \\end\{items\}}\newline
-{\tt This is the rest of the second item of the outer list.  It}\newline
-{\tt is no more interesting than any other part of the item.}\newline
-{\tt \\item\[The third\] item of the list.}\newline
-{\tt \\end\{items\}}\newline
-\end{paste}
-\endImportant
-
-Another facility for presenting lists is the {\tt \\table} command.
-The correct syntax for it is : {\tt \\table\{\{{\it item a}\} \{{\it item b}\} {\it ..}\}}.
-The items in the braces will be placed in as many aligned columns
-as is possible for the current window dimensions or page width.
-If one item is particularly long there will probably be only one column
-in the table. Here is a table of color names.
-\beginImportant
-\begin{paste}{HTXFormatPage5xPaste3}{HTXFormatPage5xPatch3}
-\pastebutton{HTXFormatPage5xPaste3}{Interpret}
-\newline
-{\tt
-\\table\{
-\{Dark Orchid\} \{Dark Salmon\} \{Dark Sea Green\} \{Dark Slate Blue\}
-\{Dark Slate Gray\} \{Dark Turquoise\} \{Dark Violet\} \{Deep Pink\}
-\{Deep Sky Blue\} \{Dodger Blue\} \{Floral White\} \{Forest Green\}
-\{Ghost White\} \{Hot Pink\} \{Indian Red\} \{Lavender Blush\}
-\}
-}
-\end{paste}
-\endImportant
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Boxes and Lines}{HTXFormatPage6}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage5xPatch1 patch}
-\label{HTXFormatPage5xPatch1}
-\index{patch!HTXFormatPage5xPatch1!htxformatpage5.ht}
-\index{htxformatpage5.ht!patch!HTXFormatPage5xPatch1}
-\index{HTXFormatPage5xPatch1!htxformatpage5.ht!patch}
-<<htxformatpage5.ht>>=
-\begin{patch}{HTXFormatPage5xPatch1}
-\begin{paste}{HTXFormatPage5xPaste1A}{HTXFormatPage5xPatch1A}
-\pastebutton{HTXFormatPage5xPaste1A}{Source}
-\newline
-\indent{5}
-\begin{items}[how wide am I]
-Here we carry on but a \newline
-new line will be indented
-\item[how wide am I] fits nicely. Here is a \newline new line in an item.
-\item[again] to show another item
-\item[\\tab]\tab{0} can be used \tab{15} effectively
-\end{items}
-\indent{0}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage5xPatch1A patch}
-\label{HTXFormatPage5xPatch1A}
-\index{patch!HTXFormatPage5xPatch1A!htxformatpage5.ht}
-\index{htxformatpage5.ht!patch!HTXFormatPage5xPatch1A}
-\index{HTXFormatPage5xPatch1A!htxformatpage5.ht!patch}
-<<htxformatpage5.ht>>=
-\begin{patch}{HTXFormatPage5xPatch1A}
-\begin{paste}{HTXFormatPage5xPaste1B}{HTXFormatPage5xPatch1}
-\pastebutton{HTXFormatPage5xPaste1B}{Interpret}
-\newline
-{\tt \\indent\{5\}}\newline
-{\tt \\begin\{items\}\[how wide am I\]}\newline
-{\tt Here we carry on but a \\newline} \newline
-{\tt new line will be indented } \newline
-{\tt \\item\[how wide am I\] fits nicely. Here is a \\newline new line in an item.}\newline
-{\tt \\item\[again\] to show another item}\newline
-{\tt \\item\[\\\\tab\]\\tab\{0\} can be used \\tab\{15\} effectively}\newline
-{\tt \\end\{items\}}\newline
-{\tt \\indent\{0\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage5xPatch2 patch}
-\label{HTXFormatPage5xPatch2}
-\index{patch!HTXFormatPage5xPatch2!htxformatpage5.ht}
-\index{htxformatpage5.ht!patch!HTXFormatPage5xPatch2}
-\index{HTXFormatPage5xPatch2!htxformatpage5.ht!patch}
-<<htxformatpage5.ht>>=
-\begin{patch}{HTXFormatPage5xPatch2}
-\begin{paste}{HTXFormatPage5xPaste2A}{HTXFormatPage5xPatch2A}
-\pastebutton{HTXFormatPage5xPaste2A}{Source}
-\newline
-\begin{items}[quitealot]
-A nested list:
-\item[The first] item of an itemized list is on this line.
-\item[The second] item of the list starts here.  It contains another
-list nested inside it.
-\begin{items}[somuchmore]
-\item [First]\tab{0}This is the first item of the
-list that is nested within the itemized list.
-\item [Second]\tab{0}This is the second item of the inner list.
-\end{items}
-This is the rest of the second item of the outer list.  It
-is no more interesting than any other part of the item.
-\item [The third] item of the list.
-\end{items}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage5xPatch2A patch}
-\label{HTXFormatPage5xPatch2A}
-\index{patch!HTXFormatPage5xPatch2A!htxformatpage5.ht}
-\index{htxformatpage5.ht!patch!HTXFormatPage5xPatch2A}
-\index{HTXFormatPage5xPatch2A!htxformatpage5.ht!patch}
-<<htxformatpage5.ht>>=
-\begin{patch}{HTXFormatPage5xPatch2A}
-\begin{paste}{HTXFormatPage5xPaste2B}{HTXFormatPage5xPatch2}
-\pastebutton{HTXFormatPage5xPaste2B}{Interpret}
-\newline
-{\tt \\begin\{items\}\[quitealot\]}\newline
-{\tt A nested list:}\newline
-{\tt \\item\[The first\] item of an itemized list is on this line.}\newline
-{\tt \\item\[The second\] item of the list starts here.  It contains another}\newline
-{\tt list nested inside it.}\newline
-{\tt \\begin\{items\}\[somuchmore\]}\newline
-{\tt \\item \[First\]\\tab\{0\}This is the first item of an enumerated}\newline
-{\tt list that is nested within the itemized list.}\newline
-{\tt \\item \[Second\]\\tab\{0\}This is the second item of the inner list.}\newline
-{\tt \\end\{items\}}\newline
-{\tt This is the rest of the second item of the outer list.  It}\newline
-{\tt is no more interesting than any other part of the item.}\newline
-{\tt \\item\[The third\] item of the list.}\newline
-{\tt \\end\{items\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage5xPatch3 patch}
-\label{HTXFormatPage5xPatch3}
-\index{patch!HTXFormatPage5xPatch3!htxformatpage5.ht}
-\index{htxformatpage5.ht!patch!HTXFormatPage5xPatch3}
-\index{HTXFormatPage5xPatch3!htxformatpage5.ht!patch}
-<<htxformatpage5.ht>>=
-\begin{patch}{HTXFormatPage5xPatch3}
-\begin{paste}{HTXFormatPage5xPaste3A}{HTXFormatPage5xPatch3A}
-\pastebutton{HTXFormatPage5xPaste3A}{Source}
-\newline
-\table{
-{Dark Orchid} {Dark Salmon} {Dark Sea Green} {Dark Slate Blue} {Dark Slate Gray}
-{Dark Turquoise} {Dark Violet} {Deep Pink} {Deep Sky Blue} {Dodger Blue}
-{Floral White} {Forest Green} {Ghost White} {Hot Pink} {Indian Red}
-{Lavender Blush}
-}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage5xPatch3A patch}
-\label{HTXFormatPage5xPatch3A}
-\index{patch!HTXFormatPage5xPatch3A!htxformatpage5.ht}
-\index{htxformatpage5.ht!patch!HTXFormatPage5xPatch3A}
-\index{HTXFormatPage5xPatch3A!htxformatpage5.ht!patch}
-<<htxformatpage5.ht>>=
-\begin{patch}{HTXFormatPage5xPatch3A}
-\begin{paste}{HTXFormatPage5xPaste3B}{HTXFormatPage5xPatch3}
-\pastebutton{HTXFormatPage5xPaste3B}{Interpret}
-\newline
-{\tt
-\\table\{
-\{Dark Orchid\} \{Dark Salmon\} \{Dark Sea Green\} \{Dark Slate Blue\}
-\{Dark Slate Gray\} \{Dark Turquoise\} \{Dark Violet\} \{Deep Pink\}
-\{Deep Sky Blue\} \{Dodger Blue\} \{Floral White\} \{Forest Green\}
-\{Ghost White\} \{Hot Pink\} \{Indian Red\} \{Lavender Blush\}
-\}
-}
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage6}
-\subsection{Boxes and Lines}
-\label{HTXFormatPage6}
-\index{pages!HTXFormatPage6!htxformatpage6.ht}
-\index{htxformatpage6.ht!pages!HTXFormatPage6}
-\index{HTXFormatPage6!htxformatpage6.ht!pages}
-<<htxformatpage6.ht>>=
-\begin{page}{HTXFormatPage6}{Boxes and Lines}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-The {\tt \\fbox} command can be used to place a box around one or more
-words. The argument of the {\tt \\fbox} command is the text that will be
-placed in the box. This command should only be used for text that can fit
-in one line.
-
-\beginImportant
-\begin{paste}{HTXFormatPage6xPaste1}{HTXFormatPage6xPatch1}
-\pastebutton{HTXFormatPage6xPaste1}{Interpret}
-\newline
-{\tt \\fbox\{Boxed!\}}\newline
-\end{paste}
-\endImportant
-
-
-Use the {\tt \\horizontalline} command to draw a horizontal line
-across the window. This might be useful for added emphasis.
-
-\beginImportant
-\begin{paste}{HTXFormatPage6xPaste2}{HTXFormatPage6xPatch2}
-\pastebutton{HTXFormatPage6xPaste2}{Interpret}
-\newline
-{\tt \\horizontalline}\newline
-\end{paste}
-\endImportant
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Micro-Spacing}{HTXFormatPage7}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage6xPatch1 patch}
-\label{HTXFormatPage6xPatch1}
-\index{patch!HTXFormatPage6xPatch1!htxformatpage6.ht}
-\index{htxformatpage6.ht!patch!HTXFormatPage6xPatch1}
-\index{HTXFormatPage6xPatch1!htxformatpage6.ht!patch}
-<<htxformatpage6.ht>>=
-\begin{patch}{HTXFormatPage6xPatch1}
-\begin{paste}{HTXFormatPage6xPaste1A}{HTXFormatPage6xPatch1A}
-\pastebutton{HTXFormatPage6xPaste1A}{Source}
-\newline
-\fbox{Boxed!}
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage6xPatch1A}
-\begin{paste}{HTXFormatPage6xPaste1B}{HTXFormatPage6xPatch1}
-\pastebutton{HTXFormatPage6xPaste1B}{Interpret}
-\newline
-{\tt \\fbox\{Boxed!\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage6xPatch2 patch}
-\label{HTXFormatPage6xPatch2}
-\index{patch!HTXFormatPage6xPatch2!htxformatpage6.ht}
-\index{htxformatpage6.ht!patch!HTXFormatPage6xPatch2}
-\index{HTXFormatPage6xPatch2!htxformatpage6.ht!patch}
-<<htxformatpage6.ht>>=
-\begin{patch}{HTXFormatPage6xPatch2}
-\begin{paste}{HTXFormatPage6xPaste2A}{HTXFormatPage6xPatch2A}
-\pastebutton{HTXFormatPage6xPaste2A}{Source}
-\newline
-\horizontalline
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage6xPatch2A}
-\begin{paste}{HTXFormatPage6xPaste2B}{HTXFormatPage6xPatch2}
-\pastebutton{HTXFormatPage6xPaste2B}{Interpret}
-\newline
-{\tt \\horizontalline}\newline
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage7}
-\subsection{Micro-Spacing}
-\label{HTXFormatPage7}
-\index{pages!HTXFormatPage7!htxformatpage7.ht}
-\index{htxformatpage7.ht!pages!HTXFormatPage7}
-\index{HTXFormatPage7!htxformatpage7.ht!pages}
-<<htxformatpage7.ht>>=
-\begin{page}{HTXFormatPage7}{Micro-Spacing}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-There are three commands that one can use to exercise finer control
-over the appearance of text on a page: {\tt \\space}, {\tt \\hspace}
-and {\tt \\vspace}.
-
-The {\tt \\space\{{\it value}\}} command accepts an integer argument and simply
-changes the position of the next character to the right or to the left.
-A negative argument will move the next character to the left and a
-positive one to the right. The unit of movement is {\it the width
-of a character}. In this way one can overstrike characters to produce
-various effects.
-
-\beginImportant
-\begin{paste}{HTXFormatPage7xPaste1}{HTXFormatPage7xPatch1}
-\pastebutton{HTXFormatPage7xPaste1}{Interpret}
-\newline
-{\tt 0\\space\{-1\}\\}\newline
-{\tt underlined\\space\{-10\}__________}\newline
-\end{paste}
-\endImportant
-
-
-The {\tt \\hspace\{{\it value}\}} command
-is similar to the {\tt \\space\{{\it value}\}} command.
-It also accepts an integer argument and
-changes the position of the next character to the right or to the left.
-A negative argument will move the next character to the left and a
-positive one to the right. The unit of movement is {\it a pixel}.
-The {\it value} argument specifies an offset from the default placement
-of the character.
-
-\beginImportant
-\begin{paste}{HTXFormatPage7xPaste2}{HTXFormatPage7xPatch2}
-\pastebutton{HTXFormatPage7xPaste2}{Interpret}
-\newline
-{\tt x\\hspace\{-4\}x\\hspace\{-3\}x\\hspace\{-2\}x\\hspace\{-1\}x\%}\newline
-{\tt x\\hspace\{1\}x\\hspace\{2\}x\\hspace\{3\}x\\hspace\{4\}x}
-\end{paste}
-\endImportant
-
-The {\tt \\vspace\{{\it value}\}} command is similar to the
-{\tt \\hspace\{{\it value}\}} command but (as the name suggests)
-works in the vertical direction. The unit of movement is {\it a
-pixel}. The {\it value} argument specifies an offset from {\it
-the next line}. A negative argument moves the next character up
-and a positive down. This command can be used for subscripts and
-superscripts. One drawback in the use of {\tt \\vspace} is that
-it can only work with a particular font at a time. This is
-because the inter-line spacing depends on the font being used
-and the value of it is needed to get "back" on the line.
-In general, the command {\tt \\vspace\{{\it - ils}\}} will
-have a null effect when {\it ils} = ( font ascent + font descent + 5 ).
-The example below assumes that {\it ils} = 25 e.g. the Rom14 font
-on the RISC System/6000.
-
-\beginImportant
-\begin{paste}{HTXFormatPage7xPaste3}{HTXFormatPage7xPatch3}
-\pastebutton{HTXFormatPage7xPaste3}{Interpret}
-\newline
-{\tt CO\\vspace\{-18\}2\\vspace\{-32\} + CaO ->}\newline
-{\tt CaCO\\vspace\{-18\}3\\vspace\{-32\}\\newline}\newline
-{\tt R\\space\{-1\}~\\vspace\{-18\}æv\\vspace\{-32\}}\newline
-{\tt \\hspace\{4\}-\\hspace\{8\}---\\hspace\{-12\}}\newline
-{\tt \\vspace\{-32\}1\\space\{-1\}\\vspace\{-7\}2}\newline
-{\tt \\vspace\{-36\}\\hspace\{8\}g\\space\{-1\}~}\newline
-{\tt \\vspace\{-18\}æv\\vspace\{-32\}\\hspace\{2\}R}\newline
-{\tt \\space\{-1\}~ = T\\vspace\{-18\}æv\\vspace\{-32\}}\newline
-{\tt \\vspace\{-25\}}
-\end{paste}
-\endImportant
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Bitmaps and Images}{HTXFormatPage8}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage7xPatch1 patch}
-\label{HTXFormatPage7xPatch1}
-\index{patch!HTXFormatPage7xPatch1!htxformatpage7.ht}
-\index{htxformatpage7.ht!patch!HTXFormatPage7xPatch1}
-\index{HTXFormatPage7xPatch1!htxformatpage7.ht!patch}
-<<htxformatpage7.ht>>=
-\begin{patch}{HTXFormatPage7xPatch1}
-\begin{paste}{HTXFormatPage7xPaste1A}{HTXFormatPage7xPatch1A}
-\pastebutton{HTXFormatPage7xPaste1A}{Source}
-\newline
-0\space{-1}\\
-underlined\space{-10}__________
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage7xPatch1A}
-\begin{paste}{HTXFormatPage7xPaste1B}{HTXFormatPage7xPatch1}
-\pastebutton{HTXFormatPage7xPaste1B}{Interpret}
-\newline
-{\tt 0\\space\{-1\}\\}\newline
-{\tt underlined\\space\{-10\}__________}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage7xPatch2 patch}
-\label{HTXFormatPage7xPatch2}
-\index{patch!HTXFormatPage7xPatch2!htxformatpage7.ht}
-\index{htxformatpage7.ht!patch!HTXFormatPage7xPatch2}
-\index{HTXFormatPage7xPatch2!htxformatpage7.ht!patch}
-<<htxformatpage7.ht>>=
-\begin{patch}{HTXFormatPage7xPatch2}
-\begin{paste}{HTXFormatPage7xPaste2A}{HTXFormatPage7xPatch2A}
-\pastebutton{HTXFormatPage7xPaste2A}{Source}
-\newline
-x\hspace{-4}x\hspace{-3}x\hspace{-2}x\hspace{-1}x%
-x\hspace{1}x\hspace{2}x\hspace{3}x\hspace{4}x
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage7xPatch2A patch}
-\label{HTXFormatPage7xPatch2A}
-\index{patch!HTXFormatPage7xPatch2A!htxformatpage7.ht}
-\index{htxformatpage7.ht!patch!HTXFormatPage7xPatch2A}
-\index{HTXFormatPage7xPatch2A!htxformatpage7.ht!patch}
-<<htxformatpage7.ht>>=
-\begin{patch}{HTXFormatPage7xPatch2A}
-\begin{paste}{HTXFormatPage7xPaste2B}{HTXFormatPage7xPatch2}
-\pastebutton{HTXFormatPage7xPaste2B}{Interpret}
-\newline
-{\tt x\\hspace\{-4\}x\\hspace\{-3\}x\\hspace\{-2\}x\\hspace\{-1\}x\%}\newline
-{\tt x\\hspace\{1\}x\\hspace\{2\}x\\hspace\{3\}x\\hspace\{4\}x}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage7xPatch3 patch}
-\label{HTXFormatPage7xPatch3}
-\index{patch!HTXFormatPage7xPatch3!htxformatpage7.ht}
-\index{htxformatpage7.ht!patch!HTXFormatPage7xPatch3}
-\index{HTXFormatPage7xPatch3!htxformatpage7.ht!patch}
-<<htxformatpage7.ht>>=
-\begin{patch}{HTXFormatPage7xPatch3}
-\begin{paste}{HTXFormatPage7xPaste3A}{HTXFormatPage7xPatch3A}
-\pastebutton{HTXFormatPage7xPaste3A}{Source}
-\newline
-CO\vspace{-18}2\vspace{-32} + CaO ->
-CaCO\vspace{-18}3\vspace{-32}\newline
-R\space{-1}~\vspace{-18}æv\vspace{-32}
-\hspace{4}-\hspace{8}---\hspace{-12}
-\vspace{-32}1\space{-1}\vspace{-7}2
-\vspace{-36}\hspace{8}g\space{-1}~
-\vspace{-18}æv\vspace{-32}\hspace{2}R
-\space{-1}~ = T\vspace{-18}æv\vspace{-32}
-\vspace{-25}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage7xPatch3A patch}
-\label{HTXFormatPage7xPatch3A}
-\index{patch!HTXFormatPage7xPatch3A!htxformatpage7.ht}
-\index{htxformatpage7.ht!patch!HTXFormatPage7xPatch3A}
-\index{HTXFormatPage7xPatch3A!htxformatpage7.ht!patch}
-<<htxformatpage7.ht>>=
-\begin{patch}{HTXFormatPage7xPatch3A}
-\begin{paste}{HTXFormatPage7xPaste3B}{HTXFormatPage7xPatch3}
-\pastebutton{HTXFormatPage7xPaste3B}{Interpret}
-\newline
-{\tt CO\\vspace\{-18\}2\\vspace\{-32\} + CaO ->}\newline
-{\tt CaCO\\vspace\{-18\}3\\vspace\{-32\}\\newline}\newline
-{\tt R\\space\{-1\}~\\vspace\{-18\}æv\\vspace\{-32\}}\newline
-{\tt \\hspace\{4\}-\\hspace\{8\}---\\hspace\{-12\}}\newline
-{\tt \\vspace\{-32\}1\\space\{-1\}\\vspace\{-7\}2}\newline
-{\tt \\vspace\{-36\}\\hspace\{8\}g\\space\{-1\}~}\newline
-{\tt \\vspace\{-18\}æv\\vspace\{-32\}\\hspace\{2\}R}\newline
-{\tt \\space\{-1\}~ = T\\vspace\{-18\}æv\\vspace\{-32\}}\newline
-{\tt \\vspace\{-25\}}
-\end{paste}
-\end{patch}
-
-@
-\section{htxformatpage8}
-\subsection{Bitmaps and Images}
-\label{HTXFormatPage8}
-\index{pages!HTXFormatPage8!htxformatpage8.ht}
-\index{htxformatpage8.ht!pages!HTXFormatPage8}
-\index{HTXFormatPage8!htxformatpage8.ht!pages}
-<<htxformatpage8.ht>>=
-\begin{page}{HTXFormatPage8}{Bitmaps and Images}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-The commands {\tt \\inputbitmap\{{\it filename}\}}
-and {\tt \\inputimage\{{\it filename}\}}
-allow you to include an X11 bitmap or an
-Axiom-generated viewport in a \HyperName{}
-page.
-
-In the case of the {\tt \\inputbitmap} command
-the {\it filename} parameter must be the full pathname
-of an X11 bitmap file.
-
-\beginImportant
-\begin{paste}{HTXFormatPage8xPaste1}{HTXFormatPage8xPatch1}
-\pastebutton{HTXFormatPage8xPaste1}{Interpret}
-\newline
-{\tt \\inputbitmap\{\env{AXIOM}/doc/hypertex/bitmaps/sup.bitmap\} }
-\end{paste}
-\endImportant
-
-The {\it filename} parameter of the {\tt \\inputimage}
-command must be the full pathname of a {\it compressed XPM image} file without the name extensions.
-\HyperName{} always adds ".xpm.Z" to whatever filename you give and looks for the augmented filename.
-Such files can be generated by Axiom command
-\axiomOp{write} with the {\tt "image"} or {\tt "pixmap"}
-options.
-
-\beginImportant
-\begin{paste}{HTXFormatPage8xPaste2}{HTXFormatPage8xPatch2}
-\pastebutton{HTXFormatPage8xPaste2}{Interpret}
-\newline
-{\tt \\inputimage\{\env{AXIOM}/doc/viewports/ugProblemNumericPage30.view/image\}}
-\end{paste}
-\endImportant
-
-Be careful not to break the pathname across lines.
-
-The {\tt \\inputimage} command will automatically select
-the {\it image.xpm} or the {\it image.bm} file for you
-based on the capabilities of your X server. 
-
-For your convenience, there are two macros defined
-in \centerline{ {\bf \env{AXIOM}{}/doc/hypertex/pages/util.ht}.}
-The {\tt \\viewport} macro eliminates the need to specify
-the {\tt .view/image} part and the
-{\tt \\axiomViewport} macro automatically selects viewport
-files in the system directories. The above {\tt \\inputimage}
-could have been written
-\beginImportant
-{\tt \\viewport\{\env{AXIOM}/doc/viewports/ugProblemNumericPage30\}}
-\endImportant
-or
-\beginImportant
-{\tt \\axiomViewport\{ugProblemNumericPage30\}}
-\endImportant
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Back to Formatting menu}{HTXFormatTopPage}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXFormatPage8xPatch1 patch}
-\label{HTXFormatPage8xPatch1}
-\index{patch!HTXFormatPage8xPatch1!htxformatpage8.ht}
-\index{htxformatpage8.ht!patch!HTXFormatPage8xPatch1}
-\index{HTXFormatPage8xPatch1!htxformatpage8.ht!patch}
-<<htxformatpage8.ht>>=
-\begin{patch}{HTXFormatPage8xPatch1}
-\begin{paste}{HTXFormatPage8xPaste1A}{HTXFormatPage8xPatch1A}
-\pastebutton{HTXFormatPage8xPaste1A}{Source}
-\newline
-\inputbitmap{\env{AXIOM}/doc/hypertex/bitmaps/sup.bitmap}
-\end{paste}
-\end{patch}
-\begin{patch}{HTXFormatPage8xPatch1A}
-\begin{paste}{HTXFormatPage8xPaste1B}{HTXFormatPage8xPatch1}
-\pastebutton{HTXFormatPage8xPaste1B}{Interpret}
-\newline
-{\tt \\inputbitmap\{\env{AXIOM}/doc/hypertex/bitmaps/sup.bitmap\} }
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXFormatPage8xPatch2 patch}
-\label{HTXFormatPage8xPatch2}
-\index{patch!HTXFormatPage8xPatch2!htxformatpage8.ht}
-\index{htxformatpage8.ht!patch!HTXFormatPage8xPatch2}
-\index{HTXFormatPage8xPatch2!htxformatpage8.ht!patch}
-<<htxformatpage8.ht>>=
-\begin{patch}{HTXFormatPage8xPatch2}
-\begin{paste}{HTXFormatPage8xPaste2A}{HTXFormatPage8xPatch2A}
-\pastebutton{HTXFormatPage8xPaste2A}{Source}
-\newline
-\inputimage{\env{AXIOM}/doc/viewports/ugProblemNumericPage30.view/image}
-\end{paste}
-\end{patch}
-@
-\subsection{HTXFormatPage8xPatch2A patch}
-\label{HTXFormatPage8xPatch2A}
-\index{patch!HTXFormatPage8xPatch2A!htxformatpage8.ht}
-\index{htxformatpage8.ht!patch!HTXFormatPage8xPatch2A}
-\index{HTXFormatPage8xPatch2A!htxformatpage8.ht!patch}
-<<htxformatpage8.ht>>=
-\begin{patch}{HTXFormatPage8xPatch2A}
-\begin{paste}{HTXFormatPage8xPaste2B}{HTXFormatPage8xPatch2}
-\pastebutton{HTXFormatPage8xPaste2B}{Interpret}
-\newline
-{\tt \\inputimage\{\env{AXIOM}/doc/viewports/ugProblemNumericPage30.view/image\}}
-\end{paste}
-\end{patch}
-
-@
-\section{htxformattoppage.ht}
-\subsection{Formatting in Hyperdoc}
-\begin{itemize}
-\item HTXFormatPage1 \ref{HTXFormatPage1} on page~\pageref{HTXFormatPage1}
-\item HTXFormatPage2 \ref{HTXFormatPage2} on page~\pageref{HTXFormatPage2}
-\item HTXFormatPage3 \ref{HTXFormatPage3} on page~\pageref{HTXFormatPage3}
-\item HTXFormatPage4 \ref{HTXFormatPage4} on page~\pageref{HTXFormatPage4}
-\item HTXFormatPage5 \ref{HTXFormatPage5} on page~\pageref{HTXFormatPage5}
-\item HTXFormatPage6 \ref{HTXFormatPage6} on page~\pageref{HTXFormatPage6}
-\item HTXFormatPage7 \ref{HTXFormatPage7} on page~\pageref{HTXFormatPage7}
-\item HTXFormatPage8 \ref{HTXFormatPage8} on page~\pageref{HTXFormatPage8}
-\end{itemize}
-\label{HTXFormatTopPage}
-\index{pages!HTXFormatTopPage!htxformattoppage.ht}
-\index{htxformattoppage.ht!pages!HTXFormatTopPage}
-\index{HTXFormatTopPage!htxformattoppage.ht!pages}
-<<htxformattoppage.ht>>=
-\begin{page}{HTXFormatTopPage}{Formatting in Hyperdoc}
-\centerline{\fbox{{\tt \thispage}}}\newline
-
-\HyperName{} offers various facilities for formatting text and images.
-You can learn about these facilities by clicking on the topics below.
-\begin{scroll}
-\beginmenu
-\menudownlink{Special Characters}{HTXFormatPage1}
-\menudownlink{Formatting without commands}{HTXFormatPage2}
-\menudownlink{Using different fonts}{HTXFormatPage3}
-\menudownlink{Indentation}{HTXFormatPage4}
-\menudownlink{Creating Lists and Tables}{HTXFormatPage5}
-\menudownlink{Boxes and Lines}{HTXFormatPage6}
-\menudownlink{Micro-Spacing}{HTXFormatPage7}
-\menudownlink{Bitmaps and Images}{HTXFormatPage8}
-\endmenu
-\end{scroll}
-\end{page}
-
-
-@
-\section{htxintropage1.ht}
-\subsection{What Hyperdoc does}
-\label{HTXIntroPage1}
-\begin{itemize}
-\item HTXIntroPage2 \ref{HTXIntroPage2} on page~\pageref{HTXIntroPage2}
-\item ugHyperPage \ref{ugHyperPage} on page~\pageref{ugHyperPage}
-\end{itemize}
-\index{pages!HTXIntroPage1!htxintropage1.ht}
-\index{htxintropage1.ht!pages!HTXIntroPage1}
-\index{HTXIntroPage1!htxintropage1.ht!pages}
-<<htxintropage1.ht>>=
-\begin{page}{HTXIntroPage1}{What Hyperdoc does}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\beginscroll
-
-Take a close look at the objects in the \HyperName{} window you are now reading.
-Most of them are text. Resize the window using the window manager
-facilities. The text is reformatted to fit the window
-border. This action is performed by \HyperName{}. At the simplest
-level, it provides a method for {\em formatting} text in a window.
-In fact, it can place other things on the window as well, such as
-bitmaps or color images. The {\em buttons} you see at either
-side at the top of the window are bitmaps.
-
-Move the cursor so that it rests on one of those buttons. You notice that
-the cursor has changed appearance. This indicates that there is an action associated
-with the button. This action will be performed when you click the mouse button
-over the {\em active area}. If you are familiar with \HyperName{}, you know
-that the active area can be words, bitmaps, images or {\em input areas}. In
-fact, anything that can be displayed in a \HyperName{} window can be an
-active area.
-
-So, what can the action associated with an active area be? \HyperName{}
-allows quite a bit of freedom in defining that action. We will have a close
-look at this issue \downlink{later on}{HTXLinkTopPage}. For now, recall
-the various actions that you have encountered so far --- executing Axiom
-commands, popping up new windows, providing parameters for other active areas,
-and replacing or changing the contents of the window. The most common action
-is to bring up some \HyperName{} text in the same or a different window.
-This lets us create {\em links} between pieces of text and images. A
-system with such capability is usually called a {\em hypertext} system.
-\HyperName{} is in fact much more.
-
-\endscroll
-\beginmenu
-\menulink{Next -- How \HyperName{} does it}{HTXIntroPage2}
-\menuwindowlink{Review some features of \HyperName{}}{ugHyperPage}
-\endmenu
-
-\helppage{ugHyperPage}
-\end{page}
-
-@
-\section{htxintropage2.ht}
-\subsection{How Hyperdoc does it}
-\label{HTXIntroPage2}
-See HTXIntroPage3 \ref{HTXIntroPage3} on page~\pageref{HTXIntroPage3}
-\index{pages!HTXIntroPage2!htxintropage2.ht}
-\index{htxintropage2.ht!pages!HTXIntroPage2}
-\index{HTXIntroPage2!htxintropage2.ht!pages}
-<<htxintropage2.ht>>=
-\begin{page}{HTXIntroPage2}{How Hyperdoc does it}
-{\centerline{\fbox{{\tt \thispage}}}\newline}
-\beginscroll
-
-\HyperName{} can read the {\em hypertext} information from standard text
-files. This means that you can create or change this information with any
-text editor. Once this information has been entered into the files, a
-special program, called {\bf htadd}, scans these files and produces
-a database (another file called {\bf ht.db}) of {\em objects}
-encountered in the files. \HyperName{}
-consults this database when it first starts and so knows where it might
-find the definitions of these objects. You can maintain several such
-databases on different directories. You indicate which database you
-want \HyperName{} to consult by setting an {\em environment variable}
-called {\bf HTPATH}.
-
-In general, hypertext must obviously use some kind of special (that is,
-non-textual) marks for all the  extra functionality it provides. In
-\HyperName{}, these marks are some special characters --- special
-in the sense that they are not interpreted as ordinary displayable text.
-These characters, however, are part of the standard ASCII set.
-There is also a way to display these special characters as text .
-The \HyperName{} special characters are :
-
-\beginImportant
-\noindent{\em Special Characters}: {\tt \table{{\$}{\\}{\{}{\}}{\[}{\]}{\%}{\#}}}
-\endImportant
-
-
-
-\HyperName{} uses the special characters to distinguish between
-{\em text} and {\em commands} (by {\em text}, we mean here anything
-displayable). The commands are instructions to
-\HyperName{} to treat some text in a particular way. Some commands
-define special \HyperName{} objects. The most important objects
-are {\em pages}, {\em patches}, and {\em macros}.
-A {\em page} is a description of the contents of a
-\HyperName{} window. A {\em patch} is a portion of a page.
-A {\em macro} is a user-defined new \HyperName{} command.
-Some commands allow special text {\em formatting} and others
-associate some text with an action.
-
-In order to display anything at all in \HyperName, you must define a
-{\em page}. The next section explains how to define a {\em page} and put
-some simple text into it.
-\endscroll
-\beginmenu
-\menudownlink{Next -- Define a simple text page}{HTXIntroPage3}
-\endmenu
-
-\end{page}
-
-
-@
-\section{htxintropage3.ht}
-\subsection{A simple text page}
-\begin{itemize}
-\item HTXLinkPage6 \ref{HTXLinkPage6} on page~\pageref{HTXLinkPage6}
-\item HTXTryPage \ref{HTXTryPage} on page~\pageref{HTXTryPage}
-\item HTXFormatTopPage \ref{HTXFormatTopPage} on 
-page~\pageref{HTXFormatTopPage}
-\end{itemize}
-\label{HTXIntroPage3}
-\index{pages!HTXIntroPage3!htxintropage3.ht}
-\index{htxintropage3.ht!pages!HTXIntroPage3}
-\index{HTXIntroPage3!htxintropage3.ht!pages}
-<<htxintropage3.ht>>=
-\begin{page}{HTXIntroPage3}{A simple text page}
-{\centerline{\fbox{{\tt \thispage}}}\newline}
-\begin{scroll}
-
-
-A page is defined by a {\em group} command. Group commands are used to
-delimit a group, that is, to declare where a group starts and where it
-ends. The proper syntax for a page definition is as follows:
-\beginImportant
-{\tt \\begin\{page\}\{{\it name}\}\{{\it a title}\}}
-\newline
-.
-\newline
-.
-\newline
-.
-\newline
-{\tt \\end\{page\}}
-\beginImportant
-
-Note the use of the special characters {\tt \\}, {\tt \{} and {\tt
-\}}.  The {\tt \\} (backslash) character introduces a command, in this
-case, {\tt begin}.  The {\tt \{ \}} (braces) delimit the {\em
-parameters} to the command.  The first parameter (the word {\tt page})
-specifies this as a page definition command.
-
-The second parameter can be any single unbroken word consisting of
-alphanumeric characters only, and specifies the name of the page by which
-it can be referred to by other commands. You should choose
-this internal name with care so as to avoid potential conflict with
-page names that are defined by the Axiom system. This caveat only
-applies in the case where you have started \HyperName{} with the Axiom
-database --- see \downlink{later on}{HTXLinkPage6}. It is suggested that
-the page names you define start with the letters {\tt UX} (standing for
-{\tt U}ser e{\tt X}tensions). You can have a look at the Axiom
-system database file {\centerline{\bf \env{AXIOM}/doc/hypertex/pages/ht.db} }
-which contains the names of all pages, macros and patches used by Axiom.
-
-The third parameter specifies a title for the page.
-The title of a page is the area at the very top
-of the window, between the buttons. Virtually anything
-that can be put in the main page can also be put in the
-title. As an example, {\em this} page's
-declaration is like this:\newline
-{\tt \\begin\{page\}\{\thispage\}\{A simple text page\}}
-
-Everything you type between the {\tt \\begin\{page\}} command and the next
-{\tt \\end\{page\}} command will become the body of the page. It is
-an error to insert another {\tt \\begin\{page\}} between the two, that is,
-this group command cannot be nested.
-
-There is another useful group command that should be mentioned here
---- the {\em scroll} command. It controls the portion of the page that
-will be scrollable. \HyperName{} will split a page in three sections:
-a {\em header}, a {\em scroll region} and a {\em footer}. \HyperName{}
-will always try to keep the header and footer regions visible on the
-page; the header at the top and the footer at the bottom. The middle
-scroll region will be truncated and a scroll bar will be automatically
-provided if the window becomes too small for the whole contents of the
-page. Only one scroll region can be defined in a page and the correct
-syntax is as follows:
-\beginImportant
-{\tt \\begin\{scroll\}}
-\newline
-.
-\newline
-.
-\newline
-.
-\newline
-{\tt \\end\{scroll\}}
-\beginImportant
-
-This group should be placed inside the relevant page group. The text
-between the {\tt \\begin\{page\}} and {\tt \\begin\{scroll\}} commands
-defines the header region, the text inside the scroll group defines
-the scroll region and the text between the {\tt \\end\{scroll\}} and
-{\tt \\end\{page\}} commands defines the footer region. It is
-important to keep the header and footer areas small.  Use them to
-display information that might be needed at any time by the user.  If
-you don't define a scroll region in your page, you may find that a
-portion of the page is truncated.
-
-You are now ready to experiment with a page of your own. If you just
-want to display some text on a page, you don't need any other
-\HyperName{} commands. Just make sure that the text you type for the
-title, header, scroll and footer regions does not contain (for the
-moment) any of the \HyperName{} special characters.
-
-\end{scroll}
-\beginmenu
-\menuwindowlink{Try out what you learned}{HTXTryPage}
-\menudownlink{Next -- Learn how to format text}{HTXFormatTopPage}
-\endmenu
-\end{page}
-
-
-@
-\section{htxintrotoppage.ht}
-\subsection{First Steps}
-\begin{itemize}
-\item HTXIntroPage1 \ref{HTXIntroPage1} on page~\pageref{HTXIntroPage1}
-\item HTXIntroPage2 \ref{HTXIntroPage2} on page~\pageref{HTXIntroPage2}
-\item HTXIntroPage3 \ref{HTXIntroPage3} on page~\pageref{HTXIntroPage3}
-\end{itemize}
-\label{HTXIntroTopPage}
-\index{pages!HTXIntroTopPage!htxintrotoppage.ht}
-\index{htxintrotoppage.ht!pages!HTXIntroTopPage}
-\index{HTXIntroTopPage!htxintrotoppage.ht!pages}
-<<htxintrotoppage.ht>>=
-\begin{page}{HTXIntroTopPage}{First Steps}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\beginscroll
-
-\HyperName{} is both a way of presenting information and
-a customisable front-end. Axiom uses
-it for its own purpose as a front-end and documentation system.
-\HyperName{} has special facilities that allow it to interact
-very closely with Axiom.  The \Browse{} facility, the Basic
-Commands section and the ability to execute Axiom commands
-by clicking on \HyperName{} text are witness to this.
-
-These pages will show you the features of \HyperName{} that might
-make it appropriate for your own use in, for example, providing
-documentation for Axiom code that you write or some other purpose.
-
-It is recommended that you get familiar with the {\em use} of
-\HyperName{} before proceeding.
-
-\endscroll
-\beginmenu
-\menudownlink{What \HyperName{} does}{HTXIntroPage1}
-\menudownlink{How \HyperName{} does it}{HTXIntroPage2}
-\menudownlink{Define a simple text page}{HTXIntroPage3}
-\endmenu
-
-\end{page}
-
-@
-\section{htxlinkpage1.ht}
-\subsection{Linking to a named page}
-\label{HTXLinkPage1}
-\begin{itemize}
-\item HTXLinkTopPage \ref{HTXLinkTopPage} on page~\pageref{HTXLinkTopPage}
-\item TestHelpPage \ref{TestHelpPage} on page~\pageref{TestHelpPage}
-\item HTXLinkPage2 \ref{HTXLinkPage2} on page~pageref{HTXLinkPage2}
-\end{itemize}
-\index{pages!HTXLinkPage1!htxlinkpage1.ht}
-\index{htxlinkpage1.ht!pages!HTXLinkPage1}
-\index{HTXLinkPage1!htxlinkpage1.ht!pages}
-<<htxlinkpage1.ht>>=
-\begin{page}{HTXLinkPage1}{Linking to a named page}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-In \HyperName{}, hypertext links are specified by different
-flavors of the {\tt \\link} command. These commands take two
-arguments. One argument specifies the active area, that
-is, the {\it trigger} of the link. The second argument specifies the
-{\it target} of the link, that is, a page. The trigger can be quite arbitrary
-\HyperName{} text and can include images or whole paragraphs. The trigger
-text will be formatted in the normal fashion but its default font will be
-the font specified by the ActiveFont resource.
-
-The simplest kind of \HyperName{} link is a link to a named page.
-Clicking on the trigger will cause the named page to appear in a
-\HyperName{} window.
-There are three flavors for such a link.
-\begin{items}[123456]
-\item\menuitemstyle{{\tt \\windowlink\{{\it trigger}\}\{{\it page name}\}}}
-\newline
-This link command, when activated, will create a new window for the named page.
-\newline
-There will be no \centerline{\UpBitmap{}  or \ReturnBitmap{}}  
-buttons on the new page.
-The new page will have a \centerline{\ExitBitmap{}} button, however.
-The original page containing the {\tt \\windowlink} command will be unaffected.
-\item\menuitemstyle{{\tt \\downlink\{{\it trigger}\}\{{\it page name}\}} }
-\newline This link command, when activated, will cause the
-current page to be replaced by the target page
-in the same \HyperName{} window.
-A \centerline{\UpBitmap{}}  button will automatically be placed
-on the new page allowing you to get back to the page
-containing the {\tt \\downlink} command.
-If the current page has a \centerline{\ReturnBitmap{}} button then
-the target page will also carry it. The associated
-target page of that button will be the same as it is
-in the current page.
-\item\menuitemstyle{{\tt \\memolink\{{\it trigger}\}\{{\it page name}\}}}
-\newline This link command is similar to the {\tt \\downlink} command.
-In addition, it will cause a \centerline{\ReturnBitmap{}}  
-button to be included in
-the target page and all pages {\tt \\downlink}ed from it. 
-This button will act as a
-direct link to the page containing the {\tt \\memolink} command allowing
-a short-cut to be taken.
-\end{items}
-
-\beginImportant
-\begin{paste}{HTXLinkPage1xPaste1}{HTXLinkPage1xPatch1}
-\pastebutton{HTXLinkPage1xPaste1}{Interpret}
-\newline
-{\tt \\windowlink\{windowlink to Actions menu\}\{HTXLinkTopPage\}\\newline}\newline
-{\tt \\downlink\{downlink to Actions menu\}\{HTXLinkTopPage\}\\newline}\newline
-{\tt \\memolink\{memolink to Actions menu\}\{HTXLinkTopPage\}}
-\end{paste}
-\endImportant
-
-
-There is a fourth button that can appear at the top of the page
-next to the \centerline{\ExitBitmap{}} button.
-Its purpose is to provide access to a particular {\it help page}
-associated with the current page.
-That is the \centerline{\HelpBitmap{}} button. The command to use
-is
-\centerline{{\tt \\helppage\{{\it help page name}\}}}
-The {\tt \\helppage} command {\it must } be placed
-just before the {\tt \\end\{page\}} command.
-For instance, to get a help button on this page
-the following command is used.
-\centerline{{\tt {\\helppage\{TestHelpPage\}}}}
-Clicking on the help button at the top
-will display the {\tt TestHelpPage} page in a new window.
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Standard Pages}{HTXLinkPage2}
-\endmenu
-
-\helppage{TestHelpPage}
-\end{page}
-
-@
-\subsection{HTXLinkPage1xPatch1 patch}
-\label{HTXLinkPage1xPatch1}
-\index{patch!HTXLinkPage1xPatch1!htxlinkpage1.ht}
-\index{htxlinkpage1.ht!patch!HTXLinkPage1xPatch1}
-\index{HTXLinkPage1xPatch1!htxlinkpage1.ht!patch}
-<<htxlinkpage1.ht>>=
-\begin{patch}{HTXLinkPage1xPatch1}
-\begin{paste}{HTXLinkPage1xPaste1A}{HTXLinkPage1xPatch1A}
-\pastebutton{HTXLinkPage1xPaste1A}{Source}
-\newline
-\windowlink{windowlink to Actions
-menu}{HTXLinkTopPage}\newline
-\downlink{downlink to Actions menu}{HTXLinkTopPage}\newline
-\memolink{memolink to Actions menu}{HTXLinkTopPage}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage1xPatch1A patch}
-\label{HTXLinkPage1xPatch1A}
-\index{patch!HTXLinkPage1xPatch1A!htxlinkpage1.ht}
-\index{htxlinkpage1.ht!patch!HTXLinkPage1xPatch1A}
-\index{HTXLinkPage1xPatch1A!htxlinkpage1.ht!patch}
-<<htxlinkpage1.ht>>=
-\begin{patch}{HTXLinkPage1xPatch1A}
-\begin{paste}{HTXLinkPage1xPaste1B}{HTXLinkPage1xPatch1}
-\pastebutton{HTXLinkPage1xPaste1B}{Interpret}
-\newline
-{\tt \\windowlink\{windowlink to Actions menu\}\{HTXLinkTopPage\}\\newline}\newline
-{\tt \\downlink\{downlink to Actions menu\}\{HTXLinkTopPage\}\\newline}\newline
-{\tt \\memolink\{memolink to Actions menu\}\{HTXLinkTopPage\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{Test Help Page}
-\label{TestHelpPage}
-\index{pages!TestHelpPage!htxlinkpage1.ht}
-\index{htxlinkpage1.ht!pages!TestHelpPage}
-\index{TestHelpPage!htxlinkpage1.ht!pages}
-<<htxlinkpage1.ht>>=
-\begin{page}{TestHelpPage}{Test Help Page}
-\begin{scroll}
-
-\vspace{100}
-\centerline{Is this any help?}
-\end{scroll}
-\end{page}
-
-@
-\section{htxlinkpage2.ht}
-\subsection{Standard Pages}
-\label{HTXLinkPage2}
-\begin{itemize}
-\item HTXLinkPage6 \ref{HTXLinkPage6} on page~\pageref{HTXLinkPage6}
-\item SpadNotConnectedPage \ref{SpadNotConnectedPage} on 
-page~\pageref{SpadNotConnectedPage}
-\item UnknownPage \ref{UnknownPage} on page~\pageref{UnknownPage}
-\item ErrorPage \ref{ErrorPage} on page~\pageref{ErrorPage}
-\item ProtectedQuitPage \ref{ProtectedQuitPage} on 
-page~\pageref{ProtectedQuitPage}
-\item HTXLinkPage3 \ref{HTXLinkPage3} on page~\pageref{HTXLinkPage3}
-\end{itemize}
-\index{pages!HTXLinkPage2!htxlinkpage2.ht}
-\index{htxlinkpage2.ht!pages!HTXLinkPage2}
-\index{HTXLinkPage2!htxlinkpage2.ht!pages}
-<<htxlinkpage2.ht>>=
-\begin{page}{HTXLinkPage2}{Standard Pages}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-You have reached this page after performing
-a series of mouse clicks on \HyperName{}
-active areas. Each time, a {\tt \\link}
-command was activated. Well, how does it all
-start?
-The answer is that \HyperName{} always puts up
-a particular page called {\tt RootPage} when
-it starts up. If this page is not found in the database,
-\HyperName{} will immediately exit.
-It is, of course, desirable that the {\tt RootPage}
-contains links to other pages!
-It is possible to override
-Axiom's choice of {\tt RootPage} and provide your own
-to \HyperName{}. This is done in the same way as
-you would override any Axiom-defined page and is
-discussed in \downlink{How to use your pages with \HyperName{}}{HTXLinkPage6}.
-
-
-
-You may have noticed that \HyperName{}
-uses some pages when certain events occur.
-There is a page that is put up, for instance,
-whenever \HyperName{} cannot connect to Axiom.
-Another page is put up whenever there is a formatting
-error and yet another when a request for an unknown page
-is made. Finally, there is a page that prompts
-for confirmation when you press the
-exit button on the initial page.
-
-
-These pages have standard names and must be provided
-in the \HyperName{} page database.
-They are already defined in the Axiom system
-\HyperName{} page database so that you do not have to
-define them yourself.
-
-Here are the pages required by \HyperName{}. You can click on any of these
-to see their contents. Click on their exit buttons when you are finished.
-
-\beginImportant
-\begin{paste}{HTXLinkPage2xPaste1}{HTXLinkPage2xPatch1}
-\pastebutton{HTXLinkPage2xPaste1}{Interpret}
-\newline
-{\tt \\table\{}\newline
-{\tt \{\\windowlink\{SpadNotConnectedPage\}\{SpadNotConnectedPage\}\}}\newline
-{\tt \{\\windowlink\{UnknownPage\}\{UnknownPage\}\}}\newline
-{\tt \{\\windowlink\{ErrorPage\}\{ErrorPage\}\}}\newline
-{\tt \{\\windowlink\{ProtectedQuitPage\}\{ProtectedQuitPage\}\}}\newline
-{\tt \}}\newline
-\end{paste}
-\endImportant
-
-
-In addition, \HyperName{} uses certain bitmaps for its buttons.
-They are also provided in the Axiom system
-bitmap directory and \HyperName{} knows where to find them.
-
-The bitmap files required by \HyperName{} are the following.
-\newline
-\tab{7}{\it exit.bitmap}\tab{22} = \tab{25}{\ExitBitmap{}} \newline
-\tab{7}{\it help2.bitmap}\tab{22} = \tab{25}{\HelpBitmap{}} \newline
-\tab{7}{\it up3.bitmap}\tab{22} = \tab{25}{\UpBitmap{}}\newline
-\tab{7}{\it return3.bitmap}\tab{22} = \tab{25}{\ReturnBitmap{}}\newline
-\tab{7}{\it noop.bitmap}\tab{22} = \tab{25}{\NoopBitmap{}}
-
-These files must exist in your current directory if
-the {\tt AXIOM} environment variable is not set.
-If it is, then \HyperName{} will assume that it points
-to the Axiom system directory and will look for
-these files in
-{\bf \$AXIOM/doc/hypertex/bitmaps}.
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Active Axiom commands}{HTXLinkPage3}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXLinkPage2xPatch1 patch}
-\label{HTXLinkPage2xPatch1}
-\index{patch!HTXLinkPage2xPatch1!htxlinkpage2.ht}
-\index{htxlinkpage2.ht!patch!HTXLinkPage2xPatch1}
-\index{HTXLinkPage2xPatch1!htxlinkpage2.ht!patch}
-<<htxlinkpage2.ht>>=
-\begin{patch}{HTXLinkPage2xPatch1}
-\begin{paste}{HTXLinkPage2xPaste1A}{HTXLinkPage2xPatch1A}
-\pastebutton{HTXLinkPage2xPaste1A}{Source}
-\newline
-\table{
-{\windowlink{SpadNotConnectedPage}{SpadNotConnectedPage}}
-{\windowlink{UnknownPage}{UnknownPage}}
-{\windowlink{ErrorPage}{ErrorPage}}
-{\windowlink{ProtectedQuitPage}{ProtectedQuitPage}}
-}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage2xPatch1A patch}
-\label{HTXLinkPage2xPatch1A}
-\index{patch!HTXLinkPage2xPatch1A!htxlinkpage2.ht}
-\index{htxlinkpage2.ht!patch!HTXLinkPage2xPatch1A}
-\index{HTXLinkPage2xPatch1A!htxlinkpage2.ht!patch}
-<<htxlinkpage2.ht>>=
-\begin{patch}{HTXLinkPage2xPatch1A}
-\begin{paste}{HTXLinkPage2xPaste1B}{HTXLinkPage2xPatch1}
-\pastebutton{HTXLinkPage2xPaste1B}{Interpret}
-\newline
-{\tt \\table\{}\newline
-{\tt \{\\windowlink\{SpadNotConnectedPage\}\{SpadNotConnectedPage\}\}}\newline
-{\tt \{\\windowlink\{UnknownPage\}\{UnknownPage\}\}}\newline
-{\tt \{\\windowlink\{ErrorPage\}\{ErrorPage\}\}}\newline
-{\tt \{\\windowlink\{ProtectedQuitPage\}\{ProtectedQuitPage\}\}}\newline
-{\tt \}}\newline
-\end{paste}
-\end{patch}
-
-@
-\section{htxlinkpage3.ht}
-\subsection{Active Axiom commands}
-\label{HTXLinkPage3}
-See HTXLinkPage4 \ref{HTXLinkPage4} on page~\pageref{HTXLinkPage4}
-\index{pages!HTXLinkPage3!htxlinkpage3.ht.ht}
-\index{htxlinkpage3.ht.ht!pages!HTXLinkPage3}
-\index{HTXLinkPage3!htxlinkpage3.ht.ht!pages}
-<<htxlinkpage3.ht.ht>>=
-\begin{page}{HTXLinkPage3}{Active Axiom commands}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-This section explains how to include Axiom
-commands in your page. The commands we will
-introduce are actually {\it macros} that are defined
-in
-\centerline{{\bf \env{AXIOM}/doc/hypertex/pages/util.ht}}
-This means that you can use them only if you include
-this file in your \HyperName{} database.
-
-The first command to learn is
-\horizontalline
-{\tt \\axiomcommand\{ {\it command }{\tt \ \\free\{}{\it var1 var2 ...}{\tt \}\ \\bound\{}{\it var}{\tt \}\ \}} }
-\horizontalline
-
-
-The {\tt \\free\{\}} and {\tt \\bound\{\}} directives are optional.
-We will come to them in a minute. The {\it command} above is the
-text of the Axiom command. Only single line commands are allowed
-here.
-This text will be displayed in the reserved AxiomFont logical
-font.  The area of the text will be active and clicking on it
-will attempt to send the command to Axiom for evaluation.
-A new Axiom interpreter window (and Axiom frame)
-will be created if this was the first Axiom command
-activated in the current page. If not, the command will be sent
-to the already opened Axiom interpreter window for the current page.
-Note that it {\it is} necessary to escape special
-\HyperName{} characters with the {\tt '\\'} backslash character.
-The exceptions are the characters {\tt \[\]}; they do not
-need to be escaped in this context.
-
-\beginImportant
-\begin{paste}{HTXLinkPage3xPaste1}{HTXLinkPage3xPatch1}
-\pastebutton{HTXLinkPage3xPaste1}{Interpret}
-\newline
-{\tt \\axiomcommand\{ l:=brace[1,2,3] ; length:=\\\# l ; m:=[1,2]\}}
-\end{paste}
-\endImportant
-
-
-The optional {\tt \\free\{\}} and {\tt \\bound\{\}} directives
-provide dependency control. The reader of a \HyperName{}
-page is not forced to click on the commands in the
-order in which in they appear on the page.  If the
-correct {\tt \\free\{\}} and {\tt \\bound\{\}}
-specifications are made, clicking on a command
-will result in execution of all those other
-commands that should be executed before it.
-This will {\it only} happen the first time the command is
-clicked.
-
-So, how are the dependencies specified?
-The arguments of the {\tt \\free\{\}} directive must
-be space-separated words (labels). The argument of {\tt \\bound\{\}}
-must be a single (unique for the page) label. Each label in the {\tt \\free\{\}} list
-must exist as an argument to one (and only one) {\tt \\bound\{\}} directive
-somewhere in the current page.
-When the command is activated, \HyperName{} will look
-in the {\tt \\free\{\}} list and check each label.
-For each label, it will find the command that specifies that label
-in its {\tt \\bound\{\}} directive and
-execute it if it has not been already executed.
-The order of labels in the {\tt \\free\{\}} directive list
-is respected. \HyperName{} will follow all
-dependency links recursively.
-
-Here is  an example.
-Clicking on the third command will automatically
-execute all of them in the correct sequence.
-Note that in this case the order of labels in the last
-line is immaterial since {\tt v2} explicitly depends on {\tt v1}.
-
-\beginImportant
-\begin{paste}{HTXLinkPage3xPaste2}{HTXLinkPage3xPatch2}
-\pastebutton{HTXLinkPage3xPaste2}{Interpret}
-\newline
-{\tt \\axiomcommand\{a:=1;d:=4 \\bound\{v1\}\}}\newline
-{\tt \\newline}\newline
-{\tt \\axiomcommand\{b:=a+3 \\free\{v1\} \\bound\{v2\}\}}\newline
-{\tt \\newline}\newline
-{\tt \\axiomcommand\{c:=b+d \\free\{v1 v2\} \\bound\{v3\}\}}\newline
-\end{paste}
-\endImportant
-
-The second command deals with multi-line Axiom
-code. This is the command to use for execution of
-an Axiom {\it pile}. It is a {\it group}
-command. The proper syntax for it is as follows:
-\horizontalline
-{\tt \\begin\{spadsrc\}\ [\\free\{{\it var1 var2} ...\}\ \\bound\{{\it var}\}]}
-\newline
-.
-\newline
-.
-\newline
-{\tt \\end\{spadsrc\}}
-\horizontalline
-
-Again, the {\tt \\free} and {\tt \\bound} directives are
-optional. If they are specified (in exactly the same way
-as {\tt \\axiomcommand}), they must be enclosed in
-square brackets {\tt []}.
-The lines between the {\tt \\begin} and {\tt \\end}
-contain the Axiom statements. Indentation
-will be respected. \HyperName{} will
-actually save this part in a temporary file
-and instruct Axiom to read the file
-with the {\tt )read} system command.
-
-Here is an example. The execution of the following
-fragment is dependent on the {\tt v3} label.
-Make sure that previous commands are active (and
-hence the label {\tt v3} is "visible") before
-trying to execute it. If the label {\tt v3}
-is not seen in the page, \HyperName{} will
-print an error message on standard output
-and ignore the dependency.
-
-
-\beginImportant
-\begin{paste}{HTXLinkPage3xPaste3}{HTXLinkPage3xPatch3}
-\pastebutton{HTXLinkPage3xPaste3}{Interpret}
-\newline
-{\tt \\begin\{spadsrc\}\ [\\free\{v3\}\ \\bound\{v4\}]}\newline
-{\tt f\ x\ ==}\newline
-{\tt \ \ \ x+c}\newline
-{\tt f\ 3}\newline
-{\tt \\end\{spadsrc\}}
-\end{paste}
-\endImportant
-
-There is, in fact, more that one can do
-with Axiom commands. In pages elsewhere
-in the system, Axiom commands appear next
-to button like this \ \MenuDotBitmap{}.
-Clicking on this button, one can see the output
-for that command. The output has been
-pre-computed and is also stored in
-\HyperName{} files. This is done using
-{\it patch} and {\it paste}.
-It is the same mechanism that
-is used to alternatively display
-\HyperName{} source and interpreted
-result in this and other pages.
-It is explained \downlink{later on}{HTXAdvPage5}.
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Linking to Lisp}{HTXLinkPage4}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXLinkPage3xPatch1 patch}
-\label{HTXLinkPage3xPatch1}
-\index{patch!HTXLinkPage3xPatch1!htxlinkpage3.ht}
-\index{htxlinkpage3.ht!patch!HTXLinkPage3xPatch1}
-\index{HTXLinkPage3xPatch1!htxlinkpage3.ht!patch}
-<<htxlinkpage3.ht>>=
-\begin{patch}{HTXLinkPage3xPatch1}
-\begin{paste}{HTXLinkPage3xPaste1A}{HTXLinkPage3xPatch1A}
-\pastebutton{HTXLinkPage3xPaste1A}{Source}
-\newline
-\axiomcommand{ l:=brace[1,2,3] ; length:=\# l ; m:=[1,2]}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage3xPatch1A patch}
-\label{HTXLinkPage3xPatch1A}
-\index{patch!HTXLinkPage3xPatch1A!htxlinkpage3.ht}
-\index{htxlinkpage3.ht!patch!HTXLinkPage3xPatch1A}
-\index{HTXLinkPage3xPatch1A!htxlinkpage3.ht!patch}
-<<htxlinkpage3.ht>>=
-\begin{patch}{HTXLinkPage3xPatch1A}
-\begin{paste}{HTXLinkPage3xPaste1B}{HTXLinkPage3xPatch1}
-\pastebutton{HTXLinkPage3xPaste1B}{Interpret}
-\newline
-{\tt \\axiomcommand\{ l:=brace[1,2,3] ; length:=\\\# l ; m:=[1,2]\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage3xPatch2 patch}
-\label{HTXLinkPage3xPatch2}
-\index{patch!HTXLinkPage3xPatch2!htxlinkpage3.ht}
-\index{htxlinkpage3.ht!patch!HTXLinkPage3xPatch2}
-\index{HTXLinkPage3xPatch2!htxlinkpage3.ht!patch}
-<<htxlinkpage3.ht>>=
-\begin{patch}{HTXLinkPage3xPatch2}
-\begin{paste}{HTXLinkPage3xPaste2A}{HTXLinkPage3xPatch2A}
-\pastebutton{HTXLinkPage3xPaste2A}{Source}
-\newline
-\axiomcommand{a:=1;d:=4 \bound{v1}}
-\newline
-\axiomcommand{b:=a+3 \free{v1} \bound{v2}}
-\newline
-\axiomcommand{c:=b+d \free{v1 v2} \bound{v3}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage3xPatch2A patch}
-\label{HTXLinkPage3xPatch2A}
-\index{patch!HTXLinkPage3xPatch2A!htxlinkpage3.ht}
-\index{htxlinkpage3.ht!patch!HTXLinkPage3xPatch2A}
-\index{HTXLinkPage3xPatch2A!htxlinkpage3.ht!patch}
-<<htxlinkpage3.ht>>=
-\begin{patch}{HTXLinkPage3xPatch2A}
-\begin{paste}{HTXLinkPage3xPaste2B}{HTXLinkPage3xPatch2}
-\pastebutton{HTXLinkPage3xPaste2B}{Interpret}
-\newline
-{\tt \\axiomcommand\{a:=1;d:=4 \\bound\{v1\}\}}\newline
-{\tt \\newline}\newline
-{\tt \\axiomcommand\{b:=a+3 \\free\{v1\} \\bound\{v2\}\}}\newline
-{\tt \\newline}\newline
-{\tt \\axiomcommand\{c:=b+d \\free\{v1 v2\} \\bound\{v3\}\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage3xPatch3 patch}
-\label{HTXLinkPage3xPatch3}
-\index{patch!HTXLinkPage3xPatch3!htxlinkpage3.ht}
-\index{htxlinkpage3.ht!patch!HTXLinkPage3xPatch3}
-\index{HTXLinkPage3xPatch3!htxlinkpage3.ht!patch}
-<<htxlinkpage3.ht>>=
-\begin{patch}{HTXLinkPage3xPatch3}
-\begin{paste}{HTXLinkPage3xPaste3A}{HTXLinkPage3xPatch3A}
-\pastebutton{HTXLinkPage3xPaste3A}{Source}
-\newline
-\begin{spadsrc} [\free{v3} \bound{v4}]
-f x ==
-   x+c
-f 3
-\end{spadsrc}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage3xPatch3A patch}
-\label{HTXLinkPage3xPatch3A}
-\index{patch!HTXLinkPage3xPatch3A!htxlinkpage3.ht}
-\index{htxlinkpage3.ht!patch!HTXLinkPage3xPatch3A}
-\index{HTXLinkPage3xPatch3A!htxlinkpage3.ht!patch}
-<<htxlinkpage3.ht>>=
-\begin{patch}{HTXLinkPage3xPatch3A}
-\begin{paste}{HTXLinkPage3xPaste3B}{HTXLinkPage3xPatch3}
-\pastebutton{HTXLinkPage3xPaste3B}{Interpret}
-\newline
-{\tt \\begin\{spadsrc\}\ [\\free\{v3\}\ \\bound\{v4\}]}\newline
-{\tt f\ x\ ==}\newline
-{\tt \ \ \ x+c}\newline
-{\tt f\ 3}\newline
-{\tt \\end\{spadsrc\}}
-\end{paste}
-\end{patch}
-
-@
-\section{htxlinkpage4.ht}
-\subsection{Linking to Lisp}
-\label{HTXLinkPage4}
-See HTXLinkPage5 \ref{HTXLinkPage5} on page~\pageref{HTXLinkPage5}
-\index{pages!HTXLinkPage4!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!pages!HTXLinkPage4}
-\index{HTXLinkPage4!htxlinkpage4.ht!pages}
-<<htxlinkpage4.ht>>=
-\begin{page}{HTXLinkPage4}{Linking to Lisp}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-Another feature of the Axiom\hspace{2}--\HyperName{}
-link is the ability to execute {\it Lisp}
-code at a click of a button.
-There are two things one can do.
-
-The first is to cause the evaluation
-of a {\it Lisp} form and ignore (as far as \HyperName{}
-is concerned) its value. The evaluation of the function
-might have an effect however on your Axiom session.
-
-The command for this is
-\horizontalline
-\centerline{ {\tt \\lispcommand\{{\it text}\}\{{\it Lisp form}\}}}
-\horizontalline
-
-Here is an example. We will first define a {\it Lisp} function
-and then execute it.  Notice that the \HyperName{}
-special characters must be escaped (this is on top
-of {\it Lisp} escaping conventions).
-
-
-\beginImportant
-\begin{paste}{HTXLinkPage4xPaste1}{HTXLinkPage4xPatch1}
-\pastebutton{HTXLinkPage4xPaste1}{Interpret}
-\newline
-{\tt \\lispcommand\{Definition\}\{(defun HTXTESTFUNCTION ()}\newline
-{\tt  (print "Hello from HyperDoc \\\\\\\\ \\\% \\\{ \\\}"))\}} \newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Execution\}\{(HTXTESTFUNCTION)\}} \newline
-\end{paste}
-\endImportant
-
-Your command will be executed as soon as
-Axiom completes any computation it might be
-carrying out.
-
-
-%\axiomcommand{)lisp (defun f () (pprint "hello"))}
-%\lispcommand{f}{(|f|)}
-
-
-The second thing you can do is quite powerful. It allows you
-to delegate to a {\it Lisp} function
-the {\it dynamic} creation of a page. This is used
-in \Browse{} to present
-the Axiom Library in a hypertext form.
-
-The command to use is a lot like the {\tt link} commands
-you encountered \downlink{earlier}{HTXLinkPage1} and comes in three flavours.
-\centerline{{\tt \\lispwindowlink\{{\it trigger}\}\{{\it Lisp form}\}}}
-\centerline{{\tt \\lispdownlink\{{\it trigger}\}\{{\it Lisp form}\}}}
-\centerline{{\tt \\lispmemolink\{{\it trigger}\}\{{\it Lisp form}\}}}
-
-The difference between the three versions is the same as before.
-When such a link is activated, \HyperName{} issues the
-{\it Lisp form} to Axiom and waits for a full
-page definition. An important point to note is that
-\HyperName{} does {\it not} use
-the value of the {\it Lisp form} but, instead, it
-depends on its {\it side-effects}.
-What {\it must} happen during evaluation
-of the form is enough evaluations of a special {\it Lisp}
-function called {\bf issueHT} to define a page.
-The argument of {\bf issueHT} is a string
-containing \HyperName{} text. Perhaps an example will clarify
-matters.
-
-First we will define a {\it Lisp} function that accepts
-a string argument and calls {\bf issueHT} a few times.
-The strings that are passed to {\bf issueHT} construct
-a \HyperName{} page that would just contain our
-original argument centered roughly on the page.
-Then we write the {\tt \\lisplink} with a call to
-the function. Finally, we execute a {\it Lisp}
-command that just pretty--prints the function's definition.
-
-
-
-\beginImportant
-\begin{paste}{HTXLinkPage4xPaste2}{HTXLinkPage4xPatch2}
-\pastebutton{HTXLinkPage4xPaste2}{Interpret}
-\newline
-{\tt \\lispcommand\{Definition\}\{(defun HTXTESTPAGE (x) (|issueHT|}\newline
-{\tt  "\\\\\\\\begin\\\{page\\\}\\\{LispTestPage\\\}\\\{Lisp Test Page\\\}}\newline
-{\tt  \\\\\\\\vspace\\\{150\\\} \\\\\\\\centerline\\\{") (|issueHT| x) (|issueHT|}\newline
-{\tt  "\\\} \\\\\\\\end\\\{page\\\}" ) ) \}}\newline
-{\tt \\newline}\newline
-{\tt \\lispwindowlink\{Link to it\}\{(HTXTESTPAGE "Hi there")\}}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Show Lisp definition\}\{(pprint (symbol-function 'HTXTESTPAGE))\}}\newline
-\end{paste}
-\endImportant
-
-The {\tt '\\\{'} and {\tt '\\\}'} is required to escape
-\HyperName{}'s special characters {\tt '\{'} and {\tt  '\}'}.
-The {\tt '\\\\\\\\'} has the following rationale.
-We need to send to \HyperName{} (from {\it Lisp}) the sequence
-{\tt \\begin}. But {\tt '\\'} is a special {\it Lisp}
-character. Therefore the {\it Lisp} string must be
-{\tt '\\\\begin'}. But to specify this
-in \HyperName{} we need to escape the two {\tt '\\'}.
-Therefore, we write {\tt '\\\\\\\\begin'}.
-
-
-The definition of {\tt HTXTESTPAGE} would have been written in {\it Lisp}
-as follows.
-\begin{verbatim}
-(defun HTXTESTPAGE (X)
-   (|issueHT|
-      "\\begin{page}{LispTestPage}{Lisp Test Page} \\vspace{200} \\centerline{")
-   (|issueHT| X)
-   (|issueHT| "} \\end{page}"))
-\end{verbatim}
-
-
-
-You should not execute {\tt HTXTESTPAGE} in the
-{\it Lisp} environment manually. It is meant to
-be executed {\it only} in response to a
-\HyperName{} request.
-
-Can you pop-up a named page from {\it Lisp} regardless of
-user action? Yes --- use {\it Lisp} function {\bf linkToHTPage}
-with the page name as a string argument. Click on the
-{\tt \\axiomcommand} below. Then, in your Axiom
-session, you can repeat it if you like.
-
-\beginImportant
-\begin{paste}{HTXLinkPage4xPaste3}{HTXLinkPage4xPatch3}
-\pastebutton{HTXLinkPage4xPaste3}{Interpret}
-\newline
-{\tt \\axiomcommand\{)lisp (|linkToHTPage| "RootPage")\}}
-\end{paste}
-\endImportant
-
-You can also pop-up a {\it dynamic} page regardless of user action.
-To do this, make sure you evaluate the {\it Lisp form}
-{\bf (|startHTPage| 50)} before using {\bf issueHT}.
-The example below requires the {\tt HTXTESTPAGE} function
-to be defined in {\it Lisp} so you should make sure
-you have executed the command above that defines it.
-
-\beginImportant
-\begin{paste}{HTXLinkPage4xPaste4}{HTXLinkPage4xPatch4}
-\pastebutton{HTXLinkPage4xPaste4}{Interpret}
-\newline
-{\tt \\axiomcommand\{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))\}}
-\end{paste}
-\endImportant
-
-Now, the most important use of this facility
-so far has been in the \Browse{} and Basic Commands components of
-\HyperName{}. Instead of giving you details of the various
-\Browse{} {\it Lisp} functions, a few macros are defined in
-\centerline{{\bf \$AXIOM/doc/hypertex/pages/util.ht}}
-
-The most important defined macros are
-\beginImportant
-\table{
-{ {\tt \\axiomType\{{\it constructor}\}} }
-{ {\tt \\axiomOp\{{\it operation}\}} }
-{ {\tt \\axiomOpFrom\{{\it operation }\}\{{\it constructor}\}}}
-}
-\endImportant
-
-Here are some examples of their use.
-\beginImportant
-\begin{paste}{HTXLinkPage4xPaste5}{HTXLinkPage4xPatch5}
-\pastebutton{HTXLinkPage4xPaste5}{Interpret}
-\newline
-{\tt \\axiomType\{Expression Integer\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomType\{Expression\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomType\{EXPR\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomOp\{reduce\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomOp\{as*\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomOpFrom\{reduce\}\{Expression\}}\newline
-\end{paste}
-\endImportant
-
-The macro {\tt \\axiomType} brings up the \Browse{}
-constructor page for the constructor specified.
-You can specify a full name, or an abbreviation
-or just the top level name.
-The macro {\tt \\axiomOp} brings up a list of operations
-matching the argument.
-The macro {\tt \\axiomOpFrom} shows documentation
-about the specified operation whose origin is
-constructor. No wildcard in the operation name
-or type abbreviation is
-allowed here.  You should also specify just the top level type.
-
-
-
-
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- Linking to Unix}{HTXLinkPage5}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXLinkPage4xPatch1 patch}
-\label{HTXLinkPage4xPatch1}
-\index{patch!HTXLinkPage4xPatch1!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch1}
-\index{HTXLinkPage4xPatch1!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch1}
-\begin{paste}{HTXLinkPage4xPaste1A}{HTXLinkPage4xPatch1A}
-\pastebutton{HTXLinkPage4xPaste1A}{Source}
-\newline
-\lispcommand{Definition}{(defun HTXTESTFUNCTION ()
-(print "Hello from HyperDoc \\\\ \% \{ \}"))}
-\newline
-\lispcommand{Execution}{(HTXTESTFUNCTION)}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch1A patch}
-\label{HTXLinkPage4xPatch1A}
-\index{patch!HTXLinkPage4xPatch1A!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch1A}
-\index{HTXLinkPage4xPatch1A!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch1A}
-\begin{paste}{HTXLinkPage4xPaste1B}{HTXLinkPage4xPatch1}
-\pastebutton{HTXLinkPage4xPaste1B}{Interpret}
-\newline
-{\tt \\lispcommand\{Definition\}\{(defun HTXTESTFUNCTION () (print "Hello from HyperDoc \\\\\\\\ \\\% \\\{ \\\}"))\}} \newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Execution\}\{(HTXTESTFUNCTION)\}} \newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch2 patch}
-\label{HTXLinkPage4xPatch2}
-\index{patch!HTXLinkPage4xPatch2!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch2}
-\index{HTXLinkPage4xPatch2!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch2}
-\begin{paste}{HTXLinkPage4xPaste2A}{HTXLinkPage4xPatch2A}
-\pastebutton{HTXLinkPage4xPaste2A}{Source}
-\newline
-\lispcommand{Definition}{(defun HTXTESTPAGE (x) (|issueHT|
-"\\\\begin\{page\}\{LispTestPage\}\{Lisp Test Page\}
-\\\\vspace\{150\} \\\\centerline\{") (|issueHT| x) (|issueHT|
-"\} \\\\end\{page\}" ) ) }
-\newline
-\lispwindowlink{Link to it}{(HTXTESTPAGE "Hi there")}
-\newline
-\lispcommand{Show Lisp definition}{(pprint (symbol-function 'HTXTESTPAGE))}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch2A patch}
-\label{HTXLinkPage4xPatch2A}
-\index{patch!HTXLinkPage4xPatch2A!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch2A}
-\index{HTXLinkPage4xPatch2A!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch2A}
-\begin{paste}{HTXLinkPage4xPaste2B}{HTXLinkPage4xPatch2}
-\pastebutton{HTXLinkPage4xPaste2B}{Interpret}
-\newline
-{\tt \\lispcommand\{Definition\}\{(defun HTXTESTPAGE (x) (|issueHT|}\newline
-{\tt  "\\\\\\\\begin\\\{page\\\}\\\{LispTestPage\\\}\\\{Lisp Test Page\\\}}\newline
-{\tt  \\\\\\\\vspace\\\{150\\\} \\\\\\\\centerline\\\{") (|issueHT| x) (|issueHT|}\newline
-{\tt  "\\\} \\\\\\\\end\\\{page\\\}" ) ) \}}\newline
-{\tt \\newline}\newline
-{\tt \\lispwindowlink\{Link to it\}\{(HTXTESTPAGE "Hi there")\}}\newline
-{\tt \\newline}\newline
-{\tt \\lispcommand\{Show Lisp definition\}\{(pprint (symbol-function 'HTXTESTPAGE))\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch3 patch}
-\label{HTXLinkPage4xPatch3}
-\index{patch!HTXLinkPage4xPatch3!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch3}
-\index{HTXLinkPage4xPatch3!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch3}
-\begin{paste}{HTXLinkPage4xPaste3A}{HTXLinkPage4xPatch3A}
-\pastebutton{HTXLinkPage4xPaste3A}{Source}
-\newline
-\axiomcommand{)lisp (|linkToHTPage| "RootPage")}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch3A patch}
-\label{HTXLinkPage4xPatch3A}
-\index{patch!HTXLinkPage4xPatch3A!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch3A}
-\index{HTXLinkPage4xPatch3A!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch3A}
-\begin{paste}{HTXLinkPage4xPaste3B}{HTXLinkPage4xPatch3}
-\pastebutton{HTXLinkPage4xPaste3B}{Interpret}
-\newline
-{\tt \\axiomcommand\{)lisp (|linkToHTPage| "RootPage")\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch4 patch}
-\label{HTXLinkPage4xPatch4}
-\index{patch!HTXLinkPage4xPatch4!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch4}
-\index{HTXLinkPage4xPatch4!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch4}
-\begin{paste}{HTXLinkPage4xPaste4A}{HTXLinkPage4xPatch4A}
-\pastebutton{HTXLinkPage4xPaste4A}{Source}
-\newline
-\axiomcommand{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch4A patch}
-\label{HTXLinkPage4xPatch4A}
-\index{patch!HTXLinkPage4xPatch4A!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch4A}
-\index{HTXLinkPage4xPatch4A!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch4A}
-\begin{paste}{HTXLinkPage4xPaste4B}{HTXLinkPage4xPatch4}
-\pastebutton{HTXLinkPage4xPaste4B}{Interpret}
-\newline
-{\tt \\axiomcommand\{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))\}}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch5 patch}
-\label{HTXLinkPage4xPatch5}
-\index{patch!HTXLinkPage4xPatch5!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch5}
-\index{HTXLinkPage4xPatch5!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch5}
-\begin{paste}{HTXLinkPage4xPaste5A}{HTXLinkPage4xPatch5A}
-\pastebutton{HTXLinkPage4xPaste5A}{Source}
-\newline
-\axiomType{Expression Integer}
-\newline
-\axiomType{Expression}
-\newline
-\axiomType{EXPR}
-\newline
-\axiomOp{reduce}
-\newline
-\axiomOp{as*}
-\newline
-\axiomOpFrom{reduce}{Expression}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage4xPatch5A patch}
-\label{HTXLinkPage4xPatch5A}
-\index{patch!HTXLinkPage4xPatch5A!htxlinkpage4.ht}
-\index{htxlinkpage4.ht!patch!HTXLinkPage4xPatch5A}
-\index{HTXLinkPage4xPatch5A!htxlinkpage4.ht!patch}
-<<htxlinkpage4.ht>>=
-\begin{patch}{HTXLinkPage4xPatch5A}
-\begin{paste}{HTXLinkPage4xPaste5B}{HTXLinkPage4xPatch5}
-\pastebutton{HTXLinkPage4xPaste5B}{Interpret}
-\newline
-{\tt \\axiomType\{Expression Integer\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomType\{Expression\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomType\{EXPR\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomOp\{reduce\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomOp\{as*\}}\newline
-{\tt \newline}\newline
-{\tt \\axiomOpFrom\{reduce\}\{Expression\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\section{htxlinkpage5.ht}
-\subsection{Linking to Unix}
-\label{HTXLinkPage5}
-\index{pages!HTXLinkPage5!htxlinkpage5.ht}
-\index{htxlinkpage5.ht!pages!HTXLinkPage5}
-\index{HTXLinkPage5!htxlinkpage5.ht!pages}
-<<htxlinkpage5.ht>>=
-\begin{page}{HTXLinkPage5}{Linking to Unix}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-Let us conclude the tour of \HyperName{}
-actions that can be triggered with a click of a button
-with two more facilities. These are
-\beginImportant
-\table{
-{ {\tt \\unixcommand\{{\it trigger text}\}\{{\it unix command}\}}}
-{ {\tt \\unixlink\{{\it trigger text}\}\{{\it unix command}\}}}
-}
-\endImportant
-
-
-The first one, {\tt \\unixcommand}, is very much like
-{\tt \\axiomcommand} and {\tt \\lispcommand}.
-The trigger text becomes an active area. Clicking on it
-will force \HyperName{} to pass the second argument
-to the system as a shell command to be executed.
-The shell used is {\bf /bin/sh}.
-\HyperName{} ignores the output of the command.
-
-
-\beginImportant
-\begin{paste}{HTXLinkPage5xPaste1}{HTXLinkPage5xPatch1}
-\pastebutton{HTXLinkPage5xPaste1}{Interpret}
-\newline
-{\tt \\unixcommand\{List \\\$HOME directory\}\{ls \\\$HOME\}}\newline
-\end{paste}
-\endImportant
-
-The {\tt \\unixlink} command delegates to a another
-program the creation of a dynamic page. When the trigger
-text is activated, \HyperName{} will invoke the command
-specified in the second argument. It will then start reading
-the {\it standard output} of the command until
-a complete page has been received. It is important that
-a single page and nothing more is written by the command.
-This command is essentially a {\tt \\downlink}, i.e.
-the new page replaces the current page in the window.
-There aren't any other flavours of {\tt \\unixlink}.
-A trivial example is to use {\bf cat} on a \HyperName{}
-file known to contain just one page.
-
-\beginImportant
-\begin{paste}{HTXLinkPage5xPaste2}{HTXLinkPage5xPatch2}
-\pastebutton{HTXLinkPage5xPaste2}{Interpret}
-\newline
-{\tt \\unixlink\{Some file\}} \newline
-{\tt \{cat\\ \\env\{AXIOM\}/doc/hypertex/pages/HTXplay.ht\}}
-\end{paste}
-\endImportant
-
-
-Two things to notice in the second argument of
-{\tt \\unixlink}: You must use a {\it hard space}
-{\tt '\\\ '} to preserve the spacing in the command.
-Also, the {\tt \\env} command allows you to use
-an environment variable in \HyperName{} text.
-
-With a little ingenuity (and maybe some shell and {\bf awk} scripts !)
-, one can use these
-facilities to create, say, a point-and-click
-directory viewer which allows you to edit
-a file by clicking on its name.
-
-\end{scroll}
-\beginmenu
-\menulink{Next -- How to use your pages with \HyperName{}}{HTXLinkPage6}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXLinkPage5xPatch1 patch}
-\label{HTXLinkPage5xPatch1}
-\index{patch!HTXLinkPage5xPatch1!htxlinkpage5.ht}
-\index{htxlinkpage5.ht!patch!HTXLinkPage5xPatch1}
-\index{HTXLinkPage5xPatch1!htxlinkpage5.ht!patch}
-<<htxlinkpage5.ht>>=
-\begin{patch}{HTXLinkPage5xPatch1}
-\begin{paste}{HTXLinkPage5xPaste1A}{HTXLinkPage5xPatch1A}
-\pastebutton{HTXLinkPage5xPaste1A}{Source}
-\newline
-\unixcommand{List \$HOME directory}{ls \$HOME}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage5xPatch1A patch}
-\label{HTXLinkPage5xPatch1A}
-\index{patch!HTXLinkPage5xPatch1A!htxlinkpage5.ht}
-\index{htxlinkpage5.ht!patch!HTXLinkPage5xPatch1A}
-\index{HTXLinkPage5xPatch1A!htxlinkpage5.ht!patch}
-<<htxlinkpage5.ht>>=
-\begin{patch}{HTXLinkPage5xPatch1A}
-\begin{paste}{HTXLinkPage5xPaste1B}{HTXLinkPage5xPatch1}
-\pastebutton{HTXLinkPage5xPaste1B}{Interpret}
-\newline
-{\tt \\unixcommand\{List \\\$HOME directory\}\{ls \\\$HOME\}}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage5xPatch2 patch}
-\label{HTXLinkPage5xPatch2}
-\index{patch!HTXLinkPage5xPatch2!htxlinkpage5.ht}
-\index{htxlinkpage5.ht!patch!HTXLinkPage5xPatch2}
-\index{HTXLinkPage5xPatch2!htxlinkpage5.ht!patch}
-<<htxlinkpage5.ht>>=
-\begin{patch}{HTXLinkPage5xPatch2}
-\begin{paste}{HTXLinkPage5xPaste2A}{HTXLinkPage5xPatch2A}
-\pastebutton{HTXLinkPage5xPaste2A}{Source}
-\newline
-\unixlink{Some file}
-{cat\ \env{AXIOM}/doc/hypertex/pages/HTXplay.ht}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage5xPatch2A patch}
-\label{HTXLinkPage5xPatch2A}
-\index{patch!HTXLinkPage5xPatch2A!htxlinkpage5.ht}
-\index{htxlinkpage5.ht!patch!HTXLinkPage5xPatch2A}
-\index{HTXLinkPage5xPatch2A!htxlinkpage5.ht!patch}
-<<htxlinkpage5.ht>>=
-\begin{patch}{HTXLinkPage5xPatch2A}
-\begin{paste}{HTXLinkPage5xPaste2B}{HTXLinkPage5xPatch2}
-\pastebutton{HTXLinkPage5xPaste2B}{Interpret}
-\newline
-{\tt \\unixlink\{Some file\}} \newline
-{\tt \{cat\\ \\env\{AXIOM\}/doc/hypertex/pages/HTXplay.ht\}}
-\end{paste}
-\end{patch}
-
-@
-\section{htxlinkpage6.ht}
-\subsection{How to use your pages with Hyperdoc}
-\label{HTXLinkPage6}
-\index{pages!HTXLinkPage6!htxlinkpage6.ht}
-\index{htxlinkpage6.ht!pages!HTXLinkPage6}
-\index{HTXLinkPage6!htxlinkpage6.ht!pages}
-<<htxlinkpage6.ht>>=
-\begin{page}{HTXLinkPage6}{How to use your pages with Hyperdoc}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\begin{scroll}
-
-Let us say that you have written a few \HyperName{}
-pages and you would like to incorporate them in the system.
-Here is what you should do.
-
-Put all your files in some directory and make sure that
-they all have the {\bf .ht} extension.
-
-You will need a way of "hooking" into a system--defined
-\HyperName{} page. The proper way to do this is to use
-the {\tt \\localinfo} macro. The Axiom system
-\HyperName{} page database includes, as it should,
-a {\tt RootPage}. This is the page that first comes up
-when you start \HyperName{}. This page contains
-a line like this.
-\beginImportant
-\newline
-{\tt \\localinfo}
-\endImportant
-
-This macro is defined in
-\centerline{ {\bf \env{AXIOM}/doc/hypertex/pages/util.ht}}
-to be (see \downlink{Macros}{HTXAdvPage3} to learn how to define macros):
-\beginImportant
-\newline
-{\tt \\newcommand\{\\localinfo\}\{\}}
-\endImportant
-which is an empty definition (the second argument of {\tt \\newcommand}).
-The idea then is that you {\it override} this definition of the macro
-with your own.
-To do that, include a definition like the following in one (possibly the
-one that contains your top--level page) of your files. You can
-put this definition in its own file if you like.
-\beginImportant
-\newline
-{\tt \\newcommand\{\\localinfo\}\{\\menuwindowlink\{{\it active text}\}} \newline
-{\tt \{{\it page name}\} \\tab\{16\}{\it short description}\}}
-\endImportant
-
-If you have a look at the initial \HyperName{} page, you will
-probably be able to decipher what this does. The macro
-{\tt \\menuwindowlink} is defined (again in {\bf util.ht})
-and is responsible for putting the little square to the left of the
-active area.
-Specify a word or two for {\it active text}. That will become the
-trigger of the {\tt \\link}. Specify the page name of your top--level page
-in {\it page name}. Finally, you can give a comment about the topic
-under {\it short description}. That will appear to the right of the
-{\it active text}.
-
-The next thing you need to do is to create a {\it local database}
-for your files. You will use the {\bf \env{AXIOM}/bin/htadd} program.
-This program will create an {\bf ht.db} file that summarises your
-definitions and acts as an index. Let us present an example
-of its use. Suppose you have two files {\bf user1.ht} and {\bf user2.ht}
-in directory {\bf /u/sugar/\HyperName{}}. You should create the {\bf ht.db}
-in that same directory. To create the {\bf ht.db} file you issue to
-the unix shell:
-\beginImportant
-\newline
-{\tt htadd -f /u/sugar/\HyperName{} /u/sugar/\HyperName{}/user1.ht /u/sugar/\HyperName{}/user2.ht}
-\centerline{or ,if you are already in /u/sugar/\HyperName{}}
-{\tt htadd -l ./user1.ht ./user2.ht}
-\endImportant
-
-
-The options and conventions for {\bf htadd} will be explained below.
-To start \HyperName{} with your own pages, you now need to tell
-it where to search for {\bf ht.db} files and \HyperName{} {\bf .ht}
-files. To do this, define the shell environment variable
-{\bf HTPATH}. The value should be a colon {\tt ':'} separated
-list of directory full pathnames.
-The order of the directories is respected with earlier entries overriding
-later ones. Since we want all the Axiom pages but need to override the
-{\tt \\localinfo} macro, we should use the value
-\centerline{{\bf /u/sugar/\HyperName{}:\env{AXIOM}/doc/hypertex/pages}}
-The way that you define environment variables depends on the shell
-you are using. In the {\bf /bin/csh}, it would be
-\newline
-{\bf setenv HTPATH /u/sugar/\HyperName{}:\env{AXIOM}{}/doc{}/hypertex{}/pages}
-
-
-
-\beginImportant
-\begin{paste}{HTXLinkPage6xPaste1}{HTXLinkPage6xPatch1}
-\pastebutton{HTXLinkPage6xPaste1}{Options for {\bf htadd}}
-\newline
-\end{paste}
-\endImportant
-
-
-\beginImportant
-\begin{paste}{HTXLinkPage6xPaste2}{HTXLinkPage6xPatch2}
-\pastebutton{HTXLinkPage6xPaste2}{Where does \HyperName{} look for files}
-\newline
-\end{paste}
-\endImportant
-
-
-
-\end{scroll}
-\beginmenu
-\menulink{Back to Actions menu}{HTXLinkTopPage}
-\endmenu
-
-\end{page}
-
-@
-\subsection{HTXLinkPage6xPatch1 patch}
-\label{HTXLinkPage6xPatch1}
-\index{patch!HTXLinkPage6xPatch1!htxlinkpage6.ht}
-\index{htxlinkpage6.ht!patch!HTXLinkPage6xPatch1}
-\index{HTXLinkPage6xPatch1!htxlinkpage6.ht!patch}
-<<htxlinkpage6.ht>>=
-\begin{patch}{HTXLinkPage6xPatch1}
-\begin{paste}{HTXLinkPage6xPaste1A}{HTXLinkPage6xPatch1A}
-\pastebutton{HTXLinkPage6xPaste1A}{Hide}
-\newline
-Name:
-
-{\tt htadd - create or modify a \HyperName{} database}
-\vspace{}
-\newline
-Syntax:
-
-{\tt htadd [ -l | -s | -f\ }{\it path}{\tt ] [ -d | -n ]\ }{\it filename ...}
-\vspace{}
-\newline
-Options:\indentrel{4}\newline
-{\tt -l}\tab{8}\indentrel{8}
-build {\bf ht.db} database in current working directory.
-This is the default behaviour if no {\tt -l}, {\tt -s} or {\tt -f}
-is specified.
-
-\indentrel{-8}\newline
-{\tt -s}\tab{8}\indentrel{8}
-build {\bf ht.db} database in {\it system} directory. The
-system directory is built as follows. If the {\tt AXIOM}
-variable is defined, the {\bf \$AXIOM/doc/hypertex/pages} directory
-is used. If {\tt AXIOM} is not defined, the
-{\bf /usr/local/axiom/doc/hypertex/pages} directory is used.
-
-
-\indentrel{-8}\newline
-{\tt -f\ }{\it path}\newline\tab{8}\indentrel{8}
-build {\bf ht.db} database in specified {\it path}.
-
-\indentrel{-8}\newline
-{\tt -d}\tab{8}\indentrel{8}
-delete the entries in the specified files from {\bf ht.db}.
-
-\indentrel{-8}\newline
-{\tt -n}\tab{8}\indentrel{8}
-delete {\bf ht.db} and create a new one using only the files
-specified.
-
-If none of {\tt -n} and {\tt -d} is specified, the {\bf ht.db}
-is updated with the entries in the file specified.
-
-
-\indentrel{-8}
-\indentrel{-4}
-\vspace{}\newline
-Filename interpretation :
-\indentrel{12}\newline
-A full pathname (i.e. anything that has a {\tt '/'} in it)
-will be taken do be a completely specified file.
-Otherwise, the following interpretation will occur:
-If the {\tt HTPATH} variable is defined, the directories
-specified in it will be tried in order. If {\tt HTPATH}
-is not defined, then, if {\tt AXIOM} is defined, the
-{\bf \$AXIOM/doc/hypertex/pages} will be tried, else
-the file will be deemed missing and {\bf htadd} will fail.
-\indentrel{-12}
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage6xPatch1A patch}
-\label{HTXLinkPage6xPatch1A}
-\index{patch!HTXLinkPage6xPatch1A!htxlinkpage6.ht}
-\index{htxlinkpage6.ht!patch!HTXLinkPage6xPatch1A}
-\index{HTXLinkPage6xPatch1A!htxlinkpage6.ht!patch}
-<<htxlinkpage6.ht>>=
-\begin{patch}{HTXLinkPage6xPatch1A}
-\begin{paste}{HTXLinkPage6xPaste1B}{HTXLinkPage6xPatch1}
-\pastebutton{HTXLinkPage6xPaste1B}{Options for {\bf htadd}}
-\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage6xPatch2 patch}
-\label{HTXLinkPage6xPatch2}
-\index{patch!HTXLinkPage6xPatch2!htxlinkpage6.ht}
-\index{htxlinkpage6.ht!patch!HTXLinkPage6xPatch2}
-\index{HTXLinkPage6xPatch2!htxlinkpage6.ht!patch}
-<<htxlinkpage6.ht>>=
-\begin{patch}{HTXLinkPage6xPatch2}
-\begin{paste}{HTXLinkPage6xPaste2A}{HTXLinkPage6xPatch2A}
-\pastebutton{HTXLinkPage6xPaste2A}{Hide}
-\indentrel{12}\newline
-The \HyperName{} program is
-\centerline{{\bf \env{AXIOM}/lib/hypertex}}
-If {\tt AXIOM} is defined and {\tt HTPATH} is not
-(this is the case when Axiom starts \HyperName{})
-\HyperName{} will look in
-\centerline{{\bf \env{AXIOM}/doc/hypertex/pages}}
-for the {\bf ht.db} file and all \HyperName{} pages.
-If {\tt HTPATH} is defined, it is assumed that
-it alone points to the directories to be searched
-(the above default will NOT be searched unless
-explicitly specified in {\tt HTPATH}).
-For each directory in {\tt HTPATH}, the {\bf ht.db}
-file, if there, will be read.
-Each file listed in {\bf ht.db} will
-then be searched for in the complete sequence
-of directories in {\tt HTPATH}. Note that
-the {\bf ht.db} does not keep full pathnames
- of files.
-If a {\it page}, {\it macro} or {\it patch}
-(specified in some {\bf ht.db}) happens
-to be (in a file) in more than one of the directories
-specified in {\tt HTPATH}, \HyperName{}
-will print a warning and explain which version
-in which file is ignored. Generally, earlier
-directories in {\tt HTPATH} are preferred over later
-ones.
-\indentrel{-12}\newline
-\end{paste}
-\end{patch}
-
-@
-\subsection{HTXLinkPage6xPatch2A patch}
-\label{HTXLinkPage6xPatch2A}
-\index{patch!HTXLinkPage6xPatch2A!htxlinkpage6.ht}
-\index{htxlinkpage6.ht!patch!HTXLinkPage6xPatch2A}
-\index{HTXLinkPage6xPatch2A!htxlinkpage6.ht!patch}
-<<htxlinkpage6.ht>>=
-\begin{patch}{HTXLinkPage6xPatch2A}
-\begin{paste}{HTXLinkPage6xPaste2B}{HTXLinkPage6xPatch2}
-\pastebutton{HTXLinkPage6xPaste2B}{Where does \HyperName{} look for files}}
-\newline
-\end{paste}
-\end{patch}
-
-@
-\section{htxlinktoppage.ht}
-\subsection{Actions in Hyperdoc}
-\label{HTXLinkTopPage}
-\begin{itemize}
-\item HTXLinkPage1 \ref{HTXLinkPage1} on page~\pageref{HTXLinkPage1}
-\item HTXLinkPage2 \ref{HTXLinkPage2} on page~\pageref{HTXLinkPage2}
-\item HTXLinkPage3 \ref{HTXLinkPage3} on page~\pageref{HTXLinkPage3}
-\item HTXLinkPage4 \ref{HTXLinkPage4} on page~\pageref{HTXLinkPage4}
-\item HTXLinkPage5 \ref{HTXLinkPage5} on page~\pageref{HTXLinkPage5}
-\item HTXLinkPage6 \ref{HTXLinkPage6} on page~\pageref{HTXLinkPage6}
-\end{itemize}
-\index{pages!HTXLinkTopPage!htxlinktoppage.ht}
-\index{htxlinktoppage.ht!pages!HTXLinkTopPage}
-\index{HTXLinkTopPage!htxlinktoppage.ht!pages}
-<<htxlinktoppage.ht>>=
-\begin{page}{HTXLinkTopPage}{Actions in Hyperdoc}
-\centerline{\fbox{{\tt \thispage}}}\newline
-\HyperName{} offers various types of hypertext links.
-You can learn about these facilities by clicking on the topics below.
-\begin{scroll}
-\beginmenu
-\menudownlink{Linking to a named page}{HTXLinkPage1}
-\menudownlink{Standard pages}{HTXLinkPage2}
-\menudownlink{Active Axiom commands}{HTXLinkPage3}
-\menudownlink{Linking to Lisp}{HTXLinkPage4}
-\menudownlink{Linking to Unix}{HTXLinkPage5}
-\menudownlink{How to use your pages with \HyperName{}}{HTXLinkPage6}
-\endmenu
-\end{scroll}
-\end{page}
-
-@
-\section{htxtoppage.ht}
-\subsection{Extending Hyperdoc}
-\label{HTXTopPage}
-\begin{itemize}
-\item HTXIntroTopPage \ref{HTXIntroTopPage} on page~\pageref{HTXIntroTopPage}
-\item HTXFormatTopPage \ref{HTXFormatTopPage} on 
-page~\pageref{HTXFormatTopPage}
-\item HTXLinkTopPage \ref{HTXLinkTopPage} on page~\pageref{HTXLinkTopPage}
-\item HTXAdvTopPage \ref{HTXAdvTopPage} on page~\pageref{HTXAdvTopPage}
-\item HTXTryPage \ref{HTXTryTopPage} on page~\pageref{HTXTryPage}
-\end{itemize}
-\index{pages!HTXTopPage!htxtoppage.ht}
-\index{htxtoppage.ht!pages!HTXTopPage}
-\index{HTXTopPage!htxtoppage.ht!pages}
-<<htxtoppage.ht>>=
-\begin{page}{HTXTopPage}{Extending Hyperdoc}
-\centerline{\fbox{{\tt \thispage}}}\newline
-This is a guide to extending \HyperName{}. You can learn
-how to write your own \HyperName{} pages and link them to the
-\HyperName{} page database that Axiom uses.
-\begin{scroll}
-\beginmenu
-\menumemolink{Introduction}{HTXIntroTopPage} \tab{20} An easy start.
-\menumemolink{Formatting}{HTXFormatTopPage} \tab{20} Learn how to format text.
-\menumemolink{Actions}{HTXLinkTopPage} \tab{20} Learn how to define actions.
-\menumemolink{Advanced features}{HTXAdvTopPage} \tab{20} More effects.
-\menuwindowlink{Try it!}{HTXTryPage} \tab{20} Try out what you learn.
-\endmenu
-\end{scroll}
-\end{page}
-
-@
-\section{htxtrypage.ht}
-\subsection{Try out Hyperdoc}
-\label{HTXTryPage}
-\index{pages!HTXTryPage!htxtrypage.ht}
-\index{htxtrypage.ht!pages!HTXTryPage}
-\index{HTXTryPage!htxtrypage.ht!pages}
-<<htxtrypage.ht>>=
-\begin{page}{HTXTryPage}{Try out Hyperdoc}
-\centerline{\fbox{{\tt \thispage}}}\newline
-
-This page allows you to quickly experiment with \HyperName{}.
-It is a good idea to keep it handy as you learn about various commands.
-
-\beginscroll
-
-We are going to use here the \HyperName{} facilities that allow
-us to communicate with external programs and files. For more
-information see \downlink{later on}{HTXLinkPage5}.
-\beginmenu
-\item\menuitemstyle{
-In order to use the buttons at the bottom of this page, you must
-first specify a name for the file you are going to use to hold
-\HyperName{} commands. Edit the input area below to change the
-name of the file.}
-\item\menuitemstyle{
-If the file you specified does not yet exist, click on the
-{\bf Initialize} button below. This action will fill the file
-with the minimum of \HyperName{} commands necessary to define a page.}
-\item\menuitemstyle{
-If you want to edit the file, just click on the {\bf Edit} button.
-This action will pop up a window, and invoke the {\it vi}
-editor on the file. Alternatively, use an editor of your choice.}
-\item\menuitemstyle{
-Once you have finished making the changes to the file, update it and
-click on the {\bf Link} button. \HyperName{} will then read
-the file, interpret it as a new page, and display the page on
-this window. If you change the file and want to display it again,
-just get back to this page and click on {\bf Link} again. }
-\endmenu
-\endscroll
-\beginmenu
-{\it Filename: }{\inputstring{filename}{40}{\env{HOME}/HTXplay.ht}}
-\menuunixcommand{Initialize}{cp\space{1}\env{AXIOM}/doc/hypertex/pages/HTXplay.ht \stringvalue{filename}} \tab{20} Get a fresh copy from the system.
-\menuunixcommand{Edit}{xterm -T "\stringvalue{filename}" -e vi \stringvalue{filename}} \tab{20} Edit the file.
-\menuunixwindow{Link}{cat \space{1}\stringvalue{filename}} \tab{20} Link to the page defined in the file.
-\endmenu
-{\it Important : The file must contain
-one and only one page definition and must not contain any macro or patch
-definitions.}
-\end{page}
-
-@
-\section{hyperdoc.ht}
-\subsection{Creating Hyperdoc Pages}
-\label{Hyperdoc}
-\begin{itemize}
-\item ViewportPage \ref{ViewportPage} on
-page~\pageref{ViewportPage}
-\item BitMaps \ref{BitMaps} on
-page~\pageref{BitMaps}
-\item CPHelp \ref{CPHelp} on
-page~\pageref{CPHelp}
-\end{itemize}
-\index{pages!Hyperdoc!hyperdoc.ht}
-\index{hyperdoc.ht!pages!Hyperdoc}
-\index{Hyperdoc!hyperdoc.ht!pages}
-<<hyperdoc.ht>>=
-\begin{page}{Hyperdoc}{Creating Hyperdoc Pages}
-
-\beginscroll
-This document tells how to create \HyperName pages.
-To start with, it is rather meager but it will grow with time.
-\beginmenu
-\menulink{Viewports}{ViewportPage} Including live graphics in documents.
-\menulink{Gadjets}{BitMaps} Bitmaps for use in macros.
-\menulink{Control Panel Bits}{CPHelp} Development page for help 
-facility for viewports. yuck.
-%\menulink{Test Pages}{TestPage} Some test pages left by J.M.
-%\menulink{Paste Pages}{PastePage} Examples of how to use paste in areas.
-\endmenu
-
-\endscroll
-\autobuttons
-\end{page}
-
-@
 \section{int.ht}
 <<int.ht>>=
 \newcommand{\IntegerXmpTitle}{Integer}
@@ -17820,25 +11886,25 @@ facility for viewports. yuck.
 \subsection{Integer}
 \label{IntegerXmpPage}
 \begin{itemize}
-\item ugIntroNumbersPage \ref{ugIntroNumbersPage} on
-page~pageref{ugIntroNumbersPage}
-\item IntegerNumberTheoryFunctionsXmpPage 
+\item ugIntroNumbersPage\\ 
+\ref{ugIntroNumbersPage} on page~pageref{ugIntroNumbersPage}
+\item IntegerNumberTheoryFunctionsXmpPage \\
 \ref{IntegerNumberTheoryFunctionsXmpPage} on
 page~pageref{IntegerNumberTheoryFunctionsXmpPage}
-\item DecimalExpansionXmpPage \ref{DecimalExpansionXmpPage} on
-page~pageref{DecimalExpansionXmpPage}
-\item BinaryExpansionXmpPage \ref{BinaryExpansionXmpPage} on
-page~pageref{BinaryExpansionXmpPage}
-\item HexadecimalExpansionXmpPage \ref{HexadecimalExpansionXmpPage} on
-page~pageref{HexadecimalExpansionXmpPage}
-\item RadixExpansionXmpPage \ref{RadixExpansionXmpPage} on
-page~pageref{RadixExpansionXmpPage}
-\item ugxIntegerBasicPage \ref{ugxIntegerBasicPage} on
-page~pageref{ugxIntegerBasicPage}
-\item ugxIntegerPrimesPage \ref{ugxIntegerPrimesPage} on
-page~pageref{ugxIntegerPrimesPage}
-\item ugxIntegerNtPage \ref{ugxIntegerNtPage} on
-page~pageref{ugxIntegerNtPage}
+\item DecimalExpansionXmpPage \\
+\ref{DecimalExpansionXmpPage} on page~pageref{DecimalExpansionXmpPage}
+\item BinaryExpansionXmpPage \\
+\ref{BinaryExpansionXmpPage} on page~pageref{BinaryExpansionXmpPage}
+\item HexadecimalExpansionXmpPage \\
+\ref{HexadecimalExpansionXmpPage} on page~pageref{HexadecimalExpansionXmpPage}
+\item RadixExpansionXmpPage\\ 
+\ref{RadixExpansionXmpPage} on page~pageref{RadixExpansionXmpPage}
+\item ugxIntegerBasicPage \\
+\ref{ugxIntegerBasicPage} on page~pageref{ugxIntegerBasicPage}
+\item ugxIntegerPrimesPage \\
+\ref{ugxIntegerPrimesPage} on page~pageref{ugxIntegerPrimesPage}
+\item ugxIntegerNTPage \\
+\ref{ugxIntegerNTPage} on page~pageref{ugxIntegerNTPage}
 \end{itemize}
 \index{pages!IntegerXmpPage!int.ht}
 \index{int.ht!pages!IntegerXmpPage}
@@ -19522,7 +13588,7 @@ page~\pageref{FoundationLibraryDocPage}
 
 @
 \subsection{Use of the Link from HyperDoc}
-\label{htx11}
+\label{htxl1}
 \begin{itemize}
 \item c02 \ref{c02} on
 page~\pageref{c02}
@@ -19553,9 +13619,9 @@ page~\pageref{f07}
 \item s \ref{s} on
 page~\pageref{s}
 \end{itemize}
-\index{pages!htx11!link.ht}
-\index{link.ht!pages!htx11}
-\index{htx11!link.ht!pages}
+\index{pages!htxl1!link.ht}
+\index{link.ht!pages!htxl1}
+\index{htxl1!link.ht!pages}
 <<link.ht>>=
 \begin{page}{htxl1}{Use of the Link from HyperDoc}
 Click on the chapter of routines that you would like to use.
@@ -19839,8 +13905,7 @@ technique
 \subsection{E01 Interpolation}
 \label{e01}
 \begin{itemize}
-\item manpageXXe01 \ref{manpageXXe01} on
-page~\pageref{manpageXXe01}
+\item manpageXXe01 \ref{manpageXXe01} on page~\pageref{manpageXXe01}
 \end{itemize}
 \index{pages!e01!link.ht}
 \index{link.ht!pages!e01}
@@ -21678,6 +15743,8 @@ Enter search string :
 \includegraphics[scale=.5]{ps/v71man0page.eps}
 \index{images!man0page}
 
+Called from ``Root Page'' (RootPage) \ref{RootPage} on page~\pageref{RootPage}
+
 See ``Commands'' (ugSysCmdPage) 
 \ref{ugSysCmdPage} on page~\pageref{ugSysCmdPage}
 \index{pages!Man0Page!man0.ht}
@@ -21693,7 +15760,10 @@ Enter search string (use {\em *} for wild card unless counter-indicated):
 \beginmenu
 \menulispmemolink{Constructors}
   { (|kSearch| '|\stringvalue{pattern}|) }
-  \tab{15} Search for \lispmemolink{categories}{(|cSearch| '|\stringvalue{pattern}|)}, \lispmemolink{domains}{(|dSearch| '|\stringvalue{pattern}|)}, or \lispmemolink{packages}{(|pSearch| '|\stringvalue{pattern}|)}
+  \tab{15} Search for 
+\lispmemolink{categories}{(|cSearch| '|\stringvalue{pattern}|)}, 
+\lispmemolink{domains}{(|dSearch| '|\stringvalue{pattern}|)}, or 
+\lispmemolink{packages}{(|pSearch| '|\stringvalue{pattern}|)}
 \menulispmemolink{Operations}
   { (|oSearch| '|\stringvalue{pattern}|) }
   \tab{15} Search for operations.
@@ -22652,6 +16722,43641 @@ For more information on related topics, see
 \end{page}
 
 @
+\section{newuser.ht}
+\subsection{No More Help :-(}
+\label{NoMoreHelpPage}
+\index{pages!NoMoreHelpPage!newuser.ht}
+\index{newuser.ht!pages!NoMoreHelpPage}
+\index{NoMoreHelpPage!newuser.ht!pages}
+<<newuser.ht>>=
+\begin{page}{NoMoreHelpPage}{No More Help :-(}
+\beginscroll\vspace{2}
+\centerline{No additional or specific help information is available.}
+\centerline{Click on \ \ExitButton{QuitPage} \  to get back.}
+\endscroll
+\end{page}
+
+@
+\subsection{You Tried It!}
+\label{YouTriedIt}
+\index{pages!YouTriedIt!newuser.ht}
+\index{newuser.ht!pages!YouTriedIt}
+\index{YouTriedIt!newuser.ht!pages}
+<<newuser.ht>>=
+\begin{page}{YouTriedIt}{You Tried It!}
+\beginscroll
+\upbutton{Click here}{UpPage} to get back.
+\endscroll
+\end{page}
+
+% Getting Started
+
+%% % Now using text from book
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{GettingStarted}{Getting Started}
+%%  % --------------------------------------------------------------------
+%%  \beginscroll
+%%  \par
+%%  \HyperName{} is the gateway to Axiom.
+%%  It's both an on-line tutorial and an on-line reference.  It also enables you
+%%  to use Axiom simply by using the mouse and filling in templates.
+%%  \HyperName{} is available to you if you are running Axiom under the
+%%  X Window System.
+%%  \par
+%%  Pages usually have active areas, marked in \downlink{this
+%%  font.}{YouTriedIt}
+%%  As you move the mouse pointer to an active area, the pointer changes from a
+%%  filled dot to an open circle.
+%%  The active areas are usually linked to other pages.
+%%  When you click on an active area, you move to the linked page.
+%%  Try clicking \downlink{here}{YouTriedIt} now.
+%%  \par
+%%  Now we suggest that you learn more about other features of
+%%  \HyperName{} by clicking on an active area in the menu below:
+%%  %
+%%  \beginmenu
+%%  \menumemolink{Headings}{ugHyperHeadingsPage}\tab{15}How to use the headings at the top of the page
+%%  \menulink{Scroll Bars}{ugHyperScrollPage}\tab{15}All about {\it scroll bars} on \HyperName{} pages
+%%  \menulink{Input Areas}{ugHyperInputPage}\tab{15}All about {\it input areas} in \HyperName{}
+%%  \menulink{Buttons}{ugHyperButtonsPage}\tab{15}Learn about {\it radio buttons} and {\it toggles}
+%%  \menulink{Search Strings}{SearchStrings}\tab{15}Learn about {\it search strings} in \HyperName{}
+%%  \menulink{Example Pages}{ugHyperExamplePage}\tab{15}How to view or run {\it examples} on \HyperName{} pages
+%%  \menulink{Settings}{ugHyperResourcesPage}\tab{15}X Window Resources for \HyperName{}
+%%  \endmenu
+%%  \endscroll
+%%  \end{page}
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{ExamplesIntro}{Axiom Examples}
+%%  % --------------------------------------------------------------------
+%%  \pp
+%%  \beginscroll
+%%  Many pages have Axiom examples.
+%%  Here are two:
+%%  \spadpaste{a:= x**2 + 1 \bound{a}} \newline
+%%  \spadpaste{(a - 2)**2 \free{a}} \newline
+%%  Each example has an active ``button'' along the left margin.
+%%  When you click on this button the output for the
+%%  command is ``pasted-in.''
+%%  Try it!
+%%  Click again on the button and you'll see
+%%  that the pasted-in output disappears. Got the idea?
+%%  \par
+%%  Maybe you would like to run an example?
+%%  To do so, just click on any part of it!
+%%  When you do, the example line is copied into a new interactive Axiom
+%%  buffer for this \HyperName{} page.
+%%  \par
+%%  Sometimes one example line cannot be run before you run an earlier one.
+%%  Don't worry---this is all automatic!
+%%  For instance, the second example line above refers to \spad{a} which is
+%%  assigned in the first example line.
+%%  What happens if you first click on the second example line?
+%%  Axiom first issues the first line (to assign \spad{a}), then the
+%%  second (to do the computation using \spad{a}).
+%%  \par
+%%  The new interactive Axiom buffer will disappear when you leave
+%%  \HyperName{}.
+%%  If you want to get rid of it beforehand,
+%%  use the ``Cancel'' button of the X window manager.
+%%  \endscroll
+%%  %\autobutt{HelpHelp}
+%%  \end{page}
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{RadioButtons}{Radio Buttons and Toggles}
+%%  % --------------------------------------------------------------------
+%%  \beginscroll
+%%  \radioboxes{sample}{\htbmfile{pick}}{\htbmfile{unpick}}
+%%  \par
+%%  Radio buttons are a group of round buttons like those on car radios: you can
+%%  select only one.
+%%  Here are three radio buttons:
+%%  \centerline{
+%%  {\em\radiobox[1]{rone}{sample}\space{}The first one}\space{3}
+%%  {\em\radiobox[0]{rtwo}{sample}\space{}The second one}\space{3}
+%%  {\em\radiobox[0]{rthree}{sample}\space{}The third one}
+%%  }
+%%  \newline
+%%  The selected button has an {\it X} in the box.
+%%  The others which are not selected are open, i.e. they have no {\it X}.
+%%  To change the selection, move the cursor with the mouse to an
+%%  alternate radio button and click. Try it now.
+%%  %\vspace{1}\centerline{To see another kind of button click on:}
+%%  %\centerline{\box{\downlink{Next Page}{ToggleButton}}}
+%%  %\endscroll
+%%  %\autobuttons\end{page}
+%%  %\begin{page}{ToggleButton}{Toggles}
+%%  %\beginscroll
+%%  \vspace{1}
+%%  \par
+%%  A toggle is a square button you can either select (it has an {\it X}) or
+%%  not (it has no {\it X}).
+%%  Unlike radio buttons, you can set a group of them any way you like.
+%%  Here are three:
+%%  \centerline{
+%%  {\em\inputbox[1]{one}{\htbmfile{pick}}{\htbmfile{unpick}}\space{}The first one}
+%%  \space{3}
+%%  {\em\inputbox[0]{two}{\htbmfile{pick}}{\htbmfile{unpick}}\space{}The second one}
+%%  \space{3}
+%%  {\em\inputbox[1]{three}{\htbmfile{pick}}{\htbmfile{unpick}}\space{}The third one}
+%%  }
+%%  \newline
+%%  To change the selections, move the cursor with the mouse
+%%  to a toggle and click.
+%%  \endscroll
+%%  \autobuttons\end{page}
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{InputAreas}{Input Areas}
+%%  % --------------------------------------------------------------------
+%%  \beginscroll
+%%  \par Input areas are boxes that you can fill in.
+%%  Here is one:
+%%  \centerline{\inputstring{one}{40}{some text}}
+%%  \newline As you can see, the input area has some initial text {\it some text}
+%%  followed by an underscore (the character {\it _}).
+%%  First, make sure that the mouse cursor is
+%%  on this page. Now type some
+%%  characters at the keyboard.
+%%  The characters that you type are now inserted in front of the underscore.
+%%  You may type as many characters as you like.
+%%  The input area will grow to accomodate as many characters as you type.
+%%  Use the {\it Backspace} key to erase
+%%  characters to the left.
+%%  Use the keys {\it Insert}, {\it Delete}, {\it Home} and {\it End}
+%%  to modify what you type.
+%%  Also try right- and left-arrow keys immediately to the right of the
+%%  standard keyboard.
+%%  \vspace{1}\newline\centerline{\box{\downlink{Next Page}{MultipleugHyperInputPage}}}
+%%  \endscroll
+%%  \end{page}
+
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{MultipleInputAreas}{Multiple Input Areas}
+%%  % --------------------------------------------------------------------
+%%  \beginscroll
+%%  Here is a large input area like the one on the last page:
+%%  \centerline{\inputstring{one}{40}{one}}
+%%  \newline
+%%  and here are two smaller ones:
+%%  \centerline{\inputstring{two}{15}{two}\space{8}\inputstring{three}{7}{three}}
+%%  Move your mouse cursor to somewhere within this page.
+%%  Note that only the first input area has an underscore cursor.
+%%  This means that when you type characters at your keyboard, they
+%%  will go into this first input area. Try it!
+%%  \par
+%%  To type information into another input area,
+%%  use the {\it Enter} or {\it Tab} key to move from one input area to another.
+%%  To move in the reverse order, use {\it Shift + Tab}.
+%%  \par
+%%  You can also move from one input area to another using your mouse.
+%%  Notice that each input area is active. Click on one of the areas.
+%%  As you can see, the underscore cursor now moves to that window.
+%%  \endscroll
+%%  \end{page}
+
+%%  % Now using text from the book
+%%
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{ScrollBars}{Using Scroll Bars}
+%%  % --------------------------------------------------------------------
+%%  When all of the text does not fit within a window, part of the window
+%%  is like a ``looking glass'' you can
+%%  move up and down over the length of the text.
+%%  The text seen by the looking glass has a {\it scroll bar}
+%%  down its right side.
+%%  The {\it scroll bar} allows you to move this looking glass.
+%%  It also tells you the position of the looking glass
+%%  relative to the whole text.
+%%  \beginscroll
+%%  \par
+%%  The part of this \HyperName{} window beginning with this line has a
+%%  {\it scroll bar} along its right side.
+%%  Move the cursor with the mouse to the scroll bar.
+%%  Now move the cursor to the `down-arrow' at the
+%%  bottom of the scroll bar and click. See that the looking glass moves
+%%  down one line. Do it again and again. Each time you click, the
+%%  looking glass moves down one line.
+%%  \par
+%%  Now move the mouse to the 'up-arrow' at the top of the scroll
+%%  bar and click. The looking glass moves up one line each time you click.
+%%  \par
+%%  Next move the mouse to any position along the middle of the
+%%  scroll bar and click.
+%%  This will attempt to move the top of the looking glass to the point where you
+%%  click.
+%%  However, you cannot make the looking glass to go off the bottom edge.
+%%  For this example page, the looking glass region is approximately
+%%  half of the whole region. So the lowest point you can
+%%  set top of the looking glass is halfway down.
+%%  Get the idea?
+%%  \par
+%%  Want to use the keyboard instead of the mouse?
+%%  Then use the {\it Page Up} and {\it Page Down} keys on your
+%%  keyboard. They move the visible part of the region up and down
+%%  one page each time you type them. Try them!
+%%  \par
+%%  If a page does not have an input area, you can also use the {\it Home}
+%%  and up and down arrow keys to move the visible part of the region.
+%%  The {\it Home} key moves the region to the very top of the page.
+%%  The up and down arrow keys move the region up and down one line,
+%%  respectively.
+%%  (If a page does have an input area, these three keys operate on the
+%%  input area.)
+%%  \endscroll
+%%  \autobuttons\end{page}
+
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{StartingButtonHelp}{Know These Buttons}
+%%  % --------------------------------------------------------------------
+%%  \beginscroll
+%%  Most pages have a standard set of buttons at the top of the page.
+%%  \newline
+%%  This is what they mean:
+%%  \par \ExitBitmap   \space{} {\it Exit} from \HyperName{}
+%%  \par \HelpBitmap   \space{} Get {\it Help}
+%%  \par \ReturnBitmap \space{} {\it Jump back} to main page
+%%  \par \UpBitmap     \space{} {\it Go back} one page
+%%  \newline
+%%  \pp
+%%  The {\it Help} button shows you pages that can give you additional
+%%  information.  You can always
+%%  click on {\it Help} while you're
+%%  exploring.
+%%  You can always make forays into new topics.
+%%  \HyperName{} remembers where you came from.
+%%  Don't worry about how to get back. Just click on either the ``up arrow''
+%%  or the ``HOME'' button. Now click on the ``up arrow'' to go back one page.
+%%  \endscroll
+%%  \autobutt{DummyHelp}\end{page}
+
+%%  % --------------------------------------------------------------------
+%%  \begin{page}{StartingMenuHelp}{Menus}
+%%  % --------------------------------------------------------------------
+%%  \pp
+%%  \beginscroll
+%%  A `menu' is a list of topics. Each topic has at least one active area.
+%%  Clicking on the active area marked {\it Menus} is how you got here.
+%%  \horizontalline
+%%  Here is another menu to practice on:
+%%  \newline
+%%  \beginmenu
+%%  %\menulink{Riddle}{RiddlePage}
+%%  %    A classic riddle.
+%%  %\menulink{\HyperName{}}{WhatIsHyperName}
+%%  %    What is \HyperName{}
+%%  \menulink{Buttons}{ButtonHelp}
+%%      Buttons in \HyperName{}.
+%%  \endmenu
+%%  \endscroll
+%%  \autobuttons\end{page}
+
+
+@
+\section{none.ht}
+<<none.ht>>=
+\newcommand{\NoneXmpTitle}{None}
+\newcommand{\NoneXmpNumber}{9.55}
+
+@
+\subsection{None}
+\label{NoneXmpPage}
+\index{pages!NoneXmpPage!none.ht}
+\index{none.ht!pages!NoneXmpPage}
+\index{NoneXmpPage!none.ht!pages}
+<<none.ht>>=
+\begin{page}{NoneXmpPage}{None}
+\beginscroll
+The \spadtype{None} domain is not very useful for interactive
+work but it is provided nevertheless for completeness of the
+Axiom type system.
+\xtc{
+Probably the only place you will ever see it is if you enter an
+empty list with no type information.
+}{
+\spadpaste{[]}
+}
+\xtc{
+Such an empty list can be converted into an empty list
+of any other type.
+}{
+\spadpaste{[] :: List Float}
+}
+\xtc{
+If you wish to produce an empty list of a particular
+type directly, such as \spadtype{List NonNegativeInteger}, do it this way.
+}{
+\spadpaste{[]\$List(NonNegativeInteger)}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{numbers.ht}
+\subsection{Axiom Number Types}
+\label{NumberPage}
+\includegraphics[scale=.5]{ps/v71numberpage.eps}
+\index{images!numberpage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
+\begin{itemize}
+\item ``Integers'' (IntegerPage) \ref{IntegerPage} on 
+page~\pageref{IntegerPage}
+\item ``Fractions'' (FractionPage) \ref{FractionPage} on 
+page~\pageref{FractionPage}
+\item ``Machine Floats'' (DoubleFloatXmpPage) \ref{DoubleFloatXmpPage} on 
+page~\pageref{DoubleFloatXmpPage}
+\item ``Real Numbers'' (FloatXmpPage) \ref{FloatXmpPage} on 
+page~\pageref{FloatXmpPage}
+\item ``Complex Numbers'' (ComplexXmpPage) \ref{ComplexXmpPage} on 
+page~\pageref{ComplexXmpPage}
+\item ``Finite Fields'' (ugProblemFinitePage) \ref{ugProblemFinitePage} on 
+page~\pageref{ugProblemFinitePage}
+\item ``Numeric Functions'' (ugProblemNumericPage) 
+\ref{ugProblemNumericPage} on 
+page~\pageref{ugProblemNumericPage}
+\item ``Cardinal Numbers'' (CardinalNumberXmpPage) 
+\ref{CardinalNumberXmpPage} on 
+page~\pageref{CardinalNumberXmpPage}
+\item ``Machine-sized Integers'' (SingleIntegerXmpPage) 
+\ref{SingleIntegerXmpPage} on 
+page~\pageref{SingleIntegerXmpPage}
+\item ``Roman Numerals'' (RomanNumeralXmpPage) \ref{RomanNumeralXmpPage} on 
+page~\pageref{RomanNumeralXmpPage}
+\item ``Continued Fractions'' (ContinuedFractionXmpPage) 
+\ref{ContinuedFractionXmpPage} on 
+page~\pageref{ContinuedFractionXmpPage}
+\item ``Partial Fractions'' (PartialFractionXmpPage) 
+\ref{PartialFractionXmpPage} on 
+page~\pageref{PartialFractionXmpPage}
+\item ``Quaternions'' (QuaternionXmpPage) \ref{QuaternionXmpPage} on 
+page~\pageref{QuaternionXmpPage}
+\item ``Octonions'' (OctonionXmpPage) \ref{OctonionXmpPage} on 
+page~\pageref{OctonionXmpPage}
+\item ``Repeating Decimals'' (DecimalExpansionXmpPage) 
+\ref{DecimalExpansionXmpPage} on 
+page~\pageref{DecimalExpansionXmpPage}
+\item ``Repeating Binary Expansions'' (BinaryExpansionXmpPage) 
+\ref{BinaryExpansionXmpPage} on 
+page~\pageref{BinaryExpansionXmpPage}
+\item ``Repeating Hexadecimal Expansions'' (HexadecimalExpansionXmpPage) 
+\ref{HexadecimalExpansionXmpPage} on 
+page~\pageref{HexadecimalExpansionXmpPage}
+\item ``Expansions in other Bases '' (RadixExpansionXmpPage) 
+\ref{RadixExpansionXmpPage} on page~\pageref{RadixExpansionXmpPage}
+\end{itemize}
+\index{pages!NumberPage!numbers.ht}
+\index{numbers.ht!pages!NumberPage}
+\index{NumberPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{NumberPage}{Axiom Number Types}
+\beginscroll
+The following types of numbers are among those available in Axiom.
+\beginmenu
+
+\menulink{Integers}{IntegerPage}\tab{16}
+Arithmetic with arbitrarily large integers.
+
+\menulink{Fractions}{FractionPage} \tab{16}
+Rational numbers and general fractions.
+
+\menulink{Machine Floats}{DoubleFloatXmpPage} \tab{16}
+Fixed precision machine floating-point.
+
+\menulink{Real Numbers}{FloatXmpPage} \tab{16}
+Arbitrary precision decimal arithmetic.
+
+\menulink{Complex Numbers}{ComplexXmpPage} \tab{16}
+Complex numbers in general.
+
+\menulink{Finite Fields}{ugProblemFinitePage} \tab{16}
+Arithmetic in characteristic \spad{p}.
+\endmenu
+\horizontalline\newline
+Additional Topics
+\beginmenu
+
+\menulink{Numeric Functions}{ugProblemNumericPage}
+\menulink{Cardinal Numbers}{CardinalNumberXmpPage}
+\menulink{Machine-sized Integers}{SingleIntegerXmpPage}
+\menulink{Roman Numerals}{RomanNumeralXmpPage}
+\menulink{Continued Fractions}{ContinuedFractionXmpPage}
+\menulink{Partial Fractions}{PartialFractionXmpPage}
+\menulink{Quaternions}{QuaternionXmpPage}
+\menulink{Octonions}{OctonionXmpPage}
+\menulink{Repeating Decimals}{DecimalExpansionXmpPage}
+\menulink{Repeating Binary Expansions}{BinaryExpansionXmpPage}
+\menulink{Repeating Hexadecimal Expansions}{HexadecimalExpansionXmpPage}
+\menulink{Expansions in other Bases}{RadixExpansionXmpPage}
+
+\endmenu
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Fraction}
+\label{FractionPage}
+\begin{itemize}
+\item RationalNumberPage \ref{RationalNumberPage} on
+page~pageref{RationalNumberPage}
+\item FractionXmpPage \ref{FractionXmpPage} on
+page~pageref{FractionXmpPage}
+\end{itemize}
+\index{pages!FractionPage!numbers.ht}
+\index{numbers.ht!pages!FractionPage}
+\index{FractionPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{FractionPage}{Fractions}
+
+\beginscroll
+Axiom handles fractions in many different contexts
+and will automatically simplify fractions whenever possible.
+Here are some examples:
+\spadpaste{1/4 - 1/5}
+\spadpaste{f := (x**2 + 1)/(x - 1) \bound{f}}
+\spadpaste{g := (x**2 - 3*x + 2)/(x + 2) \bound{g}}
+\spadpaste{f * g \free{f g}}
+\endscroll
+Additional Topics:
+\beginmenu
+
+\menulink{Rational Numbers}{RationalNumberPage} \tab{18}
+Quotients of integers
+
+\menulink{Quotient Fields}{FractionXmpPage}  \tab{18}
+Quotients over an arbitrary integral domain
+
+%\menulink{Localizations}{LocalizationPage}  \tab{18}
+%Fractions in the most general setting
+\endmenu
+\autobuttons
+\end{page}
+
+@
+\subsection{Rational Number}
+\label{RationalNumberPage}
+\index{pages!RationalNumberPage!numbers.ht}
+\index{numbers.ht!pages!RationalNumberPage}
+\index{RationalNumberPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{RationalNumberPage}{Rational Numbers}
+\beginscroll
+Like integers, rational numbers can be arbitrarily large.
+For example:
+\spadpaste{61657 ** 10 / 999983 ** 12}
+Rational numbers will not be converted to decimals unless you explicitly
+ask Axiom to do so.
+To convert a rational number to a decimal, use the function
+\spadfun{numeric}.
+Here's an example:
+\spadpaste{x := 104348/33215 \bound{x}}
+\spadpaste{numeric x \free{x}}
+You can find the numerator and denominator of rational numbers using
+the functions \spadfun{numer} and \spadfun{denom}, respectively.
+\spadpaste{numer(x) \free{x}}
+\spadpaste{denom(x) \free{x}}
+To factor the numerator and denominator of a fraction, use the following
+command:
+\spadpaste{factor(numer x) / factor(denom x) \free{x}}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Integers}
+\label{IntegerPage}
+\begin{itemize}
+\item IntegerXmpPage \ref{IntegerXmpPage} on
+page~pageref{IntegerXmpPage}
+\item ugxIntegerPrimesPage \ref{ugxIntegerPrimesPage} on
+page~pageref{ugxIntegerPrimesPage}
+\item IntegerNumberTheoryFunctionsXmpPage 
+\ref{IntegerNumberTheoryFunctionsXmpPage} on
+page~pageref{IntegerNumberTheoryFunctionsXmpPage}
+\item IntegerExamplePage \ref{IntegerExamplePage} on
+page~pageref{IntegerExamplePage}
+\item IntegerProblemPage \ref{IntegerProblemPage} on
+page~pageref{IntegerProblemPage}
+\end{itemize}
+\index{pages!IntegerPage!numbers.ht}
+\index{numbers.ht!pages!IntegerPage}
+\index{IntegerPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerPage}{Integers}
+\beginscroll
+In Axiom, integers can be as large as you like.
+Try the following examples:
+\spadpaste{x := factorial(200) \bound{x}}
+\spadpaste{y := 2**90 - 1 \bound{y}}
+Of course, you can now do arithmetic as usual on these (very)
+large integers:
+\spadpaste{x + y \free{x y}}
+\spadpaste{x - y \free{x y}}
+\spadpaste{x * y \free{x y}}
+Axiom can factor integers, but numbers with small prime factors
+\spadpaste{factor(x) \free{x}}
+will factor more rapidly than numbers with large prime factors.
+\spadpaste{factor(y) \free{y}}
+\horizontalline
+Additional Topics
+\beginmenu
+
+\menulink{General Info}{IntegerXmpPage} \tab{16}
+General information and examples of integers.
+
+\menulink{Factorization}{ugxIntegerPrimesPage} \tab{16}
+Primes and factorization.
+
+\menulink{Functions}{IntegerNumberTheoryFunctionsXmpPage} \tab{16}
+Number theoretic functions.
+
+\menulink{Examples}{IntegerExamplePage} \tab{16}
+Examples from number theory.
+
+\menulink{Problems}{IntegerProblemPage} \tab{16}
+Problems from number theory.
+
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Integer Examples}
+\label{IntegerExamplePage}
+\begin{itemize}
+\item IntegerExampleProofPage \ref{IntegerExampleProofPage} on
+page~pageref{IntegerExampleProofPage}
+\end{itemize}
+\index{pages!IntegerExamplePage!numbers.ht}
+\index{numbers.ht!pages!IntegerExamplePage}
+\index{IntegerExamplePage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerExamplePage}{Integer Examples}
+\beginscroll
+One can show that if an integer of the form 2**k + 1 is prime, then
+k must be a power of 2.
+\downlink{Proof}{IntegerExampleProofPage}
+\par
+Pierre Fermat conjectured that every integer of the forn 2**(2**n) + 1
+is prime.
+Let's look for a counterexample.
+First define a function:
+\spadpaste{f: NNI -> INT \bound{f1}}
+\spadpaste{f(n) == 2**(2**n) + 1 \bound{f} \free{f1}}
+Now try commands like:
+\spadpaste{factor f(1) \free{f}}
+\spadpaste{factor f(2) \free{f}}
+until you find an integer of this form which is composite.
+You can also try the following command:
+\spadpaste{for n in 1..6 repeat output factor f(n) \free{f}}
+Obviously, Fermat didn't have access to Axiom!
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Integer Example Proof}
+\label{IntegerExampleProofPage}
+\index{pages!IntegerExampleProofPage!numbers.ht}
+\index{numbers.ht!pages!IntegerExampleProofPage}
+\index{IntegerExampleProofPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerExampleProofPage}{Integer Example Proof}
+\beginscroll
+Proposition.  If 2**k + 1 is prime, then k is a power of 2.
+\newline
+Proof.  Suppose that k = m * n with m > 1 odd.  Then
+%
+\centerline{2**n = -1 (mod (2**n + 1))}
+\centerline{2**(n * m) = (-1)**m = -1 (mod (2**n + 1))}
+\centerline{2**k + 1 = 0 (mod (2**n + 1))}
+%
+Therefore, 2**k + 1 is divisible by 2**n + 1.
+Now 1 < 2**n + 1 and since m > 1, 2**n + 1 < 2**k + 1.
+Hence, 2**k + 1 has a non-trivial factor.
+\newline
+QED
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Integer Problems}
+\label{IntegerProblemPage}
+\begin{itemize}
+\item IntegerProblemProofPage \ref{IntegerProblemProofPage} on
+page~pageref{IntegerProblemProofPage}
+\item IntegerProblemAnswerPage1 \ref{IntegerProblemAnswerPage1} on
+page~pageref{IntegerProblemAnswerPage1}
+\item IntegerProblemAnswerPage2 \ref{IntegerProblemAnswerPage2} on
+page~pageref{IntegerProblemAnswerPage2}
+\end{itemize}
+\index{pages!IntegerProblemPage!numbers.ht}
+\index{numbers.ht!pages!IntegerProblemPage}
+\index{IntegerProblemPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerProblemPage}{Integer Problems}
+\beginscroll
+One can show that if an integer of the form 2**k - 1 is prime, then
+k must be prime.
+\downlink{Proof}{IntegerProblemProofPage}
+\newline
+Problem \#1:  Find the smallest prime p such that \spad{2**p - 1} is not prime.
+\downlink{Answer}{IntegerProblemAnswerPage1}
+\newline
+Problem \#2:  Find the smallest positive integer \spad{n} such that
+\spad{n**2 - n + 41} isn't prime.
+\downlink{Answer}{IntegerProblemAnswerPage2}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Integer Problem Proof}
+\label{IntegerProblemProofPage}
+\index{pages!IntegerProblemProofPage!numbers.ht}
+\index{numbers.ht!pages!IntegerProblemProofPage}
+\index{IntegerProblemProofPage!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerProblemProofPage}{Integer Problem Proof}
+\beginscroll
+Proposition.  If \spad{2**k - 1} is prime, then \spad{k} is prime.
+\newline
+Proof.  Suppose that k = m * n is a non-trivial factorization.
+Then
+%
+\centerline{2**m = 1 (mod (2**m - 1))}
+\centerline{2**(m * n) = 1 (mod (2**m - 1))}
+\newline
+and 2**m - 1 is a non-trivial factor of 2**k - 1.
+\newline
+QED
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Solution to Problem \#1}
+\label{IntegerProblemAnswerPage1}
+\index{pages!IntegerProblemAnswerPage1!numbers.ht}
+\index{numbers.ht!pages!IntegerProblemAnswerPage1}
+\index{IntegerProblemAnswerPage1!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerProblemAnswerPage1}{Solution to Problem \#1}
+\beginscroll
+Problem \#1:  Find the smallest prime p such that \spad{2**p - 1}
+is not prime.
+\newline
+First, define a function:
+\spadpaste{f: NNI -> INT \bound{f1}}
+\spadpaste{f(n) == 2**n - 1 \bound{f} \free{f1}}
+You can try factoring f(p) as p ranges through the set of primes.
+For example,
+\spadpaste{factor f(7) \free{f}}
+This gets tedious after a while, so let's use Axiom's stream
+facility.  (A stream is essentially an infinite sequence.)
+\newline
+First, we create a stream consisting of the positive integers:
+\spadpaste{ints := [n for n in 1..] \bound{ints}}
+Now, we create a stream consisting of the primes:
+\spadpaste{primes := [x for x in ints | prime? x] \bound{primes} \free{ints}}
+Here's the 25th prime:
+\spadpaste{primes.25 \free{primes}}
+Next, create the stream of numbers of the form 2**p - 1 with p prime:
+\spadpaste{numbers := [f(n) for n in primes] \bound{numbers} \free{primes f}}
+Finally, form
+the stream of factorizations of the elements of \spad{numbers}:
+\spadpaste{factors := [factor n for n in numbers] \bound{factors} 
+\free{numbers}}
+You can see that the fifth number in the stream (2047 = 23*89)
+is the first one that has a non-trivial factorization.
+Since 2**11 = 2048, the solution to the problem is 11.
+\newline
+Here's another way to see that 2047 is the first number in the stream that
+is composite:
+\spadpaste{nums := [x for x in numbers | not prime? x] \bound{nums} 
+\free{numbers}}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Solution to Problem \#2}
+\label{IntegerProblemAnswerPage2}
+\index{pages!IntegerProblemAnswerPage2!numbers.ht}
+\index{numbers.ht!pages!IntegerProblemAnswerPage2}
+\index{IntegerProblemAnswerPage2!numbers.ht!pages}
+<<numbers.ht>>=
+\begin{page}{IntegerProblemAnswerPage2}{Solution to Problem \#2}
+\beginscroll
+Problem \#2:  Find the smallest positive integer n such that
+\spad{n**2 - n + 41} is not prime.
+\newline
+When n = 41, n**2 - n + 41 = 41**2, which certainly isn't prime.
+Let's see if any smaller integer works.
+Here are the first 40 values:
+\spadpaste{numbers := [n**2 - n + 41 for n in 0..40] \bound{numbers}}
+Now have Axiom factor the numbers on this list:
+\spadpaste{[factor n for n in numbers] \free{numbers}}
+You can see that 41 is the smallest positive integer n such that
+n**n - n + 41 is not prime.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{oct.ht}
+<<oct.ht>>=
+\newcommand{\OctonionXmpTitle}{Octonion}
+\newcommand{\OctonionXmpNumber}{9.56}
+
+@
+\subsection{Octonion}
+\label{OctonionXmpPage}
+See QuaternionXmpPage \ref{QuaternionXmpPage} on 
+page~\pageref{QuaternionXmpPage}
+\index{pages!OctonionXmpPage!oct.ht}
+\index{oct.ht!pages!OctonionXmpPage}
+\index{OctonionXmpPage!oct.ht!pages}
+<<oct.ht>>=
+\begin{page}{OctonionXmpPage}{Octonion}
+\beginscroll
+
+The Octonions, also called the Cayley-Dixon algebra, defined over a
+commutative ring are an eight-dimensional non-associative algebra.
+Their construction from quaternions is similar to the construction
+of quaternions from complex numbers 
+(see \downlink{`Quaternion'}{QuaternionXmpPage}\ignore{Quaternion}).
+%
+\xtc{
+As \spadtype{Octonion} creates an eight-dimensional algebra, you have to
+give eight components to construct an octonion.
+}{
+\spadpaste{oci1 := octon(1,2,3,4,5,6,7,8) \bound{oci1}}
+}
+\xtc{
+}{
+\spadpaste{oci2 := octon(7,2,3,-4,5,6,-7,0) \bound{oci2}}
+}
+%
+%
+\xtc{
+Or you can use two quaternions to create an octonion.
+}{
+\spadpaste{oci3 := octon(quatern(-7,-12,3,-10), quatern(5,6,9,0)) \bound{oci3}}
+}
+%
+%
+\xtc{
+You can easily demonstrate the non-associativity of multiplication.
+}{
+\spadpaste{(oci1 * oci2) * oci3 - oci1 * (oci2 * oci3) \free{oci1 oci2 oci3}}
+}
+%
+As with the quaternions, we have a real part, the imaginary
+parts \spad{i}, \spad{j}, \spad{k}, and four
+additional imaginary parts \spad{E}, \spad{I}, \spad{J} and \spad{K}.
+These parts correspond to the canonical basis
+\spad{(1,i,j,k,E,I,J,K)}.
+\xtc{
+For each basis element there is a component operation to extract
+the coefficient of the basis element for a given octonion.
+%\spadfunFrom{real}{Octonion},
+%\spadfunFrom{imagi}{Octonion},
+%\spadfunFrom{imagj}{Octonion},
+%\spadfunFrom{imagk}{Octonion},
+%\spadfunFrom{imagE}{Octonion},
+%\spadfunFrom{imagI}{Octonion},
+%\spadfunFrom{imagJ}{Octonion}, and
+%\spadfunFrom{imagK}{Octonion}.
+}{
+\spadpaste{[real oci1, imagi oci1, imagj oci1, imagk oci1, imagE oci1, imagI oci1, imagJ oci1, imagK oci1] \free{oci1}}
+}
+%
+A basis with respect to the
+quaternions is given by \spad{(1,E)}.
+However, you might ask, what then are the commuting rules?
+To answer this, we create some generic elements.
+%
+\xtc{
+We do this in Axiom
+by simply changing the ground ring from \spadtype{Integer} to
+\spadtype{Polynomial Integer}.
+}{
+\spadpaste{q : Quaternion Polynomial Integer := quatern(q1, qi, qj, qk) \bound{q}}
+}
+\xtc{
+}{
+\spadpaste{E : Octonion Polynomial Integer:= octon(0,0,0,0,1,0,0,0) \bound{E}}
+}
+%
+\xtc{
+Note that quaternions are automatically converted to octonions in the
+obvious way.
+}{
+\spadpaste{q * E \free{q E}}
+}
+\xtc{
+}{
+\spadpaste{E * q \free{E q}}
+}
+\xtc{
+}{
+\spadpaste{q * 1\$(Octonion Polynomial Integer) \free{q}}
+}
+\xtc{
+}{
+\spadpaste{1\$(Octonion Polynomial Integer) * q \free{q}}
+}
+\xtc{
+Finally, we check that the \spadfunFrom{norm}{Octonion},
+defined as the sum of the squares of the coefficients,
+is a multiplicative map.
+}{
+\spadpaste{o : Octonion Polynomial Integer := octon(o1, oi, oj, ok, oE, oI, oJ, oK) \bound{o}}
+}
+\xtc{
+}{
+\spadpaste{norm o \free{o}}
+}
+\xtc{
+}{
+\spadpaste{p : Octonion Polynomial Integer := octon(p1, pi, pj, pk, pE, pI, pJ, pK) \bound{p}}
+}
+\xtc{
+Since the result is \spad{0}, the norm is multiplicative.
+}{
+\spadpaste{norm(o*p)-norm(p)*norm(p)\free{o p} }
+}
+\showBlurb{Octonion}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{odpol.ht}
+<<odpol.ht>>=
+\newcommand{\OrderlyDifferentialPolynomialXmpTitle}
+{OrderlyDifferentialPolynomial}
+\newcommand{\OrderlyDifferentialPolynomialXmpNumber}{9.60}
+
+@
+\subsection{OrderlyDifferentialPolynomial}
+\label{OrderlyDifferentialPolynomialXmpPage}
+\index{pages!OrderlyDifferentialPolynomialXmpPage!odpol.ht}
+\index{odpol.ht!pages!OrderlyDifferentialPolynomialXmpPage}
+\index{OrderlyDifferentialPolynomialXmpPage!odpol.ht!pages}
+<<odpol.ht>>=
+\begin{page}{OrderlyDifferentialPolynomialXmpPage}
+{OrderlyDifferentialPolynomial}
+\beginscroll
+
+Many systems of differential equations may be transformed to equivalent
+systems of ordinary differential equations where the equations are
+expressed polynomially in terms of the unknown functions.
+In Axiom, the domain constructors
+\spadtype{OrderlyDifferentialPolynomial}
+(abbreviated \spadtype{ODPOL}) and
+\spadtype{SequentialDifferentialPolynomial} (abbreviation
+\spadtype{SDPOL}) implement two domains of ordinary differential
+polynomials over any differential ring.
+In the simplest case, this differential ring is usually either the ring of
+integers, or the field of rational numbers.
+However, Axiom can handle ordinary differential polynomials over a
+field of rational functions in a single indeterminate.
+
+The two domains \spadtype{ODPOL} and \spadtype{SDPOL} are almost
+identical, the only difference being the choice of a different ranking,
+which is an ordering of the derivatives of the indeterminates.
+The first domain uses an orderly ranking, that is, derivatives of higher
+order are ranked higher, and derivatives of the same order are ranked
+alphabetically.
+The second domain uses a sequential ranking, where derivatives are ordered
+first alphabetically by the differential indeterminates, and then by
+order.
+A more general domain constructor,
+\spadtype{DifferentialSparseMultivariatePolynomial} (abbreviation
+\spadtype{DSMP}) allows both a user-provided list of differential
+indeterminates as well as a user-defined ranking.
+We shall illustrate \spadtype{ODPOL(FRAC INT)}, which constructs a domain
+of ordinary differential polynomials in an arbitrary number of
+differential indeterminates with rational numbers as coefficients.
+\xtc{
+}{
+\spadpaste{dpol:= ODPOL(FRAC INT) \bound{dpol}}
+}
+
+\xtc{
+A differential indeterminate \spad{w} may be viewed as an infinite
+sequence of algebraic indeterminates, which are the derivatives of
+\spad{w}.
+To facilitate referencing these, Axiom provides the operation
+\spadfunFrom{makeVariable}{OrderlyDifferentialPolynomial} to convert an
+element of type \spadtype{Symbol} to a map from the natural numbers to the
+differential polynomial ring.
+}{
+\spadpaste{w := makeVariable('w)\$dpol \free{dpol}\bound{w}}
+}
+\xtc{
+}{
+\spadpaste{z := makeVariable('z)\$dpol \free{dpol}\bound{z}}
+}
+\xtc{
+The fifth derivative of \spad{w} can be obtained by applying the map
+\spad{w} to the number \spad{5.}
+Note that the order of differentiation is given as a subscript (except
+when the order is 0).
+}{
+\spadpaste{w.5 \free{w}}
+}
+\xtc{
+}{
+\spadpaste{w 0 \free{w}}
+}
+\xtc{
+The first five derivatives of \spad{z} can be generated by a list.
+}{
+\spadpaste{[z.i for i in 1..5] \free{z}}
+}
+\xtc{
+The usual arithmetic can be used to form a differential polynomial from
+the derivatives.
+}{
+\spadpaste{f:= w.4 - w.1 * w.1 * z.3 \free{w}\free{z}\bound{f}}
+}
+\xtc{
+}{
+\spadpaste{g:=(z.1)**3 * (z.2)**2 - w.2 \free{z}\free{w}\bound{g}}
+}
+\xtc{
+The operation \spadfunFrom{D}{OrderlyDifferentialPolynomial}
+computes the derivative of any differential polynomial.
+}{
+\spadpaste{D(f) \free{f}}
+}
+\xtc{
+The same operation can compute higher derivatives, like the
+fourth derivative.
+}{
+\spadpaste{D(f,4) \free{f}}
+}
+\xtc{
+The operation \spadfunFrom{makeVariable}{OrderlyDifferentialPolynomial}
+creates a map to facilitate referencing the derivatives of \spad{f},
+similar to the map \spad{w}.
+}{
+\spadpaste{df:=makeVariable(f)\$dpol \free{f}\bound{df}}
+}
+\xtc{
+The fourth derivative of f may be referenced easily.
+}{
+\spadpaste{df.4 \free{df}}
+}
+\xtc{
+The operation \spadfunFrom{order}{OrderlyDifferentialPolynomial}
+returns the order of a differential polynomial, or the order
+in a specified differential indeterminate.
+}{
+\spadpaste{order(g)  \free{g}}
+}
+\xtc{
+}{
+\spadpaste{order(g, 'w)  \free{g}}
+}
+\xtc{
+The operation
+\spadfunFrom{differentialVariables}{OrderlyDifferentialPolynomial} returns
+a list of differential indeterminates occurring in a differential
+polynomial.
+}{
+\spadpaste{differentialVariables(g)  \free{g}}
+}
+\xtc{
+The operation \spadfunFrom{degree}{OrderlyDifferentialPolynomial} returns
+the degree, or the degree in the differential indeterminate specified.
+}{
+\spadpaste{degree(g) \free{g}}
+}
+\xtc{
+}{
+\spadpaste{degree(g, 'w)  \free{g}}
+}
+\xtc{
+The operation \spadfunFrom{weights}{OrderlyDifferentialPolynomial} returns
+a list of weights of differential monomials appearing in differential
+polynomial, or a list of weights in a specified differential
+indeterminate.
+}{
+\spadpaste{weights(g)  \free{g}}
+}
+\xtc{
+}{
+\spadpaste{weights(g,'w) \free{g}}
+}
+\xtc{
+The operation \spadfunFrom{weight}{OrderlyDifferentialPolynomial} returns
+the maximum weight of all differential monomials appearing in the
+differential polynomial.
+}{
+\spadpaste{weight(g)  \free{g}}
+}
+\xtc{
+A differential polynomial is {\em isobaric} if the weights of all
+differential monomials appearing in it are equal.
+}{
+\spadpaste{isobaric?(g) \free{g}}
+}
+\xtc{
+To substitute {\em differentially}, use
+\spadfunFrom{eval}{OrderlyDifferentialPolynomial}.
+Note that we must coerce \spad{'w} to \spadtype{Symbol}, since in
+\spadtype{ODPOL}, differential indeterminates belong to the domain
+\spadtype{Symbol}.
+Compare this result to the next, which substitutes {\em algebraically} (no
+substitution is done since \spad{w.0} does not appear in \spad{g}).
+}{
+\spadpaste{eval(g,['w::Symbol],[f]) \free{f}\free{g}}
+}
+\xtc{
+}{
+\spadpaste{eval(g,variables(w.0),[f]) \free{f}\free{g}}
+}
+\xtc{
+Since \spadtype{OrderlyDifferentialPolynomial} belongs to
+\spadtype{PolynomialCategory}, all the operations defined in the latter
+category, or in packages for the latter category, are available.
+}{
+\spadpaste{monomials(g) \free{g}}
+}
+\xtc{
+}{
+\spadpaste{variables(g) \free{g}}
+}
+\xtc{
+}{
+\spadpaste{gcd(f,g) \free{f}\free{g}}
+}
+\xtc{
+}{
+\spadpaste{groebner([f,g]) \free{f}\free{g}}
+}
+\xtc{
+The next three operations are essential for elimination procedures in
+differential polynomial rings.
+The operation \spadfunFrom{leader}{OrderlyDifferentialPolynomial} returns
+the leader of a differential polynomial, which is the highest ranked
+derivative of the differential indeterminates that occurs.
+}{
+\spadpaste{lg:=leader(g)  \free{g}\bound{lg}}
+}
+\xtc{
+The operation \spadfunFrom{separant}{OrderlyDifferentialPolynomial} returns
+the separant of a differential polynomial, which is the partial derivative
+with respect to the leader.
+}{
+\spadpaste{sg:=separant(g)  \free{g}\bound{sg}}
+}
+\xtc{
+The operation \spadfunFrom{initial}{OrderlyDifferentialPolynomial} returns
+the initial, which is the leading coefficient when the given differential
+polynomial is expressed as a polynomial in the leader.
+}{
+\spadpaste{ig:=initial(g)  \free{g}\bound{ig}}
+}
+\xtc{
+Using these three operations, it is possible to reduce \spad{f} modulo the
+differential ideal generated by \spad{g}.
+The general scheme is to first reduce the order, then reduce the degree in
+the leader.
+First, eliminate \spad{z.3} using the derivative of \spad{g}.
+}{
+\spadpaste{g1 := D g \free{g}\bound{g1}}
+}
+\xtc{
+Find its leader.
+}{
+\spadpaste{lg1:= leader g1 \free{g1}\bound{lg1}}
+}
+\xtc{
+Differentiate \spad{f} partially with respect to this leader.
+}{
+\spadpaste{pdf:=D(f, lg1) \free{f}\free{lg1}\bound{pdf}}
+}
+\xtc{
+Compute the partial remainder of \spad{f} with respect to \spad{g}.
+}{
+\spadpaste{prf:=sg * f- pdf * g1 \free{f}\free{sg}\free{pdf}\free{g1}\bound{prf}}
+}
+\xtc{
+Note that high powers of \spad{lg} still appear in \spad{prf}.
+Compute the leading coefficient of \spad{prf}
+as a polynomial in the leader of \spad{g}.
+}{
+\spadpaste{lcf:=leadingCoefficient univariate(prf, lg) \free{prf}\free{lg}\bound{lcf}}
+}
+\xtc{
+Finally, continue eliminating the high powers of \spad{lg} appearing in
+\spad{prf} to obtain the (pseudo) remainder of \spad{f} modulo \spad{g}
+and its derivatives.
+}{
+\spadpaste{ig * prf - lcf * g * lg \free{ig}\free{prf}\free{lcf}\free{g}\free{lg}}
+}
+\showBlurb{OrderlyDifferentialPolyomial}
+\showBlurb{SequentialDifferentialPolynomial}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{op.ht}
+<<op.ht>>=
+\newcommand{\OperatorXmpTitle}{Operator}
+\newcommand{\OperatorXmpNumber}{9.58}
+
+@
+\subsection{Operator}
+\label{OperatorXmpPage}
+\index{pages!OperatorXmpPage!alist.ht}
+\index{alist.ht!pages!OperatorXmpPage}
+\index{OperatorXmpPage!alist.ht!pages}
+<<alist.ht>>=
+\begin{page}{OperatorXmpPage}{Operator}
+\beginscroll
+Given any ring \spad{R}, the ring of the \spadtype{Integer}-linear operators
+over \spad{R} is called \spadtype{Operator(R)}.
+To create an operator over \spad{R}, first create a basic operator using the
+operation \spadfun{operator}, and then convert it to \spadtype{Operator(R)}
+for the \spad{R} you want.
+%
+\xtc{
+We choose \spad{R} to be the two by two matrices over the integers.
+}{
+\spadpaste{R := SQMATRIX(2, INT)\bound{r}}
+}
+\xtc{
+Create the operator \spad{tilde} on \spad{R}.
+}{
+\spadpaste{t := operator("tilde") :: OP(R) \free{r}\bound{t}}
+}
+%
+Since \spadtype{Operator} is unexposed we must either package-call operations
+from it, or expose it explicitly.  For convenience we will do the latter.
+%
+\noOutputXtc{
+Expose \spad{Operator}.
+}{
+\spadpaste{)set expose add constructor Operator \free{t}\bound{expose}}
+}
+%
+To attach an evaluation function (from \spad{R} to \spad{R}) to an
+operator over \spad{R}, use \spad{evaluate(op, f)} where \spad{op}
+is an operator over \spad{R} and \spad{f} is a function \spad{R ->
+R}.
+This needs to be done only once when the operator is defined.
+Note that \spad{f} must be \spadtype{Integer}-linear (that is,
+\spad{f(ax+y) = a f(x) + f(y)} for any integer \spad{a}, and any
+\spad{x} and \spad{y} in \spad{R}).
+%
+\xtc{
+We now attach the transpose map to the above operator \spad{t}.
+}{
+\spadpaste{evaluate(t, m +-> transpose m)\free{expose}\free{t}\bound{evt}}
+}
+%
+Operators can be manipulated formally as in any ring: \spadop{+} is the
+pointwise addition and \spadop{*} is composition.
+Any element \spad{x} of \spad{R} can be converted to an operator
+\subscriptText{\tt op}{\tt x}
+over \spad{R}, and the evaluation function of
+\subscriptText{\tt op}{\tt x}
+is left-multiplication by \spad{x}.
+%
+\xtc{
+Multiplying on the
+left by this matrix swaps the two rows.
+}{
+\spadpaste{s : R := matrix [[0, 1], [1, 0]]\bound{s}}
+}
+%
+\xtc{
+Can you guess what is the action of the following operator?
+}{
+\spadpaste{rho := t * s\free{evt s}\bound{rho}}
+}
+%
+%
+\xtc{
+Hint: applying \spad{rho} four times gives the identity, so
+\spad{rho**4-1} should return 0 when applied to any two by two matrix.
+}{
+\spadpaste{z := rho**4 - 1\free{rho}\bound{z}}
+}
+%
+%
+\xtc{
+Now check with this matrix.
+}{
+\spadpaste{m:R := matrix [[1, 2], [3, 4]]\bound{m}}
+}
+\xtc{
+}{
+\spadpaste{z m\free{z m}}
+}
+%
+%
+\xtc{
+As you have probably guessed by now, \spad{rho} acts on matrices
+by rotating the elements clockwise.
+}{
+\spadpaste{rho m\free{rho m}}
+}
+\xtc{
+}{
+\spadpaste{rho rho m\free{rho m}}
+}
+\xtc{
+}{
+\spadpaste{(rho**3) m\free{rho m}}
+}
+%
+%
+\xtc{
+Do the swapping of rows and transposition commute?
+We can check by computing their bracket.
+}{
+\spadpaste{b := t * s - s * t\free{s evt}\bound{b}}
+}
+%
+%
+\xtc{
+Now apply it to \spad{m}.
+}{
+\spadpaste{b m \free{b m}}
+}
+%
+ 
+Next we demonstrate how to define a differential operator
+on a polynomial ring.
+\xtc{
+This is the recursive definition of the \spad{n}-th Legendre polynomial.
+}{
+\begin{spadsrc}[\bound{l}]
+L n ==
+  n = 0 => 1
+  n = 1 => x
+  (2*n-1)/n * x * L(n-1) - (n-1)/n * L(n-2)
+\end{spadsrc}
+}
+\xtc{
+Create the differential operator \texht{$d \over {dx}$}{\spad{d/dx}} on
+polynomials in \spad{x} over the rational numbers.
+}{
+\spadpaste{dx := operator("D") :: OP(POLY FRAC INT) \bound{dx}}
+}
+\xtc{
+Now attach the map to it.
+}{
+\spadpaste{evaluate(dx, p +-> D(p, 'x)) \free{dx}\bound{edx}}
+}
+\xtc{
+This is the differential equation satisfied by the \spad{n}-th
+Legendre polynomial.
+}{
+\spadpaste{E n == (1 - x**2) * dx**2 - 2 * x * dx + n*(n+1) \free{edx}\bound{E}}
+}
+\xtc{
+Now we verify this for \spad{n = 15}.
+Here is the polynomial.
+}{
+\spadpaste{L 15 \free{L}}
+}
+\xtc{
+Here is the operator.
+}{
+\spadpaste{E 15 \free{E}}
+}
+\xtc{
+Here is the evaluation.
+}{
+\spadpaste{(E 15)(L 15) \free{L E}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{ovar.ht}
+<<ovar.ht>>=
+\newcommand{\OrderedVariableListXmpTitle}{OrderedVariableList}
+\newcommand{\OrderedVariableListXmpNumber}{9.59}
+
+@
+\subsection{OrderedVariableList}
+\label{OrderedVariableListXmpPage}
+\index{pages!OrderedVariableListXmpPage!ovar.ht}
+\index{ovar.ht!pages!OrderedVariableListXmpPage}
+\index{OrderedVariableListXmpPage!ovar.ht!pages}
+<<ovar.ht>>=
+\begin{page}{OrderedVariableListXmpPage}{OrderedVariableList}
+\beginscroll
+
+The domain \spadtype{OrderedVariableList} provides symbols
+which are restricted to a particular list and have a definite 
+ordering. Those two features are specified by a \spadtype{List Symbol}
+object that is the argument to the domain.
+\xtc{
+This is a sample ordering of three symbols.
+}{
+\spadpaste{ls:List Symbol:=['x,'a,'z] \bound{ls}}
+}
+\xtc{
+Let's build the domain
+}{
+\spadpaste{Z:=OVAR ls \bound{Z} \free{ls}}
+}
+\xtc{
+How many variables does it have?
+}{
+\spadpaste{size()$Z \free{Z}}
+}
+\xtc{
+They are (in the imposed order)
+}{
+\spadpaste{lv:=[index(i::PI)$Z for i in 1..size()$Z] \bound{lv}\free{Z}}
+}
+\xtc{
+Check that the ordering is right
+}{
+\spadpaste{sorted?(>,lv) \free{lv}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{perman.ht}
+<<perman.ht>>=
+\newcommand{\PermanentXmpTitle}{Permanent}
+\newcommand{\PermanentXmpNumber}{9.62}
+
+@
+\subsection{Permanent}
+\label{PermanentXmpPage}
+\index{pages!PermanentXmpPage!perman.ht}
+\index{perman.ht!pages!PermanentXmpPage}
+\index{PermanentXmpPage!perman.ht!pages}
+<<perman.ht>>=
+\begin{page}{PermanentXmpPage}{Permanent}
+\beginscroll
+The package \spadtype{Permanent} provides the function
+\spadfunFrom{permanent}{Permanent} for square matrices.
+The \spadfunFrom{permanent}{Permanent} of a square matrix can be computed
+in the same way as the determinant by expansion of minors except that for
+the permanent the sign for each element is \spad{1}, rather than being
+\spad{1} if the row plus column indices is positive and \spad{-1}
+otherwise.
+This function is much more difficult to compute efficiently than the
+\spadfunFrom{determinant}{Matrix}.
+An example of the use of \spadfunFrom{permanent}{Permanent} is the
+calculation of the \eth{\spad{n}} derangement number, defined to be the number
+of different possibilities for \spad{n} couples to dance but never with
+their own spouse.
+\xtc{
+Consider an \spad{n} by \spad{n} matrix with entries 
+\spad{0} on the diagonal and
+\spad{1} elsewhere.
+Think of the rows as one-half of each couple (for example, the males) and the
+columns the other half.
+The permanent of such a matrix gives the desired derangement number.
+}{
+\begin{spadsrc}[\bound{kn}]
+kn n ==
+  r : MATRIX INT := new(n,n,1)
+  for i in 1..n repeat
+    r.i.i := 0
+  r
+\end{spadsrc}
+}
+\xtc{
+Here are some derangement numbers, which you see grow quite fast.
+}{
+\spadpaste{permanent(kn(5) :: SQMATRIX(5,INT)) \free{kn}}
+}
+\xtc{
+}{
+\spadpaste{[permanent(kn(n) :: SQMATRIX(n,INT)) for n in 1..13] \free{kn}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{pfr.ht}
+<<pfr.ht>>=
+\newcommand{\PartialFractionXmpTitle}{PartialFraction}
+\newcommand{\PartialFractionXmpNumber}{9.61}
+
+@
+\subsection{PartialFraction}
+\label{PartialFractionXmpPage}
+See FullPartialFractionExpansionXmpPage 
+\ref{FullPartialFractionExpansionXmpPage} on
+page~\pageref{FullPartialFractionExpansionXmpPage}
+\index{pages!PartialFractionXmpPage!pfr.ht}
+\index{pfr.ht!pages!PartialFractionXmpPage}
+\index{PartialFractionXmpPage!pfr.ht!pages}
+<<pfr.ht>>=
+\begin{page}{PartialFractionXmpPage}{PartialFraction}
+\beginscroll
+
+A {\it partial fraction} is a decomposition of a quotient into
+a sum
+of quotients where the denominators of the summands are powers of
+primes.\footnote{Most people first encounter partial fractions when they
+are learning integral calculus.
+For a technical discussion of partial fractions, see, for example, Lang's {\it
+Algebra.}} For example, the rational number \spad{1/6} is decomposed into
+\spad{1/2 -1/3}.
+You can compute partial fractions of quotients of objects from domains
+belonging to the category \spadtype{EuclideanDomain}.
+For example, \spadtype{Integer}, \spadtype{Complex Integer}, and
+\spadtype{UnivariatePolynomial(x, Fraction Integer)} all belong to
+\spadtype{EuclideanDomain}.
+In the examples following, we demonstrate how to decompose quotients of
+each of these kinds of object into partial fractions.
+Issue the system command
+\spadcmd{)show PartialFraction}
+to display the full list of operations defined by \spadtype{PartialFraction}.
+
+It is necessary that we know how to factor the denominator when we want to
+compute a partial fraction.
+Although the interpreter can often do this automatically, it may be
+necessary for you to include a call to \spadfun{factor}.
+In these examples, it is not necessary to factor the
+denominators explicitly.
+%
+\xtc{
+The main operation for computing partial fractions is called
+\spadfunFrom{partialFraction}{PartialFraction} and we use this to
+compute a decomposition of \spad{1 / 10!}.
+The first argument to \spadfunFrom{partialFraction}{PartialFraction} is
+the numerator of the quotient and the second argument is the factored
+denominator.
+}{
+\spadpaste{partialFraction(1,factorial 10) \bound{prev1}}
+}
+\xtc{
+Since the denominators are powers of primes, it may be possible
+to expand the numerators further with respect to those primes. Use the
+operation \spadfunFrom{padicFraction}{PartialFraction} to do this.
+}{
+\spadpaste{f := padicFraction(\%) \free{prev1}\bound{f}}
+}
+%
+%
+\xtc{
+The operation \spadfunFrom{compactFraction}{PartialFraction} returns an
+expanded fraction into the usual form.
+The compacted version is used internally for computational efficiency.
+}{
+\spadpaste{compactFraction(f) \free{f}}
+}
+%
+\xtc{
+You can add, subtract, multiply
+and divide partial fractions.  In addition, you can extract the parts
+of the decomposition.
+\spadfunFrom{numberOfFractionalTerms}{PartialFraction} computes
+the number of terms in the fractional part.
+This does not include the whole part of the fraction,
+which you get by calling \spadfunFrom{wholePart}{PartialFraction}.
+In this example, the whole part is just \spad{0}.
+}{
+\spadpaste{numberOfFractionalTerms(f) \free{f}}
+}
+\xtc{
+The operation
+\spadfunFrom{nthFractionalTerm}{PartialFraction} returns the individual terms in the
+decomposition.
+Notice that the object returned is a partial fraction itself.
+\spadfunFrom{firstNumer}{PartialFraction} and
+\spadfunFrom{firstDenom}{PartialFraction} extract the numerator and
+denominator of the first term of the fraction.
+}{
+\spadpaste{nthFractionalTerm(f,3) \free{f}}
+}
+%
+
+%
+\xtc{
+Given two gaussian integers (see \downlink{`Complex'}{ComplexXmpPage}\ignore{Complex}), you can
+decompose their quotient into a partial fraction.
+}{
+\spadpaste{partialFraction(1,- 13 + 14 * \%i) \bound{prev2}}
+}
+%
+\xtc{
+To convert back to a quotient, simply use a conversion.
+}{
+\spadpaste{\% :: Fraction Complex Integer \free{prev2}}
+}
+
+To conclude this section, we compute the decomposition of
+\texht{\narrowDisplay{1 \over {{(x + 1)}{(x + 2)}^2{(x + 3)}^3{(x + 4)}^4}}}{
+\begin{verbatim}
+                   1
+     -------------------------------
+                   2       3       4
+     (x + 1)(x + 2) (x + 3) (x + 4)
+\end{verbatim}
+}
+The polynomials in this object have type
+\spadtype{UnivariatePolynomial(x, Fraction Integer)}.
+%
+\xtc{
+We use the \spadfunFrom{primeFactor}{Factored} operation (see
+\downlink{`Factored'}{FactoredXmpPage}\ignore{Factored}) to create the denominator in factored form directly.
+}{
+\spadpaste{u : FR UP(x, FRAC INT) := reduce(*,[primeFactor(x+i,i) for i in 1..4]) \bound{u}}
+}
+%
+%
+\xtc{
+These are the compact and expanded partial fractions for the quotient.
+}{
+\spadpaste{partialFraction(1,u) \free{u}\bound{prev3}}
+}
+\xtc{
+}{
+\spadpaste{padicFraction \% \free{prev3}}
+}
+
+All see \downlink{`FullPartialFractionExpansion'}{FullPartialFractionExpansionXmpPage}\ignore{FullPartialFractionExpansion} for examples of
+factor-free conversion of quotients to full partial fractions.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{poly.ht}
+\subsection{Polynomials}
+\label{PolynomialPage}
+\includegraphics[scale=.5]{ps/v71polynomialpage.eps}
+\index{images!polynomialpage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
+\begin{itemize}
+\item ``Basic Functions'' (PolynomialBasicPage) \ref{PolynomialBasicPage} on
+page~\pageref{PolynomialBasicPage}
+\item ``Substitutions'' (PolynomialSubstitutionPage) 
+\ref{PolynomialSubstitutionPage} on
+page~\pageref{PolynomialSubstitutionPage}
+\item ``Factorizations'' (ugProblemFactorPage) \ref{ugProblemFactorPage} on
+page~\pageref{ugProblemFactorPage}
+\item ``GCDs and Friends'' (PolynomialGCDPage) \ref{PolynomialGCDPage} on
+page~\pageref{PolynomialGCDPage}
+\item ``Roots'' (PolynomialRootPage) \ref{PolynomialRootPage} on
+page~\pageref{PolynomialRootPage}
+\item ``Specific Types'' (PolynomialTypesPage) \ref{PolynomialTypesPage} on
+page~\pageref{PolynomialTypesPage}
+\end{itemize}
+\index{pages!PolynomialPage!poly.ht}
+\index{poly.ht!pages!PolynomialPage}
+\index{PolynomialPage!poly.ht!pages}
+<<poly.ht>>=
+\begin{page}{PolynomialPage}{Polynomials}
+\beginscroll
+\beginmenu
+\menulink{Basic Functions}{PolynomialBasicPage} \tab{18}
+Create and manipulate polynomials.
+\menulink{Substitutions}{PolynomialSubstitutionPage} \tab{18}
+Evaluate polynomials.
+\menulink{Factorization}{ugProblemFactorPage} \tab{18}
+Factor in different contexts.
+\menulink{GCDs and Friends}{PolynomialGCDPage} \tab{18}
+Greatest common divisors etc..
+\menulink{Roots}{PolynomialRootPage}\tab{18}
+Work with and solve for roots.
+\menulink{Specific Types}{PolynomialTypesPage}\tab{18}
+More specific information.
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{The Specific Polynomial Types}
+\label{PolynomialTypesPage}
+\index{pages!PolynomialTypesPage!poly.ht}
+\index{poly.ht!pages!PolynomialTypesPage}
+\index{PolynomialTypesPage!poly.ht!pages}
+<<poly.ht>>=
+\begin{page}{PolynomialTypesPage}{The Specific Polynomial Types}
+\beginscroll
+\beginmenu
+\menulink{Polynomial}{PolynomialXmpPage} \newline
+The general type.
+\menulink{UnivariatePolynomial}{UnivariatePolynomialXmpPage} \newline
+One variable polynomials.
+\menulink{MultivariatePolynomial}{MultivariatePolynomialXmpPage} \newline
+Multiple variable polynomials, recursive structure.
+\menulink{DistributedMultivariatePolynomial}{DistributedMultivariatePolynomialXmpPage}
+\newline
+Multiple variable polynomials, non-recursive structure.
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Basic Operations On Polynomials}
+\label{PolynomialBasicPage}
+\index{pages!PolynomialBasicPage!poly.ht}
+\index{poly.ht!pages!PolynomialBasicPage}
+\index{PolynomialBasicPage!poly.ht!pages}
+<<poly.ht>>=
+\begin{page}{PolynomialBasicPage}{Basic Operations On Polynomials}
+\beginscroll
+You create
+polynomials using the usual operations of \spadopFrom{+}{Polynomial},
+\spadopFrom{-}{Polynomial}, \spadopFrom{*}{Polynomial}
+(for multiplication), and \spadopFrom{**}{Polynomial} (for exponentiation).
+Here are two examples: \newline
+\spadpaste{p := a*x**2 + b*x*y + c*y**2 \bound{p}} 
+\spadpaste{q := 13*x**2 + 3*z \bound{q}} 
+These operations can also be used to combine polynomials.
+Try the following:
+\spadpaste{p + q \free{p q}} 
+\spadpaste{p - 3*q \free{p q}} 
+\spadpaste{p**2 + p*q \free{p q}} 
+\spadpaste{r := (p + q)**2 \bound{r} \free{p q}}
+As you can see from the above examples, the variables are ordered
+by defaults \spad{z > y > x > c > b > a},
+that is, \spad{z} is the main variable, then
+\spad{y} and so on in reverse alphabetical order.
+You can redefine this
+ordering (for display purposes only) with the \spadfun{setVariableOrder}
+command.
+For example, the following
+makes \spad{a} the main variable, then \spad{b}, and so on:
+\spadpaste{setVariableOrder [a,b,c,x,y,z] \bound{vord}}
+Now compare the way polynomials are displayed:
+\spadpaste{p \free{p vord}}
+\spadpaste{q \free{q vord}}
+\spadpaste{r \free{r vord}}
+To return to the system's default ordering,
+use \spadfun{resetVariableOrder}.
+\spadpaste{resetVariableOrder() \bound{rvord}}
+\spadpaste{p \free{p rvord}}
+Polynomial coefficients can be pulled out
+using the function \spadfun{coefficient}. \newline
+For example:
+\spadpaste{coefficient(q,x,2) \free{q}} 
+will give you the coefficient of \spad{x**2} in the polynomial \spad{q}.
+\newline
+Try these commands:
+\spadpaste{coefficient(r,x,3) \free{r}} 
+\spadpaste{c := coefficient(r,z,1) \free{r} \bound{c}} 
+\spadpaste{coefficient(c,x,2) \free{c}}
+Coefficients of monomials can be obtained as follows:
+\spadpaste{coefficient(q**2, [x,z], [2,1]) \free{q}}
+This will return the coefficient of x**2 * z in the polynomial q**2.
+Also,
+\spadpaste{coefficient(r, [x,y], [2,2]) \free{r}}
+will return the coefficient of \spad{x**2 * y**2}
+in the polynomial \spad{r(x,y)}.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Polynomial Evaluation and Substitution}
+\label{PolynomialSubstitutionPage}
+\index{pages!PolynomialSubstitutionPage!poly.ht}
+\index{poly.ht!pages!PolynomialSubstitutionPage}
+\index{PolynomialSubstitutionPage!poly.ht!pages}
+<<poly.ht>>=
+\begin{page}{PolynomialSubstitutionPage}
+{Polynomial Evaluation and Substitution}
+\beginscroll
+The function \spadfun{eval} is used to substitute values into polynomials.
+Here's an example of how to use it:
+\spadpaste{p := x**2 + y**2 \bound{p}}
+\spadpaste{eval(p,x=5) \free{p}}
+\newline
+This example would give you the value of the polynomial \spad{p} at 5.
+You can also substitute into polynomials with
+several variables.  First, specify the polynomial, then give
+a list of bindings of the form \spad{variable = value}. For example:
+\spadpaste{eval(p,[x = a + b,y = c + d]) \free{p}}
+Here \spad{x} was replaced by \spad{a + b},
+and \spad{y} was replaced by \spad{c + d}.
+Here's another example:
+\spadpaste{q := x**3 + 5*x - y**4 \bound{q}}
+\spadpaste{eval(q,[x=y,y=x]) \free{q}}
+Substitution is done ``in parallel.''
+That is, Axiom takes
+\spad{q(x,y)} and returns \spad{q(y,x)}.
+\newline
+You can also substitute numerical values for some or all of the
+variables:
+\spadpaste{px := eval(p, y = sin(2.0)) \bound{px} \free{p}}
+\spadpaste{eval(px, x = cos(2.0)) \free{px}}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Greatest Common Divisors, Resultants, and Discriminants}
+\label{PolynomialGCDPage}
+\index{pages!PolynomialGCDPage!poly.ht}
+\index{poly.ht!pages!PolynomialGCDPage}
+\index{PolynomialGCDPage!poly.ht!pages}
+<<poly.ht>>=
+\begin{page}{PolynomialGCDPage}
+{Greatest Common Divisors, Resultants, and Discriminants}
+\beginscroll
+You can compute the greatest common divisor of two polynomials using the
+function \spadfun{gcd}.
+Here's an example:
+\spadpaste{p := 3*x**8 + 2*x**7 + 6*x**2 + 7*x + 2 \bound{p}}
+\spadpaste{q := 2*x**13 + 9*x**7 + 2*x**6 + 10*x + 5 \bound{q}}
+\spadpaste{gcd(p,q) \free{p q}}
+You could
+also see that \spad{p} and \spad{q} have a factor in common by using the
+function \spadfun{resultant}:
+\spadpaste{resultant(p,q,x) \free{p q}}
+The resultant of two polynomials vanishes precisely when they have a
+factor in common.
+(In the example above
+we specified the variable with
+which we wanted to compute the resultant because the
+polynomials could have involved variables other than x.)
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Roots of Polynomials}
+\label{PolynomialRootPage}
+\index{pages!PolynomialRootPage!poly.ht}
+\index{poly.ht!pages!PolynomialRootPage}
+\index{PolynomialRootPage!poly.ht!pages}
+<<poly.ht>>=
+\begin{page}{PolynomialRootPage}{Roots of Polynomials}
+\beginscroll
+\beginmenu
+\menulink{Using a Single Root of a Polynomial}{ugxProblemSymRootOnePage}
+\newline
+Working with a single root of a polynomial.
+\menulink{Using All Roots of a Polynomial}{ugxProblemSymRootAllPage}
+\newline
+Working with all the roots of a polynomial.
+\menulink{Solution of a Single Polynomial Equation}{ugxProblemOnePolPage}
+\newline
+Finding the roots of one polynomial.
+\menulink{Solution of Systems of Polynomial Equations}{ugxProblemPolSysPage}
+\newline
+Finding the roots of a system of polynomials.
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{poly1.ht}
+<<poly1.ht>>=
+\newcommand{\PolynomialXmpTitle}{Polynomial}
+\newcommand{\PolynomialXmpNumber}{9.63}
+
+@
+\subsection{Polynomial}
+\label{PolynomialXmpPage}
+\begin{itemize}
+\item DistributedMultivariatePolynomialXmpPage \ref{DistributedMultivariatePolynomialXmpPage} on
+page~pageref{DistributedMultivariatePolynomialXmpPage}
+\item MultivariatePolynomialXmpPage \ref{MultivariatePolynomialXmpPage} on
+page~pageref{MultivariatePolynomialXmpPage}
+\item UnivariatePolynomialXmpPage \ref{UnivariatePolynomialXmpPage} on
+page~pageref{UnivariatePolynomialXmpPage}
+\item FactoredXmpPage \ref{FactoredXmpPage} on
+page~pageref{FactoredXmpPage}
+\item ugProblemFactorPage \ref{ugProblemFactorPage} on
+page~pageref{ugProblemFactorPage}
+\end{itemize}
+\index{pages!PolynomialXmpPage!poly1.ht}
+\index{poly1.ht!pages!PolynomialXmpPage}
+\index{PolynomialXmpPage!poly1.ht!pages}
+<<poly1.ht>>=
+\begin{page}{PolynomialXmpPage}{Polynomial}
+\beginscroll
+
+The domain constructor \spadtype{Polynomial} (abbreviation: \spadtype{POLY})
+provides polynomials with an arbitrary number of unspecified
+variables.
+
+\xtc{
+It is used to create the default polynomial domains
+in Axiom.
+Here the coefficients are integers.
+}{
+\spadpaste{x + 1}
+}
+\xtc{
+Here the coefficients have type \spadtype{Float}.
+}{
+\spadpaste{z - 2.3}
+}
+\xtc{
+And here we have a polynomial in two variables with coefficients which
+have type \spadtype{Fraction Integer}.
+}{
+\spadpaste{y**2 - z + 3/4}
+}
+
+The representation of objects of domains created by \spadtype{Polynomial}
+is that of recursive univariate polynomials.\footnote{The term
+\spad{univariate} means ``one variable.'' \spad{multivariate} means
+``possibly more than one variable.''}
+\xtc{
+This recursive structure is sometimes obvious from the display of
+a polynomial.
+}{
+\spadpaste{y **2 + x*y + y \bound{prev}}
+}
+In this example, you see that the polynomial is stored as a polynomial in
+\spad{y} with coefficients that are polynomials in \spad{x} with integer
+coefficients.
+In fact, you really don't need to worry about the representation unless
+you are working on an advanced application where it is critical.
+The polynomial types created from
+\spadtype{DistributedMultivariatePolynomial} and
+\spadtype{NewDistributedMultivariatePolynomial} (discussed in
+\downlink{`DistributedMultivariatePolynomial'}
+{DistributedMultivariatePolynomialXmpPage}
+\ignore{DistributedMultivariatePolynomial}) are stored and displayed in a
+non-recursive manner.
+\xtc{
+You see a ``flat'' display of the above
+polynomial by converting to one of those types.
+}{
+\spadpaste{\% :: DMP([y,x],INT) \free{prev}}
+}
+
+We will demonstrate many of the polynomial facilities by using two
+polynomials with integer coefficients.
+\xtc{
+By default, the interpreter expands polynomial expressions, even if they
+are written in a factored format.
+}{
+\spadpaste{p := (y-1)**2 * x * z \bound{p}}
+}
+\xtc{
+See \downlink{`Factored'}{FactoredXmpPage}\ignore{Factored} to see
+how to create objects in factored form directly.
+}{
+\spadpaste{q := (y-1) * x * (z+5) \bound{q}}
+}
+\xtc{
+The fully factored form can be recovered by using
+\spadfunFrom{factor}{Polynomial}.
+}{
+\spadpaste{factor(q) \free{q}}
+}
+This is the same name used for the operation to factor integers.
+Such reuse of names is called \spadglos{overloading} and makes it much easier
+to think of solving problems in general ways.
+Axiom facilities for factoring polynomials created with
+\spadtype{Polynomial} are currently restricted to
+the integer and rational number coefficient cases.
+There are more complete facilities for factoring univariate polynomials:
+see \downlink{``\ugProblemFactorTitle''}{ugProblemFactorPage} 
+in Section \ugProblemFactorNumber\ignore{ugProblemFactor}.
+
+\xtc{
+The standard arithmetic operations are available for polynomials.
+}{
+\spadpaste{p - q**2\free{p q}}
+}
+\xtc{
+The operation \spadfunFrom{gcd}{Polynomial} is used to compute the
+greatest common divisor of two polynomials.
+}{
+\spadpaste{gcd(p,q) \free{p q}\bound{prev4}}
+}
+\xtc{
+In the case of \spad{p} and \spad{q}, the gcd is obvious from their
+definitions.
+We factor the gcd to show this relationship better.
+}{
+\spadpaste{factor \% \free{prev4}}
+}
+\xtc{
+The least common multiple is computed by using \spadfunFrom{lcm}{Polynomial}.
+}{
+\spadpaste{lcm(p,q) \free{p q}}
+}
+\xtc{
+Use \spadfunFrom{content}{Polynomial} to compute the 
+greatest common divisor of the
+coefficients of the polynomial.
+}{
+\spadpaste{content p \free{p}}
+}
+
+Many of the operations on polynomials require you to specify a variable.
+For example, \spadfunFrom{resultant}{Polynomial} requires you to give the
+variable in which the polynomials should be expressed.
+\xtc{
+This computes the resultant of the values of \spad{p} and
+\spad{q}, considering them as polynomials in the variable \spad{z}.
+They do not share a root when thought of as polynomials in \spad{z}.
+}{
+\spadpaste{resultant(p,q,z) \free{p q}}
+}
+\xtc{
+This value is \spad{0} because as polynomials in \spad{x} the polynomials
+have a common root.
+}{
+\spadpaste{resultant(p,q,x) \free{p}\free{q}}
+}
+The data type used for the variables created by \spadtype{Polynomial} is
+\spadtype{Symbol}.
+As mentioned above, the representation used by \spadtype{Polynomial} is
+recursive and so there is a main variable for nonconstant polynomials.
+\xtc{
+The operation \spadfunFrom{mainVariable}{Polynomial} returns this
+variable.
+The return type is actually a union of \spadtype{Symbol} and
+\spad{"failed"}.
+}{
+\spadpaste{mainVariable p \free{p}}
+}
+\xtc{
+The latter branch of the union is be used if the polynomial has no
+variables, that is, is a constant.
+}{
+\spadpaste{mainVariable(1 :: POLY INT)}
+}
+\xtc{
+You can also use the predicate \spadfunFrom{ground?}{Polynomial} to test
+whether a polynomial is in fact a member of its ground ring.
+}{
+\spadpaste{ground? p \free{p}}
+}
+\xtc{
+}{
+\spadpaste{ground?(1 :: POLY INT)}
+}
+\xtc{
+The complete list of variables actually used in a particular polynomial is
+returned by \spadfunFrom{variables}{Polynomial}.
+For constant polynomials, this list is empty.
+}{
+\spadpaste{variables p \free{p}}
+}
+
+\xtc{
+The \spadfunFrom{degree}{Polynomial} operation returns the
+degree of a polynomial in a specific variable.
+}{
+\spadpaste{degree(p,x) \free{p}}
+}
+\xtc{
+}{
+\spadpaste{degree(p,y) \free{p}}
+}
+\xtc{
+}{
+\spadpaste{degree(p,z) \free{p}}
+}
+\xtc{
+If you give a list of variables for the second argument, a list
+of the degrees in those variables is returned.
+}{
+\spadpaste{degree(p,[x,y,z]) \free{p}}
+}
+\xtc{
+The minimum degree of a variable in a polynomial is computed using
+\spadfunFrom{minimumDegree}{Polynomial}.
+}{
+\spadpaste{minimumDegree(p,z) \free{p}}
+}
+\xtc{
+The total degree of a polynomial is returned by
+\spadfunFrom{totalDegree}{Polynomial}.
+}{
+\spadpaste{totalDegree p \free{p}}
+}
+
+\xtc{
+It is often convenient to think of a polynomial as a leading monomial plus
+the remaining terms.
+}{
+\spadpaste{leadingMonomial p \free{p}}
+}
+\xtc{
+The \spadfunFrom{reductum}{Polynomial} operation returns a polynomial
+consisting of the sum of the monomials after the first.
+}{
+\spadpaste{reductum p \free{p}}
+}
+\xtc{
+These have the obvious relationship that the original polynomial
+is equal to the leading monomial plus the reductum.
+}{
+\spadpaste{p - leadingMonomial p - reductum p \free{p}}
+}
+\xtc{
+The value returned by \spadfunFrom{leadingMonomial}{Polynomial} includes
+the coefficient of that term.
+This is extracted by using
+\spadfunFrom{leadingCoefficient}{Polynomial} on the original polynomial.
+}{
+\spadpaste{leadingCoefficient p \free{p}}
+}
+\xtc{
+The operation \spadfunFrom{eval}{Polynomial} is used to substitute a value
+for a variable in a polynomial.
+}{
+\spadpaste{p  \free{p}}
+}
+\xtc{
+This value may be another variable, a constant or a polynomial.
+}{
+\spadpaste{eval(p,x,w) \free{p}}
+}
+\xtc{
+}{
+\spadpaste{eval(p,x,1) \free{p}}
+}
+\xtc{
+Actually, all the things being substituted are just polynomials,
+some more trivial than others.
+}{
+\spadpaste{eval(p,x,y**2 - 1) \free{p}}
+}
+
+\xtc{
+Derivatives are computed using the \spadfunFrom{D}{Polynomial}
+operation.
+}{
+\spadpaste{D(p,x) \free{p}}
+}
+\xtc{
+The first argument is the polynomial and the second is the variable.
+}{
+\spadpaste{D(p,y) \free{p}}
+}
+\xtc{
+Even if the polynomial has only one variable, you must specify it.
+}{
+\spadpaste{D(p,z) \free{p}}
+}
+
+Integration of polynomials is similar and the
+\spadfunFrom{integrate}{Polynomial} operation is used.
+
+\xtc{
+Integration requires that the coefficients support division.
+Consequently,
+Axiom converts polynomials over the integers to polynomials over
+the rational numbers before integrating them.
+}{
+\spadpaste{integrate(p,y) \free{p}}
+}
+
+It is not possible, in general, to divide two polynomials.
+In our example using polynomials over the integers, the operation
+\spadfunFrom{monicDivide}{Polynomial} divides a polynomial by a monic
+polynomial (that is, a polynomial with leading coefficient equal to 1).
+The result is a record of the quotient and remainder of the
+division.
+\xtc{
+You must specify the variable in which to express the polynomial.
+}{
+\spadpaste{qr := monicDivide(p,x+1,x) \free{p}\bound{qr}}
+}
+\xtc{
+The selectors of the components of the record are
+\spad{quotient} and \spad{remainder}.
+Issue this to extract the remainder.
+}{
+\spadpaste{qr.remainder \free{qr}}
+}
+\xtc{
+Now that we can extract the components, we can demonstrate the
+relationship among them and the arguments to our original expression
+\spad{qr := monicDivide(p,x+1,x)}.
+}{
+\spadpaste{p - ((x+1) * qr.quotient + qr.remainder) \free{p}\free{qr}}
+}
+
+\xtc{
+If the \spadopFrom{/}{Fraction} operator is used with polynomials, a
+fraction object is created.
+In this example, the result is an object of type \spadtype{Fraction
+Polynomial Integer}.
+}{
+\spadpaste{p/q \free{p}\free{q}}
+}
+\xtc{
+If you use rational numbers as polynomial coefficients, the
+resulting object is of type \spadtype{Polynomial Fraction Integer}.
+}{
+\spadpaste{(2/3) * x**2 - y + 4/5 \bound{prev1}}
+}
+\xtc{
+This can be converted to a fraction of polynomials and back again, if
+required.
+}{
+\spadpaste{\% :: FRAC POLY INT \free{prev1}\bound{prev2}}
+}
+\xtc{
+}{
+\spadpaste{\% :: POLY FRAC INT \free{prev2}\bound{prev3}}
+}
+\xtc{
+To convert the coefficients to floating point,
+map the \spadfun{numeric} operation on the coefficients of the polynomial.
+}{
+\spadpaste{map(numeric,\%) \free{prev3}}
+}
+
+For more information on related topics, see
+\downlink{`UnivariatePolynomial'}{UnivariatePolynomialXmpPage}\ignore{UnivariatePolynomial},
+\downlink{`MultivariatePolynomial'}{MultivariatePolynomialXmpPage}\ignore{MultivariatePolynomial}, and
+\downlink{`DistributedMultivariatePolynomial'}{DistributedMultivariatePolynomialXmpPage}\ignore{DistributedMultivariatePolynomial}.
+You can also issue the system command
+\spadcmd{)show Polynomial}
+to display the full list of operations defined by
+\spadtype{Polynomial}.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{quat.ht}
+<<quat.ht>>=
+\newcommand{\QuaternionXmpTitle}{Quaternion}
+\newcommand{\QuaternionXmpNumber}{9.64}
+
+@
+\subsection{Quaternion}
+\label{QuaternionXmpPage}
+\index{pages!QuaternionXmpPage!quat.ht}
+\index{quat.ht!pages!QuaternionXmpPage}
+\index{QuaternionXmpPage!quat.ht!pages}
+<<quat.ht>>=
+\begin{page}{QuaternionXmpPage}{Quaternion}
+% =====================================================================
+\beginscroll
+The domain constructor \spadtype{Quaternion} implements quaternions over
+commutative rings.
+For information on related topics, see
+%\menuxmpref{CliffordAlgebra}
+\downlink{`Complex'}{ComplexXmpPage}\ignore{Complex} and
+\downlink{`Octonion'}{OctonionXmpPage}\ignore{Octonion}.
+You can also issue the system command
+\spadcmd{)show Quaternion}
+to display the full list of operations defined by
+\spadtype{Quaternion}.
+
+\xtc{
+The basic operation for creating quaternions is
+\spadfunFrom{quatern}{Quaternion}.
+This is a quaternion over the rational numbers.
+}{
+\spadpaste{q := quatern(2/11,-8,3/4,1) \bound{q}}
+}
+\xtc{
+The four arguments are the real part, the \spad{i} imaginary part, the
+\spad{j} imaginary part, and the \spad{k} imaginary part, respectively.
+}{
+\spadpaste{[real q, imagI q, imagJ q, imagK q] \free{q}}
+}
+\xtc{
+Because \spad{q} is over the rationals (and nonzero), you can invert it.
+}{
+\spadpaste{inv q \free{q}}
+}
+\xtc{
+The usual arithmetic (ring) operations are available
+}{
+\spadpaste{q**6 \free{q}}
+}
+\xtc{
+}{
+\spadpaste{r := quatern(-2,3,23/9,-89); q + r \bound{r}\free{q}}
+}
+%
+\xtc{
+In general, multiplication is not commutative.
+}{
+\spadpaste{q * r - r * q\free{q r}}
+}
+\xtc{
+There are no predefined constants for the imaginary \spad{i, j},
+and \spad{k} parts, but you can easily define them.
+}{
+\spadpaste{i:=quatern(0,1,0,0); j:=quatern(0,0,1,0); k:=quatern(0,0,0,1) \bound{i j k}}
+}
+\xtc{
+These satisfy the normal identities.
+}{
+\spadpaste{[i*i, j*j, k*k, i*j, j*k, k*i, q*i] \free{i j k q}}
+}
+\xtc{
+The norm is the quaternion times its conjugate.
+}{
+\spadpaste{norm q \free{q}}
+}
+\xtc{
+}{
+\spadpaste{conjugate q \free{q} \bound{prev}}
+}
+\xtc{
+}{
+\spadpaste{q * \% \free{q prev}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{radix.ht}
+<<radix.ht>>=
+\newcommand{\RadixExpansionXmpTitle}{RadixExpansion}
+\newcommand{\RadixExpansionXmpNumber}{9.65}
+
+@
+\subsection{RadixExpansion}
+\label{RadixExpansionXmpPage}
+\begin{itemize}
+\item HexadecimalExpansionXmpPage \ref{HexadecimalExpansionXmpPage} on
+page~pageref{HexadecimalExpansionXmpPage}
+\item DecimalExpansionXmpPage \ref{DecimalExpansionXmpPage} on
+page~pageref{DecimalExpansionXmpPage}
+\item BinaryExpansionXmpPage \ref{BinaryExpansionXmpPage} on
+page~pageref{BinaryExpansionXmpPage}
+\end{itemize}
+\index{pages!RadixExpansionXmpPage!radix.ht}
+\index{radix.ht!pages!RadixExpansionXmpPage}
+\index{RadixExpansionXmpPage!radix.ht!pages}
+<<radix.ht>>=
+\begin{page}{RadixExpansionXmpPage}{RadixExpansion}
+\beginscroll
+
+It possible to expand numbers in general bases.
+
+\labelSpace{2pc}
+\xtc{
+Here we expand \spad{111} in base \spad{5}.
+This means
+\texht{$10^2+10^1+10^0 = 4 \cdot 5^2+2 \cdot 5^1 + 5^0.$}{%
+\spad{10**2+10**1+10**0 = 4*5**2+2*5**1+5**0.}}
+}{
+\spadpaste{111::RadixExpansion(5)}
+}
+
+\xtc{
+You can expand fractions to form repeating expansions.
+}{
+\spadpaste{(5/24)::RadixExpansion(2)}
+}
+\xtc{
+}{
+\spadpaste{(5/24)::RadixExpansion(3)}
+}
+\xtc{
+}{
+\spadpaste{(5/24)::RadixExpansion(8)}
+}
+\xtc{
+}{
+\spadpaste{(5/24)::RadixExpansion(10)}
+}
+\xtc{
+For bases from 11 to 36 the letters A through Z are used.
+}{
+\spadpaste{(5/24)::RadixExpansion(12)}
+}
+\xtc{
+}{
+\spadpaste{(5/24)::RadixExpansion(16)}
+}
+\xtc{
+}{
+\spadpaste{(5/24)::RadixExpansion(36)}
+}
+\xtc{
+For bases greater than 36, the ragits are separated by blanks.
+}{
+\spadpaste{(5/24)::RadixExpansion(38)}
+}
+\xtc{
+The \spadtype{RadixExpansion} type provides operations to obtain the
+individual ragits.
+Here is a rational number in base \spad{8}.
+}{
+\spadpaste{a := (76543/210)::RadixExpansion(8) \bound{a}}
+}
+\xtc{
+The operation \spadfunFrom{wholeRagits}{RadixExpansion} returns a list of the
+ragits for the integral part of the number.
+}{
+\spadpaste{w := wholeRagits a \free{a}\bound{w}}
+}
+\xtc{
+The operations \spadfunFrom{prefixRagits}{RadixExpansion} and \spadfunFrom{cycleRagits}{RadixExpansion}
+return lists of the initial and repeating ragits in the
+fractional part of the number.
+}{
+\spadpaste{f0 := prefixRagits a \free{a}\bound{f0}}
+}
+\xtc{
+}{
+\spadpaste{f1 := cycleRagits a \free{a}\bound{f1}}
+}
+\xtc{
+You can construct any radix expansion by giving the
+whole, prefix and cycle parts.
+The declaration is necessary to let Axiom
+know the base of the ragits.
+}{
+\spadpaste{u:RadixExpansion(8):=wholeRadix(w)+fractRadix(f0,f1) \free{w f0 f1}\bound{u}}
+}
+\xtc{
+If there is no repeating part, then the list \spad{[0]} should be used.
+}{
+\spadpaste{v: RadixExpansion(12) := fractRadix([1,2,3,11], [0]) \bound{v}}
+}
+\xtc{
+If you are not interested in the repeating nature of the expansion,
+an infinite stream of ragits can be obtained using
+\spadfunFrom{fractRagits}{RadixExpansion}.
+}{
+\spadpaste{fractRagits(u) \free{u}}
+}
+\xtc{
+Of course, it's possible to recover the fraction representation:
+}{
+\spadpaste{a :: Fraction(Integer) \free{a}}
+}
+
+\showBlurb{RadixExpansion}
+More examples of expansions are available in
+\downlink{`DecimalExpansion'}{DecimalExpansionXmpPage}\ignore{DecimalExpansion},
+\downlink{`BinaryExpansion'}{BinaryExpansionXmpPage}\ignore{BinaryExpansion}, and
+\downlink{`HexadecimalExpansion'}{HexadecimalExpansionXmpPage}\ignore{HexadecimalExpansion}.
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{reclos.ht}
+<<reclos.ht>>=
+\newcommand{\RealClosureXmpTitle}{RealClosure}
+\newcommand{\RealClosureXmpNumber}{9.66}
+
+@
+\subsection{RealClosure}
+\label{RealClosureXmpPage}
+\index{pages!RealClosureXmpPage!reclos.ht}
+\index{reclos.ht!pages!RealClosureXmpPage}
+\index{RealClosureXmpPage!reclos.ht!pages}
+<<reclos.ht>>=
+\begin{page}{RealClosureXmpPage}{RealClosure}
+\beginscroll
+
+The Real Closure 1.0 package provided by 
+Renaud Rioboo (Renaud.Rioboo@lip6.fr) consists of different
+packages, categories and domains :
+
+\begin{items}
+\item The package \axiomType{RealPolynomialUtilitiesPackage} which needs 
+a \axiomType{Field} {\em F} and a
+\axiomType{UnivariatePolynomialCategory} domain with coefficients in {\em F}. 
+It computes some
+simple functions such as Sturm and Sylvester sequences 
+(\axiomOpFrom{sturmSequence}{RealPolynomialUtilitiesPackage}, 
+\axiomOpFrom{sylvesterSequence}{RealPolynomialUtilitiesPackage}).
+
+\item The category \axiomType{RealRootCharacterizationCategory} provides 
+abstract
+functions to work with "real roots" of univariate polynomials. These
+resemble variables with some functionality needed to compute important
+operations.
+
+\item The category \axiomType{RealClosedField} provides common operations 
+available over
+real closed fiels. These include finding all the roots of a univariate
+polynomial, taking square (and higher) roots, ...
+
+\item The domain \axiomType{RightOpenIntervalRootCharacterization} is the 
+main code that
+provides the functionality of \axiomType{RealRootCharacterizationCategory} 
+for the case
+of archimedean fields. Abstract roots are encoded with a left closed right
+open interval containing the root together with a defining polynomial for the
+root.
+
+\item  The \axiomType{RealClosure} domain is the end-user code. It provides 
+usual arithmetic
+with real algebraic numbers, along with the functionality of a real closed
+field. It also provides functions to approximate a real algebraic number by an
+element of the base field. This approximation may either be absolute
+(\axiomOpFrom{approximate}{RealClosure}) or relative 
+(\axiomOpFrom{relativeApprox}{RealClosure}).
+
+
+\end{items}
+
+\centerline{CAVEATS}
+
+Since real algebraic expressions are stored as depending on "real roots" which
+are managed like variables, there is an ordering on these. This ordering is
+dynamical in the sense that any new algebraic takes precedence over older
+ones. In particular every creation function raises a new "real root". This has
+the effect that when you type something like 
+\spad{sqrt(2) + sqrt(2)} you have two
+new variables which happen to be equal. To avoid this name the expression such
+as in \spad{s2 := sqrt(2) ; s2 + s2}
+
+Also note that computing times depend strongly on the ordering you implicitly
+provide. Please provide algebraics in the order 
+which seems most natural to you.
+
+\centerline{LIMITATIONS}
+
+This packages uses
+algorithms which are published in [1] and [2] which are based on field
+arithmetics, in particular for polynomial gcd related algorithms. This can be
+quite slow for high degree polynomials and subresultants methods usually work
+best. Beta versions of the package try to use these techniques in a better
+way and work significantly faster. These are mostly based on unpublished
+algorithms and cannot be distributed. Please contact the author if you have a
+particular problem to solve or want to use these versions.
+
+Be aware that approximations behave as post-processing and that all
+computations are done exactly. They can thus be quite time consuming when
+depending on several "real roots".
+
+\centerline{REFERENCES}
+
+
+[1]  R. Rioboo : Real Algebraic Closure of an ordered Field : Implementation 
+     in Axiom. 
+     In proceedings of the ISSAC'92 Conference, Berkeley 1992 pp. 206-215.
+
+[2]  Z. Ligatsikas, R. Rioboo, M. F. Roy : Generic computation of the real
+     closure of an ordered field.
+     In Mathematics and Computers in Simulation Volume 42, Issue 4-6,
+     November 1996.
+
+\centerline{EXAMPLES}
+\xtc{
+We shall work with the real closure of the ordered field of 
+rational numbers.
+}{
+\spadpaste{Ran := RECLOS(FRAC INT) \bound{Ran}}
+}
+\xtc{
+Some simple signs for square roots, these correspond to an extension
+of degree 16 of the rational numbers. Examples provided by J. Abbot.
+}{
+\spadpaste{fourSquares(a:Ran,b:Ran,c:Ran,d:Ran):Ran == sqrt(a)+sqrt(b) - sqrt(c)-sqrt(d) \free{Ran} \bound{fs}}
+}
+\xtc{
+These produce values very close to zero.
+}{
+\spadpaste{squareDiff1 := fourSquares(73,548,60,586) \free{fs}\bound{sd1}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff1)\free{sd1}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff1)\free{sd1}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff2 := fourSquares(165,778,86,990) \free{fs}\bound{sd2}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff2)\free{sd2}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff2)\free{sd2}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff3 := fourSquares(217,708,226,692) \free{fs}\bound{sd3}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff3)\free{sd3}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff3)\free{sd3}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff4 := fourSquares(155,836,162,820)  \free{fs}\bound{sd4}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff4)\free{sd4}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff4)\free{sd4}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff5 := fourSquares(591,772,552,818) \free{fs}\bound{sd5}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff5)\free{sd5}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff5)\free{sd5}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff6 := fourSquares(434,1053,412,1088) \free{fs}\bound{sd6}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff6)\free{sd6}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff6)\free{sd6}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff7 := fourSquares(514,1049,446,1152) \free{fs}\bound{sd7}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff7)\free{sd7}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff7)\free{sd7}}
+}
+\xtc{
+}{
+\spadpaste{squareDiff8 := fourSquares(190,1751,208,1698) \free{fs}\bound{sd8}}
+}
+\xtc{
+}{
+\spadpaste{recip(squareDiff8)\free{sd8}}
+}
+\xtc{
+}{
+\spadpaste{sign(squareDiff8)\free{sd8}}
+}
+\xtc{
+This should give three digits of precision
+}{
+\spadpaste{relativeApprox(squareDiff8,10**(-3))::Float \free{sd8}}
+}
+\xtc{
+The sum of these 4 roots is 0
+}{
+\spadpaste{l := allRootsOf((x**2-2)**2-2)$Ran \free{Ran} \bound{l}}
+}
+\xtc{
+Check that they are all roots of the same polynomial
+}{
+\spadpaste{removeDuplicates map(mainDefiningPolynomial,l) \free{l}}
+}
+\xtc{
+We can see at a glance that they are separate roots
+}{
+\spadpaste{map(mainCharacterization,l) \free{l}}
+}
+\xtc{
+Check the sum and product
+}{
+\spadpaste{[reduce(+,l),reduce(*,l)-2] \free{l}}
+}
+\xtc{
+A more complicated test that involve an extension of degree 256.
+This is a way of checking nested radical identities.
+}{
+\spadpaste{(s2, s5, s10) := (sqrt(2)$Ran, sqrt(5)$Ran, sqrt(10)$Ran) \free{Ran}\bound{s2}\bound{s5}\bound{s10}}
+}
+\xtc{
+}{
+\spadpaste{eq1:=sqrt(s10+3)*sqrt(s5+2) - sqrt(s10-3)*sqrt(s5-2) = sqrt(10*s2+10) \free{s2}\free{s5}\free{s10}\bound{eq1}}
+}
+\xtc{
+}{
+\spadpaste{eq1::Boolean \free{eq1}}
+}
+\xtc{
+}{
+\spadpaste{eq2:=sqrt(s5+2)*sqrt(s2+1) - sqrt(s5-2)*sqrt(s2-1) = sqrt(2*s10+2)\free{s2}\free{s5}\free{s10}\bound{eq2}}
+}
+\xtc{
+}{
+\spadpaste{eq2::Boolean \free{eq2}}
+}
+\xtc{
+Some more examples from J. M. Arnaudies
+}{
+\spadpaste{s3 := sqrt(3)$Ran \free{Ran}\bound{s3}}
+}
+\xtc{
+}{
+\spadpaste{s7:= sqrt(7)$Ran \free{Ran}\bound{s7}}
+}
+\xtc{
+}{
+\spadpaste{e1 := sqrt(2*s7-3*s3,3) \free{s7} \free{s3} \bound{e1}}
+}
+\xtc{
+}{
+\spadpaste{e2 := sqrt(2*s7+3*s3,3) \free{s7} \free{s3} \bound{e2}}
+}
+\xtc{
+This should be null
+}{
+\spadpaste{e2-e1-s3 \free{e2} \free{e1} \free{s3}}
+}
+\xtc{
+A quartic polynomial
+}{
+\spadpaste{pol : UP(x,Ran) := x**4+(7/3)*x**2+30*x-(100/3) \free{Ran} \bound{pol}}
+}
+\xtc{
+Add some cubic roots
+}{
+\spadpaste{r1 := sqrt(7633)$Ran \free{Ran}\bound{r1}}
+}
+\xtc{
+}{
+\spadpaste{alpha := sqrt(5*r1-436,3)/3 \free{r1} \bound{alpha}}
+}
+\xtc{
+}{
+\spadpaste{beta := -sqrt(5*r1+436,3)/3 \free{r1} \bound{beta}}
+}
+\xtc{
+this should be null
+}{
+\spadpaste{pol.(alpha+beta-1/3) \free{pol} \free{alpha} \free{beta}}
+}
+\xtc{
+A quintic polynomial
+}{
+\spadpaste{qol : UP(x,Ran) := x**5+10*x**3+20*x+22 \free{Ran}\bound{qol}}
+}
+\xtc{
+Add some cubic roots
+}{
+\spadpaste{r2 := sqrt(153)$Ran \free{Ran}\bound{r2}}
+}
+\xtc{
+}{
+\spadpaste{alpha2 := sqrt(r2-11,5) \free{r2}\bound{alpha2}}
+}
+\xtc{
+}{
+\spadpaste{beta2 := -sqrt(r2+11,5) \free{r2}\bound{beta2}}
+}
+\xtc{
+this should be null
+}{
+\spadpaste{qol(alpha2+beta2) \free{qol}\free{alpha2}\free{beta2}}
+}
+\xtc{
+Finally, some examples from the book Computer Algebra by 
+Davenport, Siret and Tournier (page 77).
+The last one is due to Ramanujan.
+}{
+\spadpaste{dst1:=sqrt(9+4*s2)=1+2*s2 \free{s2}\bound{dst1}}
+}
+\xtc{
+}{
+\spadpaste{dst1::Boolean \free{dst1}}
+}
+\xtc{
+}{
+\spadpaste{s6:Ran:=sqrt 6 \free{Ran}\bound{s6}}
+}
+\xtc{
+}{
+\spadpaste{dst2:=sqrt(5+2*s6)+sqrt(5-2*s6) = 2*s3 \free{s6}\free{s3}\bound{dst2}}
+}
+\xtc{
+}{
+\spadpaste{dst2::Boolean \free{dst2}}
+}
+\xtc{
+}{
+\spadpaste{s29:Ran:=sqrt 29 \free{Ran}\bound{s29}}
+}
+\xtc{
+}{
+\spadpaste{dst4:=sqrt(16-2*s29+2*sqrt(55-10*s29)) = sqrt(22+2*s5)-sqrt(11+2*s29)+s5 \free{s29}\free{s5}\bound{dst4}}
+}
+\xtc{
+}{
+\spadpaste{dst4::Boolean \free{dst4}}
+}
+\xtc{
+}{
+\spadpaste{dst6:=sqrt((112+70*s2)+(46+34*s2)*s5) = (5+4*s2)+(3+s2)*s5 \free{s2}\free{s5}\bound{dst6}}
+}
+\xtc{
+}{
+\spadpaste{dst6::Boolean \free{dst6}}
+}
+\xtc{
+}{
+\spadpaste{f3:Ran:=sqrt(3,5) \free{Ran}\bound{f3}}
+}
+\xtc{
+}{
+\spadpaste{f25:Ran:=sqrt(1/25,5) \free{Ran}\bound{f25}}
+}
+\xtc{
+}{
+\spadpaste{f32:Ran:=sqrt(32/5,5) \free{Ran}\bound{f32}}
+}
+\xtc{
+}{
+\spadpaste{f27:Ran:=sqrt(27/5,5) \free{Ran}\bound{f27}}
+}
+\xtc{
+}{
+\spadpaste{dst5:=sqrt((f32-f27,3)) = f25*(1+f3-f3**2)\free{f32}\free{f27}\free{f25}\free{f3}\bound{dst5}}
+}
+\xtc{
+}{
+\spadpaste{dst5::Boolean \free{dst5}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{record.ht}
+\subsection{Domain {\bf Record(a:A,...,b:B)}}
+\label{DomainRecord}
+\index{pages!DomainRecord!record.ht}
+\index{record.ht!pages!DomainRecord}
+\index{DomainRecord!record.ht!pages}
+<<record.ht>>=
+\begin{page}{DomainRecord}{Domain {\em Record(a:A,...,b:B)}}
+\beginscroll
+{\em Record} takes any number of selector-domain pairs as arguments:
+\indentrel{2}
+\newline \spad{a}, a selector, an element of domain \spadtype{Symbol}
+\newline \spad{A}, a domain of category \spadtype{SetCategory}
+\newline\tab{10}...
+\newline \spad{b}, a selector, an element of domain \spadtype{Symbol}
+\newline \spad{B}, a domain of category \spadtype{SetCategory}
+\indentrel{-2}\newline
+This constructor is a primitive in Axiom. 
+\newline
+\beginmenu
+\item\menulispdownlink{Description}{(|dbSpecialDescription| '|Record|)}\tab{15}General description
+\item\menulispdownlink{Operations}{(|dbSpecialOperations| '|Record|)}\tab{15}All exported operations of {\em Record(a:A,b:B)}
+%\item\menudownlink{Examples}   {RecordExamples}   \tab{15}Examples illustrating use
+%\item\menudownlink{Exports}    {RecordExports}    \tab{15}Explicit categories and operations
+\endmenu
+\vspace{1}\newline
+The selectors {\em a,...,b} of a \spad{Record} type must be distinct.
+\endscroll\end{page}
+ 
+@
+\subsection{Domain Constructor {\bf Record}}
+\label{RecordDescription}
+\index{pages!RecordDescription!record.ht}
+\index{record.ht!pages!RecordDescription}
+\index{RecordDescription!record.ht!pages}
+<<record.ht>>=
+\begin{page}{RecordDescription}{Domain Constructor {\em Record}}
+\beginscroll
+\newline\menuitemstyle{}\tab{2}Record({\em a:A},{\em b:B})
+\newline\tab{2}{\em Arguments:}\indent{17}\tab{-2}
+{\em a}, a selector, an element of domain \spadtype{Symbol}
+\newline\tab{-2}
+{\em A}, a domain of category \spadtype{SetCategory}
+\newline\tab{10}...
+\newline\tab{-2}
+{\em b}, a selector, an element of domain \spadtype{Symbol}
+\newline\tab{-2}
+{\em B}, a domain of category \spadtype{SetCategory}
+\indent{0}\newline\tab{2}{\em Returns:}\indent{15}\tab{0}
+a record object with component objects of type {\em A},...,{\em B} with 
+correponding selectors {\em a},...,{\em b}
+as described below.
+\indent{0}\newline\tab{2}{\em Description:}\indent{15}\tab{0}
+{\em Record(a:A,b:B)} is used to create the class of pairs of objects made
+up of a value of type {\em A} selected by the symbol {\em a} and
+a value of type {\em B} selected by the symbol {\em b}.
+In general, the {\em Record} constructor can take any number of arguments and thus can 
+be used to create aggregates of 
+heterogeneous components of arbitrary size selectable by name.
+{\em Record} is a primitive domain of Axiom which cannot be
+defined in the Axiom language. 
+\endscroll
+\end{page}
+
+
+@
+\section{regset.ht}
+<<regset.ht>>=
+\newcommand{\RegularTriangularSetXmpTitle}{RegularTriangularSet}
+\newcommand{\RegularTriangularSetXmpNumber}{9.67}
+
+@
+\subsection{RegularTriangularSet}
+\label{RegularTriangularSetXmpPage}
+\index{pages!RegularTriangularSetXmpPage!regset.ht}
+\index{regset.ht!pages!RegularTriangularSetXmpPage}
+\index{RegularTriangularSetXmpPage!regset.ht!pages}
+<<regset.ht>>=
+\begin{page}{RegularTriangularSetXmpPage}{RegularTriangularSet}
+\beginscroll
+The \spadtype{RegularTriangularSet} domain constructor implements
+regular triangular sets.
+These particular triangular sets were introduced by M. Kalkbrener (1991) 
+in his PhD Thesis under the name regular chains.
+Regular chains and their related concepts are presented in
+the paper "On the Theories of Triangular sets" By P. Aubry, D. Lazard
+and M. Moreno Maza (to appear in the Journal of Symbolic Computation).
+The \spadtype{RegularTriangularSet} 
+constructor also provides a new method (by the third author) 
+for solving polynomial system by means of regular chains.
+This method has two ways of solving.
+One has the same specifications as Kalkbrener's algorithm (1991)
+and the other is closer to Lazard's method (Discr. App. Math, 1991).
+Moreover, this new method removes redundant component from the 
+decompositions when this is not {\em too expensive}.
+This is always the case with square-free regular chains.
+So if you want to obtain decompositions without redundant components
+just use the \spadtype{SquareFreeRegularTriangularSet} domain constructor 
+or the \spadtype{LazardSetSolvingPackage} package constructor.
+See also the \spadtype{LexTriangularPackage} and 
+\spadtype{ZeroDimensionalSolvePackage} for the case of 
+algebraic systems with a finite number of (complex) solutions.
+
+One of the main features of regular triangular sets is that they
+naturally define towers of simple extensions of a field.
+This allows to perform with multivariate polynomials the 
+same kind of operations as one can do in an \spadtype{EuclideanDomain}.
+
+The \spadtype{RegularTriangularSet} constructor takes four arguments.
+The first one, {\bf R}, is the coefficient ring of the polynomials;
+it must belong to the category \spadtype{GcdDomain}.
+The second one, {\bf E}, is the exponent monoid of the polynomials;
+it must belong to the category \spadtype{OrderedAbelianMonoidSup}.
+the third one, {\bf V}, is the ordered set of variables;
+it must belong to the category \spadtype{OrderedSet}.
+The last one is the polynomial ring;
+it must belong to the category \spadtype{RecursivePolynomialCategory(R,E,V)}.
+The abbreviation for \spadtype{RegularTriangularSet} is
+\spadtype{REGSET}.
+See also the constructor \spadtype{RegularChain} which only takes
+two arguments, the coefficient ring and the ordered set of variables;
+in that case, polynomials are necessarily built with the
+\spadtype{NewSparseMultivariatePolynomial}  domain constructor.
+
+We shall explain now how to use the constructor \spadtype{REGSET} 
+and how to read the decomposition of a polynomial system by means 
+of regular sets.
+
+Let us give some examples.
+We start with an easy one (Donati-Traverso) 
+in order to understand the two ways of
+solving polynomial systems provided by the \spadtype{REGSET} constructor.
+\xtc{
+Define the coefficient ring.
+}{
+\spadpaste{R := Integer \bound{R}}
+}
+\xtc{
+Define the list of variables,
+}{
+\spadpaste{ls : List Symbol := [x,y,z,t] \bound{ls}}
+}
+\xtc{
+and make it an ordered set;
+}{
+\spadpaste{V := OVAR(ls) \free{ls} \bound{V}}
+}
+\xtc{
+then define the exponent monoid.
+}{
+\spadpaste{E := IndexedExponents V \free{V} \bound{E}}
+}
+\xtc{
+Define the polynomial ring.
+}{
+\spadpaste{P := NSMP(R, V) \free{R} \free{V} \bound{P}}
+}
+\xtc{
+Let the variables be polynomial.
+}{
+\spadpaste{x: P := 'x \free{P} \bound{x}}
+}
+\xtc{
+}{
+\spadpaste{y: P := 'y \free{P} \bound{y}}
+}
+\xtc{
+}{
+\spadpaste{z: P := 'z \free{P} \bound{z}}
+}
+\xtc{
+}{
+\spadpaste{t: P := 't \free{P} \bound{t}}
+}
+\xtc{
+Now call the \spadtype{RegularTriangularSet} domain constructor.
+}{
+\spadpaste{T := REGSET(R,E,V,P) \free{R} \free{E} \free{V} \free{P} \bound{T} }
+}
+\xtc{
+Define a polynomial system.
+}{
+\spadpaste{p1 := x ** 31 - x ** 6 - x - y \free{x} \free{y} \bound{p1}}
+}
+\xtc{
+}{
+\spadpaste{p2 := x ** 8  - z \free{x} \free{z} \bound{p2}}
+}
+\xtc{
+}{
+\spadpaste{p3 := x ** 10 - t \free{x} \free{t} \bound{p3}}
+}
+\xtc{
+}{
+\spadpaste{lp := [p1, p2, p3] \free{p1} \free{p2} \free{p3} \bound{lp}}
+}
+\xtc{
+First of all, let us solve this system in the sense of Kalkbrener.
+}{
+\spadpaste{zeroSetSplit(lp)$T \free{lp} \free{T}}
+}
+\xtc{
+And now in the sense of Lazard (or Wu and other authors).
+}{
+\spadpaste{lts := zeroSetSplit(lp,false)$T \free{lp} \free{T} \bound{lts}}
+}
+
+We can see that the first decomposition is a subset of the second.
+So how can both be correct ?
+
+Recall first that polynomials from a domain of the category
+\spadtype{RecursivePolynomialCategory} are regarded
+as univariate polynomials in their main variable.
+For instance the second polynomial in the first set
+of each decomposition has main variable {\bf y}
+and its initial (i.e. its leading coefficient w.r.t. its main
+variable) is {\bf t z}.
+
+Now let us explain how to read the second decomposition.
+Note that the non-constant initials of the first set are
+\texht{$t^4-t$}{{\bf t^4 - t}} and \texht{$t z$}{{\bf t z}}.
+Then the solutions described by this first set are the common
+zeros of its polynomials that do not cancel the polynomials
+\texht{$t^4-t$}{{\bf t^4 - t}} and \texht{$ty z$}{{\bf t z}}.
+Now the solutions of the input system {\bf lp} satisfying
+these equations are described by the second and the third
+sets of the decomposition.
+Thus, in some sense, they can be considered as degenerated
+solutions.
+The solutions given by the first set are called the generic
+points of the system; they give the general form of the
+solutions.
+The first decomposition only provides these generic points.
+This latter decomposition is useful when they are many degenerated 
+solutions (which is sometimes hard to compute) and when
+one is only interested in general informations, like
+the dimension of the input system.
+
+\xtc{
+We can get the dimensions of each component
+of a decomposition as follows.
+}{
+\spadpaste{[coHeight(ts) for ts in lts] \free{lts}}
+}
+
+Thus the first set has dimension one.
+Indeed {\bf t} can take any value, except {\bf 0}
+or any third root of {\bf 1}, whereas {\bf z}
+is completely determined from {\bf t},
+{\bf y} is given by {\bf z} and {\bf t},
+and finally {\bf x} is given by the other three variables.
+In the second and the third sets of the second decomposition
+the four variables are completely determined and thus
+these sets have dimension zero.
+
+We give now the precise specifications of each decomposition. 
+This assume some mathematical knowledge.
+However, for the non-expert user, the above explanations will 
+be sufficient to understand the other features of the
+\spadtype{RSEGSET} constructor.
+
+The input system {\bf lp} is decomposed in the sense
+of Kalkbrener as finitely many regular sets {\bf T1,...,Ts}
+such that the radical ideal generated by {\bf lp}
+is the intersection of the radicals of the
+saturated ideals of {\bf T1,...,Ts}.
+In other words, the affine variety associated with {\bf lp} 
+is the union of the closures (w.r.t. Zarisky topology)
+of the regular-zeros sets of {\bf T1,...,Ts}.
+
+{\bf N. B.} The prime ideals associated with the 
+radical of the saturated ideal of
+a regular triangular set have all the same dimension;
+moreover these prime ideals can be given by characteristic
+sets with the same main variables. 
+Thus a decomposition in the sense of Kalkbrener
+is unmixed dimensional.
+Then it can be viewed as a {\em lazy}
+decomposition into prime ideals (some of these 
+prime ideals being merged into unmixed dimensional ideals).
+
+Now we explain the other way of solving by means of regular 
+triangular sets.
+The input system {\bf lp} is decomposed in the sense
+of Lazard as finitely many regular triangular sets {\bf T1,...,Ts}
+such that the affine variety associated with {\bf lp}
+is the union of the regular-zeros sets of {\bf T1,...,Ts}.
+Thus a decomposition in the sense of Lazard is also
+a decomposition in the sense of Kalkbrener; the converse
+is false as we have seen before.
+
+When the input system has a finite number of solutions,
+both ways of solving provide similar decompositions as
+we shall see with this second example (Caprasse).
+
+
+\xtc{
+Define a polynomial system.
+}{
+\spadpaste{f1 := y**2*z+2*x*y*t-2*x-z \free{z} \free{x} \free{y} \free{t} \bound{f1}}
+}
+\xtc{
+}{
+\spadpaste{f2 :=   -x**3*z+ 4*x*y**2*z+ 4*x**2*y*t+ 2*y**3*t+ 4*x**2- 10*y**2+ 4*x*z- 10*y*t+ 2 \free{z} \free{x} \free{y} \free{t} \bound{f2}}
+}
+\xtc{
+}{
+\spadpaste{f3 :=  2*y*z*t+x*t**2-x-2*z \free{z} \free{x} \free{y} \free{t} \bound{f3}}
+}
+\xtc{
+}{
+\spadpaste{f4 :=   -x*z**3+ 4*y*z**2*t+ 4*x*z*t**2+ 2*y*t**3+ 4*x*z+ 4*z**2-10*y*t- 10*t**2+2 \free{z} \free{x} \free{y} \free{t} \bound{f4}}
+}
+\xtc{
+}{
+\spadpaste{lf := [f1, f2, f3, f4] \free{f1} \free{f2} \free{f3}  \free{f4} \bound{lf}}
+}
+
+\xtc{
+First of all, let us solve this system in the sense of Kalkbrener.
+}{
+\spadpaste{zeroSetSplit(lf)$T \free{lf} \free{T}}
+}
+\xtc{
+And now in the sense of Lazard (or Wu and other authors).
+}{
+\spadpaste{lts2 := zeroSetSplit(lf,false)$T \free{lf} \free{T} \bound{lts2}}
+}
+
+Up to the ordering of the components, both decompositions are identical.
+
+\xtc{
+Let us check that each component has a finite number of solutions.
+}{
+\spadpaste{[coHeight(ts) for ts in lts2] \free{lts2}}
+}
+
+\xtc{
+Let us count the degrees of each component,
+}{
+\spadpaste{degrees := [degree(ts) for ts in lts2] \free{lts2} \bound{degrees}}
+}
+\xtc{
+and compute their sum.
+}{
+\spadpaste{reduce(+,degrees) \free{degrees}}
+}
+
+We study now the options of the \spadfun{zeroSetSplit} operation.
+As we have seen yet, there is an optional second argument 
+which is a boolean value. If this value is true (this
+is the default) then the decomposition is computed
+in the sense of Kalkbrener, otherwise it is computed
+in the sense of Lazard.
+
+There is a second boolean optional argument that
+can be used (in that case the first optional
+argument must be present).
+This second option allows you to get some information
+during the computations.
+
+Therefore, we need to understand a little what is 
+going on during the computations.
+An important feature of the algorithm is that 
+the intermediate computations are managed in some sense 
+like the processes of a Unix system.
+Indeed, each intermediate computation may generate
+other intermediate computations and the management
+of all these computations is a crucial task for
+the efficiency.
+Thus any intermediate computation may be suspended,
+killed or resumed, depending on algebraic considerations
+that determine priorities for these processes.
+The goal is of course to go as fast as possible 
+towards the final decomposition which means to avoid
+as much as possible unnecessary computations.
+
+To follow the computations, one needs to set to
+\spad{true} the second argument.
+Then a lot of numbers and letters are displayed.
+Between a \spad{[} and a \spad{]} one has 
+the state of the processes at a given time.
+Just after \spad{[} one can see the number of
+processes. 
+Then each process is represented by two numbers
+between \spad{<} and \spad{>}.
+A process consists of a list of polynomial {\bf ps}
+and a triangular set {\bf ts}; its goal is to compute
+the common zeros of {\bf ps} that belong to the
+regular-zeros set of {\bf ts}.
+After the processes, the number between pipes
+gives the total number of polynomials
+in all the sets \spad{ps}.
+Finally, the number between braces gives the number
+of components of a decomposition that are already
+computed. This number may decrease.
+
+Let us take a third example (Czapor-Geddes-Wang) to see how these
+informations are displayed.
+
+\xtc{
+Define a polynomial system.
+}{
+\spadpaste{u : R := 2  \free{R} \bound{u}}
+}
+\xtc{
+}{
+\spadpaste{q1 := 2*(u-1)**2+ 2*(x-z*x+z**2)+ y**2*(x-1)**2- 2*u*x+ 2*y*t*(1-x)*(x-z)+ 2*u*z*t*(t-y)+ u**2*t**2*(1-2*z)+ 2*u*t**2*(z-x)+ 2*u*t*y*(z-1)+ 2*u*z*x*(y+1)+ (u**2-2*u)*z**2*t**2+ 2*u**2*z**2+ 4*u*(1-u)*z+ t**2*(z-x)**2 \free{z} \free{x} \free{y} \free{t} \free{u} \bound{q1}}
+}
+\xtc{
+}{
+\spadpaste{q2 := t*(2*z+1)*(x-z)+ y*(z+2)*(1-x)+ u*(u-2)*t+ u*(1-2*u)*z*t+ u*y*(x+u-z*x-1)+ u*(u+1)*z**2*t \free{z} \free{x} \free{y} \free{t} \free{u} \bound{q2}}
+}
+\xtc{
+}{
+\spadpaste{q3 := -u**2*(z-1)**2+ 2*z*(z-x)-2*(x-1) \free{z} \free{x} \free{y} \free{t} \free{u}  \bound{q3}}
+}
+\xtc{
+}{
+\spadpaste{q4 :=   u**2+4*(z-x**2)+3*y**2*(x-1)**2- 3*t**2*(z-x)**2 +3*u**2*t**2*(z-1)**2+u**2*z*(z-2)+6*u*t*y*(z+x+z*x-1) \free{z} \free{x} \free{y} \free{t} \free{u} \bound{q4}}
+}
+\xtc{
+}{
+\spadpaste{lq := [q1, q2, q3, q4] \free{q1} \free{q2} \free{q3}  \free{q4} \bound{lq}}
+}
+
+
+\xtc{
+Let us try the information option.
+N.B. The timing should be between 1 and 10 minutes, depending on your machine.
+}{
+\spadpaste{zeroSetSplit(lq,true,true)$T \free{lq} \free{T}}
+}
+
+Between a sequence of processes, thus between a \spad{]} and a \spad{[}
+you can see capital letters \spad{W, G, I} and lower case letters
+\spad{i, w}. Each time a capital letter appears a non-trivial computation
+has be performed and its result is put in a hash-table.
+Each time a lower case letter appears a needed result has been 
+found in an hash-table.
+The use of these hash-tables generally speed up the computations.
+However, on very large systems, it may happen that these hash-tables
+become too  big  to be handle by your Axiom configuration.
+Then in these exceptional cases, you may prefer getting a result
+(even if it takes a long time) than getting nothing.
+Hence you need to know how to prevent the \spadtype{RSEGSET} constructor
+from using these hash-tables.
+In that case you will be using the \spadfun{zeroSetSplit} with five arguments.
+The first one is the input system {\bf lp} as above.
+The second one is a boolean value \spad{hash?} which is \spad{true}
+iff you want to use hash-tables.
+The third one is boolean value \spad{clos?} which is \spad{true}
+iff you want to solve your system in the sense of Kalkbrener,
+the other way remaining that of Lazard.
+The fourth argument is boolean value \spad{info?} which is \spad{true}
+iff you want to display information during the computations.
+The last one is boolean value \spad{prep?} which is \spad{true}
+iff you want to use some heuristics that are performed on the
+input system before starting the real algorithm.
+The value of this flag is \spad{true} when you are using \spadfun{zeroSetSplit} 
+with less than five arguments.
+Note that there is no available signature for \spadfun{zeroSetSplit} with 
+four arguments.
+
+We finish this section by some remarks about both ways of
+solving, in the sense of Kalkbrener or in the sense of Lazard.
+For problems with a finite number of solutions, there are
+theoretically equivalent and the resulting decompositions
+are identical, up to the ordering of the components.
+However, when solving in the sense of Lazard, the algorithm
+behaves differently.
+In that case, it becomes more incremental than in the sense
+of Kalkbrener. That means the polynomials of the input system
+are considered one after another whereas in the sense of Kalkbrener
+the input system is treated more globally.
+
+This makes an important difference in positive dimension.
+Indeed when solving in the sense of Kalkbrener, the
+{\em Primeidealkettensatz} of Krull is used.
+That means any regular triangular containing more polynomials
+than the input system can be deleted.
+This is not possible when solving in the sense of Lazard.
+This explains why Kalkbrener's decompositions
+usually contain less components than those of Lazard.
+However, it may happen with some examples that the incremental process
+(that cannot be used when solving in the sense of Kalkbrener)
+provide a more efficient way of solving than the global one
+even if the {\em Primeidealkettensatz} is used.
+Thus just try both, with the various options, before concluding 
+that you cannot solve your favorite system with \spadfun{zeroSetSplit}.
+There exist more options at the development level that are not
+currently available in this public version.
+So you are welcome to contact {\em marc@nag.co.uk} for more
+information and help.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{roman.ht}
+<<roman.ht>>=
+\newcommand{\RomanNumeralXmpTitle}{RomanNumeral}
+\newcommand{\RomanNumeralXmpNumber}{9.68}
+
+@
+\subsection{RomanNumeral}
+\label{RomanNumeralXmpPage}
+\index{pages!RomanNumeralXmpPage!roman.ht}
+\index{roman.ht!pages!RomanNumeralXmpPage}
+\index{RomanNumeralXmpPage!roman.ht!pages}
+<<roman.ht>>=
+\begin{page}{RomanNumeralXmpPage}{RomanNumeral}
+\beginscroll
+
+The Roman numeral package was added to Axiom in MCMLXXXVI
+for use in denoting higher order derivatives.
+
+\xtc{
+For example, let \spad{f} be a symbolic operator.
+}{
+\spadpaste{f := operator 'f \bound{f}}
+}
+\xtc{
+This is the seventh derivative of \spad{f} with respect to \spad{x}.
+}{
+\spadpaste{D(f x,x,7) \free{f}}
+}
+\xtc{
+You can have integers printed as Roman numerals by declaring variables to
+be of type \spadtype{RomanNumeral} (abbreviation \spadtype{ROMAN}).
+}{
+\spadpaste{a := roman(1978 - 1965) \bound{a}}
+}
+
+This package now has a small but devoted group of followers that claim
+this domain has shown its efficacy in many other contexts.
+They claim that Roman numerals are every bit as useful as ordinary
+integers.
+\xtc{
+In a sense, they are correct, because Roman numerals form a ring and you
+can therefore construct polynomials with Roman numeral coefficients,
+matrices over Roman numerals, etc..
+}{
+\spadpaste{x : UTS(ROMAN,'x,0) := x \bound{x}}
+}
+\xtc{
+Was Fibonacci Italian or ROMAN?
+}{
+\spadpaste{recip(1 - x - x**2) \free{x}}
+}
+\xtc{
+You can also construct fractions with Roman numeral numerators and
+denominators, as this matrix Hilberticus illustrates.
+}{
+\spadpaste{m : MATRIX FRAC ROMAN \bound{m}}
+}
+\xtc{
+}{
+\spadpaste{m := matrix [[1/(i + j) for i in 1..3] for j in 1..3] \free{m} \bound{m1}}
+}
+\xtc{
+Note that the inverse of the matrix has integral \spadtype{ROMAN} entries.
+}{
+\spadpaste{inverse m \free{m1}}
+}
+\xtc{
+Unfortunately, the spoil-sports say that the fun stops when
+the numbers get big---mostly
+because the Romans didn't establish conventions about representing
+very large numbers.
+}{
+\spadpaste{y := factorial 10 \bound{y}}
+}
+\xtc{
+You work it out!
+}{
+\spadpaste{roman y \free{y}}
+}
+Issue the system command
+\spadcmd{)show RomanNumeral}
+to display the full list of operations defined by
+\spadtype{RomanNumeral}.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{seg.ht}
+<<seg.ht>>=
+\newcommand{\SegmentXmpTitle}{Segment}
+\newcommand{\SegmentXmpNumber}{9.69}
+
+@
+\subsection{Segment}
+\label{SegmentXmpPage}
+\begin{itemize}
+\item SegmentBindingXmpPage \ref{SegmentBindingXmpPage} on
+page~pageref{SegmentBindingXmpPage}
+\item UniversalSegmentXmpPage \ref{UniversalSegmentXmpPage} on
+page~pageref{UniversalSegmentXmpPage}
+\end{itemize}
+\index{pages!SegmentXmpPage!seg.ht}
+\index{seg.ht!pages!SegmentXmpPage}
+\index{SegmentXmpPage!seg.ht!pages}
+<<seg.ht>>=
+\begin{page}{SegmentXmpPage}{Segment}
+\beginscroll
+
+The \spadtype{Segment} domain provides a generalized interval type.
+
+\labelSpace{2pc}
+\xtc{
+Segments are created using the \spadSyntax{..} construct
+by indicating the (included) end points.
+}{
+\spadpaste{s := 3..10 \bound{s}}
+}
+\xtc{
+The first end point is called the \spadfunFrom{lo}{Segment}
+and the second is called \spadfunFrom{hi}{Segment}.
+}{
+\spadpaste{lo s \free{s}}
+}
+\xtc{
+These names are used even though the end points might belong to an
+unordered set.
+}{
+\spadpaste{hi s \free{s}}
+}
+
+\xtc{
+In addition to the end points, each segment has an integer ``increment.''
+An increment can be specified using the ``\spad{by}'' construct.
+\spadkey{by}
+}{
+\spadpaste{t := 10..3 by -2 \bound{t}}
+}
+\xtc{
+This part can be obtained using the \spadfunFrom{incr}{Segment} function.
+}{
+\spadpaste{incr s \free{s}}
+}
+\xtc{
+Unless otherwise specified, the increment is \spad{1}.
+}{
+\spadpaste{incr t \free{t}}
+}
+
+\xtc{
+A single value can be converted to a segment with equal end points.
+This happens if segments and single values are mixed in a list.
+}{
+\spadpaste{l := [1..3, 5, 9, 15..11 by -1] \bound{l}}
+}
+
+\xtc{
+If the underlying type is an ordered ring, it is possible to perform
+additional operations.
+The \spadfunFrom{expand}{Segment} operation creates a list of
+points in a segment.
+}{
+\spadpaste{expand s \free{s}}
+}
+\xtc{
+If \spad{k > 0}, then \spad{expand(l..h by k)} creates the list
+\spad{[l, l+k, ..., lN]} where \spad{lN <= h < lN+k}.
+If \spad{k < 0}, then \spad{lN >= h > lN+k}.
+}{
+\spadpaste{expand t \free{t}}
+}
+
+\xtc{
+It is also possible to expand a list of segments.  This is equivalent
+to appending lists obtained by expanding each segment individually.
+}{
+\spadpaste{expand l \free{l}}
+}
+
+For more information on related topics, see
+\downlink{`SegmentBinding'}{SegmentBindingXmpPage}\ignore{SegmentBinding} and
+\downlink{`UniversalSegment'}{UniversalSegmentXmpPage}
+\ignore{UniversalSegment}.
+%
+\showBlurb{Segment}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{segbind.ht}
+<<segbind.ht>>=
+\newcommand{\SegmentBindingXmpTitle}{SegmentBinding}
+\newcommand{\SegmentBindingXmpNumber}{9.70}
+
+@
+\subsection{SegmentBinding}
+\label{SegmentBindingXmpPage}
+\begin{itemize}
+\item SegmentXmpPage \ref{SegmentXmpPage} on
+page~pageref{SegmentXmpPage}
+\item UniversalSegmentXmpPage \ref{UniversalSegmentXmpPage} on
+page~pageref{UniversalSegmentXmpPage}
+\end{itemize}
+\index{pages!SegmentBindingXmpPage!segbind.ht}
+\index{segbind.ht!pages!SegmentBindingXmpPage}
+\index{SegmentBindingXmpPage!segbind.ht!pages}
+<<segbind.ht>>=
+\begin{page}{SegmentBindingXmpPage}{SegmentBinding}
+\beginscroll
+
+The \spadtype{SegmentBinding} type is used
+to indicate a range for a named symbol.
+
+\labelSpace{2pc}
+\xtc{
+First give the symbol, then an \spadSyntax{=} and finally a
+segment of values.
+}{
+\spadpaste{x = a..b}
+}
+\xtc{
+This is used to provide a convenient
+syntax for arguments to certain operations.
+}{
+\spadpaste{sum(i**2, i = 0..n)}
+}
+\graphpaste{draw(x**2, x = -2..2)}
+
+\xtc{
+The left-hand side must be of type \spadtype{Symbol} but the
+right-hand side can be a segment over any type.
+}{
+\spadpaste{sb := y = 1/2..3/2 \bound{sb}}
+}
+\xtc{
+The left- and right-hand sides can be obtained using the
+\spadfunFrom{variable}{SegmentBinding} and
+\spadfunFrom{segment}{SegmentBinding} operations.
+}{
+\spadpaste{variable(sb) \free{sb}}
+}
+\xtc{
+}{
+\spadpaste{segment(sb)  \free{sb}}
+}
+
+For more information on related topics, see
+\downlink{`Segment'}{SegmentXmpPage}\ignore{Segment} and 
+\downlink{`UniversalSegment'}{UniversalSegmentXmpPage}
+\ignore{UniversalSegment}.
+%
+\showBlurb{SegmentBinding}
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{set.ht}
+<<set.ht>>=
+\newcommand{\SetXmpTitle}{Set}
+\newcommand{\SetXmpNumber}{9.71}
+
+@
+\subsection{Set}
+\label{SetXmpPage}
+See ListXmpPage \ref{ListXmpPage} on page~\pageref{ListXmpPage}
+\index{pages!SetXmpPage!set.ht}
+\index{set.ht!pages!SetXmpPage}
+\index{SetXmpPage!set.ht!pages}
+<<set.ht>>=
+\begin{page}{SetXmpPage}{Set}
+\beginscroll
+
+The \spadtype{Set} domain allows one to represent explicit finite 
+sets of values.
+These are similar to lists, but duplicate elements are not allowed.
+\xtc{
+Sets can be created by giving a fixed set of values \ldots
+}{
+\spadpaste{s := set [x**2-1, y**2-1, z**2-1] \bound{s}}
+}
+\xtc{
+or by using a collect form, just as for lists.
+In either case, the set is formed from a finite collection of values.
+}{
+\spadpaste{t := set [x**i - i+1 for i in 2..10 | prime? i] \bound{t}}
+}
+
+\xtc{
+The basic operations on sets are
+\spadfunFrom{intersect}{Set}, \spadfunFrom{union}{Set},
+\spadfunFrom{difference}{Set},
+and \spadfunFrom{symmetricDifference}{Set}.
+}{
+\spadpaste{i := intersect(s,t)      \free{s t}\bound{i}}
+}
+\xtc{
+}{
+\spadpaste{u := union(s,t)          \free{s t}\bound{u}}
+}
+\xtc{
+The set \spad{difference(s,t)} contains those members of \spad{s} which
+are not in \spad{t}.
+}{
+\spadpaste{difference(s,t)          \free{s t}}
+}
+\xtc{
+The set \spad{symmetricDifference(s,t)} contains those elements which are
+in \spad{s} or \spad{t} but not in both.
+}{
+\spadpaste{symmetricDifference(s,t)          \free{s t}}
+}
+
+\xtc{
+Set membership is tested using the \spadfunFrom{member?}{Set} operation.
+}{
+\spadpaste{member?(y, s)               \free{s}}
+}
+\xtc{
+}{
+\spadpaste{member?((y+1)*(y-1), s)     \free{s}}
+}
+\xtc{
+The \spadfunFrom{subset?}{Set} function determines whether one set is a subset
+of another.
+}{
+\spadpaste{subset?(i, s)               \free{i s}}
+}
+\xtc{
+}{
+\spadpaste{subset?(u, s)               \free{u s}}
+}
+
+\xtc{
+When the base type is finite, the absolute complement of a set is
+defined.
+This finds the set of all multiplicative generators of
+\spadtype{PrimeField 11}---the integers mod \spad{11.}
+}{
+\spadpaste{gs := set [g for i in 1..11 | primitive?(g := i::PF 11)] \bound{gs}}
+}
+\xtc{
+The following values are not generators.
+}{
+\spadpaste{complement gs \free{gs}}
+}
+
+Often the members of a set are computed individually; in addition,
+values can be inserted or removed from a set over the course of a
+computation.
+\xtc{
+There are two ways to do this:
+}{
+\spadpaste{a := set [i**2 for i in 1..5] \bound{a}}
+}
+\xtc{
+One is to view a set as a data structure and to apply updating operations.
+}{
+\spadpaste{insert!(32, a) \free{a}\bound{ainsert}}
+}
+\xtc{
+}{
+\spadpaste{remove!(25, a) \free{a}\bound{aremove}}
+}
+\xtc{
+}{
+\spadpaste{a \free{aremove ainsert}}
+}
+\xtc{
+The other way is to view a set as a mathematical entity and to
+create new sets from old.
+}{
+\spadpaste{b := b0 := set [i**2 for i in 1..5] \bound{b}}
+}
+\xtc{
+}{
+\spadpaste{b := union(b, {32})         \free{b}\bound{binsert}}
+}
+\xtc{
+}{
+\spadpaste{b := difference(b, {25})    \free{binsert}\bound{bremove}}
+}
+\xtc{
+}{
+\spadpaste{b0 \free{bremove}}
+}
+
+For more information about lists, see 
+\downlink{`List'}{ListXmpPage}\ignore{List}.
+\showBlurb{Set}
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{sint.ht}
+<<sint.ht>>=
+\newcommand{\SingleIntegerXmpTitle}{SingleInteger}
+\newcommand{\SingleIntegerXmpNumber}{9.72}
+
+@
+\subsection{SingleInteger}
+\label{SingleIntegerXmpPage}
+\begin{itemize}
+\item ugTypesDeclarePage \ref{ugTypesDeclarePage} on
+page~pageref{ugTypesDeclarePage}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~pageref{ugTypesPkgCallPage}
+\item ugBrowsePage \ref{ugBrowsePage} on
+page~pageref{ugBrowsePage}
+\end{itemize}
+\index{pages!SingleIntegerXmpPage!sint.ht}
+\index{sint.ht!pages!SingleIntegerXmpPage}
+\index{SingleIntegerXmpPage!sint.ht!pages}
+<<sint.ht>>=
+\begin{page}{SingleIntegerXmpPage}{SingleInteger}
+\beginscroll
+
+The \axiomType{SingleInteger} domain is intended to provide support
+in Axiom for machine integer arithmetic.
+It is generally much faster than (bignum) \axiomType{Integer} arithmetic
+but suffers from a limited range of values.
+Since Axiom can be implemented on top of various
+dialects of Lisp, the actual representation of small integers
+may not correspond exactly to the host machines integer representation.
+
+In the CCL implementation of Axiom (Release 2.1 onwards) the underlying
+representation of \axiomType{SingleInteger} 
+is the same as \axiomType{Integer}.  
+The underlying Lisp primitives treat machine-word sized computations
+specially.
+
+\xtc{
+You can discover the minimum and maximum values in your implementation
+by using \spadfunFrom{min}{SingleInteger} and \spadfunFrom{max}{SingleInteger}.
+}{
+\spadpaste{min()\$SingleInteger}
+}
+\xtc{
+}{
+\spadpaste{max()\$SingleInteger}
+}
+\xtc{
+To avoid confusion with \axiomType{Integer}, which is the default
+type for integers, you usually need to work with declared variables
+(\downlink{``\ugTypesDeclareTitle''}{ugTypesDeclarePage} 
+in Section \ugTypesDeclareNumber\ignore{ugTypesDeclare}) \ldots
+}{
+\spadpaste{a := 1234 :: SingleInteger \bound{a}}
+}
+\xtc{
+or use package calling
+(\downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} 
+in Section \ugTypesPkgCallNumber\ignore{ugTypesPkgCall}).
+}{
+\spadpaste{b := 124\$SingleInteger \bound{b}}
+}
+\xtc{
+You can add, multiply and subtract \axiomType{SingleInteger} objects,
+and ask for the greatest common divisor (\spadfun{gcd}).
+}{
+\spadpaste{gcd(a,b) \free{a}\free{b}}
+}
+\xtc{
+The least common multiple (\spadfun{lcm}) is also available.
+}{
+\spadpaste{lcm(a,b) \free{a}\free{b}}
+}
+
+\xtc{
+Operations \spadfunFrom{mulmod}{SingleInteger},
+\spadfunFrom{addmod}{SingleInteger},
+\spadfunFrom{submod}{SingleInteger}, and
+\spadfunFrom{invmod}{SingleInteger} are similar---they provide
+arithmetic modulo a given small integer.
+Here is \spad{5 * 6 {\tt mod} 13}.
+}{
+\spadpaste{mulmod(5,6,13)\$SingleInteger}
+}
+\xtc{
+To reduce a small integer modulo a prime, use 
+\spadfunFrom{positiveRemainder}{SingleInteger}.
+}{
+\spadpaste{positiveRemainder(37,13)\$SingleInteger}
+}
+\xtc{
+Operations
+\spadfunFrom{And}{SingleInteger},
+\spadfunFrom{Or}{SingleInteger},
+\spadfunFrom{xor}{SingleInteger},
+and \spadfunFrom{Not}{SingleInteger}
+provide bit level operations on small integers.
+}{
+\spadpaste{And(3,4)\$SingleInteger}
+}
+\xtc{
+Use
+\spad{shift(int,numToShift)} to shift bits, where
+\spad{i} is shifted left if \spad{numToShift} is positive, right
+if negative.
+}{
+\spadpaste{shift(1,4)\$SingleInteger}
+}
+\xtc{
+}{
+\spadpaste{shift(31,-1)\$SingleInteger}
+}
+
+Many other operations are available for small integers, including
+many of those provided for \axiomType{Integer}.
+To see the other operations, use the Browse \HyperName{} facility
+(\downlink{``\ugBrowseTitle''}{ugBrowsePage} in Section 
+\ugBrowseNumber\ignore{ugBrowse}).
+\showBlurb{SingleInteger}.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{sqmatrix.ht}
+<<sqmatrix.ht>>=
+\newcommand{\SquareMatrixXmpTitle}{SquareMatrix}
+\newcommand{\SquareMatrixXmpNumber}{9.74}
+
+@
+\subsection{SquareMatrix}
+\label{SquareMatrixXmpPage}
+\begin{itemize}
+\item MatrixXmpPage \ref{MatrixXmpPage} on
+page~pageref{MatrixXmpPage}
+\item ugTypesWritingModesPage \ref{ugTypesWritingModesPage} on
+page~pageref{ugTypesWritingModesPage}
+\item ugTypesExposePage \ref{ugTypesExposePage} on
+page~pageref{ugTypesExposePage}
+\end{itemize}
+\index{pages!SquareMatrixXmpPage!sqmatrix.ht}
+\index{sqmatrix.ht!pages!SquareMatrixXmpPage}
+\index{SquareMatrixXmpPage!sqmatrix.ht!pages}
+<<sqmatrix.ht>>=
+\begin{page}{SquareMatrixXmpPage}{SquareMatrix}
+\beginscroll
+ 
+The top level matrix type in Axiom is \spadtype{Matrix}
+(see \downlink{`Matrix'}{MatrixXmpPage}\ignore{Matrix}), which
+provides basic arithmetic and linear algebra functions.
+However, since the matrices can be of any size it is not true that any pair
+can be added or multiplied.
+Thus \spadtype{Matrix} has little algebraic structure.
+ 
+Sometimes you want to use matrices as coefficients for polynomials
+or in other algebraic contexts.  In this case, \spadtype{SquareMatrix}
+should be used.  The domain \spadtype{SquareMatrix(n,R)} gives the ring of
+\spad{n} by \spad{n} square matrices over \spad{R}.
+ 
+\xtc{
+Since \spadtype{SquareMatrix} is not normally exposed at the top level,
+you must expose it before it can be used.
+}{
+\spadpaste{)set expose add constructor SquareMatrix \bound{SQ}}
+}
+\xtc{
+Once \spad{SQMATRIX} has been exposed,
+values can be created using the \spadfunFrom{squareMatrix}{SquareMatrix}
+function.
+}{
+\spadpaste{m := squareMatrix [[1,-\%i],[\%i,4]] \bound{m}\free{SQ}}
+}
+\xtc{
+The usual arithmetic operations are available.
+}{
+\spadpaste{m*m - m \free{m}}
+}
+\xtc{
+Square matrices can be used where ring elements are required.
+For example, here is a matrix with matrix entries.
+}{
+\spadpaste{mm := squareMatrix [[m, 1], [1-m, m**2]] \free{m}\bound{mm}}
+}
+\xtc{
+Or you can construct a polynomial with  square matrix coefficients.
+}{
+\spadpaste{p := (x + m)**2 \free{m}\bound{p}}
+}
+\xtc{
+This value can be converted to a square matrix with polynomial coefficients.
+}{
+\spadpaste{p::SquareMatrix(2, ?) \free{p}}
+}
+ 
+For more information on related topics, see
+\downlink{``\ugTypesWritingModesTitle''}{ugTypesWritingModesPage} 
+in Section \ugTypesWritingModesNumber\ignore{ugTypesWritingModes},
+\downlink{``\ugTypesExposeTitle''}{ugTypesExposePage} 
+in Section \ugTypesExposeNumber\ignore{ugTypesExpose}, and
+\downlink{`Matrix'}{MatrixXmpPage}\ignore{Matrix}.
+\showBlurb{SquareMatrix}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{sregset.ht}
+<<sregset.ht>>=
+\newcommand{\SquareFreeRegularTriangularSetXmpTitle}{SquareFreeRegularTriangularSet}
+\newcommand{\SquareFreeRegularTriangularSetXmpNumber}{9.75}
+
+@
+\subsection{SquareFreeRegularTriangularSet}
+\label{SquareFreeRegularTriangularSetXmpPage}
+\index{pages!SquareFreeRegularTriangularSetXmpPage!sregset.ht}
+\index{sregset.ht!pages!SquareFreeRegularTriangularSetXmpPage}
+\index{SquareFreeRegularTriangularSetXmpPage!sregset.ht!pages}
+<<sregset.ht>>=
+\begin{page}{SquareFreeRegularTriangularSetXmpPage}
+{SquareFreeRegularTriangularSet}
+\beginscroll
+The \spadtype{SquareFreeRegularTriangularSet} domain constructor implements
+square-free regular triangular sets.
+See the \spadtype{RegularTriangularSet} domain constructor
+for general regular triangular sets.
+Let {\em T} be a regular triangular set consisting of polynomials
+{\em t1, ..., tm} ordered by increasing main variables.
+The regular triangular set {\em T} is square-free if {\em T} 
+is empty or if {\em t1, ..., tm-1} is square-free  and if
+the polynomial {\em tm} is square-free as
+a univariate polynomial with coefficients in the tower
+of simple extensions associated with {\em t1, ..., tm-1}.
+
+The main interest of square-free regular triangular sets
+is that their associated towers of simple extensions
+are product of fields.
+Consequently, the saturated ideal of a square-free regular triangular set
+is radical.
+This property simplifies some of the operations related
+to regular triangular sets.
+However, building square-free regular triangular sets
+is generally more  expensive than building
+general regular triangular sets.
+
+As the \spadtype{RegularTriangularSet} domain constructor,
+the \spadtype{SquareFreeRegularTriangularSet} 
+domain constructor also implements
+a method for solving polynomial systems by means of regular triangular sets.
+This is in fact the same method with some adaptations to take into
+account the fact that the computed regular chains are square-free.
+Note that it is also possible to pass from a decomposition
+into general regular triangular sets to a decomposition into
+square-free regular triangular sets.
+This conversion is used internally by the 
+\spadtype{LazardSetSolvingPackage} package constructor.
+
+{\bf N.B.} When solving polynomial systems with the 
+\spadtype{SquareFreeRegularTriangularSet} domain constructor
+or the \spadtype{LazardSetSolvingPackage} package constructor,
+decompositions have no redundant components.
+See also \spadtype{LexTriangularPackage} and 
+\spadtype{ZeroDimensionalSolvePackage} for the case of 
+algebraic systems with a finite number of (complex) solutions.
+
+We shall explain now how to use the constructor 
+\spadtype{SquareFreeRegularTriangularSet}.
+
+This constructor takes four arguments.
+The first one, {\bf R}, is the coefficient ring of the polynomials;
+it must belong to the category \spadtype{GcdDomain}.
+The second one, {\bf E}, is the exponent monoid of the polynomials;
+it must belong to the category \spadtype{OrderedAbelianMonoidSup}.
+the third one, {\bf V}, is the ordered set of variables;
+it must belong to the category \spadtype{OrderedSet}.
+The last one is the polynomial ring;
+it must belong to the category \spadtype{RecursivePolynomialCategory(R,E,V)}.
+The abbreviation for \spadtype{SquareFreeRegularTriangularSet} is
+\spadtype{SREGSET}.
+
+Note that the way of understanding triangular decompositions 
+is detailed in the example of the \spadtype{RegularTriangularSet}
+constructor.
+
+\xtc{
+Let us illustrate the use of this constructor 
+with one example (Donati-Traverso).
+Define the coefficient ring.
+}{
+\spadpaste{R := Integer \bound{R}}
+}
+\xtc{
+Define the list of variables,
+}{
+\spadpaste{ls : List Symbol := [x,y,z,t] \bound{ls}}
+}
+\xtc{
+and make it an ordered set;
+}{
+\spadpaste{V := OVAR(ls) \free{ls} \bound{V}}
+}
+\xtc{
+then define the exponent monoid.
+}{
+\spadpaste{E := IndexedExponents V \free{V} \bound{E}}
+}
+\xtc{
+Define the polynomial ring.
+}{
+\spadpaste{P := NSMP(R, V) \free{R} \free{V} \bound{P}}
+}
+\xtc{
+Let the variables be polynomial.
+}{
+\spadpaste{x: P := 'x \free{P} \bound{x}}
+}
+\xtc{
+}{
+\spadpaste{y: P := 'y \free{P} \bound{y}}
+}
+\xtc{
+}{
+\spadpaste{z: P := 'z \free{P} \bound{z}}
+}
+\xtc{
+}{
+\spadpaste{t: P := 't \free{P} \bound{t}}
+}
+\xtc{
+Now call the \spadtype{SquareFreeRegularTriangularSet} domain constructor.
+}{
+\spadpaste{ST := SREGSET(R,E,V,P) \free{R} \free{E} \free{V} \free{P} \bound{ST} }
+}
+\xtc{
+Define a polynomial system.
+}{
+\spadpaste{p1 := x ** 31 - x ** 6 - x - y \free{x} \free{y} \bound{p1}}
+}
+\xtc{
+}{
+\spadpaste{p2 := x ** 8  - z \free{x} \free{z} \bound{p2}}
+}
+\xtc{
+}{
+\spadpaste{p3 := x ** 10 - t \free{x} \free{t} \bound{p3}}
+}
+\xtc{
+}{
+\spadpaste{lp := [p1, p2, p3] \free{p1} \free{p2} \free{p3} \bound{lp}}
+}
+
+\xtc{
+First of all, let us solve this system in the sense of Kalkbrener.
+}{
+\spadpaste{zeroSetSplit(lp)$ST \free{lp} \free{ST}}
+}
+\xtc{
+And now in the sense of Lazard (or Wu and other authors).
+}{
+\spadpaste{zeroSetSplit(lp,false)$ST \free{lp} \free{ST} \bound{lts}}
+}
+
+Now to see the difference with the \spadtype{RegularTriangularSet} domain constructor,
+\xtc{
+we define:
+}{
+\spadpaste{T := REGSET(R,E,V,P) \free{R} \free{E} \free{V} \free{P} \bound{T} }
+}
+\xtc{
+and compute:
+}{
+\spadpaste{lts := zeroSetSplit(lp,false)$T \free{lp} \free{T} \bound{lts}}
+}
+If you look at the second set in both decompositions in the sense of Lazard,
+you will see that the polynomial with main variable {\bf y} is not the same.
+
+Let us understand what has happened.
+\xtc{
+We define:
+}{
+\spadpaste{ts := lts.2  \free{lts}  \bound{ts}}
+}
+\xtc{
+}{
+\spadpaste{pol := select(ts,'y)$T \free{ts} \free{y} \free{T} \bound{pol}}
+}
+\xtc{
+}{
+\spadpaste{tower := collectUnder(ts,'y)$T \free{ts} \free{y} \free{T} \bound{tower}}
+}
+\xtc{
+}{
+\spadpaste{pack := RegularTriangularSetGcdPackage(R,E,V,P,T) \free{R} \free{E} \free{V} \free{P} \free{T} \bound{pack}}
+}
+\xtc{
+Then we compute:
+}{
+\spadpaste{toseSquareFreePart(pol,tower)$pack \free{pol} \free{tower} \free{pack}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{stbl.ht}
+<<stbl.ht>>=
+\newcommand{\SparseTableXmpTitle}{SparseTable}
+\newcommand{\SparseTableXmpNumber}{9.73}
+
+@
+\subsection{SparseTable}
+\label{SparseTableXmpPage}
+\begin{itemize}
+\item TableXmpPage \ref{TableXmpPage} on
+page~pageref{TableXmpPage}
+\item GeneralSparseTableXmpPage \ref{GeneralSparseTableXmpPage} on
+page~pageref{GeneralSparseTableXmpPage}
+\end{itemize}
+\index{pages!SparseTableXmpPage!stbl.ht}
+\index{stbl.ht!pages!SparseTableXmpPage}
+\index{SparseTableXmpPage!stbl.ht!pages}
+<<stbl.ht>>=
+\begin{page}{SparseTableXmpPage}{SparseTable}
+\beginscroll
+%
+The \spadtype{SparseTable} domain provides a general purpose
+table type with default entries.
+\xtc{
+Here we create a table to save strings under integer keys.
+The value \spad{"Try again!"} is returned if no other value has been
+stored for a key.
+}{
+\spadpaste{t: SparseTable(Integer, String, "Try again!") := table() \bound{t}}
+}
+\xtc{
+Entries can be stored in the table.
+}{
+\spadpaste{t.3 := "Number three" \free{t}\bound{t1}}
+}
+\xtc{
+}{
+\spadpaste{t.4 := "Number four" \free{t}\bound{t2}}
+}
+\xtc{
+These values can be retrieved as usual, but if a look up fails
+the default entry will be returned.
+}{
+\spadpaste{t.3 \free{t1}}
+}
+\xtc{
+}{
+\spadpaste{t.2 \free{t}}
+}
+\xtc{
+To see which values are explicitly stored, the
+\spadfunFrom{keys}{SparseTable} and \spadfunFrom{entries}{SparseTable}
+functions can be used.
+}{
+\spadpaste{keys t \free{t1 t2}}
+}
+\xtc{
+}{
+\spadpaste{entries t \free{t1 t2}}
+}
+If a specific table representation
+is required, the \spadtype{GeneralSparseTable} constructor should be used.
+The domain \spadtype{SparseTable(K, E, dflt)} is equivalent to
+\spadtype{GeneralSparseTable(K,E, Table(K,E), dflt)}.
+For more information, see
+\downlink{`Table'}{TableXmpPage}\ignore{Table} and
+\downlink{`GeneralSparseTable'}{GeneralSparseTableXmpPage}
+\ignore{GeneralSparseTable}.
+\showBlurb{SparseTable}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{stream.ht}
+<<stream.ht>>=
+\newcommand{\StreamXmpTitle}{Stream}
+\newcommand{\StreamXmpNumber}{9.76}
+
+@
+\subsection{Stream}
+\label{StreamXmpPage}
+\begin{itemize}
+\item ugLangItsPage \ref{ugLangItsPage} on
+page~pageref{ugLangItsPage}
+\item ugProblemSeriesPage \ref{ugProblemSeriesPage} on
+page~pageref{ugProblemSeriesPage}
+\item ContinuedFractionXmpPage \ref{ContinuedFractionXmpPage} on
+page~pageref{ContinuedFractionXmpPage}
+\item ListXmpPage \ref{ListXmpPage} on
+page~pageref{ListXmpPage}
+\end{itemize}
+\index{pages!StreamXmpPage!stream.ht}
+\index{stream.ht!pages!StreamXmpPage}
+\index{StreamXmpPage!stream.ht!pages}
+<<stream.ht>>=
+\begin{page}{StreamXmpPage}{Stream}
+\beginscroll
+
+A \spadtype{Stream} object is represented as a list whose 
+last element contains the
+wherewithal to create the next element, should it ever be required.
+\xtc{
+Let \spad{ints} be the infinite stream of non-negative integers.
+}{
+\spadpaste{ints := [i for i in 0..] \bound{ints}}
+}
+By default, ten stream elements are calculated.
+This number may be changed to something else by the system command
+\spadcmd{)set streams calculate}.
+For the display purposes of this book, we have chosen a smaller value.
+\xtc{
+More generally, you can construct a stream by specifying its initial
+value and a function which, when given an element, creates the next element.
+}{
+\spadpaste{f : List INT -> List INT \bound{fdec}}
+}
+\xtc{
+}{
+\spadpaste{f x == [x.1 + x.2, x.1] \bound{f}\free{fdec}}
+}
+\xtc{
+}{
+\spadpaste{fibs := [i.2 for i in [generate(f,[1,1])]] \bound{fibs}\free{f}}
+}
+\xtc{
+You can create the stream of odd non-negative integers by either filtering
+them from the integers, or by evaluating an expression for each integer.
+}{
+\spadpaste{[i for i in ints | odd? i] \free{ints}}
+}
+\xtc{
+}{
+\spadpaste{odds := [2*i+1 for i in ints]\bound{odds}\free{ints}}
+}
+\xtc{
+You can accumulate the initial segments of a stream using the
+\spadfunFrom{scan}{StreamFunctions2} operation.
+}{
+\spadpaste{scan(0,+,odds) \free{odds}}
+}
+\xtc{
+The corresponding elements of
+two or more streams can be combined in this way.
+}{
+\spadpaste{[i*j for i in ints for j in odds]\free{ints} \free{odds}}
+}
+\xtc{
+}{
+\spadpaste{map(*,ints,odds)\free{ints odds}}
+}
+\xtc{
+Many operations similar to those applicable to lists are available for
+streams.
+}{
+\spadpaste{first ints \free{ints}}
+}
+\xtc{
+}{
+\spadpaste{rest ints \free{ints}}
+}
+\xtc{
+}{
+\spadpaste{fibs 20 \free{fibs}}
+}
+The packages \spadtype{StreamFunctions1},
+\spadtype{StreamFunctions2} and
+\spadtype{StreamFunctions3} export some useful stream manipulation
+operations.
+For more information, see
+\downlink{``\ugLangItsTitle''}{ugLangItsPage} in Section 
+\ugLangItsNumber\ignore{ugLangIts},
+\downlink{``\ugProblemSeriesTitle''}{ugProblemSeriesPage} 
+in Section \ugProblemSeriesNumber\ignore{ugProblemSeries},
+\downlink{`ContinuedFraction'}{ContinuedFractionXmpPage}
+\ignore{ContinuedFraction}, and
+\downlink{`List'}{ListXmpPage}\ignore{List}.
+%
+\showBlurb{Stream}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{string.ht}
+<<string.ht>>=
+\newcommand{\StringXmpTitle}{String}
+\newcommand{\StringXmpNumber}{9.77}
+
+@
+\subsection{String}
+\label{StringXmpPage}
+\begin{itemize}
+\item CharacterXmpPage \ref{CharacterXmpPage} on
+page~pageref{CharacterXmpPage}
+\item CharacterClassXmpPage \ref{CharacterClassXmpPage} on
+page~pageref{CharacterClassXmpPage}
+\end{itemize}
+\index{pages!StringXmpPage!string.ht}
+\index{string.ht!pages!StringXmpPage}
+\index{StringXmpPage!string.ht!pages}
+<<string.ht>>=
+\begin{page}{StringXmpPage}{String}
+\beginscroll
+
+The type \spadtype{String} provides character strings.  Character
+strings provide all the operations for a one-dimensional array of
+characters, plus additional operations for manipulating text.  For
+more information on related topics, see
+\downlink{`Character'}{CharacterXmpPage}\ignore{Character} and
+\downlink{`CharacterClass'}{CharacterClassXmpPage}\ignore{CharacterClass}.
+You can also issue the system command \spadcmd{)show String} to
+display the full list of operations defined by \spadtype{String}.
+
+\xtc{
+String values can be created using double quotes.
+}{
+\spadpaste{hello := "Hello, I'm Axiom!" \bound{hello}}
+}
+\xtc{
+Note, however, that double quotes and underscores must be preceded by
+an extra underscore.
+}{
+\spadpaste{said  := "Jane said, _"Look!_"" \bound{said}}
+}
+\xtc{
+}{
+\spadpaste{saw   := "She saw exactly one underscore: __." \bound{saw}}
+}
+\xtc{
+It is also possible to use \spadfunFrom{new}{String} to create a string of any size
+filled with a given character.
+Since there are many \spadfun{new} functions
+it is necessary to indicate the desired type.
+}{
+\spadpaste{gasp: String := new(32, char "x") \bound{gasp}}
+}
+\xtc{
+The length of a string is given by \spadopFrom{\#}{List}.
+}{
+\spadpaste{\#gasp \free{gasp}}
+}
+\xtc{
+Indexing operations allow characters to be extracted or replaced in strings.
+For any string \spad{s}, indices lie in the range \spad{1..\#s}.
+}{
+\spadpaste{hello.2 \free{hello}}
+}
+\xtc{
+Indexing is really just the application of a string to a subscript,
+so any application syntax works.
+}{
+\spadpaste{hello 2  \free{hello}}
+}
+\xtc{
+}{
+\spadpaste{hello(2) \free{hello}}
+}
+\xtc{
+If it is important not to modify a given string, it should be copied
+before any updating operations are used.
+}{
+\spadpaste{hullo := copy hello \free{hello}\bound{hullo0}}
+}
+\xtc{
+}{
+\spadpaste{hullo.2 := char "u"; [hello, hullo] \free{hullo0 hello}\bound{hullo}}
+}
+
+\xtc{
+Operations are provided to split and join strings.
+The \spadfunFrom{concat}{String} operation allows several strings to be joined
+together.
+}{
+\spadpaste{saidsaw := concat ["alpha","---","omega"] \bound{saidsaw}}
+}
+\xtc{
+There is a version of \spadfunFrom{concat}{String} that works with
+two strings.
+}{
+\spadpaste{concat("hello ","goodbye")}
+}
+\xtc{
+Juxtaposition can also be used to concatenate strings.
+}{
+\spadpaste{"This " "is " "several " "strings " "concatenated."}
+}
+\xtc{
+Substrings are obtained by giving an index range.
+}{
+\spadpaste{hello(1..5) \free{hello}}
+}
+\xtc{
+}{
+\spadpaste{hello(8..) \free{hello}}
+}
+\xtc{
+A string can be split into several substrings by giving a separation character
+or character class.
+}{
+\spadpaste{split(hello, char " ")              \free{hello}}
+}
+\xtc{
+}{
+\spadpaste{other := complement alphanumeric(); \bound{other}}
+}
+\xtc{
+}{
+\spadpaste{split(saidsaw, other)               \free{saidsaw other}}
+}
+\xtc{
+Unwanted characters can be trimmed from the beginning or end of a string
+using the operations \spadfunFrom{trim}{String}, \spadfunFrom{leftTrim}{String}
+and \spadfunFrom{rightTrim}{String}.
+}{
+\spadpaste{trim     ("\#\# ++ relax ++ \#\#", char "\#")}
+}
+\xtc{
+Each of these functions takes a string and a second argument to specify
+the characters to be discarded.
+}{
+\spadpaste{trim     ("\#\# ++ relax ++ \#\#", other) \free{other}}
+}
+\xtc{
+The second argument can be given
+either as a single character or as a character class.
+}{
+\spadpaste{leftTrim ("\#\# ++ relax ++ \#\#", other) \free{other}}
+}
+\xtc{
+}{
+\spadpaste{rightTrim("\#\# ++ relax ++ \#\#", other) \free{other}}
+}
+
+\xtc{
+Strings can be changed to upper case or lower case using the operations
+\spadfunFrom{upperCase}{String}, \spadfunFromX{upperCase}{String}, 
+\spadfunFrom{lowerCase}{String} and
+\spadfunFromX{lowerCase}{String}.
+}{
+\spadpaste{upperCase hello \free{hello}}
+}
+\xtc{
+The versions with the exclamation mark
+change the original string, while the others produce a copy.
+}{
+\spadpaste{lowerCase hello \free{hello}}
+}
+
+\xtc{
+Some basic string matching is provided.
+The function \spadfunFrom{prefix?}{String}
+tests whether one string is an initial prefix of another.
+}{
+\spadpaste{prefix?("He", "Hello")}
+}
+\xtc{
+}{
+\spadpaste{prefix?("Her", "Hello")}
+}
+\xtc{
+A similar function, \spadfunFrom{suffix?}{String}, tests for suffixes.
+}{
+\spadpaste{suffix?("", "Hello")}
+}
+\xtc{
+}{
+\spadpaste{suffix?("LO", "Hello")}
+}
+\xtc{
+The function \spadfunFrom{substring?}{String} tests for a substring 
+given a starting
+position.
+}{
+\spadpaste{substring?("ll", "Hello", 3)}
+}
+\xtc{
+}{
+\spadpaste{substring?("ll", "Hello", 4)}
+}
+
+\xtc{
+A number of \spadfunFrom{position}{String} functions locate things in strings.
+If the first argument to position is a string, then \spad{position(s,t,i)}
+finds the location of \spad{s} as a substring of \spad{t} starting the
+search at position \spad{i}.
+}{
+\spadpaste{n := position("nd", "underground",   1) \bound{n}}
+}
+\xtc{
+}{
+\spadpaste{n := position("nd", "underground", n+1) \free{n} \bound{n1}}
+}
+\xtc{
+If \spad{s} is not found, then \spad{0} is returned (\spad{minIndex(s)-1}
+in \spadtype{IndexedString}).
+}{
+\spadpaste{n := position("nd", "underground", n+1) \free{n1}\bound{n2}}
+}
+\xtc{
+To search for a specific character or a member of a character class,
+a different first argument is used.
+}{
+\spadpaste{position(char "d", "underground", 1)}
+}
+\xtc{
+}{
+\spadpaste{position(hexDigit(), "underground", 1)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{strtbl.ht}
+<<strtbl.ht>>=
+\newcommand{\StringTableXmpTitle}{StringTable}
+\newcommand{\StringTableXmpNumber}{9.78}
+
+@
+\subsection{StringTable}
+\label{StringTableXmpPage}
+See TableXmpPage \ref{TableXmpPage} on page~\pageref{TableXmpPage}
+\index{pages!StringTableXmpPage!strtbl.ht}
+\index{strtbl.ht!pages!StringTableXmpPage}
+\index{StringTableXmpPage!strtbl.ht!pages}
+<<strtbl.ht>>=
+\begin{page}{StringTableXmpPage}{StringTable}
+\beginscroll
+%
+This domain provides a table type in which the keys are known to
+be strings so special techniques can be used.
+Other than performance, the type \spadtype{StringTable(S)} should
+behave exactly the same way as \spadtype{Table(String,S)}.
+See \downlink{`Table'}{TableXmpPage}\ignore{Table} 
+for general information about tables.
+\showBlurb{StringTable}
+
+\xtc{
+This creates a new table whose keys are strings.
+}{
+\spadpaste{t: StringTable(Integer) := table()  \bound{t}}
+}
+\xtc{
+The value associated with each string key is the number of
+characters in the string.
+}{
+\begin{spadsrc}[\free{t}\bound{h}]
+for s in split("My name is Ian Watt.",char " ")
+  repeat
+    t.s := #s
+\end{spadsrc}
+}
+\xtc{
+}{
+\spadpaste{for key in keys t repeat output [key, t.key] \free{t h}}
+}
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{symbol.ht}
+<<symbol.ht>>=
+\newcommand{\SymbolXmpTitle}{Symbol}
+\newcommand{\SymbolXmpNumber}{9.79}
+
+@
+\subsection{Symbol}
+\label{SymbolXmpPage}
+\index{pages!SymbolXmpPage!symbol.ht}
+\index{symbol.ht!pages!SymbolXmpPage}
+\index{SymbolXmpPage!symbol.ht!pages}
+<<symbol.ht>>=
+\begin{page}{SymbolXmpPage}{Symbol}
+\beginscroll
+ 
+Symbols are one of the basic types manipulated by Axiom.
+The \spadtype{Symbol} domain provides ways to create
+symbols of many varieties.
+\showBlurb{Symbol}
+ 
+\xtc{
+The simplest way to create a symbol is to ``single quote'' an identifier.
+}{
+\spadpaste{X: Symbol := 'x \bound{X}}
+}
+\xtc{
+This gives the symbol even if \spad{x} has been assigned a value.
+If \spad{x} has not been assigned a value, then it is possible to omit
+the quote.
+}{
+\spadpaste{XX: Symbol := x}
+}
+\xtc{
+Declarations must be used when working
+with symbols, because otherwise the interpreter tries to place
+values in a more specialized type \spadtype{Variable}.
+}{
+\spadpaste{A := 'a}
+}
+\xtc{
+}{
+\spadpaste{B := b}
+}
+\xtc{
+The normal way of entering polynomials uses this fact.
+}{
+\spadpaste{x**2 + 1}
+}
+ 
+\xtc{
+Another convenient way to create symbols is to convert a string.
+This is useful when the name is to be constructed by a program.
+}{
+\spadpaste{"Hello"::Symbol}
+}
+\xtc{
+Sometimes it is necessary to generate new unique symbols, for example, to
+name constants of integration.
+The expression \spad{new()} generates a symbol starting with \spad{\%}.
+}{
+\spadpaste{new()\$Symbol}
+}
+\xtc{
+Successive calls to \spadfunFrom{new}{Symbol} produce different symbols.
+}{
+\spadpaste{new()\$Symbol}
+}
+\xtc{
+The expression \spad{new("s")} produces a symbol starting with \spad{\%s}.
+}{
+\spadpaste{new("xyz")\$Symbol}
+}
+ 
+\xtc{
+A symbol can be adorned in various ways.
+The most basic thing is applying a symbol to a list
+of subscripts.
+}{
+\spadpaste{X[i,j] \free{X}}
+}
+ 
+\xtc{
+Somewhat less pretty is to attach subscripts, superscripts or arguments.
+}{
+\spadpaste{U := subscript(u, [1,2,1,2]) \bound{U}}
+}
+\xtc{
+}{
+\spadpaste{V := superscript(v, [n]) \bound{V}}
+}
+\xtc{
+}{
+\spadpaste{P := argscript(p, [t]) \bound{P}}
+}
+ 
+\xtc{
+It is possible to test whether a symbol has scripts using the
+\spadfunFrom{scripted?}{Symbol} test.
+}{
+\spadpaste{scripted? U \free{U}}
+}
+\xtc{
+}{
+\spadpaste{scripted? X \free{X}}
+}
+\xtc{
+If a symbol is not scripted, then it may be converted to a string.
+}{
+\spadpaste{string X \free{X}}
+}
+\xtc{
+The basic parts can always be extracted using the
+\spadfunFrom{name}{Symbol} and \spadfunFrom{scripts}{Symbol} operations.
+}{
+\spadpaste{name U \free{U}}
+}
+\xtc{
+}{
+\spadpaste{scripts U \free{U}}
+}
+\xtc{
+}{
+\spadpaste{name X \free{X}}
+}
+\xtc{
+}{
+\spadpaste{scripts X \free{X}}
+}
+ 
+\xtc{
+The most general form is obtained using the \spadfunFrom{script}{Symbol}
+operation.
+This operation takes an argument which is a list containing, in this order,
+lists of subscripts, superscripts, presuperscripts, presubscripts and
+arguments to a symbol.
+}{
+\spadpaste{M := script(Mammoth, [[i,j],[k,l],[0,1],[2],[u,v,w]]) \bound{M}}
+}
+\xtc{
+}{
+\spadpaste{scripts M \free{M}}
+}
+\xtc{
+If trailing lists of scripts are omitted, they are assumed to be empty.
+}{
+\spadpaste{N := script(Nut, [[i,j],[k,l],[0,1]]) \bound{N}}
+}
+\xtc{
+}{
+\spadpaste{scripts N \free{N}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{table.ht}
+<<table.ht>>=
+\newcommand{\TableXmpTitle}{Table}
+\newcommand{\TableXmpNumber}{9.80}
+
+@
+\subsection{Table}
+\label{TableXmpPage}
+\begin{itemize}
+\item AssociationListXmpPage \ref{AssociationListXmpPage} on
+page~pageref{AssociationListXmpPage}
+\item EqTableXmpPage \ref{EqTableXmpPage} on
+page~pageref{EqTableXmpPage}
+\item StringTableXmpPage \ref{StringTableXmpPage} on
+page~pageref{StringTableXmpPage}
+\item SparseTableXmpPage \ref{SparseTableXmpPage} on
+page~pageref{SparseTableXmpPage}
+\item KeyedAccessFileXmpPage \ref{KeyedAccessFileXmpPage} on
+page~pageref{KeyedAccessFileXmpPage}
+\end{itemize}
+\index{pages!TableXmpPage!table.ht}
+\index{table.ht!pages!TableXmpPage}
+\index{TableXmpPage!table.ht!pages}
+<<table.ht>>=
+\begin{page}{TableXmpPage}{Table}
+\beginscroll
+
+The \spadtype{Table} constructor provides a general structure
+for associative storage.
+This type provides hash tables in which data objects
+can be saved according to keys of any type.
+For a given table, specific types must be chosen for the keys and entries.
+
+\xtc{
+In this example the keys to the table are polynomials with
+integer coefficients.
+The entries in the table are strings.
+}{
+\spadpaste{t: Table(Polynomial Integer, String) := table() \bound{t}}
+}
+\xtc{
+To save an entry in the table, the \spadfunFrom{setelt}{Table} operation is used.
+This can be called directly, giving the table a key and an entry.
+}{
+\spadpaste{setelt(t, x**2 - 1, "Easy to factor") \bound{p1}\free{t}}
+}
+\xtc{
+Alternatively, you can use assignment syntax.
+}{
+\spadpaste{t(x**3 + 1) := "Harder to factor" \bound{p2}\free{p1}}
+}
+\xtc{
+}{
+\spadpaste{t(x)        := "The easiest to factor" \bound{p3}\free{p2}}
+}
+\xtc{
+Entries are retrieved from the table by calling the
+\spadfunFrom{elt}{Table} operation.
+}{
+\spadpaste{elt(t, x) \free{p3}}
+}
+\xtc{
+This operation is called when a table is ``applied'' to a key using
+this or the following syntax.
+}{
+\spadpaste{t.x \free{p3}}
+}
+\xtc{
+}{
+\spadpaste{t x \free{p3}}
+}
+\xtc{
+Parentheses are used only for grouping.  They are needed if the key is
+an infixed expression.
+}{
+\spadpaste{t.(x**2 - 1) \free{p3}}
+}
+\xtc{
+Note that the \spadfunFrom{elt}{Table} operation is used only when the
+key is known to be in the table---otherwise an error is generated.
+}{
+\spadpaste{t (x**3 + 1) \free{p3}}
+}
+
+\xtc{
+You can get a list of all the keys to a table using the
+\spadfunFrom{keys}{Table} operation.
+}{
+\spadpaste{keys t \free{p3}}
+}
+\xtc{
+If you wish to test whether a key is in a table, the
+\spadfunFrom{search}{Table} operation is used.
+This operation returns either an entry or \spad{"failed"}.
+}{
+\spadpaste{search(x, t) \free{p3}}
+}
+\xtc{
+}{
+\spadpaste{search(x**2, t) \free{p3}}
+}
+\xtc{
+The return type is a union so the success of the search can be tested
+using \spad{case}.
+\spadkey{case}
+}{
+\spadpaste{search(x**2, t) case "failed" \free{p3}}
+}
+\xtc{
+The \spadfunFromX{remove}{Table} operation is used to delete values from a
+table.
+}{
+\spadpaste{remove!(x**2-1, t) \free{p3} \bound{p4}}
+}
+\xtc{
+If an entry exists under the key, then it is returned.  Otherwise
+\spadfunFromX{remove}{Table} returns \spad{"failed"}.
+}{
+\spadpaste{remove!(x-1, t) \free{p4}\bound{p5}}
+}
+
+\xtc{
+The number of key-entry pairs can be found using the
+\spadfunFrom{\#}{Table} operation.
+}{
+\spadpaste{\#t \free{p5}}
+}
+\xtc{
+Just as \spadfunFrom{keys}{Table} returns a list of keys to the table, a
+list of all the entries can be obtained using the
+\spadfunFrom{members}{Table} operation.
+}{
+\spadpaste{members t \free{p5}}
+}
+\xtc{
+A number of useful operations take functions and map them on to the
+table to compute the result.  Here we count the entries which
+have \spad{"Hard"} as a prefix.
+}{
+\spadpaste{count(s: String +-> prefix?("Hard", s), t) \free{p5}}
+}
+
+Other table types are provided to support various needs.
+\indent{4}
+\beginitems
+\item[-] \spadtype{AssociationList} gives a list with a table view.
+This allows new entries to be appended onto the front of the list
+to cover up old entries.
+This is useful when table entries need to be stacked or when
+frequent list traversals are required.
+See 
+\downlink{`AssociationList'}{AssociationListXmpPage}\ignore{AssociationList} 
+for more information.
+\item[-] \spadtype{EqTable} gives tables in which keys are considered
+equal only when they are in fact the same instance of a structure.
+See \downlink{`EqTable'}{EqTableXmpPage}\ignore{EqTable} for more information.
+\item[-] \spadtype{StringTable} should be used when the keys are known to
+be strings.
+See \downlink{`StringTable'}{StringTableXmpPage}\ignore{StringTable} 
+for more information.
+\item[-] \spadtype{SparseTable} provides tables with default
+entries, so
+lookup never fails.  The \spadtype{GeneralSparseTable} constructor
+can be used to make any table type behave this way.
+See \downlink{`SparseTable'}{SparseTableXmpPage}\ignore{SparseTable} 
+for more information.
+\item[-] \spadtype{KeyedAccessFile} allows values to be saved in a file,
+accessed as a table.
+See 
+\downlink{`KeyedAccessFile'}{KeyedAccessFileXmpPage}\ignore{KeyedAccessFile} 
+for more information.
+\enditems
+\indent{0}
+%
+\showBlurb{Table}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{textfile.ht}
+<<textfile.ht>>=
+\newcommand{\TextFileXmpTitle}{TextFile}
+\newcommand{\TextFileXmpNumber}{9.81}
+
+@
+\subsection{TextFile}
+\label{TextFileXmpPage}
+\begin{itemize}
+\item FileXmpPage \ref{FileXmpPage} on
+page~pageref{FileXmpPage}
+\item KeyedAccessFileXmpPage \ref{KeyedAccessFileXmpPage} on
+page~pageref{KeyedAccessFileXmpPage}
+\item LibraryXmpPage \ref{LibraryXmpPage} on
+page~pageref{LibraryXmpPage}
+\end{itemize}
+\index{pages!TextFileXmpPage!textfile.ht}
+\index{textfile.ht!pages!TextFileXmpPage}
+\index{TextFileXmpPage!textfile.ht!pages}
+<<textfile.ht>>=
+\begin{page}{TextFileXmpPage}{TextFile}
+\beginscroll
+
+The domain \spadtype{TextFile} allows Axiom to read and write
+character data and exchange text with other programs.
+This type behaves in Axiom much like a \spadtype{File} of strings,
+with additional operations to cause new lines.
+We give an example of how to produce an upper case copy of a file.
+\xtc{
+This is the file from which we read the text.
+}{
+\spadpaste{f1: TextFile := open("/etc/group", "input")   \bound{f1}}
+}
+\xtc{
+This is the file to which we read the text.
+}{
+\spadpaste{f2: TextFile := open("/tmp/MOTD", "output")  \bound{f2}}
+}
+\xtc{
+Entire lines are handled using the \spadfunFromX{readLine}{TextFile} and
+\spadfunFromX{writeLine}{TextFile} operations.
+}{
+\spadpaste{l := readLine! f1 \free{f1}\bound{l}}
+}
+\xtc{
+}{
+\spadpaste{writeLine!(f2, upperCase l) \free{f2 l}}
+}
+\xtc{
+Use the
+\spadfunFrom{endOfFile?}{TextFile} operation to check if you have
+reached the end of the file.
+}{
+\begin{spadsrc}[\free{f1 f2}\bound{Copied}]
+while not endOfFile? f1 repeat
+    s := readLine! f1
+    writeLine!(f2, upperCase s)
+\end{spadsrc}
+}
+\xtc{
+The file \spad{f1} is exhausted and should be closed.
+}{
+\spadpaste{close! f1  \free{Copied}\bound{closed1}}
+}
+
+\xtc{
+It is sometimes useful to write lines a bit at a time.
+The \spadfunFromX{write}{TextFile} operation allows this.
+}{
+\spadpaste{write!(f2, "-The-")  \free{Copied}\bound{tthhee}}
+}
+\xtc{
+}{
+\spadpaste{write!(f2, "-End-")  \free{tthhee}\bound{eenndd}}
+}
+\xtc{
+This ends the line.
+This is done in a machine-dependent manner.
+}{
+\spadpaste{writeLine! f2        \free{eenndd}\bound{LastLine}}
+}
+\xtc{
+}{
+\spadpaste{close! f2              \free{LastLine}\bound{closed2}}
+}
+\noOutputXtc{
+Finally, clean up.
+}{
+\spadpaste{)system rm /tmp/MOTD   \free{closed2}}
+}
+
+For more information on related topics,  see
+\downlink{`File'}{FileXmpPage}\ignore{File},
+\downlink{`KeyedAccessFile'}{KeyedAccessFileXmpPage}\ignore{KeyedAccessFile}, and
+\downlink{`Library'}{LibraryXmpPage}\ignore{Library}.
+\showBlurb{TextFile}
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{topics.ht}
+\subsection{Axiom Topics}
+\label{TopicPage}
+\includegraphics[scale=.5]{ps/v71topics.eps}
+\index{images!topics}
+
+Called from ``Root Page'' (RootPage) \ref{RootPage} on page~\pageref{RootPage}
+\begin{itemize}
+\item ``Numbers'' (NumberPage) \ref{NumberPage} on page~\pageref{NumberPage}
+\item ``Polynomials'' (PolynomialPage) 
+\ref{PolynomialPage} on page~\pageref{PolynomialPage}
+\item ``Functions'' (FunctionPage) 
+\ref{FunctionPage} on page~\pageref{FunctionPage}
+\item ``Solving Equations'' (EquationPage) 
+\ref{EquationPage} on page~\pageref{EquationPage}
+\item ``Calculus'' (CalculusPage) 
+\ref{CalculusPage} on page~\pageref{CalculusPage}
+\item ``Linear Algebra'' (LinAlgPage) 
+\ref{LinAlgPage} on page~\pageref{LinAlgPage}
+\item ``Graphics'' (GraphicsPage) 
+\ref{GraphicsPage} on page~\pageref{GraphicsPage}
+\item ``Algebra'' (AlgebraPage) 
+\ref{AlgebraPage} on page~\pageref{AlgebraPage}
+\end{itemize}
+\index{pages!TopicPage!topics.ht}
+\index{topics.ht!pages!TopicPage}
+\index{TopicPage!topics.ht!pages}
+<<topics.ht>>=
+\begin{page}{TopicPage}{Axiom Topics}
+\beginscroll
+Select a topic below: % or
+%\lispmemolink{search}{(|htTutorialSearch| '|\stringvalue{pattern}|))}
+%for string (use {\em *} for wild card):
+%\newline\inputstring{pattern}{58}{}
+\beginmenu
+\menumemolink{Numbers}{NumberPage}\tab{18}
+A look at different types of numbers
+
+\menumemolink{Polynomials}{PolynomialPage}\tab{18}
+Polynomials in Axiom
+%
+\menumemolink{Functions}{FunctionPage}\tab{18}
+Built-in and user-defined functions
+%
+\menumemolink{Solving Equations}{EquationPage}\tab{18}
+Facilities for solving equations
+%
+\menumemolink{Calculus}{CalculusPage}\tab{18}
+Using Axiom to do calculus
+%
+\menumemolink{Linear Algebra}{LinAlgPage}\tab{18}
+Axiom's linear algebra facilities
+%
+\menumemolink{Graphics}{GraphicsPage}\tab{18}
+Axiom's graphics facilities
+%
+\menumemolink{Algebra}{AlgebraPage}\tab{18}
+Axiom's abstract algebra facilities
+%
+\endmenu
+\endscroll
+\end{page}
+
+@
+\subsection{Solving Equations}
+\label{EquationPage}
+\includegraphics[scale=.5]{ps/v71equationpage.eps}
+\index{images!equationpage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
+\begin{itemize}
+\item ``Solution of Systems of Linear Equations''\\
+(ugxProblemLinSysPage) \ref{ugxProblemLinSysPage} on 
+page~\pageref{ugxProblemLinSysPage}
+\item ``Solution of a Single Polynomial Equation''\\
+(ugxProblemOnePolPage) \ref{ugxProblemOnePolPage} on 
+page~\pageref{ugxProblemOnePolPage}
+\item ``Solution of Systems of Polynomial Equations''\\
+(ugxProblemPolSysPage) \ref{ugxProblemPolSysPage} on 
+page~\pageref{ugxProblemPolSysPage}
+\item ``Solution of Differential Equations''\\
+(ugProblemDEQPage) \ref{ugProblemDEQPage} on 
+page~\pageref{ugProblemDEQPage}
+\end{itemize}
+\index{pages!EquationPage!topics.ht}
+\index{topics.ht!pages!EquationPage}
+\index{EquationPage!topics.ht!pages}
+<<topics.ht>>=
+\begin{page}{EquationPage}{Solving Equations}
+\beginscroll
+Axiom lets you solve equations of various types:
+\beginmenu
+  \menulink{Solution of Systems of Linear Equations}{ugxProblemLinSysPage}
+    \newline Solve systems of linear equations.
+  \menulink{Solution of a Single Polynomial Equation}{ugxProblemOnePolPage}
+    \newline Find roots of polynomials.
+  \menulink{Solution of Systems of Polynomial Equations}{ugxProblemPolSysPage}
+  \newline Solve systems of polynomial equations.
+  \menulink{Solution of Differential Equations}{ugProblemDEQPage}
+  \newline Closed form and series solutions of differential equations.
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Linear Algebra}
+\label{LinAlgPage}
+\includegraphics[scale=.5]{ps/v71linalgpage.eps}
+\index{images!linalgpage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
+\begin{itemize}
+\item ``Introduction'' (ugIntroTwoDimPage) 
+\ref{ugIntroTwoDimPage} on page~\pageref{ugIntroTwoDimPage}
+\item ``Creating Matrices'' (ugxMatrixCreatePage) 
+\ref{ugxMatrixCreatePage} on page~\pageref{ugxMatrixCreatePage}
+\item ``Operations on Matrices'' (ugxMatrixOpsPage) 
+\ref{ugxMatrixOpsPage} on page~\pageref{ugxMatrixOpsPage}
+\item ``Eigenvalues and Eigenvectors'' (ugProblemEigenPage) 
+\ref{ugProblemEigenPage} on page~\pageref{ugProblemEigenPage}
+\item ``Example: Determinant of a Hilbert Matrix'' (ugxFloatHilbertPage) 
+\ref{ugxFloatHilbertPage} on page~\pageref{ugxFloatHilbertPage}
+\item ``Computing the Permanent'' (PermanentXmpPage) 
+\ref{PermanentXmpPage} on page~\pageref{PermanentXmpPage}
+\item ``Working with Vectors'' (VectorXmpPage) 
+\ref{VectorXmpPage} on page~\pageref{VectorXmpPage}
+\item ``Working with Square Matrices'' (SquareMatrixXmpPage) 
+\ref{SquareMatrixXmpPage} on page~\pageref{SquareMatrixXmpPage}
+\item ``Working with One-dimensional Arrays'' (OneDimensionalArrayXmpPage) 
+\ref{OneDimensionalArrayXmpPage} on page~\pageref{OneDimensionalArrayXmpPage}
+\item ``Working with Two-dimensional Arrays'' (TwoDimensionalArrayXmpPage) 
+\ref{TwoDimensionalArrayXmpPage} on page~\pageref{TwoDimensionalArrayXmpPage}
+\item ``Conversion (Polynomials of Matrices)'' (ugTypesConvertPage) 
+\ref{ugTypesConvertPage} on page~\pageref{ugTypesConvertPage}
+\end{itemize}
+\index{pages!LinAlgPage!topics.ht}
+\index{topics.ht!pages!LinAlgPage}
+\index{LinAlgPage!topics.ht!pages}
+<<topics.ht>>=
+\begin{page}{LinAlgPage}{Linear Algebra}
+\beginscroll
+\beginmenu
+
+\menulink{Introduction}{ugIntroTwoDimPage}\newline
+
+Create and manipulate matrices.
+Work with the entries of a matrix.
+Perform matrix arithmetic.
+
+\menulink{Creating Matrices}{ugxMatrixCreatePage} \newline
+
+Create matrices from scratch and from other matrices.
+
+\menulink{Operations on Matrices}{ugxMatrixOpsPage} \newline
+
+Algebraic manipulations with matrices.
+Compute the inverse, determinant and trace of a matrix.
+Find the rank, nullspace and row echelon form of a matrix.
+
+\menulink{Eigenvalues and Eigenvectors}{ugProblemEigenPage} \newline
+
+How to compute eigenvalues and eigenvectors.
+\endmenu
+\horizontalline\newline
+Additional Topics:
+\beginmenu
+\menulink{Example: Determinant of a Hilbert Matrix}{ugxFloatHilbertPage}
+\menulink{Computing the Permanent}{PermanentXmpPage}
+\menulink{Working with Vectors}{VectorXmpPage}
+\menulink{Working with Square Matrices}{SquareMatrixXmpPage}
+\menulink{Working with One-Dimensional Arrays}{OneDimensionalArrayXmpPage}
+\menulink{Working with Two-Dimensional Arrays}{TwoDimensionalArrayXmpPage}
+\menulink{Conversion (Polynomials of Matrices)}{ugTypesConvertPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\subsection{Calculus}
+\label{CalculusPage}
+\includegraphics[scale=.5]{ps/v71calculuspage.eps}
+\index{images!calculuspage}
+
+Called from ``Topics'' (TopicPage) \ref{TopicPage} on page~\pageref{TopicPage}
+\begin{itemize}
+\item ``Limits'' (ugProblemLimitsPage) \ref{ugProblemLimitsPage} on 
+page~\pageref{ugProblemLimitsPage}
+\item ``Derivatives'' (ugIntroCalcDerivPage) \ref{ugIntroCalcDerivPage} on 
+page~\pageref{ugIntroCalcDerivPage}
+\item ``Integrals'' (ugIntroIntegratePage) \ref{ugIntroIntegratePage} on 
+page~\pageref{ugIntroIntegratePage}
+\item ``More Integrals'' (ugProblemIntegrationPage) 
+\ref{ugProblemIntegrationPage} on 
+page~\pageref{ugProblemIntegrationPage}
+\item ``Laplace'' (ugProblemLaplacePage) \ref{ugProblemLaplacePage} on 
+page~\pageref{ugProblemLaplacePage}
+\item ``Series'' (ugProblemSeriesPage)n \ref{ugProblemSeriesPage} on 
+page~\pageref{ugProblemSeriesPage}
+\item ``Differential Eqns'' (ugProblemDEQPage) \ref{ugProblemDEQPage} on 
+page~\pageref{ugProblemDEQPage}
+\end{itemize}
+\index{pages!CalculusPage!topics.ht}
+\index{topics.ht!pages!CalculusPage}
+\index{CalculusPage!topics.ht!pages}
+<<topics.ht>>=
+\begin{page}{CalculusPage}{Calculus}
+\beginscroll
+\beginmenu
+\menulink{Limits}{ugProblemLimitsPage} \tab{17}
+Compute limits of functional expressions.
+\menulink{Derivatives}{ugIntroCalcDerivPage}\tab{17}
+Compute derivatives and partial derivatives.
+\menulink{Integrals}{ugIntroIntegratePage}\tab{17}
+Introduction to Axiom's symbolic integrator.
+\menulink{More Integrals}{ugProblemIntegrationPage}\tab{17}
+More information about symbolic integration.
+\menulink{Laplace}{ugProblemLaplacePage}\tab{17}
+Computing Laplace transforms.
+\menulink{Series}{ugProblemSeriesPage}\tab{17}
+Compute series expansions of expressions.
+\menulink{Differential Eqns}{ugProblemDEQPage}\tab{17}
+Solve differential equations.
+\endmenu
+\endscroll
+\autobuttons \end{page}
+
+@
+\section{type.ht}
+@
+\subsection{Category {\bf Type}}
+\label{CategoryType}
+\index{pages!CategoryType!type.ht}
+\index{type.ht!pages!CategoryType}
+\index{CategoryType!type.ht!pages}
+<<type.ht>>=
+\begin{page}{CategoryType}{Category {\em Type}}
+\beginscroll
+{\em Type} is a primitive category in Axiom,
+one which is an ancestor of all Axiom categories.
+
+{\em Type} is the root of Axiom's category hierarchy,
+a category with no properties (exported operations 
+and attributes) of which all other categories are descendants.
+Two important children of {\em Type} are
+\spadtype{SetCategory}, the category of all algebraic domains,
+and \spadtype{Aggregate}, the category of all data structures.
+\endscroll
+
+@
+\section{union.ht}
+\subsection{Domain {\bf Union(a:A,...,b:B)}}
+\label{DomainUnion}
+\index{pages!DomainUnion!union.ht}
+\index{union.ht!pages!DomainUnion}
+\index{DomainUnion!union.ht!pages}
+<<union.ht>>=
+\begin{page}{DomainUnion}{Domain {\em Union(a:A,...,b:B)}}
+\beginscroll
+{\em Union} takes any number of "tag"-domain pairs of arguments:
+\indentrel{2}
+\newline \spad{a}, a tag, an element of domain \spadtype{Symbol}
+\newline \spad{A}, a domain of category \spadtype{SetCategory}
+\newline\tab{10}...
+\newline \spad{b}, a tag, an element of domain \spadtype{Symbol}
+\newline \spad{B}, a domain of category \spadtype{SetCategory}
+\indentrel{-2}\newline
+This constructor is a primitive in Axiom. 
+\newline
+\beginmenu
+\item\menulispdownlink{Description}{(|dbSpecialDescription| '|Union|)) }\tab{15}General description
+\item\menulispdownlink{Operations}{(|dbSpecialOperations| '|Union|)}\tab{15}All exported operations of \spad{Union(a:A,b:B)}
+%\item\menudownlink{Examples}   {UnionExamples}   \tab{15}Examples illustrating use
+\item\menulispdownlink{Exports}{(|dbSpecialExports| '|Union|)}\tab{15}Explicit categories and operations
+\endmenu
+\vspace{1}\newline
+In this tagged \spad{Union}, tags \spad{a,...,b} must be distinct. 
+\newline
+For an alternate "untagged" form of \spad{Union}, see \downlink{Union(A,B)}{UntaggedUnion}.
+\endscroll\end{page}
+ 
+@
+\subsection{Domain Constructor {\bf Union}}
+\label{UnionDescription}
+\index{pages!UnionDescription!union.ht}
+\index{union.ht!pages!UnionDescription}
+\index{UnionDescription!union.ht!pages}
+<<union.ht>>=
+\begin{page}{UnionDescription}{Domain Constructor {\em Union}}
+\beginscroll
+\newline\menuitemstyle{}\tab{2}Union({\em a:A},{\em b:B})
+\newline\tab{2}{\em Arguments:}\indent{17}\tab{-2}
+{\em a}, a tag, an element of domain \spadtype{Symbol}
+\newline\tab{-2}
+{\em A}, a domain of category \spadtype{SetCategory}
+\newline\tab{-2}
+{\em b}, a tag, an element of domain \spadtype{Symbol}
+\newline\tab{-2}
+{\em B}, a domain of category \spadtype{SetCategory}
+\indent{0}\newline\tab{2}{\em Returns:}\indent{17}\tab{-2}
+the "union of {\em A} and {\em B}" as described below.
+\indent{0}\newline\tab{2}{\em Description:}\indent{15}\tab{0}
+{\em Union(a:A,b:B)} denotes the class of objects 
+which are either members of domain {\em A} or of domain {\em B}.
+The symbols {\em a} and {\em b} are called "tags" and 
+are used to identify the two "branches"
+of the union.
+The {\em Union} constructor can take any number of arguments and
+has an alternate form without {\em tags}.
+This tagged {\em Union} type is necessary, for example, to disambiguate
+two branches of a union where {\em A} and {\em B} denote the same type.
+{\em Union} is a primitive domain of Axiom which cannot be
+defined in the Axiom language. 
+\endscroll\end{page}
+
+@
+\subsection{Domain {\bf Union(A,...,B)}}
+\label{UntaggedUnion}
+\index{pages!UntaggedUnion!union.ht}
+\index{union.ht!pages!UntaggedUnion}
+\index{UntaggedUnion!union.ht!pages}
+<<union.ht>>=
+\begin{page}{UntaggedUnion}{Domain {\em Union(A,...,B)}}
+\beginscroll
+{\em Union} takes any number of domain arguments:
+\indentrel{2}
+\newline \spad{A}, a domain of category \spadtype{SetCategory}
+\newline\tab{10}...
+\newline \spad{B}, a domain of category \spadtype{SetCategory}
+\indentrel{-2}\newline
+\spad{Union} is a primitive constructor in Axiom. 
+\newline
+\beginmenu
+\item\menulispdownlink{Description}{(|dbSpecialDescription| '|UntaggedUnion|)) }\tab{15}General description
+\item\menulispdownlink{Operations}{(|dbSpecialOperations| '|UntaggedUnion|)}\tab{15}All exported operations of \spad{Union(A,B)}
+%\item\menudownlink{Examples}   {UTUnionExamples}   \tab{15}Examples illustrating use
+%\item\menudownlink{Exports}    {UTUnionExports}    \tab{15}Explicit categories and operations
+\endmenu
+\vspace{1}\newline
+In this untagged form of \spad{Union}, domains \spad{A,...,B} must be distinct.
+\endscroll\end{page}
+
+@
+\subsection{Domain Constructor {\bf Union}}
+\label{UTUnionDescription}
+\index{pages!UTUnionDescription!union.ht}
+\index{union.ht!pages!UTUnionDescription}
+\index{UTUnionDescription!union.ht!pages}
+<<union.ht>>=
+\begin{page}{UTUnionDescription}{Domain Constructor {\em Union}}
+\beginscroll
+\newline\menuitemstyle{}\tab{2}Union({\em A},{\em B})
+\newline\tab{2}{\em Arguments:}\indent{17}\tab{-2}
+{\em A}, a domain of category \spadtype{SetCategory}
+\newline\tab{-2}
+{\em B}, a domain of category \spadtype{SetCategory}
+\indent{0}\newline\tab{2}{\em Returns:}\indent{17}\tab{-2}
+the "union of {\em A} and {\em B}" as described below.
+\indent{0}\newline\tab{2}{\em Description:}\indent{15}\tab{0}
+{\em Union(A,B)} denotes the class of objects which are
+which are either members of domain {\em A} or of domain {\em B}.
+The {\em Union} constructor can take any number of arguments and
+has an alternate form using {\em tags}.
+{\em Union} is a primitive domain of Axiom which cannot be
+defined in the Axiom language. 
+\endscroll\end{page}
+
+
+@
+\section{uniseg.ht}
+<<uniseg.ht>>=
+\newcommand{\UniversalSegmentXmpTitle}{UniversalSegment}
+\newcommand{\UniversalSegmentXmpNumber}{9.84}
+
+@
+\subsection{UniversalSegment}
+\label{UniversalSegmentXmpPage}
+\begin{itemize}
+\item SegmentXmpPage \ref{SegmentXmpPage} on
+page~pageref{SegmentXmpPage}
+\item SegmentBindingXmpPage \ref{SegmentBindingXmpPage} on
+page~pageref{SegmentBindingXmpPage}
+\item ListXmpPage \ref{ListXmpPage} on
+page~pageref{ListXmpPage}
+\item StreamXmpPage \ref{StreamXmpPage} on
+page~pageref{StreamXmpPage}
+\end{itemize}
+\index{pages!UniversalSegmentXmpPage!uniseg.ht}
+\index{uniseg.ht!pages!UniversalSegmentXmpPage}
+\index{UniversalSegmentXmpPage!uniseg.ht!pages}
+<<uniseg.ht>>=
+\begin{page}{UniversalSegmentXmpPage}{UniversalSegment}
+\beginscroll
+
+The \spadtype{UniversalSegment} domain generalizes \spadtype{Segment}
+by allowing segments without a ``hi'' end point.
+\xtc{
+}{
+\spadpaste{pints  := 1..         \bound{pints}}
+}
+\xtc{
+}{
+\spadpaste{nevens := (0..) by -2 \bound{nevens}}
+}
+\xtc{
+Values of type \spadtype{Segment} are automatically converted to
+type \spadtype{UniversalSegment} when appropriate.
+}{
+\spadpaste{useg: UniversalSegment(Integer) := 3..10 \bound{useg}}
+}
+\xtc{
+The operation \spadfunFrom{hasHi}{UniversalSegment} is used to test
+whether a segment has a \spad{hi} end point.
+}{
+\spadpaste{hasHi pints  \free{pints}}
+}
+\xtc{
+}{
+\spadpaste{hasHi nevens \free{nevens}}
+}
+\xtc{
+}{
+\spadpaste{hasHi useg   \free{useg}}
+}
+\xtc{
+All operations available on type \spadtype{Segment} apply to
+\spadtype{UniversalSegment}, with the proviso that expansions produce
+streams rather than lists.
+This is to accommodate infinite expansions.
+}{
+\spadpaste{expand pints \free{pints}}
+}
+\xtc{
+}{
+\spadpaste{expand nevens \free{nevens}}
+}
+\xtc{
+}{
+\spadpaste{expand [1, 3, 10..15, 100..]}
+}
+
+For more information on related topics,  see
+\downlink{`Segment'}{SegmentXmpPage}\ignore{Segment},
+\downlink{`SegmentBinding'}{SegmentBindingXmpPage}\ignore{SegmentBinding},
+\downlink{`List'}{ListXmpPage}\ignore{List}, and
+\downlink{`Stream'}{StreamXmpPage}\ignore{Stream}.
+\showBlurb{UniversalSegment}
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{up.ht}
+<<up.ht>>=
+\newcommand{\UnivariatePolynomialXmpTitle}{UnivariatePolynomial}
+\newcommand{\UnivariatePolynomialXmpNumber}{9.83}
+
+@
+\subsection{UnivariatePolynomial}
+\label{UnivariatePolynomialXmpPage}
+\begin{itemize}
+\item ugProblemFactorPage \ref{ugProblemFactorPage} on
+page~pageref{ugProblemFactorPage}
+\item ugIntroVariablesPage \ref{ugIntroVariablesPage} on
+page~pageref{ugIntroVariablesPage}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~pageref{ugTypesConvertPage}
+\item PolynomialXmpPage \ref{PolynomialXmpPage} on
+page~pageref{PolynomialXmpPage}
+\item MultivariatePolynomialXmpPage \ref{MultivariatePolynomialXmpPage} on
+page~pageref{MultivariatePolynomialXmpPage}
+\item DistributedMultivariatePolynomialXmpPage \ref{DistributedMultivariatePolynomialXmpPage} on
+page~pageref{DistributedMultivariatePolynomialXmpPage}
+\end{itemize}
+\index{pages!UnivariatePolynomialXmpPage!up.ht}
+\index{up.ht!pages!UnivariatePolynomialXmpPage}
+\index{UnivariatePolynomialXmpPage!up.ht!pages}
+<<up.ht>>=
+\begin{page}{UnivariatePolynomialXmpPage}{UnivariatePolynomial}
+\beginscroll
+
+The domain constructor \spadtype{UnivariatePolynomial}
+(abbreviated \spadtype{UP})
+creates domains of univariate polynomials in a specified variable.
+For example, the domain
+\spadtype{UP(a1,POLY FRAC INT)} provides polynomials in the single variable
+\spad{a1} whose coefficients are general polynomials with rational
+number coefficients.
+
+\beginImportant
+\noindent {\bf Restriction:}
+\texht{\begin{quotation}\noindent}{\newline\indent{5}}
+Axiom does not allow you to create types where
+\spadtype{UnivariatePolynomial} is contained in the coefficient type of
+\spadtype{Polynomial}. Therefore,
+\spadtype{UP(x,POLY INT)} is legal but \spadtype{POLY UP(x,INT)} is not.
+\texht{\end{quotation}}{\indent{0}}
+\endImportant
+
+\xtc{
+\spadtype{UP(x,INT)} is the domain of polynomials in the single
+variable \spad{x} with integer coefficients.
+}{
+\spadpaste{(p,q) : UP(x,INT) \bound{pdec}\bound{qdec}}
+}
+\xtc{
+}{
+\spadpaste{p := (3*x-1)**2 * (2*x + 8) \free{pdec}\bound{p}}
+}
+\xtc{
+}{
+\spadpaste{q := (1 - 6*x + 9*x**2)**2 \free{qdec}\bound{q}}
+}
+\xtc{
+The usual arithmetic operations are available for univariate
+polynomials.
+}{
+\spadpaste{p**2 + p*q  \free{p q}}
+}
+\xtc{
+The operation \spadfunFrom{leadingCoefficient}{UnivariatePolynomial}
+extracts the coefficient of the term of highest degree.
+}{
+\spadpaste{leadingCoefficient p \free{p}}
+}
+\xtc{
+The operation \spadfunFrom{degree}{UnivariatePolynomial} returns
+the degree of the polynomial.
+Since the polynomial has only one variable, the variable is not supplied
+to operations like \spadfunFrom{degree}{UnivariatePolynomial}.
+}{
+\spadpaste{degree p \free{p}}
+}
+\xtc{
+The reductum of the polynomial, the polynomial obtained by
+subtracting the term of highest order, is returned by
+\spadfunFrom{reductum}{UnivariatePolynomial}.
+}{
+\spadpaste{reductum p \free{p}}
+}
+\xtc{
+The operation \spadfunFrom{gcd}{UnivariatePolynomial} computes the
+greatest common divisor of two polynomials.
+}{
+\spadpaste{gcd(p,q) \free{p q}}
+}
+\xtc{
+The operation \spadfunFrom{lcm}{UnivariatePolynomial} computes the
+least common multiple.
+}{
+\spadpaste{lcm(p,q) \free{p q}}
+}
+\xtc{
+The operation \spadfunFrom{resultant}{UnivariatePolynomial}
+computes the resultant of two univariate polynomials.
+In the case of \spad{p} and \spad{q}, the resultant is \spad{0} because they
+share a common root.
+}{
+\spadpaste{resultant(p,q) \free{p q}}
+}
+\xtc{
+To compute the derivative of a univariate polynomial with respect to its
+variable, use \spadfunFrom{D}{UnivariatePolynomial}.
+}{
+\spadpaste{D p \free{p}}
+}
+\xtc{
+Univariate polynomials can also be used as if they were functions.
+To evaluate a univariate polynomial at some point, apply
+the polynomial to the point.
+}{
+\spadpaste{p(2) \free{p}}
+}
+\xtc{
+The same syntax is used for composing two univariate polynomials, i.e.
+substituting one polynomial for the variable in another.
+This substitutes \spad{q} for the variable in \spad{p}.
+}{
+\spadpaste{p(q) \free{p q}}
+}
+\xtc{
+This substitutes \spad{p} for the variable in \spad{q}.
+}{
+\spadpaste{q(p) \free{p q}}
+}
+\xtc{
+To obtain a list of coefficients of the polynomial, use
+\spadfunFrom{coefficients}{UnivariatePolynomial}.
+}{
+\spadpaste{l := coefficients p \free{p}\bound{l}}
+}
+\xtc{
+From this you can use \spadfunFrom{gcd}{UnivariatePolynomial}
+and \spadfunFrom{reduce}{List}
+to compute the content of the polynomial.
+}{
+\spadpaste{reduce(gcd,l) \free{l}}
+}
+\xtc{
+Alternatively (and more easily),
+you can just call \spadfunFrom{content}{UnivariatePolynomial}.
+}{
+\spadpaste{content p \free{p}}
+}
+
+Note that the operation \spadfunFrom{coefficients}{UnivariatePolynomial}
+omits the zero coefficients from the list.
+Sometimes it is useful to convert a univariate polynomial
+to a vector whose \eth{\spad{i }} position contains the degree \spad{i-1}
+coefficient of the polynomial.
+\xtc{
+}{
+\spadpaste{ux := (x**4+2*x+3)::UP(x,INT) \bound{ux}}
+}
+\xtc{
+To get a complete vector of coefficients, use the operation
+\spadfunFrom{vectorise}{UnivariatePolynomial}, which takes a
+univariate polynomial and an integer denoting the length of the
+desired vector.
+}{
+\spadpaste{vectorise(ux,5) \free{ux}}
+}
+
+It is common to want to do something to every term of a polynomial,
+creating a new polynomial in the process.
+\xtc{
+This is a function for iterating across the terms of a polynomial,
+squaring each term.
+}{
+\begin{spadsrc}[\bound{squareTerms}]
+squareTerms(p) ==
+  reduce(+,[t**2 for t in monomials p])
+\end{spadsrc}
+}
+\xtc{
+Recall what \spad{p} looked like.
+}{
+\spadpaste{p \free{p}}
+}
+\xtc{
+We can demonstrate \userfun{squareTerms} on \spad{p}.
+}{
+\spadpaste{squareTerms p \free{p}\free{squareTerms}}
+}
+
+When the coefficients of the univariate polynomial belong to a
+field,\footnote{For example, when the coefficients are rational
+numbers, as opposed to integers.  The important property of
+a field is that non-zero elements can be divided and produce
+another element. The quotient of the integers 2 and 3 is not
+another integer.}
+it is possible to compute quotients and remainders.
+\xtc{
+}{
+\spadpaste{(r,s) : UP(a1,FRAC INT) \bound{rdec}\bound{sdec}}
+}
+\xtc{
+}{
+\spadpaste{r := a1**2 - 2/3  \free{rdec}\bound{r}}
+}
+\xtc{
+}{
+\spadpaste{s := a1 + 4       \free{sdec}\bound{s}}
+}
+\xtc{
+When the coefficients are rational numbers or rational expressions, the
+operation \spadfunFrom{quo}{UnivariatePolynomial} computes the quotient
+of two polynomials.
+}{
+\spadpaste{r quo s \free{r s}}
+}
+\xtc{
+The operation
+\spadfunFrom{rem}{UnivariatePolynomial} computes the remainder.
+}{
+\spadpaste{r rem s \free{r s}}
+}
+\xtc{
+The operation \spadfunFrom{divide}{UnivariatePolynomial} can be used to
+return a record of both components.
+}{
+\spadpaste{d := divide(r, s) \free{r s}\bound{d}}
+}
+\xtc{
+Now we check the arithmetic!
+}{
+\spadpaste{r - (d.quotient * s + d.remainder) \free{r s d}}
+}
+\xtc{
+It is also possible to integrate univariate polynomials when the
+coefficients belong to a field.
+}{
+\spadpaste{integrate r \free{r}}
+}
+\xtc{
+}{
+\spadpaste{integrate s \free{s}}
+}
+
+One application of univariate polynomials is to see expressions in terms
+of a specific variable.
+%
+\xtc{
+We start with a polynomial in \spad{a1} whose coefficients
+are quotients of polynomials in \spad{b1} and \spad{b2}.
+}{
+\spadpaste{t : UP(a1,FRAC POLY INT) \bound{tdec}}
+}
+\xtc{
+Since in this case we are not talking about using multivariate
+polynomials in only two variables, we use \spadtype{Polynomial}.
+We also use \spadtype{Fraction} because we want fractions.
+}{
+\spadpaste{t := a1**2 - a1/b2 + (b1**2-b1)/(b2+3) \free{tdec}\bound{t}}
+}
+\xtc{
+We push all the variables into a single quotient of polynomials.
+}{
+\spadpaste{u : FRAC POLY INT := t \bound{u}\free{t}}
+}
+\xtc{
+Alternatively, we can view this as a polynomial in the variable
+This is a {\it mode-directed} conversion: you indicate
+as much of the structure as you care about and let Axiom
+decide on the full type and how to do the transformation.
+}{
+\spadpaste{u :: UP(b1,?) \free{u}}
+}
+
+See \downlink{``\ugProblemFactorTitle''}{ugProblemFactorPage} in 
+Section \ugProblemFactorNumber\ignore{ugProblemFactor}
+for a discussion of the factorization facilities
+in Axiom for univariate polynomials.
+For more information on related topics, see
+\downlink{``\ugIntroVariablesTitle''}{ugIntroVariablesPage} in 
+Section \ugIntroVariablesNumber\ignore{ugIntroVariables},
+\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} in 
+Section \ugTypesConvertNumber\ignore{ugTypesConvert},
+\downlink{`Polynomial'}{PolynomialXmpPage}\ignore{Polynomial},
+\downlink{`MultivariatePolynomial'}{MultivariatePolynomialXmpPage}
+\ignore{MultivariatePolynomial}, and
+\downlink{`DistributedMultivariatePolynomial'}
+{DistributedMultivariatePolynomialXmpPage}
+\ignore{DistributedMultivariatePolynomial}.
+%
+\showBlurb{UnivariatePolynomial}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{vector.ht}
+<<vector.ht>>=
+\newcommand{\VectorXmpTitle}{Vector}
+\newcommand{\VectorXmpNumber}{9.85}
+
+@
+\subsection{Vector}
+\label{VectorXmpPage}
+\begin{itemize}
+\item OneDimensionalArrayXmpPage \ref{OneDimensionalArrayXmpPage} on
+page~pageref{OneDimensionalArrayXmpPage}
+\item ListXmpPage \ref{ListXmpPage} on
+page~pageref{ListXmpPage}
+\item MatrixXmpPage \ref{MatrixXmpPage} on
+page~pageref{MatrixXmpPage}
+\item OneDimensionalArrayXmpPage \ref{OneDimensionalArrayXmpPage} on
+page~pageref{OneDimensionalArrayXmpPage}
+\item SetXmpPage \ref{SetXmpPage} on
+page~pageref{SetXmpPage}
+\item TableXmpPage \ref{TableXmpPage} on
+page~pageref{TableXmpPage}
+\item TwoDimensionalArrayXmpPage \ref{TwoDimensionalArrayXmpPage} on
+page~pageref{TwoDimensionalArrayXmpPage}
+\end{itemize}
+\index{pages!VectorXmpPage!vector.ht}
+\index{vector.ht!pages!VectorXmpPage}
+\index{VectorXmpPage!vector.ht!pages}
+<<vector.ht>>=
+\begin{page}{VectorXmpPage}{Vector}
+\beginscroll
+
+The \spadtype{Vector} domain is used for storing data in a one-dimensional
+indexed data structure.
+A vector is a homogeneous data structure in that all the components of the
+vector must belong to the same Axiom domain.
+Each vector has a fixed length specified by the user; vectors are not
+extensible.
+This domain is similar to the \spadtype{OneDimensionalArray} domain,
+except that when the components of a \spadtype{Vector} belong to a
+\spadtype{Ring}, arithmetic operations are provided.
+For more examples of operations that are defined for both
+\spadtype{Vector} and \spadtype{OneDimensionalArray}, see
+\downlink{`OneDimensionalArray'}{OneDimensionalArrayXmpPage}
+\ignore{OneDimensionalArray}.
+
+As with the \spadtype{OneDimensionalArray} domain, a \spadtype{Vector} can
+be created by calling the operation \spadfunFrom{new}{Vector}, its components
+can be accessed by calling the operations \spadfunFrom{elt}{Vector} and
+\spadfunFrom{qelt}{Vector}, and its components can be reset by calling the
+operations \spadfunFrom{setelt}{Vector} and
+\spadfunFromX{qsetelt}{Vector}.
+\xtc{
+This creates a vector of integers of length
+\spad{5} all of whose components are \spad{12}.
+}{
+\spadpaste{u : VECTOR INT := new(5,12) \bound{u}}
+}
+\xtc{
+This is how you create a vector from a list of its components.
+}{
+\spadpaste{v : VECTOR INT := vector([1,2,3,4,5]) \bound{v}}
+}
+
+\xtc{
+Indexing for vectors begins at \spad{1}.
+The last element has index equal to the length of the vector,
+which is computed by \spadopFrom{\#}{Vector}.
+}{
+\spadpaste{\#(v) \free{v}}
+}
+\xtc{
+This is the standard way to use \spadfunFrom{elt}{Vector} to extract an
+element.
+Functionally, it is the same as if you had typed \spad{elt(v,2)}.
+}{
+\spadpaste{v.2 \free{v}}
+}
+\xtc{
+This is the standard way to use \spadfunFrom{setelt}{Vector} to change an
+element.
+It is the same as if you had typed \spad{setelt(v,3,99)}.
+}{
+\spadpaste{v.3 := 99 \free{v}\bound{vdelta}}
+}
+\xtc{
+Now look at \spad{v} to see the change.
+You can
+use \spadfunFrom{qelt}{Vector} and \spadfunFromX{qsetelt}{Vector} (instead
+of \spadfunFrom{elt}{Vector} and \spadfunFrom{setelt}{Vector},
+respectively) but {\it only} when you know that the index is within the valid
+range.
+}{
+\spadpaste{v \free{vdelta}}
+}
+
+\xtc{
+When the components belong to a \spadtype{Ring}, Axiom
+provides arithmetic operations for \spadtype{Vector}.
+These include left and right scalar multiplication.
+}{
+\spadpaste{5 * v \free{vdelta}}
+}
+\xtc{
+}{
+\spadpaste{v * 7 \free{vdelta}}
+}
+\xtc{
+}{
+\spadpaste{w : VECTOR INT := vector([2,3,4,5,6]) \bound{w}}
+}
+\xtc{
+Addition and subtraction are also available.
+}{
+\spadpaste{v + w \free{vdelta w}}
+}
+\xtc{
+Of course, when adding or subtracting, the two vectors must have the same
+length or an error message is displayed.
+}{
+\spadpaste{v - w \free{vdelta w}}
+}
+
+For more information about other aggregate domains,
+see the following:
+\downlink{`List'}{ListXmpPage}\ignore{List},
+\downlink{`Matrix'}{MatrixXmpPage}\ignore{Matrix},
+\downlink{`OneDimensionalArray'}{OneDimensionalArrayXmpPage}\ignore{OneDimensionalArray},
+\downlink{`Set'}{SetXmpPage}\ignore{Set},
+\downlink{`Table'}{TableXmpPage}\ignore{Table}, and
+\downlink{`TwoDimensionalArray'}{TwoDimensionalArrayXmpPage}\ignore{TwoDimensionalArray}.
+Issue the system command \spadcmd{)show Vector}
+to display the full list of operations defined by
+\spadtype{Vector}.
+
+\endscroll
+\autobuttons
+\end{page}
+%
+
+@
+\section{void.ht}
+<<void.ht>>=
+\newcommand{\VoidXmpTitle}{Void}
+\newcommand{\VoidXmpNumber}{9.86}
+
+@
+\subsection{Void}
+\label{VoidXmpPage}
+\index{pages!VoidXmpPage!void.ht}
+\index{void.ht!pages!VoidXmpPage}
+\index{VoidXmpPage!void.ht!pages}
+<<void.ht>>=
+\begin{page}{VoidXmpPage}{Void}
+\beginscroll
+
+When an expression is not in a value context, it is given type \spadtype{Void}.
+For example, in the expression
+\begin{verbatim}
+r := (a; b; if c then d else e; f)
+\end{verbatim}
+values are used only from the subexpressions \spad{c} and \spad{f}: all
+others are thrown away.
+The subexpressions \spad{a}, \spad{b}, \spad{d} and \spad{e}
+are evaluated for side-effects only and have type \spadtype{Void}.
+There is a unique value of type \spadtype{Void}.
+
+\xtc{
+You will most often see results of type \spadtype{Void} when you
+declare a variable.
+}{
+\spadpaste{a : Integer}
+}
+\noOutputXtc{
+Usually no output is displayed for \spadtype{Void} results.
+You can force the display of a rather ugly object by issuing
+\spadcmd{)set message void on}.
+}{
+\spadpaste{)set message void on}
+}
+\xtc{
+}{
+\spadpaste{b : Fraction Integer}
+}
+\noOutputXtc{
+}{
+\spadpaste{)set message void off}
+}
+\xtc{
+All values can be converted to type \spadtype{Void}.
+}{
+\spadpaste{3::Void \bound{prev}}
+}
+\xtc{
+Once a value has been converted to \spadtype{Void}, it cannot be recovered.
+}{
+\spadpaste{\% :: PositiveInteger \free{prev}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{wutset.ht}
+<<wutset.ht>>=
+\newcommand{\WuWenTsunTriangularSetXmpTitle}{WuWenTsunTriangularSet}
+\newcommand{\WuWenTsunTriangularSetXmpNumber}{9.87}
+
+@
+\subsection{WuWenTsunTriangularSet}
+\label{WuWenTsunTriangularSetXmpPage}
+\index{pages!WuWenTsunTriangularSetXmpPage!wutset.ht}
+\index{wutset.ht!pages!WuWenTsunTriangularSetXmpPage}
+\index{WuWenTsunTriangularSetXmpPage!wutset.ht!pages}
+<<wutset.ht>>=
+\begin{page}{WuWenTsunTriangularSetXmpPage}{WuWenTsunTriangularSet}
+\beginscroll
+The \spadtype{WuWenTsunTriangularSet} domain constructor implements
+the characteristic set method of Wu Wen Tsun.
+This algorithm computes a list of triangular sets from a list
+of polynomials such that the algebraic variety defined by the 
+given list of polynomials decomposes into the union of the regular-zero sets 
+of the computed triangular sets.
+The constructor takes four arguments.
+The first one, {\bf R}, is the coefficient ring of the polynomials;
+it must belong to the category \spadtype{IntegralDomain}.
+The second one, {\bf E}, is the exponent monoid of the polynomials;
+it must belong to the category \spadtype{OrderedAbelianMonoidSup}.
+The third one, {\bf V}, is the ordered set of variables;
+it must belong to the category \spadtype{OrderedSet}.
+The last one is the polynomial ring;
+it must belong to the category \spadtype{RecursivePolynomialCategory(R,E,V)}.
+The abbreviation for \spadtype{WuWenTsunTriangularSet} is
+\spadtype{WUTSET}.
+
+Let us illustrate the facilities by an example.
+
+\xtc{
+Define the coefficient ring.
+}{
+\spadpaste{R := Integer \bound{R}}
+}
+\xtc{
+Define the list of variables,
+}{
+\spadpaste{ls : List Symbol := [x,y,z,t] \bound{ls}}
+}
+\xtc{
+and make it an ordered set;
+}{
+\spadpaste{V := OVAR(ls) \free{ls} \bound{V}}
+}
+\xtc{
+then define the exponent monoid.
+}{
+\spadpaste{E := IndexedExponents V \free{V} \bound{E}}
+}
+\xtc{
+Define the polynomial ring.
+}{
+\spadpaste{P := NSMP(R, V) \free{R} \free{V} \bound{P}}
+}
+\xtc{
+Let the variables be polynomial.
+}{
+\spadpaste{x: P := 'x \free{P} \bound{x}}
+}
+\xtc{
+}{
+\spadpaste{y: P := 'y \free{P} \bound{y}}
+}
+\xtc{
+}{
+\spadpaste{z: P := 'z \free{P} \bound{z}}
+}
+\xtc{
+}{
+\spadpaste{t: P := 't \free{P} \bound{t}}
+}
+\xtc{
+Now call the \spadtype{WuWenTsunTriangularSet} domain constructor.
+}{
+\spadpaste{T := WUTSET(R,E,V,P) \free{R} \free{E} \free{V} \free{P} \bound{T} }
+}
+\xtc{
+Define a polynomial system.
+}{
+\spadpaste{p1 := x ** 31 - x ** 6 - x - y \free{x} \free{y} \bound{p1}}
+}
+\xtc{
+}{
+\spadpaste{p2 := x ** 8  - z \free{x} \free{z} \bound{p2}}
+}
+\xtc{
+}{
+\spadpaste{p3 := x ** 10 - t \free{x} \free{t} \bound{p3}}
+}
+\xtc{
+}{
+\spadpaste{lp := [p1, p2, p3] \free{p1} \free{p2} \free{p3} \bound{lp}}
+}
+\xtc{
+Compute a characteristic set of the system.
+}{
+\spadpaste{characteristicSet(lp)$T \free{lp} \free{T}}
+}
+\xtc{
+Solve the system.
+}{
+\spadpaste{zeroSetSplit(lp)$T \free{lp} \free{T}}
+}
+
+
+The \spadtype{RegularTriangularSet} and 
+\spadtype{SquareFreeRegularTriangularSet} domain constructors,
+and the  \spadtype{LazardSetSolvingPackage}, 
+\spadtype{SquareFreeRegularTriangularSet} 
+and \spadtype{ZeroDimensionalSolvePackage} package constructors
+also provide operations to compute triangular 
+decompositions of algebraic varieties.
+These five constructor use a special kind of 
+characteristic sets, called regular triangular sets.
+These special characteristic sets have better 
+properties than the general ones.
+Regular triangular sets and their related concepts are presented in
+the paper "On the Theories of Triangular sets" By P. Aubry, D. Lazard
+and M. Moreno Maza (to appear in the Journal of Symbolic Computation).
+The decomposition algorithm (due to the third author) available in the 
+four above constructors provide generally better timings than 
+the characteristic set method.
+In fact, the \spadtype{WUTSET} constructor remains interesting 
+for the purpose of manipulating characteristic sets whereas
+the other constructors are more convenient for solving polynomial systems.
+
+Note that the way of understanding triangular decompositions 
+is detailed in the example of the \spadtype{RegularTriangularSet}
+constructor.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{xmpexp.ht}
+<<xmpexp.ht>>=
+\newcommand{\ExamplesExposedTitle}{Some Examples of Domains and Packages}
+\newcommand{\ExamplesExposedNumber}{9.}
+
+@
+\subsection{Some Examples of Domains and Packages}
+\label{ExamplesExposedPage}
+\begin{itemize}
+\item AssociationListXmpPage \ref{AssociationListXmpPage} on
+page~pageref{AssociationListXmpPage}
+\item BalancedBinaryTreeXmpPage \ref{BalancedBinaryTreeXmpPage} on
+page~pageref{BalancedBinaryTreeXmpPage}
+\item BasicOperatorXmpPage \ref{BasicOperatorXmpPage} on
+page~pageref{BasicOperatorXmpPage}
+\item BinaryExpansionXmpPage \ref{BinaryExpansionXmpPage} on
+page~pageref{BinaryExpansionXmpPage}
+\item BinarySearchTreeXmpPage \ref{BinarySearchTreeXmpPage} on
+page~pageref{BinarySearchTreeXmpPage}
+\item CardinalNumberXmpPage \ref{CardinalNumberXmpPage} on
+page~pageref{CardinalNumberXmpPage}
+\item CartesianTensorXmpPage \ref{CartesianTensorXmpPage} on
+page~pageref{CartesianTensorXmpPage}
+\item CharacterXmpPage \ref{CharacterXmpPage} on
+page~pageref{CharacterXmpPage}
+\item CharacterClassXmpPage \ref{CharacterClassXmpPage} on
+page~pageref{CharacterClassXmpPage}
+\item CliffordAlgebraXmpPage \ref{CliffordAlgebraXmpPage} on
+page~pageref{CliffordAlgebraXmpPage}
+\item ComplexXmpPage \ref{ComplexXmpPage} on
+page~pageref{ComplexXmpPage}
+\item ContinuedFractionXmpPage \ref{ContinuedFractionXmpPage} on
+page~pageref{ContinuedFractionXmpPage}
+\item CycleIndicatorsXmpPage \ref{CycleIndicatorsXmpPage} on
+page~pageref{CycleIndicatorsXmpPage}
+\item DeRhamComplexXmpPage \ref{DeRhamComplexXmpPage} on
+page~pageref{DeRhamComplexXmpPage}
+\item DecimalExpansionXmpPage \ref{DecimalExpansionXmpPage} on
+page~pageref{DecimalExpansionXmpPage}
+\item DistributedMultivariatePolynomialXmpPage 
+\ref{DistributedMultivariatePolynomialXmpPage} on
+page~pageref{DistributedMultivariatePolynomialXmpPage}
+\item DoubleFloatXmpPage \ref{DoubleFloatXmpPage} on
+page~pageref{DoubleFloatXmpPage}
+\item EqTableXmpPage \ref{EqTableXmpPage} on
+page~pageref{EqTableXmpPage}
+\item EquationXmpPage \ref{EquationXmpPage} on
+page~pageref{EquationXmpPage}
+\item ExitXmpPage \ref{ExitXmpPage} on
+page~pageref{ExitXmpPage}
+\item ExpressionXmpPage \ref{ExpressionXmpPage} on
+page~pageref{ExpressionXmpPage}
+\item FactoredXmpPage \ref{FactoredXmpPage} on
+page~pageref{FactoredXmpPage}
+\item FactoredFunctionsTwoXmpPage \ref{FactoredFunctionsTwoXmpPage} on
+page~pageref{FactoredFunctionsTwoXmpPage}
+\item FileXmpPage \ref{FileXmpPage} on
+page~pageref{FileXmpPage}
+\item FileNameXmpPage \ref{FileNameXmpPage} on
+page~pageref{FileNameXmpPage}
+\item FlexibleArrayXmpPage \ref{FlexibleArrayXmpPage} on
+page~pageref{FlexibleArrayXmpPage}
+\item FloatXmpPage \ref{FloatXmpPage} on
+page~pageref{FloatXmpPage}
+\item FractionXmpPage \ref{FractionXmpPage} on
+page~pageref{FractionXmpPage}
+\item FullPartialFractionExpansionXmpPage 
+\ref{FullPartialFractionExpansionXmpPage} on
+page~pageref{FullPartialFractionExpansionXmpPage}
+\item GeneralSparseTableXmpPage \ref{GeneralSparseTableXmpPage} on
+page~pageref{GeneralSparseTableXmpPage}
+\item GroebnerFactorizationPackageXmpPage 
+\ref{GroebnerFactorizationPackageXmpPage} on
+page~pageref{GroebnerFactorizationPackageXmpPage}
+\item HeapXmpPage \ref{HeapXmpPage} on
+page~pageref{HeapXmpPage}
+\item HexadecimalExpansionXmpPage \ref{HexadecimalExpansionXmpPage} on
+page~pageref{HexadecimalExpansionXmpPage}
+\item IntegerXmpPage \ref{IntegerXmpPage} on
+page~pageref{IntegerXmpPage}
+\item IntegerLinearDependenceXmpPage \ref{IntegerLinearDependenceXmpPage} on
+page~pageref{IntegerLinearDependenceXmpPage}
+\item IntegerNumberTheoryFunctionsXmpPage 
+\ref{IntegerNumberTheoryFunctionsXmpPage} on
+page~pageref{IntegerNumberTheoryFunctionsXmpPage}
+\item KernelXmpPage \ref{KernelXmpPage} on
+page~pageref{KernelXmpPage}
+\item KeyedAccessFileXmpPage \ref{KeyedAccessFileXmpPage} on
+page~pageref{KeyedAccessFileXmpPage}
+\item LexTriangularPackageXmpPage \ref{LexTriangularPackageXmpPage} on
+page~pageref{LexTriangularPackageXmpPage}
+\item LazardSetSolvingPackageXmpPage \ref{LazardSetSolvingPackageXmpPage} on
+page~pageref{LazardSetSolvingPackageXmpPage}
+\item LibraryXmpPage \ref{LibraryXmpPage} on
+page~pageref{LibraryXmpPage}
+\item LieExponentialsXmpPage \ref{LieExponentialsXmpPage} on
+page~pageref{LieExponentialsXmpPage}
+\item LiePolynomialXmpPage \ref{LiePolynomialXmpPage} on
+page~pageref{LiePolynomialXmpPage}
+\item LinearOrdinaryDifferentialOperatorXmpPage 
+\ref{LinearOrdinaryDifferentialOperatorXmpPage} on
+page~pageref{LinearOrdinaryDifferentialOperatorXmpPage}
+\item LinearOrdinaryDifferentialOperatorOneXmpPage 
+\ref{LinearOrdinaryDifferentialOperatorOneXmpPage} on
+page~pageref{LinearOrdinaryDifferentialOperatorOneXmpPage}
+\item LinearOrdinaryDifferentialOperatorTwoXmpPage 
+\ref{LinearOrdinaryDifferentialOperatorTwoXmpPage} on
+page~pageref{LinearOrdinaryDifferentialOperatorTwoXmpPage}
+\item ListXmpPage \ref{ListXmpPage} on
+page~pageref{ListXmpPage}
+\item LyndonWordXmpPage \ref{LyndonWordXmpPage} on
+page~pageref{LyndonWordXmpPage}
+\item MagmaXmpPage \ref{MagmaXmpPage} on
+page~pageref{MagmaXmpPage}
+\item MakeFunctionXmpPage \ref{MakeFunctionXmpPage} on
+page~pageref{MakeFunctionXmpPage}
+\item MappingPackageOneXmpPage \ref{MappingPackageOneXmpPage} on
+page~pageref{MappingPackageOneXmpPage}
+\item MatrixXmpPage \ref{MatrixXmpPage} on
+page~pageref{MatrixXmpPage}
+\item MultiSetXmpPage \ref{MultiSetXmpPage} on
+page~pageref{MultiSetXmpPage}
+\item MultivariatePolynomialXmpPage \ref{MultivariatePolynomialXmpPage} on
+page~pageref{MultivariatePolynomialXmpPage}
+\item NoneXmpPage \ref{NoneXmpPage} on
+page~pageref{NoneXmpPage}
+\item OctonionXmpPage \ref{OctonionXmpPage} on
+page~pageref{OctonionXmpPage}
+\item OneDimensionalArrayXmpPage \ref{OneDimensionalArrayXmpPage} on
+page~pageref{OneDimensionalArrayXmpPage}
+\item OperatorXmpPage \ref{OperatorXmpPage} on
+page~pageref{OperatorXmpPage}
+\item OrderedVariableListXmpPage \ref{OrderedVariableListXmpPage} on
+page~pageref{OrderedVariableListXmpPage}
+\item OrderlyDifferentialPolynomialXmpPage 
+\ref{OrderlyDifferentialPolynomialXmpPage} on
+page~pageref{OrderlyDifferentialPolynomialXmpPage}
+\item PartialFractionXmpPage \ref{PartialFractionXmpPage} on
+page~pageref{PartialFractionXmpPage}
+\item PermanentXmpPage \ref{PermanentXmpPage} on
+page~pageref{PermanentXmpPage}
+\item PolynomialXmpPage \ref{PolynomialXmpPage} on
+page~pageref{PolynomialXmpPage}
+\item QuaternionXmpPage \ref{QuaternionXmpPage} on
+page~pageref{QuaternionXmpPage}
+\item RadixExpansionXmpPage \ref{RadixExpansionXmpPage} on
+page~pageref{RadixExpansionXmpPage}
+\item RealClosureXmpPage \ref{RealClosureXmpPage} on
+page~pageref{RealClosureXmpPage}
+\item RegularTriangularSetXmpPage \ref{RegularTriangularSetXmpPage} on
+page~pageref{RegularTriangularSetXmpPage}
+\item RomanNumeralXmpPage \ref{RomanNumeralXmpPage} on
+page~pageref{RomanNumeralXmpPage}
+\item SegmentXmpPage \ref{SegmentXmpPage} on
+page~pageref{SegmentXmpPage}
+\item SegmentBindingXmpPage \ref{SegmentBindingXmpPage} on
+page~pageref{SegmentBindingXmpPage}
+\item SetXmpPage \ref{SetXmpPage} on
+page~pageref{SetXmpPage}
+\item SingleIntegerXmpPage \ref{SingleIntegerXmpPage} on
+page~pageref{SingleIntegerXmpPage}
+\item SparseTableXmpPage \ref{SparseTableXmpPage} on
+page~pageref{SparseTableXmpPage}
+\item SquareMatrixXmpPage \ref{SquareMatrixXmpPage} on
+page~pageref{SquareMatrixXmpPage}
+\item SquareFreeRegularTriangularSetXmpPage 
+\ref{SquareFreeRegularTriangularSetXmpPage} on
+page~pageref{SquareFreeRegularTriangularSetXmpPage}
+\item StreamXmpPage \ref{StreamXmpPage} on
+page~pageref{StreamXmpPage}
+\item StringXmpPage \ref{StringXmpPage} on
+page~pageref{StringXmpPage}
+\item StringTableXmpPage \ref{StringTableXmpPage} on
+page~pageref{StringTableXmpPage}
+\item SymbolXmpPage \ref{SymbolXmpPage} on
+page~pageref{SymbolXmpPage}
+\item TableXmpPage \ref{TableXmpPage} on
+page~pageref{TableXmpPage}
+\item TextFileXmpPage \ref{TextFileXmpPage} on
+page~pageref{TextFileXmpPage}
+\item TwoDimensionalArrayXmpPage \ref{TwoDimensionalArrayXmpPage} on
+page~pageref{TwoDimensionalArrayXmpPage}
+\item UnivariatePolynomialXmpPage \ref{UnivariatePolynomialXmpPage} on
+page~pageref{UnivariatePolynomialXmpPage}
+\item UniversalSegmentXmpPage \ref{UniversalSegmentXmpPage} on
+page~pageref{UniversalSegmentXmpPage}
+\item VectorXmpPage \ref{VectorXmpPage} on
+page~pageref{VectorXmpPage}
+\item VoidXmpPage \ref{VoidXmpPage} on
+page~pageref{VoidXmpPage}
+\item WuWenTsunTriangularSetXmpPage \ref{WuWenTsunTriangularSetXmpPage} on
+page~pageref{WuWenTsunTriangularSetXmpPage}
+\item XPBWPolynomialXmpPage \ref{XPBWPolynomialXmpPage} on
+page~pageref{XPBWPolynomialXmpPage}
+\item XPolynomialXmpPage \ref{XPolynomialXmpPage} on
+page~pageref{XPolynomialXmpPage}
+\item XPolynomialRingXmpPage \ref{XPolynomialRingXmpPage} on
+page~pageref{XPolynomialRingXmpPage}
+\item ZeroDimensionalSolvePackageXmpPage 
+\ref{ZeroDimensionalSolvePackageXmpPage} on
+page~pageref{ZeroDimensionalSolvePackageXmpPage}
+\end{itemize}
+\index{pages!ExamplesExposedPage!xmpexp.ht}
+\index{xmpexp.ht!pages!ExamplesExposedPage}
+\index{ExamplesExposedPage!xmpexp.ht!pages}
+<<xmpexp.ht>>=
+\begin{page}{ExamplesExposedPage}{Some Examples of Domains and Packages}
+This is a menu of examples of some domains and packages.
+Click on any item below to see that section.
+\beginscroll
+\table{
+{ \downlink{AssociationList}{AssociationListXmpPage} }
+{ \downlink{BalancedBinaryTree}{BalancedBinaryTreeXmpPage} }
+{ \downlink{BasicOperator}{BasicOperatorXmpPage} }
+{ \downlink{BinaryExpansion}{BinaryExpansionXmpPage} }
+{ \downlink{BinarySearchTree}{BinarySearchTreeXmpPage} }
+{ \downlink{CardinalNumber}{CardinalNumberXmpPage} }
+{ \downlink{CartesianTensor}{CartesianTensorXmpPage} }
+{ \downlink{Character}{CharacterXmpPage} }
+{ \downlink{CharacterClass}{CharacterClassXmpPage} }
+{ \downlink{CliffordAlgebra}{CliffordAlgebraXmpPage} }
+{ \downlink{Complex}{ComplexXmpPage} }
+{ \downlink{ContinuedFraction}{ContinuedFractionXmpPage} }
+{ \downlink{CycleIndicators}{CycleIndicatorsXmpPage} }
+{ \downlink{DeRhamComplex}{DeRhamComplexXmpPage} }
+{ \downlink{DecimalExpansion}{DecimalExpansionXmpPage} }
+{ \downlink{DistributedMultivariatePolynomial}{DistributedMultivariatePolynomialXmpPage} }
+{ \downlink{DoubleFloat}{DoubleFloatXmpPage} }
+{ \downlink{EqTable}{EqTableXmpPage} }
+{ \downlink{Equation}{EquationXmpPage} }
+{ \downlink{Exit}{ExitXmpPage} }
+{ \downlink{Expression}{ExpressionXmpPage} }
+{ \downlink{Factored}{FactoredXmpPage} }
+{ \downlink{FactoredFunctions2}{FactoredFunctionsTwoXmpPage} }
+{ \downlink{File}{FileXmpPage} }
+{ \downlink{FileName}{FileNameXmpPage} }
+{ \downlink{FlexibleArray}{FlexibleArrayXmpPage} }
+{ \downlink{Float}{FloatXmpPage} }
+{ \downlink{Fraction}{FractionXmpPage} }
+{ \downlink{FullPartialFractionExpansion}{FullPartialFractionExpansionXmpPage} }
+{ \downlink{GeneralSparseTable}{GeneralSparseTableXmpPage} }
+{ \downlink{GroebnerFactorizationPackage}{GroebnerFactorizationPackageXmpPage} }
+{ \downlink{Heap}{HeapXmpPage} }
+{ \downlink{HexadecimalExpansion}{HexadecimalExpansionXmpPage} }
+{ \downlink{Integer}{IntegerXmpPage} }
+{ \downlink{IntegerLinearDependence}{IntegerLinearDependenceXmpPage} }
+{ \downlink{IntegerNumberTheoryFunctions}{IntegerNumberTheoryFunctionsXmpPage} }
+{ \downlink{Kernel}{KernelXmpPage} }
+{ \downlink{KeyedAccessFile}{KeyedAccessFileXmpPage} }
+{ \downlink{LexTriangularPackage}{LexTriangularPackageXmpPage} }
+{ \downlink{LazardSetSolvingPackage}{LazardSetSolvingPackageXmpPage} }
+{ \downlink{Library}{LibraryXmpPage} }
+{ \downlink{LieExponentials}{LieExponentialsXmpPage} }
+{ \downlink{LiePolynomial}{LiePolynomialXmpPage} }
+{ \downlink{LinearOrdinaryDifferentialOperator}{LinearOrdinaryDifferentialOperatorXmpPage} }
+{ \downlink{LinearOrdinaryDifferentialOperator1}{LinearOrdinaryDifferentialOperatorOneXmpPage} }
+{ \downlink{LinearOrdinaryDifferentialOperator2}{LinearOrdinaryDifferentialOperatorTwoXmpPage} }
+{ \downlink{List}{ListXmpPage} }
+{ \downlink{LyndonWord}{LyndonWordXmpPage} }
+{ \downlink{Magma}{MagmaXmpPage} }
+{ \downlink{MakeFunction}{MakeFunctionXmpPage} }
+{ \downlink{MappingPackage1}{MappingPackageOneXmpPage} }
+{ \downlink{Matrix}{MatrixXmpPage} }
+{ \downlink{MultiSet}{MultiSetXmpPage} }
+{ \downlink{MultivariatePolynomial}{MultivariatePolynomialXmpPage} }
+{ \downlink{None}{NoneXmpPage} }
+{ \downlink{Octonion}{OctonionXmpPage} }
+{ \downlink{OneDimensionalArray}{OneDimensionalArrayXmpPage} }
+{ \downlink{Operator}{OperatorXmpPage} }
+{ \downlink{OrderedVariableList}{OrderedVariableListXmpPage} }
+{ \downlink{OrderlyDifferentialPolynomial}{OrderlyDifferentialPolynomialXmpPage} }
+{ \downlink{PartialFraction}{PartialFractionXmpPage} }
+{ \downlink{Permanent}{PermanentXmpPage} }
+{ \downlink{Polynomial}{PolynomialXmpPage} }
+{ \downlink{Quaternion}{QuaternionXmpPage} }
+{ \downlink{RadixExpansion}{RadixExpansionXmpPage} }
+{ \downlink{RealClosure}{RealClosureXmpPage} }
+{ \downlink{RegularTriangularSet}{RegularTriangularSetXmpPage} }
+{ \downlink{RomanNumeral}{RomanNumeralXmpPage} }
+{ \downlink{Segment}{SegmentXmpPage} }
+{ \downlink{SegmentBinding}{SegmentBindingXmpPage} }
+{ \downlink{Set}{SetXmpPage} }
+{ \downlink{SingleInteger}{SingleIntegerXmpPage} }
+{ \downlink{SparseTable}{SparseTableXmpPage} }
+{ \downlink{SquareMatrix}{SquareMatrixXmpPage} }
+{ \downlink{SquareFreeRegularTriangularSet}{SquareFreeRegularTriangularSetXmpPage} }
+{ \downlink{Stream}{StreamXmpPage} }
+{ \downlink{String}{StringXmpPage} }
+{ \downlink{StringTable}{StringTableXmpPage} }
+{ \downlink{Symbol}{SymbolXmpPage} }
+{ \downlink{Table}{TableXmpPage} }
+{ \downlink{TextFile}{TextFileXmpPage} }
+{ \downlink{TwoDimensionalArray}{TwoDimensionalArrayXmpPage} }
+{ \downlink{UnivariatePolynomial}{UnivariatePolynomialXmpPage} }
+{ \downlink{UniversalSegment}{UniversalSegmentXmpPage} }
+{ \downlink{Vector}{VectorXmpPage} }
+{ \downlink{Void}{VoidXmpPage} }
+{ \downlink{WuWenTsunTriangularSet}{WuWenTsunTriangularSetXmpPage} }
+{ \downlink{XPBWPolynomial}{XPBWPolynomialXmpPage} }
+{ \downlink{XPolynomial}{XPolynomialXmpPage} }
+{ \downlink{XPolynomialRing}{XPolynomialRingXmpPage} }
+{ \downlink{ZeroDimensionalSolvePackage}{ZeroDimensionalSolvePackageXmpPage} }
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{xpbwpoly.ht}
+<<xpbwpoly.ht>>=
+\newcommand{\XPBWPolynomialXmpTitle}{XPBWPolynomial}
+\newcommand{\XPBWPolynomialXmpNumber}{9.88}
+
+@
+\subsection{XPBWPolynomial}
+\label{XPBWPolynomialXmpPage}
+\index{pages!XPBWPolynomialXmpPage!xpbwpoly.ht}
+\index{xpbwpoly.ht!pages!XPBWPolynomialXmpPage}
+\index{XPBWPolynomialXmpPage!xpbwpoly.ht!pages}
+<<xpbwpoly.ht>>=
+\begin{page}{XPBWPolynomialXmpPage}{XPBWPolynomial}
+\beginscroll
+Initialisations
+\xtc{
+}{
+\spadpaste{a:Symbol := 'a \bound{a}}
+}
+\xtc{
+}{
+\spadpaste{b:Symbol := 'b \bound{b}}
+}
+\xtc{
+}{
+\spadpaste{RN    := Fraction(Integer) \bound{RN}}
+}
+\xtc{
+}{
+\spadpaste{word   := OrderedFreeMonoid Symbol \bound{word}}
+}
+\xtc{
+}{
+\spadpaste{lword := LyndonWord(Symbol) \bound{lword}}
+}
+\xtc{
+}{
+\spadpaste{base  := PoincareBirkhoffWittLyndonBasis Symbol \bound{base}}
+}
+\xtc{
+}{
+\spadpaste{dpoly := XDistributedPolynomial(Symbol, RN) \bound{dpoly} \free{RN}}
+}
+\xtc{
+}{
+\spadpaste{rpoly := XRecursivePolynomial(Symbol, RN) \bound{rpoly} \free{RN}}
+}
+\xtc{
+}{
+\spadpaste{lpoly := LiePolynomial(Symbol, RN) \bound{lpoly} \free{RN}}
+}
+\xtc{
+}{
+\spadpaste{poly  := XPBWPolynomial(Symbol, RN) \bound{poly} \free{RN}}
+}
+\xtc{
+}{
+\spadpaste{liste : List lword := LyndonWordsList([a,b], 6) \bound{liste} \free{lword a b }}
+}
+
+Let's make some polynomials
+\xtc{
+}{
+\spadpaste{0$poly \free{poly}}
+}
+\xtc{
+}{
+\spadpaste{1$poly \free{poly}}
+}
+\xtc{
+}{
+\spadpaste{p : poly := a \free{a poly} \bound{p}}
+}
+\xtc{
+}{
+\spadpaste{q : poly := b \free{b poly} \bound{q}}
+}
+\xtc{
+}{
+\spadpaste{pq: poly := p*q \free{p q poly} \bound{pq}}
+}
+\xtc{
+Coerce to distributed polynomial
+}{
+\spadpaste{pq :: dpoly \free{pq dpoly}}
+}
+
+Check some polynomial operations
+\xtc{
+}{
+\spadpaste{mirror pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{ListOfTerms pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{reductum pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{leadingMonomial pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{coefficients pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{leadingTerm pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{degree pq \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{pq4:=exp(pq,4) \bound{pq4} \free{pq}}
+}
+\xtc{
+}{
+\spadpaste{log(pq4,4) - pq \free{pq4 pq} }
+}
+
+Calculations with verification in \axiomType{XDistributedPolynomial}.
+\xtc{
+}{
+\spadpaste{lp1 :lpoly := LiePoly liste.10 \free{liste lpoly} \bound{lp1}}
+}
+\xtc{
+}{
+\spadpaste{lp2 :lpoly := LiePoly liste.11 \free{liste lpoly} \bound{lp2}}
+}
+\xtc{
+}{
+\spadpaste{lp  :lpoly := [lp1, lp2] \free{lp1 lp2 lpoly} \bound{lp}}
+}
+\xtc{
+}{
+\spadpaste{lpd1: dpoly := lp1 \free{lp1 dpoly} \bound{lpd1}}
+}
+\xtc{
+}{
+\spadpaste{lpd2: dpoly := lp2 \free{lp2 dpoly} \bound{lpd2}}
+}
+\xtc{
+}{
+\spadpaste{lpd : dpoly := lpd1 * lpd2 - lpd2 * lpd1 \free{dpoly lpd1 lpd2} \bound{lpd}}
+}
+\xtc{
+}{
+\spadpaste{lp :: dpoly - lpd \free{lpd dpoly lp}}
+}
+
+Calculations with verification in \axiomType{XRecursivePolynomial}.
+\xtc{
+}{
+\spadpaste{p := 3 * lp \free{lp} \bound{pp}}
+}
+\xtc{
+}{
+\spadpaste{q := lp1 \free{lp1} \bound{qq}}
+}
+\xtc{
+}{
+\spadpaste{pq:= p * q \free{pp qq} \bound{pqpq}}
+}
+\xtc{
+}{
+\spadpaste{pr:rpoly := p :: rpoly \free{rpoly pp} \bound{pr}}
+}
+\xtc{
+}{
+\spadpaste{qr:rpoly := q :: rpoly \free{rpoly qq} \bound{qr}}
+}
+\xtc{
+}{
+\spadpaste{pq :: rpoly - pr*qr \free{pr qr rpoly pqpq} }
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{xpoly.ht}
+<<xpoly.ht>>=
+\newcommand{\XPolynomialXmpTitle}{XPolynomial}
+\newcommand{\XPolynomialXmpNumber}{9.89}
+
+@
+\subsection{XPolynomial}
+\label{XPolynomialXmpPage}
+\index{pages!XPolynomialXmpPage!xpoly.ht.ht}
+\index{xpoly.ht.ht!pages!XPolynomialXmpPage}
+\index{XPolynomialXmpPage!xpoly.ht.ht!pages}
+<<xpoly.ht.ht>>=
+\begin{page}{XPolynomialXmpPage}{XPolynomial}
+\beginscroll
+The \spadtype{XPolynomial} domain constructor implements 
+multivariate polynomials
+whose set of variables is \spadtype{Symbol}.
+These variables do not commute.
+The only parameter of this construtor is 
+the coefficient ring which may be non-commutative.
+However, coefficients and variables commute.
+The representation of the polynomials is recursive.
+The abbreviation for \spadtype{XPolynomial} is \spadtype{XPOLY}.
+
+Other constructors like \spadtype{XPolynomialRing}, 
+\spadtype{XRecursivePolynomial} 
+\spadtype{XDistributedPolynomial},
+\spadtype{LiePolynomial} and
+\spadtype{XPBWPolynomial}
+implement multivariate polynomials
+in non-commutative variables.
+
+We illustrate now some of the facilities of the \spadtype{XPOLY} domain constructor.
+
+
+\xtc{
+Define a polynomial ring over the integers.
+}{
+\spadpaste{poly := XPolynomial(Integer) \bound{poly}}
+}
+
+\xtc{
+Define a first polynomial,
+}{
+\spadpaste{pr: poly := 2*x + 3*y-5  \free{poly} \bound{pr}}
+}
+
+
+\xtc{
+and a second one.
+}{
+\spadpaste{pr2: poly := pr*pr  \free{poly} \bound{pr2}}
+}
+
+\xtc{
+Rewrite {\bf pr} in a distributive way,
+}{
+\spadpaste{pd  := expand pr   \free{pr} \bound{pd}}
+}
+
+\xtc{
+compute its square,
+}{
+\spadpaste{pd2 := pd*pd   \free{pd} \bound{pd2}}
+}
+
+\xtc{
+and checks that:
+}{
+\spadpaste{expand(pr2) - pd2 \free{pr2} \free{pd2}}
+}
+
+
+\xtc{
+We define:
+}{
+\spadpaste{qr :=  pr**3 \free{pr} \bound{qr}}
+}
+
+\xtc{
+and:
+}{
+\spadpaste{qd :=  pd**3 \free{pd} \bound{qd}}
+}
+
+\xtc{
+We truncate {\bf qd} at degree {\bf 3}:
+}{
+\spadpaste{ trunc(qd,2) \free{qd}}
+}
+
+\xtc{
+The same for {\bf qr}:
+}{
+\spadpaste{trunc(qr,2) \free{qr}}
+}
+
+\xtc{
+We define:
+}{
+\spadpaste{Word := OrderedFreeMonoid Symbol \bound{Word}}
+}
+
+\xtc{
+and:
+}{
+\spadpaste{w: Word := x*y**2 \free{Word} \bound{w}}
+}
+
+\xtc{
+The we can compute the right-quotient of {\bf qr} by {\bf r}:
+}{
+\spadpaste{rquo(qr,w) \free{qr} \free{w}}
+}
+
+\xtc{
+and the shuffle-product of {\bf pr} by {\bf r}:
+}{
+\spadpaste{sh(pr,w::poly) \free{pr} \free{w}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{xpr.ht}
+<<xpr.ht>>=
+\newcommand{\XPolynomialRingXmpTitle}{XPolynomialRing}
+\newcommand{\XPolynomialRingXmpNumber}{9.90}
+
+@
+\subsection{XPolynomialRing}
+\label{XPolynomialRingXmpPage}
+\index{pages!XPolynomialRingXmpPage!xpr.ht}
+\index{xpr.ht!pages!XPolynomialRingXmpPage}
+\index{XPolynomialRingXmpPage!xpr.ht!pages}
+<<xpr.ht>>=
+\begin{page}{XPolynomialRingXmpPage}{XPolynomialRing}
+\beginscroll
+The \spadtype{XPolynomialRing} domain constructor implements
+generalized polynomials with coefficients from an arbitrary \spadtype{Ring}
+(not necessarily commutative) and whose exponents are
+words from an arbitrary \spadtype{OrderedMonoid}
+(not necessarily commutative too).
+Thus these polynomials are (finite) linear combinations of words.
+
+This constructor takes two arguments.
+The first one is a \spadtype{Ring}
+and the second is an \spadtype{OrderedMonoid}.
+The abbreviation for \spadtype{XPolynomialRing} is \spadtype{XPR}.
+
+Other constructors like \spadtype{XPolynomial}, 
+\spadtype{XRecursivePolynomial} 
+\spadtype{XDistributedPolynomial},
+\spadtype{LiePolynomial} and
+\spadtype{XPBWPolynomial}
+implement multivariate polynomials
+in non-commutative variables.
+
+We illustrate now some of the facilities of the \spadtype{XPR} domain constructor.
+
+\xtc{
+Define the free ordered monoid generated by the symbols.
+}{
+\spadpaste{Word := OrderedFreeMonoid(Symbol) \bound{Word}}
+}
+
+\xtc{
+Define the linear combinations of these words with integer coefficients.
+}{
+\spadpaste{poly:= XPR(Integer,Word) \free{Word} \bound{poly}}
+}
+
+
+\xtc{
+Then we define a first element from {\bf poly}.
+}{
+\spadpaste{p:poly := 2 * x - 3 * y + 1 \free{poly} \bound{p}}
+}
+
+\xtc{
+And a second one.
+}{
+\spadpaste{q:poly := 2 * x + 1 \free{poly} \bound{q}}
+}
+
+
+\xtc{
+We compute their sum,
+}{
+\spadpaste{p + q  \free{p}\free{q} }
+}
+
+\xtc{
+their product,
+}{
+\spadpaste{p * q  \free{p}\free{q} }
+}
+
+\xtc{
+and see that variables do not commute.
+}{
+\spadpaste{(p +q)^2 -p^2 -q^2 - 2*p*q  \free{p}\free{q} }
+}
+
+
+
+\xtc{
+Now we define a ring of square matrices,
+}{
+\spadpaste{M := SquareMatrix(2,Fraction Integer)  \bound{M}}
+}
+
+\xtc{
+and the linear combinations of words with these  matrices as coefficients.
+}{
+\spadpaste{poly1:= XPR(M,Word) \free{Word} \free{M} \bound{poly1}}
+}
+
+
+\xtc{
+Define a first matrix,
+}{
+\spadpaste{m1:M := matrix [[i*j**2 for i in 1..2] for j in 1..2] \free{M} \bound{m1}}
+}
+
+\xtc{
+a second one,
+}{
+\spadpaste{m2:M := m1 - 5/4 \free{M} \free{m1} \bound{m2}}
+}
+
+\xtc{
+and a third one.
+}{
+\spadpaste{m3: M := m2**2 \free{M} \free{m2} \bound{m3}}
+}
+
+\xtc{
+Define a polynomial,
+}{
+\spadpaste{pm:poly1   := m1*x + m2*y + m3*z - 2/3 \free{poly1} \free{m1} \free{m2} \free{m3} \bound{pm}}
+}
+
+
+\xtc{
+a second one,
+}{
+\spadpaste{qm:poly1 := pm - m1*x \free{m1} \free{pm} \bound{qm}}
+}
+
+\xtc{
+and the following power.
+}{
+\spadpaste{qm**3 \bound{qm}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{zdsolve.ht}
+<<zdsolve.ht>>=
+\newcommand{\ZeroDimensionalSolvePackageXmpTitle}{ZeroDimensionalSolvePackage}
+\newcommand{\ZeroDimensionalSolvePackageXmpNumber}{9.91}
+
+@
+\subsection{ZeroDimensionalSolvePackage}
+\label{ZeroDimensionalSolvePackageXmpPage}
+\index{pages!ZeroDimensionalSolvePackageXmpPage!zdsolve.ht}
+\index{zdsolve.ht!pages!ZeroDimensionalSolvePackageXmpPage}
+\index{ZeroDimensionalSolvePackageXmpPage!zdsolve.ht!pages}
+<<zdsolve.ht>>=
+\begin{page}{ZeroDimensionalSolvePackageXmpPage}{ZeroDimensionalSolvePackage}
+\beginscroll
+The \spadtype{ZeroDimensionalSolvePackage} package constructor 
+provides operations for computing symbolically the complex or real roots of 
+zero-dimensional algebraic systems.
+
+The package provides {\bf no} multiplicity information (i.e. some returned
+roots may be double or higher) but only distinct roots are returned. 
+
+Complex roots are given by means of univariate representations
+of irreducible regular chains. 
+These representations are computed by the 
+\axiomOpFrom{univariateSolve}{ZeroDimensionalSolvePackage}
+operation (by calling the 
+\spadtype{InternalRationalUnivariateRepresentationPackage} 
+package constructor which does the job).
+
+Real roots are given by means of tuples
+of coordinates lying in the \spadtype{RealClosure} of the coefficient ring.
+They are computed by the \axiomOpFrom{realSolve}{ZeroDimensionalSolvePackage}
+and \axiomOpFrom{positiveSolve}{ZeroDimensionalSolvePackage} operations.
+The former computes all the solutions of the input system with real coordinates
+whereas the later concentrate 
+on the solutions with (strictly) positive coordinates.
+In both cases, the computations 
+are performed by the \spadtype{RealClosure} constructor.
+
+Both computations of complex roots 
+and real roots rely on triangular decompositions.
+These decompositions can be computed in two different ways.
+First, by a applying the \axiomOpFrom{zeroSetSplit}{RegularTriangularSet} 
+operation from the \spadtype{REGSET} domain constructor.
+In that case, no Groebner bases are computed.
+This strategy is used by default.
+Secondly, by applying the \axiomOpFrom{zeroSetSplit}{LexTriangularPackage}
+from \spadtype{LEXTRIPK}.
+To use this later strategy with the operations
+\axiomOpFrom{univariateSolve}{ZeroDimensionalSolvePackage},
+\axiomOpFrom{realSolve}{ZeroDimensionalSolvePackage}
+and \axiomOpFrom{positiveSolve}{ZeroDimensionalSolvePackage} 
+one just needs to use an extra boolean argument.
+
+Note that the way of understanding triangular decompositions 
+is detailed in the example of the \spadtype{RegularTriangularSet}
+constructor.
+
+The \spadtype{ZeroDimensionalSolvePackage} constructor takes three arguments. 
+The first one {\bf R} is the coefficient ring;
+it must belong to the categories
+\spadtype{OrderedRing}, \spadtype{EuclideanDomain},  
+\spadtype{CharacteristicZero}
+and \spadtype{RealConstant}.
+This means essentially that {\bf R} is \spadtype{Integer} or 
+\spadtype{Fraction(Integer)}.
+The second argument {\bf ls} is the list of variables involved 
+in the systems to solve. 
+The third one MUST BE {\bf concat(ls,s)} where
+{\bf s} is an additional symbol used for the univariate representations.
+The abbreviation for \spadtype{ZeroDimensionalSolvePackage} is 
+\spadtype{ZDSOLVE}.
+
+We illustrate now how to use the constructor \spadtype{ZDSOLVE}
+by two examples: the {\em Arnborg and Lazard} system and the 
+{\em L-3} system (Aubry and Moreno Maza).
+Note that the use of this package is also demonstrated in the example
+of the \spadtype{LexTriangularPackage} constructor.
+
+\xtc{
+Define the coefficient ring.
+}{
+\spadpaste{R := Integer \bound{R}}
+}
+
+\xtc{
+Define the lists of variables:
+}{
+\spadpaste{ls : List Symbol := [x,y,z,t] \bound{ls}}
+}
+
+\xtc{
+and:
+}{
+\spadpaste{ls2 : List Symbol := [x,y,z,t,new()$Symbol] \bound{ls2}}
+}
+
+\xtc{
+Call the package:
+}{
+\spadpaste{pack := ZDSOLVE(R,ls,ls2) \free{ls} \free{ls2} \free{R} \bound{pack}}
+}
+
+\xtc{
+Define a polynomial system (Arnborg-Lazard)
+}{
+\spadpaste{p1 := x**2*y*z + x*y**2*z + x*y*z**2 + x*y*z + x*y + x*z + y*z \bound{p1}}
+}
+\xtc{
+}{
+\spadpaste{p2 := x**2*y**2*z + x*y**2*z**2 + x**2*y*z + x*y*z + y*z + x + z \bound{p2}}
+}
+\xtc{
+}{
+\spadpaste{p3 := x**2*y**2*z**2 + x**2*y**2*z + x*y**2*z + x*y*z + x*z + z + 1 \bound{p3}}
+}
+\xtc{
+}{
+\spadpaste{lp := [p1, p2, p3] \free{p1} \free{p2} \free{p3} \bound{lp}}
+}
+Note that these polynomials do not involve the variable {\bf t};
+we will use it in the second example.
+
+\xtc{
+First compute a decomposition into regular chains 
+(i.e. regular triangular sets).
+}{
+\spadpaste{triangSolve(lp)$pack \free{lp} \free{pack}}
+}
+
+We can see easily from this decomposition (consisting of a single
+regular chain) that the input system has 20 complex roots.
+
+\xtc{
+Then we compute a univariate representation of this regular chain.
+}{
+\spadpaste{univariateSolve(lp)$pack \free{lp} \free{pack}}
+}
+
+We see that the zeros of our regular chain are split into three components.
+This is due to the use of univariate polynomial factorization.
+
+Each of these components consist of two parts.
+The first one is an irreducible univariate polynomial {\bf p(?)} which defines
+a simple algebraic extension of the field of fractions of {\bf R}.
+The second one consists of multivariate polynomials {\bf pol1(x,\%A)},
+{\bf pol2(y,\%A)} and {\bf pol3(z,\%A)}.
+Each of these polynomials involve two variables: one is an indeterminate
+{\bf x}, {\bf y} or {\bf z}
+of the input system {\bf lp} and the 
+other is {\bf \%A} which represents any root of {\bf p(?)}.
+Recall that this {\bf \%A} is the last element of the third parameter of 
+\spadtype{ZDSOLVE}.
+Thus any complex root {\bf ?} of {\bf p(?)} 
+leads to a solution of the input system {\bf lp} 
+by replacing {\bf \%A} by this {\bf ?} in {\bf pol1(x,\%A)},
+{\bf pol2(y,\%A)} and {\bf pol3(z,\%A)}.
+Note that the polynomials {\bf pol1(x,\%A)},
+{\bf pol2(y,\%A)} and {\bf pol3(z,\%A)} have degree one 
+w.r.t. {\bf x}, {\bf y} or {\bf z} respectively.
+This is always the case for all univariate representations.
+Hence the operation {\bf univariateSolve} replaces a
+system of multivariate polynomials by a list of univariate
+polynomials, what justifies its name.
+Another example of univariate representations illustrates
+the \spadtype{LexTriangularPackage} package constructor.
+
+\xtc{
+We now compute the solutions with real coordinates:
+}{
+\spadpaste{lr := realSolve(lp)$pack \free{lp} \free{pack} \bound{lr}}
+}
+
+\xtc{
+The number of real solutions for the input system is:
+}{
+\spadpaste{\# lr \free{lr}}
+}
+
+Each of these real solutions is given by a 
+list of elements in  \spadtype{RealClosure(R)}.
+In these 8 lists, the first element is a value of {\bf z}, 
+the second of {\bf y} and the last of {\bf x}.
+This is logical since by setting the list of variables of the package
+to {\bf [x,y,z,t]} we mean that the elimination ordering on the
+variables is {\bf t < z < y < x }.
+Note that each system treated by the \spadtype{ZDSOLVE} package constructor
+needs only to be zero-dimensional w.r.t. the variables involved in the system it-self
+and not necessarily w.r.t. all the variables used to define the package.
+
+\xtc{
+We can approximate these real numbers as follows. 
+This computation takes between 30 sec. and 5 min, depending on your machine.
+}{
+\spadpaste{[[approximate(r,1/1000000) for r in point] for point in lr] \free{lr}}
+}
+
+\xtc{
+We can also concentrate on the solutions with real (strictly) positive coordinates:
+}{
+\spadpaste{lpr := positiveSolve(lp)$pack \free{lp} \free{pack} \bound{lpr}}
+}
+
+Thus we have checked that the input system has no solution with strictly positive coordinates.
+
+
+\xtc{
+Let us define another polynomial system ({\em L-3}).
+}{
+\spadpaste{f0 := x**3 + y + z + t- 1 \bound{f0}}
+}
+\xtc{
+}{
+\spadpaste{f1 := x + y**3 + z + t -1 \bound{f1}}
+}
+\xtc{
+}{
+\spadpaste{f2 := x + y + z**3 + t-1 \bound{f2}}
+}
+\xtc{
+}{
+\spadpaste{f3 := x + y + z + t**3 -1 \bound{f3}}
+}
+\xtc{
+}{
+\spadpaste{lf := [f0, f1, f2, f3] \free{f0} \free{f1} \free{f2} \free{f3} \bound{lf}}
+}
+
+
+\xtc{
+First compute a decomposition into regular chains 
+(i.e. regular triangular sets).
+}{
+\spadpaste{lts := triangSolve(lf)$pack \free{lf} \free{pack} \bound{lts}}
+}
+
+
+\xtc{
+Then we compute a univariate representation.
+}{
+\spadpaste{univariateSolve(lf)$pack \free{lf} \free{pack}}
+}
+
+Note that this computation is made from the input system {\bf lf}.
+\xtc{
+However it is possible to reuse a pre-computed regular chain as follows:
+}{
+\spadpaste{ts := lts.1 \free{lts} \bound{ts}}
+}
+\xtc{
+}{
+\spadpaste{univariateSolve(ts)$pack \free{ts} \free{pack}}
+}
+\xtc{
+}{
+\spadpaste{realSolve(ts)$pack  \free{ts} \free{pack}}
+}
+
+\xtc{
+We compute now the full set of points with real coordinates:
+}{
+\spadpaste{lr2 := realSolve(lf)$pack \free{lf} \free{pack}  \bound{lr2}}
+}
+
+
+\xtc{
+The number of real solutions for the input system is:
+}{
+\spadpaste{\#lr2 \free{lr2}}
+}
+Another example of computation of real solutions illustrates
+the \spadtype{LexTriangularPackage} package constructor.
+
+\xtc{
+We concentrate now on the solutions with real (strictly) positive coordinates:
+}{
+\spadpaste{lpr2 := positiveSolve(lf)$pack \free{lf} \free{pack} \bound{lpr2}}
+}
+
+\xtc{
+Finally, we approximate the coordinates of this point with 20 exact digits:
+}{
+\spadpaste{[approximate(r,1/10**21)::Float for r in lpr2.1] \free{lpr2}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\section{zlindep.ht}
+<<zlindep.ht>>=
+\newcommand{\IntegerLinearDependenceXmpTitle}{IntegerLinearDependence}
+\newcommand{\IntegerLinearDependenceXmpNumber}{9.35}
+
+@
+\subsection{IntegerLinearDependence}
+\label{IntegerLinearDependenceXmpPage}
+\index{pages!IntegerLinearDependenceXmpPage!zlindep.ht}
+\index{zlindep.ht!pages!IntegerLinearDependenceXmpPage}
+\index{IntegerLinearDependenceXmpPage!zlindep.ht!pages}
+<<zlindep.ht>>=
+\begin{page}{IntegerLinearDependenceXmpPage}{IntegerLinearDependence}
+\beginscroll
+
+The elements \texht{$v_1, \dots,v_n$}{\spad{v1,...,vn}}
+of a module \spad{M} over a ring \spad{R} are
+said to be {\it linearly dependent over \spad{R}} if there exist
+\texht{$c_1,\dots,c_n$}{\spad{c1, ..., cn}} in \spad{R},
+not all \smath{0},
+such that 
+\texht{$c_1 v_1 + \dots c_n v_n = 0$}{\spad{c1*v1 + ... + cn*vn = 0}}.
+If such \texht{$c_i$}{\spad{ci}}'s exist,
+they form what is called a {\it linear dependence
+relation over \spad{R}} for the \texht{$v_i$}{\spad{vi}}'s.
+
+The package \spadtype{IntegerLinearDependence} provides functions
+for testing whether some elements of a module over the integers are
+linearly dependent over the integers, and to find the linear
+dependence relations, if any.
+%
+\xtc{
+Consider the domain of two by two square matrices with integer entries.
+}{
+\spadpaste{M := SQMATRIX(2,INT) \bound{M}}
+}
+%
+%
+\xtc{
+Now create three such matrices.
+}{
+\spadpaste{m1: M := squareMatrix matrix [[1, 2], [0, -1]] \free{M}\bound{m1}}
+}
+\xtc{
+}{
+\spadpaste{m2: M := squareMatrix matrix [[2, 3], [1, -2]] \free{M}\bound{m2}}
+}
+\xtc{
+}{
+\spadpaste{m3: M := squareMatrix matrix [[3, 4], [2, -3]] \free{M}\bound{m3}}
+}
+%
+%
+\xtc{
+This tells you whether \spad{m1}, \spad{m2} and \spad{m3} are linearly
+dependent over the integers.
+}{
+\spadpaste{linearlyDependentOverZ? vector [m1, m2, m3] \free{m1 m2 m3}}
+}
+%
+%
+\xtc{
+Since they are linearly dependent, you can ask for the dependence
+relation.
+}{
+\spadpaste{c := linearDependenceOverZ vector [m1, m2, m3] \free{m1 m2 m3}\bound{c}}
+}
+%
+%
+\xtc{
+This means that the following linear combination should be \spad{0}.
+}{
+\spadpaste{c.1 * m1 + c.2 * m2 + c.3 * m3 \free{c m1 m2 m3}}
+}
+%
+When a given set of elements are linearly dependent over \spad{R}, this
+also means that at least one of them can be rewritten as a linear
+combination of the others with coefficients in the quotient field of
+\spad{R}.
+%
+\xtc{
+To express a given element in terms of other elements, use the operation
+\spadfunFrom{solveLinearlyOverQ}{IntegerLinearDependence}.
+}{
+\spadpaste{solveLinearlyOverQ(vector [m1, m3], m2) \free{m1 m2 m3}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\chapter{Users Guide Pages (ug.ht)}
+DO NOT MODIFY THIS FILE BY HAND !! Created by chapmenu.awk.
+\section{Users Guide}
+\label{UsersGuidePage}
+\begin{itemize}
+\item ugWhatsNewTwoTwoPage \ref{ugWhatsNewTwoTwoPage} on 
+page~\pageref{ugWhatsNewTwoTwoPage}
+\item ugIntroPage \ref{ugIntroPage} on page~\pageref{ugIntroPage}
+\item ugTypesPage \ref{ugTypesPage} on page~\pageref{ugTypesPage}
+\item ugHyperPage \ref{ugHyperPage} on page~\pageref{ugHyperPage}
+\item ugInOutPage \ref{ugInOutPage} on page~\pageref{ugInOutPage}
+\item ugLangPage \ref{ugLangPage} on page~\pageref{ugLangPage}
+\item ugUserPage \ref{ugUserPage} on page~\pageref{ugUserPage}
+\item ugGraphPage \ref{ugGraphPage} on page~\pageref{ugGraphPage}
+\item ugProblemPage \ref{ugProblemPage} on page~\pageref{ugProblemPage}
+\item ExamplesExposedPage \ref{ExamplesExposedPage} on 
+page~\pageref{ExamplesExposedPage}
+\item ugIntProgPage \ref{ugIntProgPage} on page~\pageref{ugIntProgPage}
+\item ugPackagesPage \ref{ugPackagesPage} on page~\pageref{ugPackagesPage}
+\item ugCategoriesPage \ref{ugCategoriesPage} on 
+page~\pageref{ugCategoriesPage}
+\item ugDomainsPage \ref{ugDomainsPage} on page~\pageref{ugDomainsPage}
+\item ugBrowsePage \ref{ugBrowsePage} on page~\pageref{ugBrowsePage}
+\item ugWhatsNewPage \ref{ugWhatsNewPage} on page~\pageref{ugWhatsNewPage}
+\item ugSysCmdPage \ref{ugSysCmdPage} on page~\pageref{ugSysCmdPage}
+\item ugAppGraphicsPage \ref{ugAppGraphicsPage} on 
+page~\pageref{ugAppGraphicsPage}
+\end{itemize}
+\index{pages!UsersGuidePage!ug.ht}
+\index{ug.ht!pages!UsersGuidePage}
+\index{UsersGuidePage!ug.ht!pages}
+<<ug.ht>>=
+\begin{page}{UsersGuidePage}{Users Guide}
+This is the table of contents for the Users Guide.
+Click on any item below to see that section.
+\beginscroll
+\indent{3}
+\beginmenu
+\menudownlink{{0. What's New in Axiom Version 2.2}}{ugWhatsNewTwoTwoPage}
+\endmenu
+\indent{0}
+Part I.   Basic Features of Axiom
+\indent{3}
+\beginmenu
+\menudownlink{{1. An Overview of Axiom}}{ugIntroPage}
+\menudownlink{{2. Using Types and Modes}}{ugTypesPage}
+\menudownlink{{3. Using \HyperName{}}}{ugHyperPage}
+\menudownlink{{4. Input Files and Output Styles}}{ugInOutPage}
+\menudownlink{{5. Introduction to the Axiom Interactive Language}}{ugLangPage}
+\menudownlink{{6. User-Defined Functions, Macros and Rules}}{ugUserPage}
+\menudownlink{{7. Graphics}}{ugGraphPage}
+\endmenu
+\indent{0}
+Part II.  Advanced Problem Solving and Examples
+\indent{3}
+\beginmenu
+\menudownlink{{8. Advanced Problem Solving}}{ugProblemPage}
+\menudownlink{{9. Some Examples for Domains and Packages}}{ExamplesExposedPage}
+\endmenu
+\indent{0}
+Part III. Advanced Programming in Axiom
+\indent{3}
+\beginmenu
+\menudownlink{{10. Interactive Programming}}{ugIntProgPage}
+\menudownlink{{11. Packages}}{ugPackagesPage}
+\menudownlink{{12. Categories}}{ugCategoriesPage}
+\menudownlink{{13. Domains}}{ugDomainsPage}
+\menudownlink{{14. Browse}}{ugBrowsePage}
+\menudownlink{{15. What's New in Axiom Version 2.0}}{ugWhatsNewPage}
+\endmenu
+\indent{0}
+Appendices.
+\indent{3}
+\beginmenu
+\menudownlink{{A. Axiom System Commands}}{ugSysCmdPage}
+\menudownlink{{F. Programs for Axiom Images}}{ugAppGraphicsPage}
+\menudownlink{{G. Glossary}}{GlossaryPage}
+\endmenu
+\indent{0}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\chapter{Users Guide Chapter 0 (ug00.ht)}
+<<ug00.ht>>=
+\newcommand{\ugWhatsNewTwoTwoTitle}{What's New in Axiom Version 2.2}
+\newcommand{\ugWhatsNewTwoTwoNumber}{0.}
+
+@
+\section{What's New in Axiom Version 2.2}
+\label{ugWhatsNewTwoTwoPage}
+\begin{itemize}
+\item ugTwoTwoAldorPage \ref{ugTwoTwoAldorPage} on
+page~\pageref{ugTwoTwoAldorPage}
+\item ugTwoTwoPolynomialsPage \ref{ugTwoTwoPolynomialsPage} on
+page~\pageref{ugTwoTwoPolynomialsPage}
+\item ugTwoTwoHyperdocPage \ref{ugTwoTwoHyperdocPage} on
+page~\pageref{ugTwoTwoHyperdocPage}
+\item ugTwoTwoNAGLinkPage \ref{ugTwoTwoNAGLinkPage} on
+page~\pageref{ugTwoTwoNAGLinkPage}
+\item ugTwoTwoCCLPage \ref{ugTwoTwoCCLPage} on
+page~\pageref{ugTwoTwoCCLPage}
+\end{itemize}
+\index{pages!ugWhatsNewTwoTwoPage!ug00.ht}
+\index{ug00.ht!pages!ugWhatsNewTwoTwoPage}
+\index{ugWhatsNewTwoTwoPage!ug00.ht!pages}
+<<ug00.ht>>=
+\begin{page}{ugWhatsNewTwoTwoPage}{0. What's New in Axiom Version 2.2}
+\beginscroll
+
+\beginmenu
+    \menudownlink{{0.1. \axiomxl{} compiler - Enhancements and Additions}}
+{ugTwoTwoAldorPage}
+    \menudownlink{{0.2. New polynomial domains and algorithms}}
+{ugTwoTwoPolynomialsPage}
+    \menudownlink{{0.3. Enhancements to HyperDoc and Graphics}}
+{ugTwoTwoHyperdocPage}
+    \menudownlink{{0.4. Enhancements to NAGLink}}{ugTwoTwoNAGLinkPage}
+    \menudownlink{{0.5. Enhancements to the Lisp system}}{ugTwoTwoCCLPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug00.ht>>=
+\newcommand{\ugTwoTwoAldorTitle}{\axiomxl{} compiler - Enhancements and Additions}
+\newcommand{\ugTwoTwoAldorNumber}{0.1.}
+
+@
+\section{Aldor compiler - Enhancements and Additions}
+\label{ugTwoTwoAldorPage}
+\index{pages!ugTwoTwoAldorPage!ug00.ht}
+\index{ug00.ht!pages!ugTwoTwoAldorPage}
+\index{ugTwoTwoAldorPage!ug00.ht!pages}
+<<ug00.ht>>=
+\begin{page}{ugTwoTwoAldorPage}{0.1. \axiomxl{} compiler - Enhancements and Additions}
+\beginscroll
+
+Numerous bug fixes and improvements have been implemented in version 1.1.12
+of \axiomxl{} which is included in this release. You may also notice the name
+{\it Aldor} being used when referring to \axiomxl{}.
+
+The format of {\bf .ao} files has changed somewhat so you need
+to recompile your {\bf .as} source files.
+
+An updated User's Guide is included for on-line use. We provide
+TeX {\bf .dvi} format (including hyper-references), Acrobat {\bf .pdf}
+format, PostScript {\bf .ps} format and plain ASCII {bf .txt}. 
+An up-to-date {\bf .dvi}
+viewer should be able to allow you to follow the cross-references.
+These files can be found in 
+{\bf \env{AXIOM}/compiler/doc/axlugII.*}.
+
+An exception mechanism has been implemented. You can now throw and 
+catch exceptions which are fully-fledged domains that can carry information.
+See Chapter 31 in the on-line guide for details.
+
+Support for linking with Fortran-77 code has been added. You can call
+Fortran-77 code from {\it Aldor}  and vice-versa. See Chapter 32
+in the on-line guide for details.
+
+The \spad{ref} keyword has been added. You must use \spad{_ref} to 
+enable use as an identifier.
+
+A generic configurable C compiler and linker driver i{\bf unicl} has been 
+implemented. You can now select C compiler and linker options with
+greater ease and you can give names to specific configurations. 
+See Chapter 28 in the on-line guide for details.
+
+There is now support for accessing IEEE floating-point rounding modes
+and exception flags. You must ensure however that your C compiler 
+and linker will respect the IEEE standard by enabling the appropriate
+options through {\bf unicl}. 
+See BasicIeeeControlPackage (26.7) in the on-line guide.
+
+Special runtime libraries ({\bf libfoam-gmp.a}) have been prepared to enable
+a drop-in replacement of Aldor's big-integer arithmetic with the GNU gmp
+big-integer library. The executable script {\bf axiomxl.gmp} (in the same place
+as {\bf axiomxl}) expects the {\bf GmpDir} environment variable to be set 
+to the directory where a compiled GNU gmp library resides ({\bf libgmp.a}) and 
+arranges for the appropriate libraries to be linked in when generating 
+a stand-alone executable. 
+
+The language-defined type TrailingArray has been introduced. See 
+TrailingArray (13.7) in the on-line guide.
+
+The supplied library {\bf libaxllib.al}, supporting stand-alone programs, 
+has been updated. Automatically
+generated documentation can be found in Chapters 25 and 26 of the on-line
+guide.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug00.ht>>=
+\newcommand{\ugTwoTwoPolynomialsTitle}{New polynomial domains and algorithms}
+\newcommand{\ugTwoTwoPolynomialsNumber}{0.2.}
+
+@
+\section{New polynomial domains and algorithms}
+\label{ugTwoTwoPolynomialsPage}
+\index{pages!ugTwoTwoPolynomialsPage!ug00.ht}
+\index{ug00.ht!pages!ugTwoTwoPolynomialsPage}
+\index{ugTwoTwoPolynomialsPage!ug00.ht!pages}
+<<ug00.ht>>=
+\begin{page}{ugTwoTwoPolynomialsPage}{0.2. New polynomial domains and algorithms}
+\beginscroll
+
+Univariate polynomial factorisation over the integers has been 
+enhanced by updates to the \spadtype{GaloisGroupFactorizer} type
+and friends from Frederic Lehobey (Frederic.Lehobey@lifl.fr, University of 
+Lille I, France).
+
+The package constructor \spadtype{PseudoRemainderSequence}
+provides efficient algorithms by Lionel Ducos 
+(Lionel.Ducos@mathlabo.univ-poitiers.fr, University of Poitiers, France) 
+for computing sub-resultants.
+This leads to a speed up in many places in Axiom where 
+sub-resultants are computed (polynomial system solving, 
+algebraic factorization, integration).
+
+Based on this package, the domain constructor 
+\spadtype{NewSparseUnivariatePolynomial}
+extends the constructor \spadtype{SparseUnivariatePolynomial}.
+In a similar way, the \spadtype{NewSparseMultivariatePolynomial} extends
+the constructor \spadtype{SparseUnivariatePolynomial};
+it also provides some additional operations related 
+to polynomial system solving by means of triangular sets.
+
+Several domain constructors implement
+regular triangular sets (or regular chains).
+Among them \spadtype{RegularTriangularSet}
+and \spadtype{SquareFreeRegularTriangularSet}.
+They also implement an algorithm by Marc Moreno Maza (marc@nag.co.uk, NAG)
+for computing triangular decompositions of polynomial systems.
+This method is refined in the package \spadtype{LazardSetSolvingPackage}
+in order to produce decompositions by means of Lazard triangular sets.
+For the case of polynomial systems with finitely many solutions,
+these decompositions can also be computed by
+the package \spadtype{LexTriangularPackage}.
+
+The domain constructor \spadtype{RealClosure} by Renaud Rioboo
+(Renaud.Rioboo@lip6.fr, University of Paris 6, France)
+provides the real closure of an ordered field.
+The implementation is based on interval arithmetic.
+Moreover, the design of this constructor and its related 
+packages allows an easy use of other codings for real algebraic numbers.
+
+Based on triangular decompositions and the \spadtype{RealClosure} constructor,
+the package \spadtype{ZeroDimensionalSolvePackage}
+provides operations for computing symbolically the real or complex roots
+of polynomial systems with finitely many solutions.
+
+Polynomial arithmetic with non-commutative variables 
+has been improved too by a contribution of Michel Petitot
+(Michel.Petitot@lifl.fr, University of Lille I, France).
+The domain constructors \spadtype{XRecursivePolynomial}
+and \spadtype{XDistributedPolynomial} provide
+recursive and distributed representations for these polynomials.
+They are the non-commutative equivalents for
+the \spadtype{SparseMultivariatePolynomial} 
+and \spadtype{DistributedMultivariatePolynomial} constructors.
+The constructor \spadtype{LiePolynomial} implement Lie
+polynomials in the Lyndon basis.
+The constructor \spadtype{XPBWPolynomial} manage polynomials
+with non-commutative variables in
+the \texht{Poincar\'e}{Poincare\space{-1}'}-Birkhoff-Witt basis from the Lyndon basis.
+This allows to compute in the Lie Group associated with a
+free nilpotent Lie algebra by using the \spadtype{LieExponentials}
+domain constructor.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug00.ht>>=
+\newcommand{\ugTwoTwoHyperdocTitle}{Enhancements to HyperDoc and Graphics}
+\newcommand{\ugTwoTwoHyperdocNumber}{0.3.}
+
+@
+\section{Enhancements to HyperDoc and Graphics}
+\label{ugTwoTwoHyperdocPage}
+\index{pages!ugTwoTwoHyperdocPage!ug00.ht}
+\index{ug00.ht!pages!ugTwoTwoHyperdocPage}
+\index{ugTwoTwoHyperdocPage!ug00.ht!pages}
+<<ug00.ht>>=
+\begin{page}{ugTwoTwoHyperdocPage}{0.3. Enhancements to HyperDoc and Graphics}
+\beginscroll
+
+From this version of Axiom onwards, the pixmap format used to save graphics
+images in color and to display them in HyperDoc has been changed to the 
+industry-standard XPM format. See {\tt ftp://koala.inria.fr/pub/xpm}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug00.ht>>=
+\newcommand{\ugTwoTwoNAGLinkTitle}{Enhancements to NAGLink}
+\newcommand{\ugTwoTwoNAGLinkNumber}{0.4.}
+
+@
+\section{Enhancements to NAGLink}
+\label{ugTwoTwoNAGLinkPage}
+\index{pages!ugTwoTwoNAGLinkPage!ug00.ht}
+\index{ug00.ht!pages!ugTwoTwoNAGLinkPage}
+\index{ugTwoTwoNAGLinkPage!ug00.ht!pages}
+<<ug00.ht>>=
+\begin{page}{ugTwoTwoNAGLinkPage}{0.4. Enhancements to NAGLink}
+\beginscroll
+
+This version of Axiom incorporates the Axiom/NAG Numerical Analyst (ANNA)
+software developed in the University of Bath. ANNA is an expert system which 
+uses Axiom algebra functionality in choosing the most appropriate NAG Fortran Library
+routine for a particular problem. Documentation is provided on-line on the main HyperDoc page.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug00.ht>>=
+\newcommand{\ugTwoTwoCCLTitle}{Enhancements to the Lisp system}
+\newcommand{\ugTwoTwoCCLNumber}{0.5.}
+
+@
+\section{Enhancements to the Lisp system}
+\label{ugTwoTwoCCLPage}
+\index{pages!ugTwoTwoCCLPage!ug00.ht}
+\index{ug00.ht!pages!ugTwoTwoCCLPage}
+\index{ugTwoTwoCCLPage!ug00.ht!pages}
+<<ug00.ht>>=
+\begin{page}{ugTwoTwoCCLPage}{0.5. Enhancements to the Lisp system}
+\beginscroll
+
+In this version of Axiom, certain Library operations have been
+accelerated by converting their Lisp implementations into kernel
+operations implemented directly in C. Here is a list of the
+accelerated operations. The given names encode the abbreviated type
+the operation comes from, the name of the operation and, in the case
+of exported functions, an encoded signature and numerical index.
+
+\begin{verbatim}
+|A1AGG-;=;2AB;28|
+|A1AGG-;copy;2A;19|
+|A1AGG-;sort!;M2A;2|
+|ABELGRP-;*;Nni2S;3|
+|ABELGRP-;-;3S;1|
+|ABELMON-;*;Pi2S;2|
+|ABELMON-;zero?;SB;1|
+|AGG-;empty?;SB;3|
+|AGG-;size?;SNniB;6|
+|ALIST;keys;$L;6|
+|ALIST;search;Key$U;15|
+|ARR2CAT-;copy;2S;10|
+|BOP;<;2$B;29|
+|BOP;=;2$B;27|
+|BOP;has?;$SB;9|
+|BOP;is?;$SB;1|
+|BOP;name;$S;2|
+|BOP;properties;$Al;3|
+|BOP;property;$SU;7|
+|BOP;weight;$Nni;28|
+|COMPCAT-;*;R2S;18|
+|COMPCAT-;-;2S;17|
+|COMPCAT-;=;2SB;15|
+|COMPCAT-;exquo;SRU;46|
+|COMPCAT-;recip;SU;48|
+|COMPCAT-;rem;3S;53|
+|COMPCAT-;unitNormal;SR;49|
+|COMPLEX;*;3$;10|
+|COMPLEX;+;3$;9|
+|COMPLEX;coerce;R$;5|
+|COMPLEX;exquo;2$U;11|
+|COMPLEX;one?;$B;4|
+|COMPLEX;zero?;$B;3|
+|DIRPROD;<;2$B;18|
+|DIRPROD;subtractIfCan;2$U;14|
+|ELAGG-;removeDuplicates;2A;12|
+|ELTAGG-;qelt;SDomIm;1|
+|ELTAGG-;qsetelt!;SDom2Im;2|
+|EUCDOM-;gcd;3S;5|
+|EUCDOM-;unitNormalizeIdealElt|
+|EXPR;*;3$;11|
+|EXPR;+;3$;12|
+|EXPR;-;2$;8|
+|EXPR;/;3$;14|
+|EXPR;=;2$B;21|
+|EXPR;algkernels!0|
+|EXPR;algkernels|
+|EXPR;coerce;I$;10|
+|EXPR;coerce;Smp$;24|
+|EXPR;commonk0|
+|EXPR;commonk|
+|EXPR;denom;$Smp;23|
+|EXPR;numer;$Smp;22|
+|EXPR;reduc|
+|EXPR;zero?;$B;7|
+|FACUTIL;lowerPolynomial;SupSup;1|
+|FAMR-;coefficients;SL;4|
+|FAMR-;ground;SR;2|
+|FFP;*;3$;21|
+|FFP;+;3$;22|
+|FFP;-;3$;23|
+|FFP;=;2$B;24|
+|FIELD-;/;3S;11|
+|FIELD-;inv;2S;4|
+|FLAGG-;sort!;2A;8|
+|FLAGG-;sort;M2A;6|
+|FLASORT;QuickSort|
+|FLASORT;partition|
+|FLASORT;quickSort;M2V;1|
+|FM;*;R2$;1|
+|FRAC;*;3$;18|
+|FRAC;*;I2$;19|
+|FRAC;+;3$;16|
+|FRAC;=;2$B;22|
+|FRAC;cancelGcd|
+|FRAC;coerce;S$;1|
+|FRAC;normalize|
+|FRAC;one?;$B;23|
+|FRAC;recip;$U;13|
+|FRAC;zero?;$B;2|
+|FSAGG-;brace;LA;3|
+|GDMP;univariate;$OvlSup;21|
+|HDP;<;2$B;1|
+|IARRAY1;#;$Nni;1|
+|IARRAY1;elt;$IS;16|
+|IARRAY1;fill!;$S$;2|
+|IARRAY1;map;M3$;8|
+|IARRAY1;maxIndex;$I;13|
+|IARRAY1;minIndex;$I;3|
+|IARRAY1;new;NniS$;5|
+|IARRAY1;qelt;$IS;14|
+|IARRAY1;qsetelt!;$I2S;15|
+|IARRAY1;setelt;$I2S;17|
+|IDPAM;+;3$;4|
+|IDPAM;map;M2$;7|
+|IDPAM;monomial;AS$;6|
+|IDPO;=;2$B;1|
+|IFARRAY;#;$Nni;4|
+|IFARRAY;concat!;$S$;21|
+|IFARRAY;elt;$IS;17|
+|IFARRAY;empty;$;3|
+|IFARRAY;growAndFill|
+|IFARRAY;growWith|
+|IFARRAY;maxIndex;$I;6|
+|IFARRAY;minIndex;$I;7|
+|IFARRAY;new;NniS$;8|
+|IFARRAY;removeDuplicates!;2$;30|
+|IFARRAY;setelt;$I2S;18|
+|IIARRAY2;elt;$2IR;11|
+|IIARRAY2;empty?;$B;1|
+|IIARRAY2;maxColIndex;$I;7|
+|IIARRAY2;maxRowIndex;$I;6|
+|IIARRAY2;minColIndex;$I;5|
+|IIARRAY2;minRowIndex;$I;4|
+|IIARRAY2;ncols;$Nni;9|
+|IIARRAY2;nrows;$Nni;8|
+|IIARRAY2;qelt;$2IR;10|
+|IIARRAY2;qsetelt!;$2I2R;12|
+|ILIST;concat!;3$;25|
+|ILIST;copy;2$;20|
+|ILIST;empty;$;6|
+|ILIST;first;$S;4|
+|ILIST;member?;S$B;24|
+|ILIST;mergeSort|
+|ILIST;minIndex;$I;18|
+|ILIST;removeDuplicates!;2$;26|
+|ILIST;rest;$Nni$;19|
+|ILIST;sort!;M2$;27|
+|ILIST;split!;$I$;29|
+|IMATLIN;rowEchelon;2M;3|
+|INS-;symmetricRemainder;3S;27|
+|INT;exquo;2$U;44|
+|INT;one?;$B;2|
+|INT;positiveRemainder;3$;23|
+|INT;unitNormal;$R;47|
+|INTDOM-;unitCanonical;2S;2|
+|ISTRING;<;2$B;6|
+|KDAGG-;key?;KeySB;1|
+|KERNEL;<;2$B;14|
+|KERNEL;=;2$B;13|
+|KERNEL;B2Z|
+|KERNEL;argument;$L;6|
+|KERNEL;operator;$Bo;5|
+|KERNEL;position;$Nni;7|
+|KERNEL;triage|
+|LO;-;2$;3|
+|LO;=;2$B;4|
+|LSAGG-;<;2AB;25|
+|LSAGG-;reduce;MA2S;16|
+|LSAGG-;select!;M2A;5|
+|MATCAT-;*;3S;29|
+|MATCAT-;*;S2Col;32|
+|MDDFACT;reduction!0|
+|MDDFACT;reduction|
+|MODRING;reduce;RMod$;6|
+|MODRING;zero?;$B;10|
+|MONOID-;one?;SB;2|
+|NNI;subtractIfCan;2$U;3|
+|NSMP;mvar;$VarSet;5|
+|OVAR;<;2$B;10|
+|PERMGRP;inv|
+|PERMGRP;orbitWithSvc|
+|PERMGRP;testIdentity|
+|PERMGRP;times|
+|PGCD;better|
+|PGCD;gcd;3P;15|
+|PGCD;gcdTermList|
+|POLYCATQ;variables;FL;5|
+|PR;*;3$;20|
+|PR;addm!|
+|PR;coerce;R$;12|
+|PR;degree;$E;4|
+|PR;leadingCoefficient;$R;6|
+|PR;reductum;2$;8|
+|PRIMARR;#;$Nni;1|
+|PRIMARR;fill!;$S$;9|
+|PRIMARR;new;NniS$;4|
+|PRTITION;<;2$B;5|
+|REPSQ;expt;SPiS;1|
+|RING-;coerce;IS;1|
+|SAE;*;3$;15|
+|SAE;+;3$;13|
+|SAE;-;2$;14|
+|SAE;=;2$B;12|
+|SAE;reduce;UP$;11|
+|SCACHE;enterInCache;SMS;5|
+|SET;construct;L$;19|
+|SET;empty;$;4|
+|SGROUP-;**;SPiS;1|
+|SINT;zero?;$B;33|
+|SMP;*;3$;29|
+|SMP;*;R2$;25|
+|SMP;+;3$;26|
+|SMP;-;2$;23|
+|SMP;=;2$B;28|
+|SMP;coerce;R$;20|
+|SMP;coerce;VarSet$;7|
+|SMP;exquo;2$U;35|
+|SMP;exquo;2$U;36|
+|SMP;gcd;3$;41|
+|SMP;gcd;3$;44|
+|SMP;gcd;3$;48|
+|SMP;gcd;3$;51|
+|SMP;ground?;$B;15|
+|SMP;leadingCoefficient;$R;73|
+|SMP;mainVariable;$U;59|
+|SMP;one?;$B;4|
+|SMP;retract;$R;55|
+|SMP;unitNormal;$R;31|
+|SMP;variables;$L;58|
+|SMP;zero?;$B;3|
+|STAGG-;c2|
+|STAGG-;concat;3A;7|
+|STAGG-;elt;AIS;5|
+|STAGG-;first;ANniA;3|
+|STREAM2;map;MSS;2|
+|STREAM2;mapp!0|
+|STREAM2;mapp|
+|STREAM;empty;$;33|
+|STREAM;lazyEval|
+|STREAM;setfrst!|
+|STREAM;setrst!|
+|STTAYLOR;+;3S;2|
+|SUP;exquo;2$U;19|
+|SUP;exquo;2$U;20|
+|SUP;fmecg;$NniR2$;21|
+|SUP;ground?;$B;3|
+|SUP;monicDivide;2$R;28|
+|URAGG-;tail;2A;16|
+|ZMOD;*;3$;30|
+|ZMOD;+;3$;32|
+|ZMOD;-;2$;36|
+|ZMOD;-;3$;33|
+\end{verbatim}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\chapter{Users Guide Chapter 1 (ug01.ht)}
+<<ug01.ht>>=
+\newcommand{\ugIntroTitle}{An Overview of Axiom}
+\newcommand{\ugIntroNumber}{1.}
+
+@
+\section{An Overview of Axiom}
+\label{ugIntroPage}
+\begin{itemize}
+\item ugIntroTypoPage \ref{ugIntroTypoPage} on
+page~\pageref{ugIntroTypoPage}
+\item ugIntroStartPage \ref{ugIntroStartPage} on
+page~\pageref{ugIntroStartPage}
+\item ugIntroTypoPage \ref{ugIntroTypoPage} on
+page~\pageref{ugIntroTypoPage}
+\item ugIntroExpressionsPage \ref{ugIntroExpressionsPage} on
+page~\pageref{ugIntroExpressionsPage}
+\item ugIntroGraphicsPage \ref{ugIntroGraphicsPage} on
+page~\pageref{ugIntroGraphicsPage}
+\item ugIntroNumbersPage \ref{ugIntroNumbersPage} on
+page~\pageref{ugIntroNumbersPage}
+\item ugIntroCollectPage \ref{ugIntroCollectPage} on
+page~\pageref{ugIntroCollectPage}
+\item ugIntroTwoDimPage \ref{ugIntroTwoDimPage} on
+page~\pageref{ugIntroTwoDimPage}
+\item ugIntroYouPage \ref{ugIntroYouPage} on
+page~\pageref{ugIntroYouPage}
+\item ugIntroVariablesPage \ref{ugIntroVariablesPage} on
+page~\pageref{ugIntroVariablesPage}
+\item ugIntroCalcLimitsPage \ref{ugIntroCalcLimitsPage} on
+page~\pageref{ugIntroCalcLimitsPage}
+\item ugIntroSeriesPage \ref{ugIntroSeriesPage} on
+page~\pageref{ugIntroSeriesPage}
+\item ugIntroCalcDerivPage \ref{ugIntroCalcDerivPage} on
+page~\pageref{ugIntroCalcDerivPage}
+\item ugIntroIntegratePage \ref{ugIntroIntegratePage} on
+page~\pageref{ugIntroIntegratePage}
+\item ugIntroDiffEqnsPage \ref{ugIntroDiffEqnsPage} on
+page~\pageref{ugIntroDiffEqnsPage}
+\item ugIntroSolutionPage \ref{ugIntroSolutionPage} on
+page~\pageref{ugIntroSolutionPage}
+\item ugIntroSysCmmandsPage \ref{ugIntroSysCmmandsPage} on
+page~\pageref{ugIntroSysCmmandsPage}
+\end{itemize}
+\index{pages!ugIntroPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroPage}
+\index{ugIntroPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroPage}{1. An Overview of Axiom}
+
+\beginscroll
+
+Welcome to the Axiom environment for interactive computation
+and problem solving.
+Consider this chapter a brief, whirlwind tour of the Axiom
+world.
+We introduce you to Axiom's graphics and the Axiom
+language.
+Then we give a sampling of the large variety of facilities
+in the Axiom system, ranging from the various kinds of
+numbers, to data types (like lists, arrays, and sets) and
+mathematical objects (like matrices, integrals, and differential
+equations).
+We conclude with the discussion of system commands and an
+interactive ``undo.''
+
+Before embarking on the tour, we need to brief those readers
+working interactively with Axiom on some details.
+Others can skip right immediately to
+\downlink{``\ugIntroTypoTitle''}{ugIntroTypoPage} in 
+Section \ugIntroTypoNumber\ignore{ugIntroTypo}.
+
+\beginmenu
+    \menudownlink{{1.1. Starting Up and Winding Down}}{ugIntroStartPage}
+    \menudownlink{{1.2. Typographic Conventions}}{ugIntroTypoPage}
+    \menudownlink{{1.3. The Axiom Language}}{ugIntroExpressionsPage}
+    \menudownlink{{1.4. Graphics}}{ugIntroGraphicsPage}
+    \menudownlink{{1.5. Numbers}}{ugIntroNumbersPage}
+    \menudownlink{{1.6. Data Structures}}{ugIntroCollectPage}
+    \menudownlink{{1.7. Expanding to Higher Dimensions}}{ugIntroTwoDimPage}
+    \menudownlink{{1.8. Writing Your Own Functions}}{ugIntroYouPage}
+    \menudownlink{{1.9. Polynomials}}{ugIntroVariablesPage}
+    \menudownlink{{1.10. Limits}}{ugIntroCalcLimitsPage}
+    \menudownlink{{1.11. Series}}{ugIntroSeriesPage}
+    \menudownlink{{1.12. Derivatives}}{ugIntroCalcDerivPage}
+    \menudownlink{{1.13. Integration}}{ugIntroIntegratePage}
+    \menudownlink{{1.14. Differential Equations}}{ugIntroDiffEqnsPage}
+    \menudownlink{{1.15. Solution of Equations}}{ugIntroSolutionPage}
+    \menudownlink{{1.16. System Commands}}{ugIntroSysCmmandsPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroStartTitle}{Starting Up and Winding Down}
+\newcommand{\ugIntroStartNumber}{1.1.}
+
+@
+\section{Starting Up and Winding Down}
+\label{ugIntroStartPage}
+\begin{itemize}
+\item ugHyperPage \ref{ugHyperPage} on
+page~\pageref{ugHyperPage}
+\item ugSysCmdPage \ref{ugSysCmdPage} on
+page~\pageref{ugSysCmdPage}
+\item ugAvailCLEFPage \ref{ugAvailCLEFPage} on
+page~\pageref{ugAvailCLEFPage}
+\end{itemize}
+\index{pages!ugIntroStartPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroStartPage}
+\index{ugIntroStartPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroStartPage}{1.1. Starting Up and Winding Down}
+\beginscroll
+
+You need to know how to start the Axiom system and how to stop it.
+We assume that Axiom has been correctly installed on your
+machine (as described in another Axiom document).
+
+To begin using Axiom, issue the command {\bf axiom} to the
+operating system shell.
+There is a brief pause, some start-up messages, and then one
+or more windows appear.
+
+If you are not running Axiom under the X Window System, there is
+only one window (the console).
+At the lower left of the screen there is a prompt that
+looks like
+\begin{verbatim}
+(1) ->
+\end{verbatim}
+%%--> do you want to talk about equation numbers on the right, etc.
+When you want to enter input to Axiom, you do so on the same line
+after the prompt.
+The ``1'' in ``(1)'' is the computation step number and is incremented
+after you enter Axiom statements.
+Note, however, that a system command
+such as \spadsys{)clear all}
+may change the step number in other ways.
+We talk about step numbers more when we discuss system commands
+and the workspace history facility.
+
+If you are running Axiom under the X Window System, there may be two
+windows: the console window (as just described) and the \HyperName{}
+main menu.
+\HyperName{} is a multiple-window hypertext system that lets you
+view Axiom documentation and examples on-line,
+execute Axiom expressions, and generate graphics.
+If you are in a graphical windowing environment,
+it is usually started automatically when Axiom begins.
+If it is not running, issue \spadsys{)hd} to start it.
+We discuss the basics of \HyperName{} in
+\downlink{``\ugHyperTitle''}{ugHyperPage} in Chapter 
+\ugHyperNumber\ignore{ugHyper}.
+
+To interrupt an Axiom computation, hold down the
+\texht{\fbox{\bf Ctrl}}{{\bf Ctrl}} (control) key and press
+\texht{\fbox{\bf c}}{{\bf c}}.
+This  brings you back to the Axiom prompt.
+
+\beginImportant
+To exit from Axiom,  move to the console window,
+type \spadsys{)quit}
+at the input prompt and press the \texht{\fbox{\bf Enter}}{{\bf Enter}} key.
+You will probably be prompted with the following message:
+\centerline{{Please enter {\bf y} or {\bf yes} if you really want to leave the }}
+\centerline{{interactive environment and return to the operating system}}
+You should respond {\bf yes}, for example, to exit Axiom.
+\endImportant
+
+We are purposely vague in describing exactly what your screen
+looks like or what messages Axiom displays.
+Axiom runs on a number of different machines, operating
+systems and window environments, and these differences all affect
+the physical look of the system.
+You can also change the way that Axiom behaves via
+\spadgloss{system commands} described later in this chapter and in
+\downlink{``\ugSysCmdTitle''}{ugSysCmdPage} 
+in Appendix \ugSysCmdNumber\ignore{ugSysCmd}.
+System commands are special commands, like \spadcmd{)set}, that begin
+with a closing parenthesis and are used to change your
+environment.
+For example, you can set a system variable so that you are not
+prompted for confirmation when you want to leave Axiom.
+
+\beginmenu
+    \menudownlink{{1.1.1. \Clef{}}}{ugAvailCLEFPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugAvailCLEFTitle}{\Clef{}}
+\newcommand{\ugAvailCLEFNumber}{1.1.1.}
+
+@
+\section{Clef}
+\label{ugAvailCLEFPage}
+\index{pages!ugAvailCLEFPage!ug01.ht}
+\index{ug01.ht!pages!ugAvailCLEFPage}
+\index{ugAvailCLEFPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugAvailCLEFPage}{1.1.1. \Clef{}}
+\beginscroll
+%
+If you are using Axiom under the X Window System, the
+\Clef{} command line editor is probably available and installed.
+With this editor you can recall previous lines with the up and
+down arrow keys\texht{ (\fbox{$\uparrow$} and
+\fbox{$\downarrow$})}{}.
+To move forward and backward on a line, use the right and
+left arrows\texht{ (\fbox{$\rightarrow$} and
+\fbox{$\leftarrow$})}{}.
+You can use the
+\texht{\fbox{\bf Insert}}{{\bf Insert}}
+key to toggle insert mode on or off.
+When you are in insert mode,
+the cursor appears as a large block and if you type
+anything, the characters are inserted into the line without
+deleting the previous ones.
+
+If you press the
+\texht{\fbox{\bf Home}}{{\bf Home}}
+key, the cursor moves to the beginning of the line and if you press the
+\texht{\fbox{\bf End}}{{\bf End}}
+key, the cursor moves to the end of the line.
+Pressing
+\texht{\fbox{\bf Ctrl}--\fbox{\bf End}}{{\bf Ctrl-End}}
+deletes all the text from the cursor to the end of the line.
+
+\Clef{} also provides Axiom operation name completion for
+a limited set of operations.
+If you enter a few letters and then press the
+\texht{\fbox{\bf Tab}}{{\bf Tab}} key,
+\Clef{} tries to use those letters as the prefix of an Axiom
+operation name.
+If a name appears and it is not what you want, press
+\texht{\fbox{\bf Tab}}{{\bf Tab}} again
+to see another name.
+
+You are ready to begin your journey into the world of Axiom.
+Proceed to the first stop.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroTypoTitle}{Typographic Conventions}
+\newcommand{\ugIntroTypoNumber}{1.2.}
+
+@
+\section{Typographic Conventions}
+\label{ugIntroTypoPage}
+\index{pages!ugIntroTypoPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroTypoPage}
+\index{ugIntroTypoPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroTypoPage}{1.2. Typographic Conventions}
+\beginscroll
+
+In this book we have followed these typographical conventions:
+\indent{4}
+\beginitems
+%
+\item[-] Categories, domains and packages are displayed in
+\texht{a sans-serif typeface:}{this font:}
+\axiomType{Ring}, \axiomType{Integer}, \axiomType{DiophantineSolutionPackage}.
+%
+\item[-] Prefix operators, infix operators, and punctuation symbols in the Axiom
+language are displayed in the text like this:
+\axiomOp{+}, \axiomSyntax{\$}, \axiomSyntax{+->}.
+%
+\item[-] Axiom expressions or expression fragments are displayed in
+\texht{a mon\-o\-space typeface:}{this font:}
+\axiom{inc(x) == x + 1}.
+%
+\item[-] For clarity of presentation, \TeX{} is often
+used to format expressions\texht{: $g(x)=x^2+1.$}{.}
+%
+\item[-] Function names and \HyperName{} button names
+are displayed in the text in
+\texht{a bold typeface:}{this font:}
+\axiomFun{factor}, \axiomFun{integrate},  {\bf Lighting}.
+%
+\item[-] Italics are used for emphasis and for words defined in the
+glossary: \spadgloss{category}.
+\enditems
+\indent{0}
+
+This book contains over 2500 examples of Axiom input and output.
+All examples were run though Axiom and their output was
+created in \texht{\TeX{}}{TeX} form for this book by the Axiom
+\axiomType{TexFormat} package.
+We have deleted system messages from the example output if those
+messages are not important for the discussions in which the examples
+appear.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroExpressionsTitle}{The Axiom Language}
+\newcommand{\ugIntroExpressionsNumber}{1.3.}
+
+@
+\section{The Axiom Language}
+\label{ugIntroExpressionsPage}
+\begin{itemize}
+\item ugIntroArithmeticPage \ref{ugIntroArithmeticPage} on
+page~\pageref{ugIntroArithmeticPage}
+\item ugIntroPreviousPage \ref{ugIntroPreviousPage} on
+page~\pageref{ugIntroPreviousPage}
+\item ugIntroTypesPage \ref{ugIntroTypesPage} on
+page~\pageref{ugIntroTypesPage}
+\item ugIntroAssignPage \ref{ugIntroAssignPage} on
+page~\pageref{ugIntroAssignPage}
+\item ugIntroConversionPage \ref{ugIntroConversionPage} on
+page~\pageref{ugIntroConversionPage}
+\item ugIntroCallFunPage \ref{ugIntroCallFunPage} on
+page~\pageref{ugIntroCallFunPage}
+\item ugIntroMacrosPage \ref{ugIntroMacrosPage} on
+page~\pageref{ugIntroMacrosPage}
+\item ugIntroLongPage \ref{ugIntroLongPage} on
+page~\pageref{ugIntroLongPage}
+\item ugIntroCommentsPage \ref{ugIntroCommentsPage} on
+page~\pageref{ugIntroCommentsPage}
+\end{itemize}
+\index{pages!ugIntroExpressionsPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroExpressionsPage}
+\index{ugIntroExpressionsPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroExpressionsPage}{1.3. The Axiom Language}
+\beginscroll
+%
+
+The Axiom language is a rich language for performing
+interactive computations and for building components of the
+Axiom library.
+Here we present only some basic aspects of the language that you
+need to know for the rest of this chapter.
+Our discussion here is intentionally informal, with details
+unveiled on an ``as needed'' basis.
+For more information on a particular construct, we suggest you
+consult the index at the back of the book.
+
+\beginmenu
+    \menudownlink{{1.3.1. Arithmetic Expressions}}{ugIntroArithmeticPage}
+    \menudownlink{{1.3.2. Previous Results}}{ugIntroPreviousPage}
+    \menudownlink{{1.3.3. Some Types}}{ugIntroTypesPage}
+    \menudownlink{{1.3.4. Symbols, Variables, Assignments, and Declarations}}{ugIntroAssignPage}
+    \menudownlink{{1.3.5. Conversion}}{ugIntroConversionPage}
+    \menudownlink{{1.3.6. Calling Functions}}{ugIntroCallFunPage}
+    \menudownlink{{1.3.7. Some Predefined Macros}}{ugIntroMacrosPage}
+    \menudownlink{{1.3.8. Long Lines}}{ugIntroLongPage}
+    \menudownlink{{1.3.9. Comments}}{ugIntroCommentsPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroArithmeticTitle}{Arithmetic Expressions}
+\newcommand{\ugIntroArithmeticNumber}{1.3.1.}
+
+@
+\section{Arithmetic Expressions}
+\label{ugIntroArithmeticPage}
+\index{pages!ugIntroArithmeticPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroArithmeticPage}
+\index{ugIntroArithmeticPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroArithmeticPage}{1.3.1. Arithmetic Expressions}
+\beginscroll
+
+For arithmetic expressions, use the \spadop{+} and \spadop{-}
+\spadglossSee{operators}{operator} as in mathematics.
+Use \spadop{*} for multiplication, and \spadop{**} for
+exponentiation.
+To create a fraction, use \spadop{/}.
+When an expression contains several operators, those of highest
+\spadgloss{precedence} are evaluated first.
+For arithmetic operators, \spadop{**} has highest precedence,
+\spadop{*} and \spadop{/} have the next highest
+precedence, and \spadop{+} and \spadop{-} have the lowest
+precedence.
+
+\xtc{
+Axiom puts implicit parentheses around operations of higher
+precedence, and groups those of equal precedence from left to right.
+}{
+\spadpaste{1 + 2 - 3 / 4 * 3 ** 2 - 1}
+}
+\xtc{
+The above expression is equivalent to this.
+}{
+\spadpaste{((1 + 2) - ((3 / 4) * (3 ** 2))) - 1}
+}
+\xtc{
+If an expression contains subexpressions enclosed in parentheses,
+the parenthesized subexpressions are evaluated first (from left to
+right, from inside out).
+}{
+\spadpaste{1 + 2 - 3/ (4 * 3 ** (2 - 1))}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroPreviousTitle}{Previous Results}
+\newcommand{\ugIntroPreviousNumber}{1.3.2.}
+
+@
+\section{Previous Results}
+\label{ugIntroPreviousPage}
+\index{pages!ugIntroPreviousPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroPreviousPage}
+\index{ugIntroPreviousPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroPreviousPage}{1.3.2. Previous Results}
+\beginscroll
+
+Use the percent sign (\axiomSyntax{\%}) to refer to the last
+result.
+Also, use \axiomSyntax{\%\%} to refer to previous results.
+\axiom{\%\%(-1)} is equivalent to \axiomSyntax{\%},
+\axiom{\%\%(-2)} returns the next to the last result, and so on.
+\axiom{\%\%(1)} returns the result from step number 1,
+\axiom{\%\%(2)} returns the result from step number 2, and so on.
+\axiom{\%\%(0)} is not defined.
+
+\xtc{
+This is ten to the tenth power.
+}{
+\spadpaste{10 ** 10 \bound{prev}}
+}
+\xtc{
+This is the last result minus one.
+}{
+\spadpaste{\% - 1 \free{prev}\bound{prev1}}
+}
+\xtc{
+This is the last result.
+}{
+\spadpaste{\%\%(-1) \free{prev1}\bound{prev2}}
+}
+\xtc{
+This is the result from step number 1.
+}{
+\spadpaste{\%\%(1) \free{prev2}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroTypesTitle}{Some Types}
+\newcommand{\ugIntroTypesNumber}{1.3.3.}
+
+@
+\section{Some Types}
+\label{ugIntroTypesPage}
+\begin{itemize}
+\item ugTypesPage \ref{ugTypesPage} on
+page~\pageref{ugTypesPage}
+\end{itemize}
+\index{pages!ugIntroTypesPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroTypesPage}
+\index{ugIntroTypesPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroTypesPage}{1.3.3. Some Types}
+\beginscroll
+
+Everything in Axiom has a type.
+The type determines what operations you can perform on an object and
+how the object can be used.
+An entire chapter of this book (\downlink{``\ugTypesTitle''}{ugTypesPage} 
+in Chapter \ugTypesNumber\ignore{ugTypes}) is dedicated to
+the interactive use of types.
+Several of the final chapters discuss how types are built and how
+they are organized in the Axiom library.
+
+\xtc{
+Positive integers are given type \spadtype{PositiveInteger}.
+}{
+\spadpaste{8}
+}
+\xtc{
+Negative ones are given type \spadtype{Integer}.
+This fine distinction is helpful to the
+Axiom interpreter.
+}{
+\spadpaste{-8}
+}
+\xtc{
+Here a positive integer exponent gives a polynomial result.
+}{
+\spadpaste{x**8}
+}
+\xtc{
+Here a negative integer exponent produces a fraction.
+}{
+\spadpaste{x**(-8)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroAssignTitle}{Symbols, Variables, Assignments, and Declarations}
+\newcommand{\ugIntroAssignNumber}{1.3.4.}
+
+@
+\section{Symbols, Variables, Assignments, and Declarations}
+\label{ugIntroAssignPage}
+\begin{itemize}
+\item ugLangAssignPage \ref{ugLangAssignPage} on
+page~\pageref{ugLangAssignPage}
+\end{itemize}
+\index{pages!ugIntroAssignPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroAssignPage}
+\index{ugIntroAssignPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroAssignPage}
+{1.3.4. Symbols, Variables, Assignments, and Declarations}
+\beginscroll
+
+A \spadgloss{symbol} is a literal used for the input of things like
+the ``variables'' in polynomials and power series.
+
+\labelSpace{2pc}
+\xtc{
+We use the three symbols \axiom{x}, \axiom{y}, and \axiom{z} in
+entering this polynomial.
+}{
+\spadpaste{(x - y*z)**2}
+}
+A symbol has a name beginning with an uppercase or lowercase alphabetic
+character, \axiomSyntax{\%}, or \axiomSyntax{!}.
+Successive characters (if any) can be any of the above, digits, or
+\axiomSyntax{?}.
+Case is distinguished: the symbol \axiom{points} is different
+from the symbol \axiom{Points}.
+
+A symbol can also be used in Axiom as a \spadgloss{variable}.
+A variable refers to a value.
+To \spadglossSee{assign}{assignment}
+a value to a variable,
+the operator \axiomSyntax{:=}
+is used.\footnote{Axiom actually has two forms of assignment:
+{\it immediate} assignment, as discussed here,
+and {\it delayed assignment}. See 
+\downlink{``\ugLangAssignTitle''}{ugLangAssignPage} 
+in Section \ugLangAssignNumber\ignore{ugLangAssign} for details.}
+A variable initially has no restrictions on the kinds of
+values to which it can refer.
+
+\xtc{
+This assignment gives the value \axiom{4} (an integer) to
+a variable named \axiom{x}.
+}{
+\spadpaste{x := 4}
+}
+\xtc{
+This gives the value \axiom{z + 3/5} (a polynomial)  to \axiom{x}.
+}{
+\spadpaste{x := z + 3/5}
+}
+\xtc{
+To restrict the types of objects that can be assigned to a variable,
+use a \spadgloss{declaration}
+}{
+\spadpaste{y : Integer \bound{y}}
+}
+\xtc{
+After a variable is declared to be of some type, only values
+of that type can be assigned to that variable.
+}{
+\spadpaste{y := 89\bound{y1}\free{y}}
+}
+\xtc{
+The declaration for \axiom{y} forces values assigned to \axiom{y} to
+be converted to integer values.
+}{
+\spadpaste{y := sin \%pi}
+}
+\xtc{
+If no such conversion is possible,
+Axiom refuses to assign a value to \axiom{y}.
+}{
+\spadpaste{y := 2/3}
+}
+\xtc{
+A type declaration can also be given together with an assignment.
+The declaration can assist Axiom in choosing the correct
+operations to apply.
+}{
+\spadpaste{f : Float := 2/3}
+}
+
+Any number of expressions can be given on input line.
+Just separate them by semicolons.
+Only the result of evaluating the last expression is displayed.
+
+\xtc{
+These two expressions have the same effect as
+the previous single expression.
+}{
+\spadpaste{f : Float; f := 2/3 \bound{fff}}
+}
+
+The type of a symbol is either \axiomType{Symbol}
+or \axiomType{Variable({\it name})} where {\it name} is the name
+of the symbol.
+
+\xtc{
+By default, the interpreter
+gives this symbol the type \axiomType{Variable(q)}.
+}{
+\spadpaste{q}
+}
+\xtc{
+When multiple symbols are involved, \axiomType{Symbol} is used.
+}{
+\spadpaste{[q, r]}
+}
+
+\xtc{
+What happens when you try to use a symbol that is the name of a variable?
+}{
+\spadpaste{f \free{fff}}
+}
+\xtc{
+Use a single quote (\axiomSyntax{'}) before
+the name to get the symbol.
+}{
+\spadpaste{'f}
+}
+
+Quoting a name creates a symbol by
+preventing evaluation of the name as a variable.
+Experience will teach you when you are most likely going to need to use
+a quote.
+We try to point out the location of such trouble spots.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroConversionTitle}{Conversion}
+\newcommand{\ugIntroConversionNumber}{1.3.5.}
+
+@
+\section{Conversion}
+\label{ugIntroConversionPage}
+\begin{itemize}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~\pageref{ugTypesConvertPage}
+\end{itemize}
+\index{pages!ugIntroConversionPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroConversionPage}
+\index{ugIntroConversionPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroConversionPage}{1.3.5. Conversion}
+\beginscroll
+
+Objects of one type can usually be ``converted'' to objects of several
+other types.
+To \spadglossSee{convert}{conversion}
+an object to a new type, use the \axiomSyntax{::} infix
+operator.\footnote{Conversion is discussed in detail in 
+\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} 
+in Section \ugTypesConvertNumber\ignore{ugTypesConvert}.}
+For example, to display an object, it is necessary to
+convert the object to type \spadtype{OutputForm}.
+
+\xtc{
+This produces a polynomial with rational number coefficients.
+}{
+\spadpaste{p := r**2 + 2/3 \bound{p}}
+}
+\xtc{
+Create a quotient of polynomials with integer coefficients
+by using \axiomSyntax{::}.
+}{
+\spadpaste{p :: Fraction Polynomial Integer \free{p}}
+}
+
+Some conversions can be performed automatically when
+Axiom tries to evaluate your input.
+Others conversions must be explicitly requested.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroCallFunTitle}{Calling Functions}
+\newcommand{\ugIntroCallFunNumber}{1.3.6.}
+
+@
+\section{Calling Functions}
+\label{ugIntroCallFunPage}
+\index{pages!ugIntroCallFunPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroCallFunPage}
+\index{ugIntroCallFunPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroCallFunPage}{1.3.6. Calling Functions}
+\beginscroll
+
+As we saw earlier, when you want to add or subtract two values,
+you place the arithmetic operator \spadop{+}
+or \spadop{-} between the two
+\spadglossSee{arguments}{argument} denoting the values.
+To use most other Axiom operations, however, you use another syntax:
+write the name
+of the operation first, then an open parenthesis, then each of the
+arguments separated by commas, and, finally, a closing parenthesis.
+If the operation takes only one argument and the argument is a number
+or a symbol, you can omit the parentheses.
+
+\xtc{
+This calls the operation \axiomFun{factor} with the single
+integer argument \axiom{120}.
+}{
+\spadpaste{factor(120)}
+}
+\xtc{
+This is a call to \axiomFun{divide} with the two integer arguments
+\axiom{125} and \axiom{7}.
+}{
+\spadpaste{divide(125,7)}
+}
+\xtc{
+This calls \axiomFun{quatern} with four floating-point arguments.
+}{
+\spadpaste{quatern(3.4,5.6,2.9,0.1)}
+}
+\xtc{
+This is the same as \axiom{factorial(10)}.
+}{
+\spadpaste{factorial 10}
+}
+
+An operations that returns a \spadtype{Boolean} value (that is,
+\spad{true} or \spad{false}) frequently has a name suffixed with
+a question mark (``?'').  For example, the \spadfun{even?}
+operation returns \spad{true} if its integer argument is an even
+number, \spad{false} otherwise.
+
+An operation that can be destructive on one or more arguments
+usually has a name ending in a exclamation point (``!'').
+This actually means that it is {\it allowed} to update its
+arguments but it is not {\it required} to do so. For example,
+the underlying representation of a collection type may not allow
+the very last element to removed and so an empty object may be
+returned instead. Therefore, it is important that you use the
+object returned by the operation and not rely on a physical
+change having occurred within the object. Usually, destructive
+operations are provided for efficiency reasons.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroMacrosTitle}{Some Predefined Macros}
+\newcommand{\ugIntroMacrosNumber}{1.3.7.}
+
+@
+\section{Some Predefined Macros}
+\label{ugIntroMacrosPage}
+\begin{itemize}
+\item ugUserMacrosPage \ref{ugUserMacrosPage} on
+page~\pageref{ugUserMacrosPage}
+\end{itemize}
+\index{pages!ugIntroMacrosPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroMacrosPage}
+\index{ugIntroMacrosPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroMacrosPage}{1.3.7. Some Predefined Macros}
+\beginscroll
+
+Axiom provides several \spadglossSee{macros}{macro}
+for your convenience.\footnote{See 
+\downlink{``\ugUserMacrosTitle''}{ugUserMacrosPage} 
+in Section \ugUserMacrosNumber\ignore{ugUserMacros}
+for a discussion on how to write your own macros.}
+Macros are names
+(or forms) that expand to larger expressions for commonly used values.
+
+\texht{
+\centerline{{\begin{tabular}{ll}}}
+\centerline{{\spadgloss{\%i}             &  The square root of -1. }}
+\centerline{{\spadgloss{\%e}             &  The base of the natural logarithm. }}
+\centerline{{\spadgloss{\%pi}            &  $\pi$. }}
+\centerline{{\spadgloss{\%infinity}      &  $\infty$. }}
+\centerline{{\spadgloss{\%plusInfinity}  &  $+\infty$. }}
+\centerline{{\spadgloss{\%minusInfinity} &  $-\infty$.}}
+\centerline{{\end{tabular}}}
+}{
+\indent{0}
+\beginitems
+\item[\axiomSyntax{\%i}]             \tab{17} The square root of -1.
+\item[\axiomSyntax{\%e}]             \tab{17} The base of the natural logarithm.
+\item[\axiomSyntax{\%pi}]            \tab{17} Pi.
+\item[\axiomSyntax{\%infinity}]      \tab{17} Infinity.
+\item[\axiomSyntax{\%plusInfinity}]  \tab{17} Plus infinity.
+\item[\axiomSyntax{\%minusInfinity}] \tab{17} Minus infinity.
+\enditems
+\indent{0}
+}
+
+%To display all the macros (along with anything you have
+%defined in the workspace), issue the system command \spadsys{)display all}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroLongTitle}{Long Lines}
+\newcommand{\ugIntroLongNumber}{1.3.8.}
+
+@
+\section{Long Lines}
+\label{ugIntroLongPage}
+\begin{itemize}
+\item ugInOutInPage \ref{ugInOutInPage} on
+page~\pageref{ugInOutInPage}
+\item ugLangBlocksPage \ref{ugLangBlocksPage} on
+page~\pageref{ugLangBlocksPage}
+\end{itemize}
+\index{pages!ugIntroLongPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroLongPage}
+\index{ugIntroLongPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroLongPage}{1.3.8. Long Lines}
+\beginscroll
+
+When you enter Axiom expressions from your keyboard, there
+will be times when they are too long to fit on one line.
+Axiom does not care how long your lines are, so you can let
+them continue from the right margin to the left side of the
+next line.
+
+Alternatively, you may want to enter several shorter lines and
+have Axiom glue them together.
+To get this glue, put an underscore (\_) at the end of
+each line you wish to continue.
+\begin{verbatim}
+2_
++_
+3
+\end{verbatim}
+is the same as if you had entered
+\begin{verbatim}
+2+3
+\end{verbatim}
+
+If you are putting your Axiom statements in an input file
+(see \downlink{``\ugInOutInTitle''}{ugInOutInPage} 
+in Section \ugInOutInNumber\ignore{ugInOutIn}),
+you can use indentation to indicate the structure of your program.
+(see \downlink{``\ugLangBlocksTitle''}{ugLangBlocksPage} 
+in Section \ugLangBlocksNumber\ignore{ugLangBlocks}).
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroCommentsTitle}{Comments}
+\newcommand{\ugIntroCommentsNumber}{1.3.9.}
+
+@
+\section{Comments}
+\label{ugIntroCommentsPage}
+\index{pages!ugIntroCommentsPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroCommentsPage}
+\index{ugIntroCommentsPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroCommentsPage}{1.3.9. Comments}
+\beginscroll
+
+Comment statements begin with two consecutive hyphens or two
+consecutive plus signs and continue until the end of the line.
+
+\xtc{
+The comment beginning with {\tt --} is ignored by Axiom.
+}{
+\spadpaste{2 + 3   -- this is rather simple, no?}
+}
+
+There is no way to write long multi-line comments
+other than starting each line with \axiomSyntax{--} or
+\axiomSyntax{++}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroGraphicsTitle}{Graphics}
+\newcommand{\ugIntroGraphicsNumber}{1.4.}
+
+@
+\section{Graphics}
+\label{ugIntroGraphicsPage}
+\begin{itemize}
+\item ugProblemNumericPage \ref{ugProblemNumericPage} on
+page~\pageref{ugProblemNumericPage}
+\item ugAppGraphicsPage \ref{ugAppGraphicsPage} on
+page~\pageref{ugAppGraphicsPage}
+\item ugGraphPage \ref{ugGraphPage} on
+page~\pageref{ugGraphPage}
+\end{itemize}
+\index{pages!ugIntroGraphicsPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroGraphicsPage}
+\index{ugIntroGraphicsPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroGraphicsPage}{1.4. Graphics}
+\beginscroll
+%
+
+Axiom has a two- and three-dimensional drawing and rendering
+package that allows you to draw, shade, color, rotate, translate, map,
+clip, scale and combine graphic output of Axiom computations.
+The graphics interface is capable of plotting functions of one or more
+variables and plotting parametric surfaces.
+Once the graphics figure appears in a window,
+move your mouse to the window and click.
+A control panel appears immediately  and allows you to
+interactively transform the object.
+
+\psXtc{
+This is an example of Axiom's two-dimensional plotting.
+From the 2D Control Panel you can rescale the plot, turn axes and units
+on and off and save the image, among other things.
+This PostScript image was produced by clicking on the
+\texht{\fbox{\bf PS}}{{\bf PS}} 2D Control Panel button.
+}{
+\graphpaste{draw(cos(5*t/8), t=0..16*\%pi, coordinates==polar)}
+}{
+\epsffile[72 72 300 300]{../ps/rose-1.ps}
+}
+
+\psXtc{
+This is an example of Axiom's three-dimensional plotting.
+It is a monochrome graph of the complex arctangent
+function.
+The image displayed was rotated and had the ``shade'' and ``outline''
+display options set from the 3D Control Panel.
+The PostScript output was produced by clicking on the
+\texht{\fbox{\bf save}}{{\bf save}} 3D Control Panel button and then
+clicking on the \texht{\fbox{\bf PS}}{{\bf PS}} button.
+See \downlink{``\ugProblemNumericTitle''}{ugProblemNumericPage} 
+in Section \ugProblemNumericNumber\ignore{ugProblemNumeric} for 
+more details and examples
+of Axiom's numeric and graphics capabilities.
+}{
+\graphpaste{draw((x,y) +-> real atan complex(x,y), -\%pi..\%pi, -\%pi..\%pi, colorFunction == (x,y) +-> argument atan complex(x,y))}
+}{
+\epsffile[72 72 285 285]{../ps/atan-1.ps}
+}
+
+An exhibit of \Gallery{} is given in the
+center section of this book.
+For a description of the commands and programs that
+produced these figures, see 
+\downlink{``\ugAppGraphicsTitle''}{ugAppGraphicsPage} 
+in Appendix \ugAppGraphicsNumber\ignore{ugAppGraphics}.
+PostScript
+output is available so that Axiom images can be
+printed.\footnote{PostScript is a trademark of Adobe Systems Incorporated,
+registered in the United States.}
+See \downlink{``\ugGraphTitle''}{ugGraphPage} 
+in Chapter \ugGraphNumber\ignore{ugGraph} for 
+more examples and details about using
+Axiom's graphics facilities.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroNumbersTitle}{Numbers}
+\newcommand{\ugIntroNumbersNumber}{1.5.}
+
+@
+\section{Numbers}
+\label{ugIntroNumbersPage}
+\begin{itemize}
+\item FloatXmpPage \ref{FloatXmpPage} on
+page~\pageref{FloatXmpPage}
+\item DoubleFloatXmpPage \ref{DoubleFloatXmpPage} on
+page~\pageref{DoubleFloatXmpPage}
+\item ComplexXmpPage \ref{ComplexXmpPage} on
+page~\pageref{ComplexXmpPage}
+\item DecimalExpansionXmpPage \ref{DecimalExpansionXmpPage} on
+page~\pageref{DecimalExpansionXmpPage}
+\item ContinuedFractionXmpPage \ref{ContinuedFractionXmpPage} on
+page~\pageref{ContinuedFractionXmpPage}
+\item PartialFractionXmpPage \ref{PartialFractionXmpPage} on
+page~\pageref{PartialFractionXmpPage}
+\item RadixExpansionXmpPage \ref{RadixExpansionXmpPage} on
+page~\pageref{RadixExpansionXmpPage}
+\item ugxProblemFinitePrimePage \ref{ugxProblemFinitePrimePage} on
+page~\pageref{ugxProblemFinitePrimePage}
+\end{itemize}
+\index{pages!ugIntroNumbersPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroNumbersPage}
+\index{ugIntroNumbersPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroNumbersPage}{1.5. Numbers}
+\beginscroll
+%
+
+Axiom distinguishes very carefully between different kinds
+of numbers, how they are represented and what their properties
+are.
+Here are a sampling of some of these kinds of numbers and some
+things you can do with them.
+
+\xtc{
+Integer arithmetic is always exact.
+}{
+\spadpaste{11**13 * 13**11 * 17**7 - 19**5 * 23**3}
+}
+\xtc{
+Integers can be represented in factored form.
+}{
+\spadpaste{factor 643238070748569023720594412551704344145570763243 \bound{ex1}}
+}
+\xtc{
+Results stay factored when you do arithmetic.
+Note that the \axiom{12} is automatically factored for you.
+}{
+\spadpaste{\% * 12 \free{ex1}}
+}
+\xtc{
+Integers can also be displayed to bases other than 10.
+This is an integer in base 11.
+}{
+\spadpaste{radix(25937424601,11)}
+}
+\xtc{
+Roman numerals are also available for those special occasions.
+}{
+\spadpaste{roman(1992)}
+}
+\xtc{
+Rational number arithmetic is also exact.
+}{
+\spadpaste{r := 10 + 9/2 + 8/3 + 7/4 + 6/5 + 5/6 + 4/7 + 3/8 + 2/9\bound{r}}
+}
+\xtc{
+To factor fractions, you have to
+map \axiomFun{factor} onto the numerator and denominator.
+}{
+\spadpaste{map(factor,r) \free{r}}
+}
+\xtc{
+Type \spadtype{SingleInteger} refers to machine word-length
+integers.
+In English, this expression means ``\axiom{11} as a small
+integer''.
+}{
+\spadpaste{11@SingleInteger}
+}
+\xtc{
+Machine double-precision floating-point numbers are also
+available for numeric and graphical
+applications.
+}{
+\spadpaste{123.21@DoubleFloat}
+}
+
+The normal floating-point type in Axiom, \spadtype{Float},
+is a software implementation of floating-point numbers in which
+the exponent and the mantissa may have any number of
+digits.\footnote{See 
+\downlink{`Float'}{FloatXmpPage}\ignore{Float} and 
+\downlink{`DoubleFloat'}{DoubleFloatXmpPage}\ignore{DoubleFloat} for
+additional information on floating-point types.}
+The types \spadtype{Complex(Float)} and
+\spadtype{Complex(DoubleFloat)} are the corresponding software
+implementations of complex floating-point numbers.
+
+\xtc{
+This is a floating-point approximation to about twenty digits.
+The \axiomSyntax{::}
+is used here to change from one kind of object
+(here, a rational number) to another (a floating-point number).
+}{
+\spadpaste{r :: Float \free{r}}
+}
+\xtc{
+Use \spadfunFrom{digits}{Float} to change the number of digits in
+the representation.
+This operation returns the previous value so you can reset it
+later.
+}{
+\spadpaste{digits(22) \bound{fewerdigits}}
+}
+\xtc{
+To \axiom{22} digits of precision, the number
+\texht{$e^{\pi {\sqrt {163.0}}}$}{\axiom{exp(\%pi * sqrt 163.0)}}
+appears to be an integer.
+}{
+\spadpaste{exp(\%pi * sqrt 163.0) \free{fewerdigits}}
+}
+\xtc{
+Increase the precision to forty digits and try again.
+}{
+\spadpaste{digits(40);  exp(\%pi * sqrt 163.0) \free{moredigits}}
+}
+\xtc{
+Here are complex numbers with rational numbers as real and
+imaginary parts.
+}{
+\spadpaste{(2/3 + \%i)**3 \bound{gaussint}}
+}
+\xtc{
+The standard operations on complex numbers are available.
+}{
+\spadpaste{conjugate \% \free{gaussint}}
+}
+\xtc{
+You can factor complex integers.
+}{
+\spadpaste{factor(89 - 23 * \%i)}
+}
+\xtc{
+Complex numbers with floating point parts are also available.
+}{
+\spadpaste{exp(\%pi/4.0 * \%i)}
+}
+%%--> These are not numbers:
+%\xtc{
+%The real and imaginary parts can be symbolic.
+%}{
+%\spadcommand{complex(u,v) \bound{cuv}}
+%}
+%\xtc{
+%Of course, you can do complex arithmetic with these also.
+%See \downlink{`Complex'}{ComplexXmpPage}\ignore{Complex} 
+for more information.
+%}{
+%\spadcommand{\% ** 2 \free{cuv}}
+%}
+\xtc{
+Every rational number has an exact representation as a
+repeating decimal expansion
+(see \downlink{`DecimalExpansion'}{DecimalExpansionXmpPage}
+\ignore{DecimalExpansion}).
+}{
+\spadpaste{decimal(1/352)}
+}
+\xtc{
+A rational number can also be expressed as a continued fraction (see
+\downlink{`ContinuedFraction'}{ContinuedFractionXmpPage}
+\ignore{ContinuedFraction}).
+}{
+\spadpaste{continuedFraction(6543/210)}
+}
+\xtc{
+Also, partial fractions can be used and can be displayed in a
+compact \ldots
+}{
+\spadpaste{partialFraction(1,factorial(10)) \bound{partfrac}}
+}
+\xtc{
+or expanded format (see 
+\downlink{`PartialFraction'}{PartialFractionXmpPage}\ignore{PartialFraction}).
+}{
+\spadpaste{padicFraction(\%) \free{partfrac}}
+}
+\xtc{
+Like integers, bases (radices) other than ten can be used for rational
+numbers (see 
+\downlink{`RadixExpansion'}{RadixExpansionXmpPage}\ignore{RadixExpansion}).
+Here we use base eight.
+}{
+\spadpaste{radix(4/7, 8)\bound{rad}}
+}
+\xtc{
+Of course, there are complex versions of these as well.
+Axiom decides to make the result a complex rational number.
+}{
+\spadpaste{\% + 2/3*\%i\free{rad}}
+}
+\xtc{
+You can also use Axiom to manipulate fractional powers.
+}{
+\spadpaste{(5 + sqrt 63 + sqrt 847)**(1/3)}
+}
+\xtc{
+You can also compute with integers modulo a prime.
+}{
+\spadpaste{x : PrimeField 7 := 5 \bound{x}}
+}
+\xtc{
+Arithmetic is then done modulo \mathOrSpad{7}.
+}{
+\spadpaste{x**3 \free{x}}
+}
+\xtc{
+Since \mathOrSpad{7} is prime, you can invert nonzero values.
+}{
+\spadpaste{1/x \free{x}}
+}
+\xtc{
+You can also compute modulo an integer that is not a prime.
+}{
+\spadpaste{y : IntegerMod 6 := 5 \bound{y}}
+}
+\xtc{
+All of the usual arithmetic operations are available.
+}{
+\spadpaste{y**3 \free{y}}
+}
+\xtc{
+Inversion is not available if the modulus is not a prime
+number.
+Modular arithmetic and prime fields are discussed in
+\downlink{``\ugxProblemFinitePrimeTitle''}{ugxProblemFinitePrimePage} 
+in Section \ugxProblemFinitePrimeNumber\ignore{ugxProblemFinitePrime}.
+}{
+\spadpaste{1/y \free{y}}
+}
+\xtc{
+This defines \axiom{a} to be an algebraic number, that is,
+a root of a polynomial equation.
+}{
+\spadpaste{a := rootOf(a**5 + a**3 + a**2 + 3,a) \bound{a}}
+}
+\xtc{
+Computations with \axiom{a} are reduced according
+to the polynomial equation.
+}{
+\spadpaste{(a + 1)**10\free{a}}
+}
+\xtc{
+Define \axiom{b} to be an algebraic number involving \axiom{a}.
+}{
+\spadpaste{b := rootOf(b**4 + a,b) \bound{b}\free{a}}
+}
+\xtc{
+Do some arithmetic.
+}{
+\spadpaste{2/(b - 1) \free{b}\bound{check}}
+}
+\xtc{
+To expand and simplify this, call \axiomFun{ratDenom}
+to rationalize the denominator.
+}{
+\spadpaste{ratDenom(\%) \free{check}\bound{check1}}
+}
+\xtc{
+If we do this, we should get \axiom{b}.
+}{
+\spadpaste{2/\%+1 \free{check1}\bound{check2}}
+}
+\xtc{
+But we need to rationalize the denominator again.
+}{
+\spadpaste{ratDenom(\%) \free{check2}}
+}
+\xtc{
+Types \spadtype{Quaternion} and \spadtype{Octonion} are also available.
+Multiplication of quaternions is non-commutative, as expected.
+}{
+\spadpaste{q:=quatern(1,2,3,4)*quatern(5,6,7,8) - quatern(5,6,7,8)*quatern(1,2,3,4)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroCollectTitle}{Data Structures}
+\newcommand{\ugIntroCollectNumber}{1.6.}
+
+@
+\section{Data Structures}
+\label{ugIntroCollectPage}
+\begin{itemize}
+\item ListXmpPage \ref{ListXmpPage} on
+page~\pageref{ListXmpPage}
+\item ugLangItsPage \ref{ugLangItsPage} on
+page~\pageref{ugLangItsPage}
+\item StreamXmpPage \ref{StreamXmpPage} on
+page~\pageref{StreamXmpPage}
+\item ugLangItsPage \ref{ugLangItsPage} on
+page~\pageref{ugLangItsPage}
+\item OneDimensionalArrayXmpPage \ref{OneDimensionalArrayXmpPage} on
+page~\pageref{OneDimensionalArrayXmpPage}
+\item FlexibleArrayXmpPage \ref{FlexibleArrayXmpPage} on
+page~\pageref{FlexibleArrayXmpPage}
+\item HeapXmpPage \ref{HeapXmpPage} on
+page~\pageref{HeapXmpPage}
+\item BinarySearchTreeXmpPage \ref{BinarySearchTreeXmpPage} on
+page~\pageref{BinarySearchTreeXmpPage}
+\item BalancedBinaryTreeXmpPage \ref{BalancedBinaryTreeXmpPage} on
+page~\pageref{BalancedBinaryTreeXmpPage}
+\item SetXmpPage \ref{SetXmpPage} on
+page~\pageref{SetXmpPage}
+\item MultiSetXmpPage \ref{MultiSetXmpPage} on
+page~\pageref{MultiSetXmpPage}
+\item AssociationListXmpPage \ref{AssociationListXmpPage} on
+page~\pageref{AssociationListXmpPage}
+\item KeyedAccessFileXmpPage \ref{KeyedAccessFileXmpPage} on
+page~\pageref{KeyedAccessFileXmpPage}
+\item LibraryXmpPage \ref{LibraryXmpPage} on
+page~\pageref{LibraryXmpPage}
+\item SparseTableXmpPage \ref{SparseTableXmpPage} on
+page~\pageref{SparseTableXmpPage}
+\item StringTableXmpPage \ref{StringTableXmpPage} on
+page~\pageref{StringTableXmpPage}
+\item TableXmpPage \ref{TableXmpPage} on
+page~\pageref{TableXmpPage}
+\item ugTypesRecordsPage \ref{ugTypesRecordsPage} on
+page~\pageref{ugTypesRecordsPage}
+\item ugTypesUnionsPage \ref{ugTypesUnionsPage} on
+page~\pageref{ugTypesUnionsPage}
+\item ugDomainsPage \ref{ugDomainsPage} on
+page~\pageref{ugDomainsPage}
+\end{itemize}
+\index{pages!ugIntroCollectPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroCollectPage}
+\index{ugIntroCollectPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroCollectPage}{1.6. Data Structures}
+\beginscroll
+%
+
+Axiom has a large variety of data structures available.
+Many data structures are particularly useful for interactive
+computation and others are useful for building applications.
+The data structures of Axiom are organized into
+\spadglossSee{category hierarchies}{hierarchy} as shown on
+the inside back cover.
+
+A \spadgloss{list} is the most commonly used data structure in
+Axiom for holding objects all of the same
+type.\footnote{Lists are discussed in 
+\downlink{`List'}{ListXmpPage}\ignore{List} and in
+\downlink{``\ugLangItsTitle''}{ugLangItsPage} 
+in Section \ugLangItsNumber\ignore{ugLangIts}.}
+The name {\it list} is short for ``linked-list of nodes.'' Each
+node consists of a value (\spadfunFrom{first}{List}) and a link
+(\spadfunFrom{rest}{List}) that
+\spadglossSee{points}{pointer} to the next node, or to a
+distinguished value denoting the empty list.
+To get to, say, the third element, Axiom starts at the front
+of the list, then traverses across two links to the third node.
+
+\xtc{
+Write a list of elements using
+square brackets with commas separating the elements.
+}{
+\spadpaste{u := [1,-7,11] \bound{u}}
+}
+\xtc{
+This is the value at the third node.
+Alternatively, you can say \axiom{u.3}.
+}{
+\spadpaste{first rest rest u\free{u}}
+}
+
+Many operations are defined on lists, such as:
+\axiomFun{empty?}, to test that a list has no elements;
+\axiomFun{cons}\axiom{(x,l)}, to create a new list with
+\axiomFun{first} element \axiom{x} and \axiomFun{rest} \axiom{l};
+\axiomFun{reverse}, to create a new list with elements in reverse
+order; and \axiomFun{sort}, to arrange elements in order.
+
+An important point about lists is that they are ``mutable'': their
+constituent elements and links can be changed ``in place.''
+To do this, use any of the operations whose names end with the
+character \axiomSyntax{!}.
+
+\xtc{
+The operation \spadfunFromX{concat}{List}\axiom{(u,v)}
+replaces the last link of the list
+\axiom{u} to point to some other list \axiom{v}.
+Since \axiom{u} refers to the original list,
+this change is seen by \axiom{u}.
+}{
+\spadpaste{concat!(u,[9,1,3,-4]); u\free{u}\bound{u1}}
+}
+\xtc{
+A {\it cyclic list} is a list with a ``cycle'':
+a link pointing back to an earlier node of the list.
+To create a cycle, first get a node somewhere down
+the list.
+}{
+\spadpaste{lastnode := rest(u,3)\free{u1}\bound{u2}}
+}
+\xtc{
+Use \spadfunFromX{setrest}{List} to
+change the link emanating from that node to point back to an
+earlier part of the list.
+}{
+\spadpaste{setrest!(lastnode,rest(u,2)); u\free{u2}}
+}
+
+A \spadgloss{stream}
+is a structure that (potentially) has an infinite number of
+distinct elements.\footnote{Streams are discussed in
+\downlink{`Stream'}{StreamXmpPage}\ignore{Stream} and in 
+\downlink{``\ugLangItsTitle''}{ugLangItsPage} 
+in Section \ugLangItsNumber\ignore{ugLangIts}.}
+Think of a stream as an ``infinite list'' where elements are
+computed successively.
+
+\xtc{
+Create an infinite stream of factored integers.
+Only a certain number of initial elements are computed
+and displayed.
+}{
+\spadpaste{[factor(i) for i in 2.. by 2] \bound{stream1}}
+}
+\xtc{
+Axiom represents streams by a collection of already-computed
+elements together with a function to compute the next element
+``on demand.''
+Asking for the \eth{\axiom{n}} element causes elements \axiom{1} through
+\axiom{n} to be evaluated.
+}{
+\spadpaste{\%.36 \free{stream1}}
+}
+
+Streams can also be finite or cyclic.
+They are implemented by a linked list structure similar to lists
+and have many of the same operations.
+For example, \axiomFun{first} and \axiomFun{rest} are used to access
+elements and successive nodes of a stream.
+%%> reverse and sort do not exist for streams
+%%Don't try to reverse or sort a stream: the
+%%operation will generally run forever!
+
+A \spadgloss{one-dimensional array} is another data structure used
+to hold objects of the same type.\footnote{See 
+\downlink{`OneDimensionalArray'}{OneDimensionalArrayXmpPage}
+\ignore{OneDimensionalArray} for
+details.}
+Unlike lists, one-dimensional arrays are inflexible---they are
+implemented using a fixed block of storage.
+Their advantage is that they give quick and equal access time to
+any element.
+
+\xtc{
+A simple way to create a one-dimensional array is to apply the
+operation \axiomFun{oneDimensionalArray} to a list of elements.
+}{
+\spadpaste{a := oneDimensionalArray [1, -7, 3, 3/2]\bound{a}}
+}
+\xtc{
+One-dimensional arrays are also mutable:
+you can change their constituent elements ``in place.''
+}{
+\spadpaste{a.3 := 11; a\bound{a1}\free{a}}
+}
+\xtc{
+However, one-dimensional arrays are not flexible structures.
+You cannot destructively \spadfunX{concat} them together.
+}{
+\spadpaste{concat!(a,oneDimensionalArray [1,-2])\free{a1}}
+}
+
+Examples of datatypes similar to \spadtype{OneDimensionalArray}
+are: \spadtype{Vector} (vectors are mathematical structures
+implemented by one-dimensional arrays), \spadtype{String} (arrays
+of ``characters,'' represented by byte vectors), and
+\spadtype{Bits} (represented by ``bit vectors'').
+
+\xtc{
+A vector of 32 bits, 
+each representing the \spadtype{Boolean} value \axiom{true}.
+}{
+\spadpaste{bits(32,true)}
+}
+
+A \spadgloss{flexible array} is a cross between a list
+and a one-dimensional array.\footnote{See 
+\downlink{`FlexibleArray'}{FlexibleArrayXmpPage}\ignore{FlexibleArray} for
+details.}
+Like a one-dimensional array, a flexible array occupies a fixed
+block of storage.
+Its block of storage, however, has room to expand!
+When it gets full, it grows (a new, larger block of storage is
+allocated); when it has too much room, it contracts.
+
+\xtc{
+Create a flexible array of three elements.
+}{
+\spadpaste{f := flexibleArray [2, 7, -5]\bound{f}}
+}
+\xtc{
+Insert some elements between the second and third elements.
+}{
+\spadpaste{insert!(flexibleArray [11, -3],f,2)\free{f}}
+}
+
+Flexible arrays are used to implement ``heaps.'' A
+\spadgloss{heap} is an example of a data structure called a
+\spadgloss{priority queue}, where elements are ordered with
+respect to one another.\footnote{See 
+\downlink{`Heap'}{HeapXmpPage}\ignore{Heap} for more details.
+Heaps are also examples of data structures called
+\spadglossSee{bags}{bag}.
+Other bag data structures are \spadtype{Stack}, \spadtype{Queue},
+and \spadtype{Dequeue}.}
+A heap is organized
+so as to optimize insertion and extraction of maximum elements.
+The \spadfunX{extract} operation
+returns the maximum element of the heap, after destructively
+removing that element and
+reorganizing the heap
+so that the next maximum element is ready to be delivered.
+
+\xtc{
+An easy way to create a heap is to apply the
+operation \spadfun{heap} to a list of values.
+}{
+\spadpaste{h := heap [-4,7,11,3,4,-7]\bound{h}}
+}
+\xtc{
+This loop extracts elements one-at-a-time from \spad{h}
+until the heap is exhausted, returning the elements
+as a list in the order they were extracted.
+}{
+\spadpaste{[extract!(h) while not empty?(h)]\free{h}}
+}
+
+A \spadgloss{binary tree} is a ``tree'' with at most two branches
+per node: it is either empty, or else is a node consisting of a
+value, and a left and right subtree (again, binary trees).\footnote{Example of binary tree types are
+\spadtype{BinarySearchTree} (see 
+\downlink{`BinarySearchTree'}{BinarySearchTreeXmpPage}
+\ignore{BinarySearchTree},
+\spadtype{PendantTree}, \spadtype{TournamentTree},
+and \spadtype{BalancedBinaryTree} (see 
+\downlink{`BalancedBinaryTree'}{BalancedBinaryTreeXmpPage}
+\ignore{BalancedBinaryTree}).}
+
+\xtc{
+A {\it binary search tree} is a binary tree such that,
+for each node, the value of the node is
+greater than all values (if any) in the left subtree,
+and less than or equal all values (if any) in the right subtree.
+}{
+\spadpaste{binarySearchTree [5,3,2,9,4,7,11]}
+}
+
+\xtc{
+A {\it balanced binary tree} is useful for doing modular computations.
+Given a list \axiom{lm} of moduli,
+\axiomFun{modTree}\axiom{(a,lm)} produces a balanced binary
+tree with the values \texht{$a \bmod m$}{a {\tt mod} m}
+at its leaves.
+}{
+\spadpaste{modTree(8,[2,3,5,7])}
+}
+
+A \spadgloss{set} is a collection of elements where duplication
+and order is irrelevant.\footnote{See 
+\downlink{`Set'}{SetXmpPage}\ignore{Set} for more
+details.}
+Sets are always finite and have no corresponding
+structure like streams for infinite collections.
+
+\xtc{
+%Create sets using braces (\axiomSyntax{\{} and \axiomSyntax{\}})
+%rather than brackets.
+}{
+\spadpaste{fs := set[1/3,4/5,-1/3,4/5] \bound{fs}}
+}
+
+A \spadgloss{multiset}
+is a set that keeps track of the number
+of duplicate values.\footnote{See 
+\downlink{`MultiSet'}{MultiSetXmpPage}\ignore{MultiSet} for details.}
+\xtc{
+For all the primes \axiom{p} between 2 and 1000, find the
+distribution of \texht{$p \bmod 5$}{p mod 5}.
+}{
+\spadpaste{multiset [x rem 5 for x in primes(2,1000)]}
+}
+
+A \spadgloss{table}
+is conceptually a set of ``key--value'' pairs and
+is a generalization of a multiset.\footnote{For examples of tables, see
+\spadtype{AssociationList} (
+\downlink{`AssociationList'}{AssociationListXmpPage}\ignore{AssociationList}),
+\spadtype{HashTable},
+\spadtype{KeyedAccessFile} (
+\downlink{`KeyedAccessFile'}{KeyedAccessFileXmpPage}\ignore{KeyedAccessFile}),
+\spadtype{Library} (\downlink{`Library'}{LibraryXmpPage}\ignore{Library}),
+\spadtype{SparseTable} (
+\downlink{`SparseTable'}{SparseTableXmpPage}\ignore{SparseTable}),
+\spadtype{StringTable} (
+\downlink{`StringTable'}{StringTableXmpPage}\ignore{StringTable}),
+and \spadtype{Table} (\downlink{`Table'}{TableXmpPage}\ignore{Table}).}
+The domain \spadtype{Table(Key, Entry)} provides a general-purpose
+type for tables with {\it values} of type \axiom{Entry} indexed
+by {\it keys} of type \axiom{Key}.
+
+\xtc{
+Compute the above distribution of primes using tables.
+First, let \axiom{t} denote an empty table of keys and values,
+each of type \spadtype{Integer}.
+}{
+\spadpaste{t : Table(Integer,Integer) := empty()\bound{t}}
+}
+
+We define a function \userfun{howMany} to return the number
+of values of a given modulus \axiom{k} seen so far.
+It calls \axiomFun{search}\axiom{(k,t)} which returns the number of
+values stored under the key \axiom{k} in table \axiom{t}, or
+\axiom{"failed"} if no such value is yet stored in \axiom{t} under
+\axiom{k}.
+
+\xtc{
+In English, this says ``Define \axiom{howMany(k)} as follows.
+First, let \smath{n} be the value of \axiomFun{search}\smath{(k,t)}.
+Then, if \smath{n} has the value \smath{"failed"}, return the value
+\smath{1}; otherwise return \smath{n + 1}.''
+}{
+\spadpaste{howMany(k) == (n:=search(k,t); n case "failed" => 1; n+1)\bound{how}}
+}
+\xtc{
+Run through the primes to create the table, then print the table.
+The expression \axiom{t.m := howMany(m)} updates the value in table \axiom{t}
+stored under key \axiom{m}.
+}{
+\spadpaste{for p in primes(2,1000) repeat (m:= p rem 5; t.m:= howMany(m)); t\free{how t}}
+}
+
+A {\it record}
+is an example of an inhomogeneous collection
+of objects.\footnote{See 
+\downlink{``\ugTypesRecordsTitle''}{ugTypesRecordsPage} 
+in Section \ugTypesRecordsNumber\ignore{ugTypesRecords} for details.}
+A record consists of a set of named {\it selectors} that
+can be used to access its components.
+
+\xtc{
+Declare that \axiom{daniel} can only be
+assigned a record with two prescribed fields.
+}{
+\spadpaste{daniel : Record(age : Integer, salary : Float) \bound{danieldec}}
+}
+\xtc{
+Give \axiom{daniel} a value, using square brackets to enclose the values of
+the fields.
+}{
+\spadpaste{daniel := [28, 32005.12] \free{danieldec}\bound{daniel}}
+}
+\xtc{
+Give \axiom{daniel} a raise.
+}{
+\spadpaste{daniel.salary := 35000; daniel \free{daniel}}
+}
+
+A {\it union}
+is a data structure used when objects
+have multiple types.\footnote{See 
+\downlink{``\ugTypesUnionsTitle''}{ugTypesUnionsPage} 
+in Section \ugTypesUnionsNumber\ignore{ugTypesUnions} for details.}
+
+\xtc{
+Let \axiom{dog} be either an integer or a string value.
+}{
+\spadpaste{dog: Union(licenseNumber: Integer, name: String)\bound{xint}}
+}
+\xtc{
+Give \axiom{dog} a name.
+}{
+\spadpaste{dog := "Whisper"\free{xint}}
+}
+
+All told, there are over forty different data structures in
+Axiom.
+Using the domain constructors described in 
+\downlink{``\ugDomainsTitle''}{ugDomainsPage} 
+in Chapter \ugDomainsNumber\ignore{ugDomains}, you
+can add your own data structure or extend an existing one.
+Choosing the right data structure for your application may be the key
+to obtaining good performance.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroTwoDimTitle}{Expanding to Higher Dimensions}
+\newcommand{\ugIntroTwoDimNumber}{1.7.}
+
+@
+\section{Expanding to Higher Dimensions}
+\label{ugIntroTwoDimPage}
+\begin{itemize}
+\item TwoDimensionalArrayXmpPage \ref{TwoDimensionalArrayXmpPage} on
+page~\pageref{TwoDimensionalArrayXmpPage}
+\item MatrixXmpPage \ref{MatrixXmpPage} on
+page~\pageref{MatrixXmpPage}
+\item PermanentXmpPage \ref{PermanentXmpPage} on
+page~\pageref{PermanentXmpPage}
+\item SquareMatrixXmpPage \ref{SquareMatrixXmpPage} on
+page~\pageref{SquareMatrixXmpPage}
+\item VectorXmpPage \ref{VectorXmpPage} on
+page~\pageref{VectorXmpPage}
+\item ugProblemEigenPage \ref{ugProblemEigenPage} on
+page~\pageref{ugProblemEigenPage}
+\item ugProblemLinPolEqnPage \ref{ugProblemLinPolEqnPage} on
+page~\pageref{ugProblemLinPolEqnPage}
+\item ugLangItsPage \ref{ugLangItsPage} on
+page~\pageref{ugLangItsPage}
+\end{itemize}
+\index{pages!ugIntroTwoDimPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroTwoDimPage}
+\index{ugIntroTwoDimPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroTwoDimPage}{1.7. Expanding to Higher Dimensions}
+\beginscroll
+%
+
+To get higher dimensional aggregates, you can create one-dimensional
+aggregates with elements that are themselves
+aggregates, for example, lists of lists, one-dimensional arrays of
+lists of multisets, and so on.
+For applications requiring two-dimensional homogeneous aggregates,
+you will likely find {\it two-dimensional arrays}
+and {\it matrices} most useful.
+
+The entries in \spadtype{TwoDimensionalArray} and
+\spadtype{Matrix} objects
+are all the same type, except that those for
+\spadtype{Matrix} must belong to a \spadtype{Ring}.
+You create and access elements in roughly the same way.
+Since matrices have an understood algebraic structure, certain algebraic
+operations are available for matrices but not for arrays.
+Because of this, we limit our discussion here to
+\spadtype{Matrix}, that can be regarded as an extension of
+\spadtype{TwoDimensionalArray}.\footnote{See
+\downlink{`TwoDimensionalArray'}{TwoDimensionalArrayXmpPage}
+\ignore{TwoDimensionalArray} for more information about arrays.
+For more information about Axiom's linear algebra
+facilities, see \downlink{`Matrix'}{MatrixXmpPage}\ignore{Matrix}, 
+\downlink{`Permanent'}{PermanentXmpPage}\ignore{Permanent},
+\downlink{`SquareMatrix'}{SquareMatrixXmpPage}\ignore{SquareMatrix}, 
+\downlink{`Vector'}{VectorXmpPage}\ignore{Vector},
+\downlink{``\ugProblemEigenTitle''}{ugProblemEigenPage} 
+in Section \ugProblemEigenNumber\ignore{ugProblemEigen}
+\texht{(computation of eigenvalues and
+eigenvectors)}{}, and
+\downlink{``\ugProblemLinPolEqnTitle''}{ugProblemLinPolEqnPage} 
+in Section \ugProblemLinPolEqnNumber\ignore{ugProblemLinPolEqn}\
+texht{(solution of linear and
+polynomial equations)}{}.}
+
+\xtc{
+You can create a matrix from a list of lists,
+where each of the inner lists represents a row of the matrix.
+}{
+\spadpaste{m := matrix([[1,2], [3,4]]) \bound{m}}
+}
+\xtc{
+The ``collections'' construct (see 
+\downlink{``\ugLangItsTitle''}{ugLangItsPage} 
+in Section \ugLangItsNumber\ignore{ugLangIts}) is
+useful for creating matrices whose entries are given by formulas.
+}{
+\spadpaste{matrix([[1/(i + j - x) for i in 1..4] for j in 1..4]) \bound{hilb}}
+}
+\xtc{
+Let \axiom{vm} denote the three by three Vandermonde matrix.
+}{
+\spadpaste{vm := matrix [[1,1,1], [x,y,z], [x*x,y*y,z*z]] \bound{vm}}
+}
+\xtc{
+Use this syntax to extract an entry in the matrix.
+}{
+\spadpaste{vm(3,3) \free{vm}}
+}
+\xtc{
+You can also pull out a \axiomFun{row} or a \axiom{column}.
+}{
+\spadpaste{column(vm,2) \free{vm}}
+}
+\xtc{
+You can do arithmetic.
+}{
+\spadpaste{vm * vm \free{vm}}
+}
+\xtc{
+You can perform operations such as
+\axiomFun{transpose}, \axiomFun{trace}, and \axiomFun{determinant}.
+}{
+\spadpaste{factor determinant vm \free{vm}\bound{d}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroYouTitle}{Writing Your Own Functions}
+\newcommand{\ugIntroYouNumber}{1.8.}
+
+@
+\section{Writing Your Own Functions}
+\label{ugIntroYouPage}
+\begin{itemize}
+\item ugUserPage \ref{ugUserPage} on
+page~\pageref{ugUserPage}
+\item ugInOutInPage \ref{ugInOutInPage} on
+page~\pageref{ugInOutInPage}
+\end{itemize}
+\index{pages!ugIntroYouPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroYouPage}
+\index{ugIntroYouPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroYouPage}{1.8. Writing Your Own Functions}
+\beginscroll
+%
+
+Axiom provides you with a very large library of predefined
+operations and objects to compute with.
+You can use the Axiom library of constructors to create new
+objects dynamically of quite arbitrary complexity.
+For example, you can make lists of matrices of fractions of
+polynomials with complex floating point numbers as coefficients.
+Moreover, the library provides a wealth of operations that allow
+you to create and manipulate these objects.
+
+For many applications,
+you need to interact with the interpreter and write some
+Axiom programs to tackle your application.
+Axiom allows you to write functions interactively,
+thereby effectively extending the system library.
+Here we give a few simple examples, leaving the details to 
+\downlink{``\ugUserTitle''}{ugUserPage} in 
+Chapter \ugUserNumber\ignore{ugUser}.
+
+We begin by looking at several ways that you can define the
+``factorial'' function in Axiom.
+The first way is to give a
+piece-wise definition of the function.
+This method is best for a general recurrence
+relation since the pieces are gathered together and compiled into
+an efficient iterative function.
+Furthermore, enough previously computed values are automatically
+saved so that a subsequent call to the function can pick up from
+where it left off.
+
+\xtc{
+Define the value of \userfun{fact} at \axiom{0}.
+}{
+\spadpaste{fact(0) == 1 \bound{fact}}
+}
+\xtc{
+Define the value of \axiom{fact(n)} for general \axiom{n}.
+}{
+\spadpaste{fact(n) == n*fact(n-1)\bound{facta}\free{fact}}
+}
+\xtc{
+Ask for the value at \axiom{50}.
+The resulting function created by Axiom
+computes the value by iteration.
+}{
+\spadpaste{fact(50) \free{facta}}
+}
+\xtc{
+A second definition uses an \axiom{if-then-else} and recursion.
+}{
+\spadpaste{fac(n) == if n < 3 then n else n * fac(n - 1) \bound{fac}}
+}
+\xtc{
+This function is less efficient than the previous version since
+each iteration involves a recursive function call.
+}{
+\spadpaste{fac(50) \free{fac}}
+}
+\xtc{
+A third version directly uses iteration.
+}{
+\spadpaste{fa(n) == (a := 1; for i in 2..n repeat a := a*i; a) \bound{fa}}
+}
+\xtc{
+This is the least space-consumptive version.
+}{
+\spadpaste{fa(50) \free{fa}}
+}
+\xtc{
+A final version appears to construct a large list and then reduces over
+it with multiplication.
+}{
+\spadpaste{f(n) == reduce(*,[i for i in 2..n]) \bound{f}}
+}
+\xtc{
+In fact, the resulting computation is optimized into an efficient
+iteration loop equivalent to that of the third version.
+}{
+\spadpaste{f(50) \free{f}}
+}
+\xtc{
+The library version uses an algorithm that is different from the four
+above because it highly optimizes the recurrence relation definition of
+\axiomFun{factorial}.
+}{
+\spadpaste{factorial(50)}
+}
+
+You are not limited to one-line functions in Axiom.
+If you place your function definitions in {\bf .input} files
+(see \downlink{``\ugInOutInTitle''}{ugInOutInPage} 
+in Section \ugInOutInNumber\ignore{ugInOutIn}), you can have
+multi-line functions that use indentation for grouping.
+
+Given \axiom{n} elements, \axiomFun{diagonalMatrix} creates an
+\axiom{n} by \axiom{n} matrix with those elements down the diagonal.
+This function uses a permutation matrix
+that interchanges the \axiom{i}th and \axiom{j}th rows of a matrix
+by which it is right-multiplied.
+
+\xtc{
+This function definition shows a style of definition that can be used
+in {\bf .input} files.
+Indentation is used to create \spadglossSee{blocks}{block}\texht{\/}{}:
+sequences of expressions that are evaluated in sequence except as
+modified by control statements such as \axiom{if-then-else} and \axiom{return}.
+}{
+\begin{spadsrc}[\bound{permMat}]
+permMat(n, i, j) ==
+  m := diagonalMatrix
+    [(if i = k or j = k then 0 else 1)
+      for k in 1..n]
+  m(i,j) := 1
+  m(j,i) := 1
+  m
+\end{spadsrc}
+}
+\xtc{
+This creates a four by four matrix that interchanges the second and third
+rows.
+}{
+\spadpaste{p := permMat(4,2,3) \free{permMat}\bound{p}}
+}
+\xtc{
+Create an example matrix to permute.
+}{
+\spadpaste{m := matrix [[4*i + j for j in 1..4] for i in 0..3]\bound{m}}
+}
+\xtc{
+Interchange the second and third rows of m.
+}{
+\spadpaste{permMat(4,2,3) * m \free{p m}}
+}
+
+A function can also be passed as an argument to another function,
+which then applies the function or passes it off to some other
+function that does.
+You often have to declare the type of a function that has
+functional arguments.
+
+\xtc{
+This declares \userfun{t} to be a two-argument function that
+returns a \spadtype{Float}.
+The first argument is a function that takes one \spadtype{Float}
+argument and returns a \spadtype{Float}.
+}{
+\spadpaste{t : (Float -> Float, Float) -> Float \bound{tdecl}}
+}
+\xtc{
+This is the definition of \userfun{t}.
+}{
+\spadpaste{t(fun, x) == fun(x)**2 + sin(x)**2 \free{tdecl}\bound{t}}
+}
+\xtc{
+We have not defined a \axiomFun{cos} in the workspace. The one from the
+Axiom library will do.
+}{
+\spadpaste{t(cos, 5.2058) \free{t}}
+}
+\xtc{
+Here we define our own (user-defined) function.
+}{
+\spadpaste{cosinv(y) == cos(1/y) \bound{cosinv}}
+}
+\xtc{
+Pass this function as an argument to \userfun{t}.
+}{
+\spadpaste{t(cosinv, 5.2058) \free{t}\free{cosinv}}
+}
+
+Axiom also has pattern matching capabilities for
+simplification
+of expressions and for defining new functions by rules.
+For example, suppose that you want to apply regularly a transformation
+that groups together products of radicals:
+\texht{$$\sqrt{a}\:\sqrt{b} \mapsto \sqrt{ab}, \quad
+(\forall a)(\forall b)$$}{\axiom{sqrt(a) * sqrt(b) by sqrt(a*b)} for any \axiom{a} and \axiom{b}}
+Note that such a transformation is not generally correct.
+Axiom never uses it automatically.
+
+\xtc{
+Give this rule the name \userfun{groupSqrt}.
+}{
+\spadpaste{groupSqrt := rule(sqrt(a) * sqrt(b) == sqrt(a*b)) \bound{g}}
+}
+\xtc{
+Here is a test expression.
+}{
+\spadpaste{a := (sqrt(x) + sqrt(y) + sqrt(z))**4 \bound{sxy}}
+}
+\xtc{
+The rule
+\userfun{groupSqrt} successfully simplifies the expression.
+}{
+\spadpaste{groupSqrt a \free{sxy} \free{g}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroVariablesTitle}{Polynomials}
+\newcommand{\ugIntroVariablesNumber}{1.9.}
+
+@
+\section{Polynomials}
+\label{ugIntroVariablesPage}
+\index{pages!ugIntroVariablesPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroVariablesPage}
+\index{ugIntroVariablesPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroVariablesPage}{1.9. Polynomials}
+\beginscroll
+%
+
+Polynomials are the commonly used algebraic types in symbolic
+computation.
+Interactive users of Axiom generally only see one type
+of polynomial: \spadtype{Polynomial(R)}.
+This type represents polynomials in any number of unspecified
+variables over a particular coefficient domain \axiom{R}.
+This type represents its coefficients
+\spadglossSee{sparsely}{sparse}: only terms with non-zero
+coefficients are represented.
+
+In building applications, many other kinds of polynomial
+representations are useful.
+Polynomials may have one variable or multiple variables, the
+variables can be named or unnamed, the coefficients can be stored
+sparsely or densely.
+So-called ``distributed multivariate polynomials'' store
+polynomials as coefficients paired with vectors of exponents.
+This type is particularly efficient for use in algorithms for
+solving systems of non-linear polynomial equations.
+
+\xtc{
+The polynomial constructor most familiar to the interactive user
+is \spadtype{Polynomial}.
+}{
+\spadpaste{(x**2 - x*y**3 +3*y)**2}
+}
+\xtc{
+If you wish to restrict the variables used,
+\spadtype{UnivariatePolynomial}
+provides polynomials in one variable.
+}{
+\spadpaste{p: UP(x,INT) := (3*x-1)**2 * (2*x + 8)}
+}
+\xtc{
+The constructor
+\spadtype{MultivariatePolynomial} provides polynomials in one or more
+specified variables.
+}{
+\spadpaste{m: MPOLY([x,y],INT) := (x**2-x*y**3+3*y)**2 \bound{m}}
+}
+\xtc{
+You can change the way the polynomial appears by modifying the variable
+ordering in the explicit list.
+}{
+\spadpaste{m :: MPOLY([y,x],INT) \free{m}}
+}
+\xtc{
+The constructor
+\spadtype{DistributedMultivariatePolynomial} provides
+polynomials in one or more specified variables with the monomials
+ordered lexicographically.
+}{
+\spadpaste{m :: DMP([y,x],INT) \free{m}}
+}
+\xtc{
+The constructor
+\spadtype{HomogeneousDistributedMultivariatePolynomial} is similar except that
+the monomials are ordered by total order refined by reverse
+lexicographic order.
+}{
+\spadpaste{m :: HDMP([y,x],INT) \free{m}}
+}
+
+More generally, the domain constructor
+\spadtype{GeneralDistributedMultivariatePolynomial} allows the
+user to provide an arbitrary predicate to define his own term ordering.
+These last three constructors are typically used in
+\texht{Gr\"{o}bner}{Groebner} basis
+applications and when a flat (that is, non-recursive) display is
+wanted and the term ordering is critical for controlling the computation.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroCalcLimitsTitle}{Limits}
+\newcommand{\ugIntroCalcLimitsNumber}{1.10.}
+
+@
+\section{Limits}
+\label{ugIntroCalcLimitsPage}
+\begin{itemize}
+\item ugProblemLimitsPage \ref{ugProblemLimitsPage} on
+page~\pageref{ugProblemLimitsPage}
+\end{itemize}
+\index{pages!ugIntroCalcLimitsPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroCalcLimitsPage}
+\index{ugIntroCalcLimitsPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroCalcLimitsPage}{1.10. Limits}
+\beginscroll
+%
+
+Axiom's \axiomFun{limit} function is usually used to
+evaluate limits of quotients where the numerator and denominator
+both tend to zero or both tend to infinity.
+To find the limit of an expression \axiom{f} as a real variable
+\axiom{x} tends to a limit value \axiom{a}, enter \axiom{limit(f, x=a)}.
+Use \axiomFun{complexLimit} if the variable is complex.
+Additional information and examples of limits are in
+\downlink{``\ugProblemLimitsTitle''}{ugProblemLimitsPage} 
+in Section \ugProblemLimitsNumber\ignore{ugProblemLimits}.
+
+\xtc{
+You can take limits of functions with parameters.
+}{
+\spadpaste{g := csc(a*x) / csch(b*x) \bound{g}}
+}
+\xtc{
+As you can see, the limit is expressed in terms of the parameters.
+}{
+\spadpaste{limit(g,x=0) \free{g}}
+}
+%
+\xtc{
+A variable may also approach plus or minus infinity:
+}{
+\spadpaste{h := (1 + k/x)**x \bound{h}}
+}
+\xtc{
+\texht{Use \axiom{\%plusInfinity} and \axiom{\%minusInfinity} to
+denote $\infty$ and $-\infty$.}{}
+}{
+\spadpaste{limit(h,x=\%plusInfinity) \free{h}}
+}
+\xtc{
+A function can be defined on both sides of a particular value, but
+may tend to different limits as its variable approaches that value from the
+left and from the right.
+}{
+\spadpaste{limit(sqrt(y**2)/y,y = 0)}
+}
+\xtc{
+As \axiom{x} approaches \axiom{0} along the real axis, \axiom{exp(-1/x**2)}
+tends to \axiom{0}.
+}{
+\spadpaste{limit(exp(-1/x**2),x = 0)}
+}
+\xtc{
+However, if \axiom{x} is allowed to approach \axiom{0} along any path in the
+complex plane, the limiting value of \axiom{exp(-1/x**2)} depends on the
+path taken because the function has an essential singularity at \axiom{x=0}.
+This is reflected in the error message returned by the function.
+}{
+\spadpaste{complexLimit(exp(-1/x**2),x = 0)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroSeriesTitle}{Series}
+\newcommand{\ugIntroSeriesNumber}{1.11.}
+
+@
+\section{Series}
+\label{ugIntroSeriesPage}
+\begin{itemize}
+\item ugProblemSeriesPage \ref{ugProblemSeriesPage} on
+page~\pageref{ugProblemSeriesPage}
+\end{itemize}
+\index{pages!ugIntroSeriesPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroSeriesPage}
+\index{ugIntroSeriesPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroSeriesPage}{1.11. Series}
+\beginscroll
+%
+
+Axiom also provides power series.
+By default, Axiom tries to compute and display the first ten elements
+of a series.
+Use \spadsys{)set streams calculate} to change the default value
+to something else.
+For the purposes of this book, we have used this system command to display
+fewer than ten terms.
+For more information about working with series, see
+\downlink{``\ugProblemSeriesTitle''}{ugProblemSeriesPage} 
+in Section \ugProblemSeriesNumber\ignore{ugProblemSeries}.
+
+\xtc{
+You can convert a functional expression to a power series by using the
+operation \axiomFun{series}.
+In this example,
+\axiom{sin(a*x)} is expanded in powers of \axiom{(x - 0)},
+that is, in powers of \axiom{x}.
+}{
+\spadpaste{series(sin(a*x),x = 0)}
+}
+\xtc{
+This expression expands
+\axiom{sin(a*x)} in powers of \axiom{(x - \%pi/4)}.
+}{
+\spadpaste{series(sin(a*x),x = \%pi/4)}
+}
+\xtc{
+Axiom provides
+{\it Puiseux series:}
+series with rational number exponents.
+The first argument to \axiomFun{series} is an in-place function that
+computes the \eth{\axiom{n}} coefficient.
+(Recall that
+the \axiomSyntax{+->} is an infix operator meaning ``maps to.'')
+}{
+\spadpaste{series(n +-> (-1)**((3*n - 4)/6)/factorial(n - 1/3),x = 0,4/3..,2)}
+}
+\xtc{
+Once you have created a power series, you can perform arithmetic operations
+on that series.
+We compute the Taylor expansion of \axiom{1/(1-x)}.
+}{
+\spadpaste{f := series(1/(1-x),x = 0) \bound{f}}
+}
+\xtc{
+Compute the square of the series.
+}{
+\spadpaste{f ** 2 \free{f}}
+}
+\xtc{
+The usual elementary functions
+(\axiomFun{log}, \axiomFun{exp}, trigonometric functions, and so on)
+are defined for power series.
+}{
+\spadpaste{f := series(1/(1-x),x = 0) \bound{f1}}
+}
+\xtc{
+}{
+\spadpaste{g := log(f) \free{f1}\bound{g}}
+}
+\xtc{
+}{
+\spadpaste{exp(g) \free{g}}
+}
+\xtc{
+Here is a way to obtain numerical approximations of
+\axiom{e} from the Taylor series expansion of \axiom{exp(x)}.
+First create the desired Taylor expansion.
+}{
+\spadpaste{f := taylor(exp(x)) \bound{f2}}
+}
+\xtc{
+Evaluate the series at the value \axiom{1.0}.
+As you see, you get a sequence of partial sums.
+}{
+\spadpaste{eval(f,1.0) \free{f2}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroCalcDerivTitle}{Derivatives}
+\newcommand{\ugIntroCalcDerivNumber}{1.12.}
+
+@
+\section{Derivatives}
+\label{ugIntroCalcDerivPage}
+\index{pages!ugIntroCalcDerivPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroCalcDerivPage}
+\index{ugIntroCalcDerivPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroCalcDerivPage}{1.12. Derivatives}
+\beginscroll
+%
+Use the Axiom function \axiomFun{D} to differentiate an
+expression.
+
+\texht{\vskip 2pc}{}
+\xtc{
+To find the derivative of an expression \axiom{f} with respect to a
+variable \axiom{x}, enter \axiom{D(f, x)}.
+}{
+\spadpaste{f := exp exp x \bound{f}}
+}
+\xtc{
+}{
+\spadpaste{D(f, x) \free{f}}
+}
+\xtc{
+An optional third argument \axiom{n} in \axiomFun{D} asks
+Axiom for the \eth{\axiom{n}} derivative of \axiom{f}.
+This finds the fourth derivative of \axiom{f} with respect to \axiom{x}.
+}{
+\spadpaste{D(f, x, 4) \free{f}}
+}
+\xtc{
+You can also compute partial derivatives by specifying the order of
+differentiation.
+}{
+\spadpaste{g := sin(x**2 + y) \bound{g}}
+}
+\xtc{
+}{
+\spadpaste{D(g, y) \free{g}}
+}
+\xtc{
+}{
+\spadpaste{D(g, [y, y, x, x]) \free{g}}
+}
+
+Axiom can manipulate the derivatives (partial and iterated) of
+expressions involving formal operators.
+All the dependencies must be explicit.
+\xtc{
+This returns \axiom{0} since \axiom{F} (so far)
+does not explicitly depend on \axiom{x}.
+}{
+\spadpaste{D(F,x)}
+}
+Suppose that we have \axiom{F} a function of \axiom{x},
+\axiom{y}, and \axiom{z}, where \axiom{x} and \axiom{y} are themselves
+functions of \axiom{z}.
+\xtc{
+Start by declaring that \axiom{F}, \axiom{x}, and \axiom{y}
+are operators.
+}{
+\spadpaste{F := operator 'F; x := operator 'x; y := operator 'y\bound{F x y}}
+}
+\xtc{
+You can use \axiom{F}, \axiom{x}, and \axiom{y} in expressions.
+}{
+\spadpaste{a := F(x z, y z, z**2) + x y(z+1) \bound{a}\free{F}\free{x}\free{y}}
+}
+\xtc{
+Differentiate formally with respect to \axiom{z}.
+The formal derivatives appearing in \axiom{dadz} are not just formal symbols,
+but do represent the derivatives of \axiom{x}, \axiom{y}, and \axiom{F}.
+}{
+\spadpaste{dadz := D(a, z)\bound{da}\free{a}}
+}
+\xtc{
+You can evaluate the above for particular functional
+values of \axiom{F}, \axiom{x}, and \axiom{y}.
+If \axiom{x(z)} is \axiom{exp(z)} and \axiom{y(z)} is \axiom{log(z+1)}, then
+this evaluates \axiom{dadz}.
+}{
+\spadpaste{eval(eval(dadz, 'x, z +-> exp z), 'y, z +-> log(z+1))\free{da}}
+}
+\xtc{
+You obtain the same result by first evaluating \axiom{a} and
+then differentiating.
+}{
+\spadpaste{eval(eval(a, 'x, z +-> exp z), 'y, z +-> log(z+1)) \free{a}\bound{eva}}
+}
+\xtc{
+}{
+\spadpaste{D(\%, z)\free{eva}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroIntegrateTitle}{Integration}
+\newcommand{\ugIntroIntegrateNumber}{1.13.}
+
+@
+\section{Integration}
+\label{ugIntroIntegratePage}
+\begin{itemize}
+\item ugProblemIntegrationPage \ref{ugProblemIntegrationPage} on
+page~\pageref{ugProblemIntegrationPage}
+\end{itemize}
+\index{pages!ugIntroIntegratePage!ug01.ht}
+\index{ug01.ht!pages!ugIntroIntegratePage}
+\index{ugIntroIntegratePage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroIntegratePage}{1.13. Integration}
+\beginscroll
+%
+
+Axiom has extensive library facilities for integration.
+
+The first example is the integration of a fraction with
+denominator that factors into a quadratic and a quartic
+irreducible polynomial.
+The usual partial fraction approach used by most other computer
+algebra systems either fails or introduces expensive unneeded
+algebraic numbers.
+
+\xtc{
+We use a factorization-free algorithm.
+}{
+\spadpaste{integrate((x**2+2*x+1)/((x+1)**6+1),x)}
+}
+
+When real parameters are present, the form of the integral can depend on
+the signs of some expressions.
+
+\xtc{
+Rather than query the user or make sign assumptions, Axiom returns
+all possible answers.
+}{
+\spadpaste{integrate(1/(x**2 + a),x)}
+}
+
+The \axiomFun{integrate} operation generally assumes that all
+parameters are real.
+The only exception is when the integrand has complex valued
+quantities.
+
+\xtc{
+If the parameter is complex instead of real, then the notion of sign is
+undefined and there is a unique answer.
+You can request this answer by ``prepending'' the word ``complex'' to the
+command name:
+}{
+\spadpaste{complexIntegrate(1/(x**2 + a),x)}
+}
+
+The following two examples illustrate the limitations of
+table-based approaches.
+The two integrands are very similar, but the answer to one of them
+requires the addition of two new algebraic numbers.
+
+\xtc{
+This one is the easy one.
+The next one looks very similar
+but the answer is much more complicated.
+}{
+\spadpaste{integrate(x**3 / (a+b*x)**(1/3),x)}
+}
+\xtc{
+Only an algorithmic approach
+is guaranteed to find what new constants must be added in order to
+find a solution.
+}{
+\spadpaste{integrate(1 / (x**3 * (a+b*x)**(1/3)),x)}
+}
+
+Some computer algebra systems use heuristics or table-driven
+approaches to integration.
+When these systems cannot determine the answer to an integration
+problem, they reply ``I don't know.'' Axiom uses a
+algorithm for integration.
+that conclusively proves that an integral cannot be expressed in
+terms of elementary functions.
+
+\xtc{
+When Axiom returns an integral sign, it has proved
+that no answer exists as an elementary function.
+}{
+\spadpaste{integrate(log(1 + sqrt(a*x + b)) / x,x)}
+}
+Axiom can handle complicated mixed functions much beyond what you
+can find in tables.
+\xtc{
+Whenever possible, Axiom tries to express the answer using the functions
+present in the integrand.
+}{
+\spadpaste{integrate((sinh(1+sqrt(x+b))+2*sqrt(x+b)) / (sqrt(x+b) * (x + cosh(1+sqrt(x + b)))), x)}
+}
+\xtc{
+A strong structure-checking algorithm in Axiom finds hidden algebraic
+relationships between functions.
+}{
+\spadpaste{integrate(tan(atan(x)/3),x)}
+}
+\noindent
+%%--> Bob---> please make these formulas in this section smaller.
+The discovery of this algebraic relationship is necessary for correct
+integration of this function.
+Here are the details:
+\indent{4}
+\beginitems
+\item[1. ] 
+If \texht{$x=\tan t$}{\axiom{x=tan(t)}} and
+\texht{$g=\tan (t/3)$}{\axiom{g=tan(t/3)}} then the following
+algebraic relation is true:
+\texht{$${g^3-3xg^2-3g+x=0}$$}{\centerline{\axiom{g**3 - 3*x*g**2 - 3*g + x = 0}}}
+\item[2. ] 
+Integrate \axiom{g} using this algebraic relation; this produces:
+\texht{$${%
+{(24g^2 - 8)\log(3g^2 - 1) + (81x^2 + 24)g^2 + 72xg - 27x^2 - 16}
+\over{54g^2 - 18}}$$}{\centerline{\axiom{(24g**2 - 8)log(3g**2 - 1) +
+(81x**2 + 24)g**2 + 72xg - 27x**2 - 16/ (54g**2 - 18)}}}
+\item[3. ] 
+Rationalize the denominator, producing:
+\texht{\narrowDisplay{{8\log(3g^2-1) - 3g^2 + 18xg + 16} \over
+{18}}}{\centerline{\axiom{(8*log(3*g**2-1) - 3*g**2 + 18*x*g + 16)/18}}}
+Replace \axiom{g} by the initial definition
+\texht{$g = \tan(\arctan(x)/3)$}{\axiom{g = tan(arctan(x)/3)}}
+to produce the final result.
+\enditems
+\indent{0}
+
+\xtc{
+This is an example of a mixed function where
+the algebraic layer is over the transcendental one.
+}{
+\spadpaste{integrate((x + 1) / (x*(x + log x) ** (3/2)), x)}
+}
+\xtc{
+While incomplete for non-elementary functions, Axiom can
+handle some of them.
+}{
+\spadpaste{integrate(exp(-x**2) * erf(x) / (erf(x)**3 - erf(x)**2 - erf(x) + 1),x)}
+}
+
+More examples of Axiom's integration capabilities are discussed in
+\downlink{``\ugProblemIntegrationTitle''}{ugProblemIntegrationPage} 
+in Section \ugProblemIntegrationNumber\ignore{ugProblemIntegration}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroDiffEqnsTitle}{Differential Equations}
+\newcommand{\ugIntroDiffEqnsNumber}{1.14.}
+
+@
+\section{Differential Equations}
+\label{ugIntroDiffEqnsPage}
+\index{pages!ugIntroDiffEqnsPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroDiffEqnsPage}
+\index{ugIntroDiffEqnsPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroDiffEqnsPage}{1.14. Differential Equations}
+\beginscroll
+%
+The general approach used in integration also carries over to the
+solution of linear differential equations.
+
+\labelSpace{2pc}
+\xtc{
+Let's solve some differential equations.
+Let \axiom{y} be the unknown function in terms of \axiom{x}.
+}{
+\spadpaste{y := operator 'y \bound{y}}
+}
+\xtc{
+Here we solve a third order equation with polynomial coefficients.
+}{
+\spadpaste{deq := x**3 * D(y x, x, 3) + x**2 * D(y x, x, 2) - 2 * x * D(y x, x) + 2 * y x = 2 * x**4 \bound{e3}\free{y}}
+}
+\xtc{
+}{
+\spadpaste{solve(deq, y, x) \free{e3}\free{y}}
+}
+\xtc{
+Here we find all the algebraic function solutions of the equation.
+}{
+\spadpaste{deq := (x**2 + 1) * D(y x, x, 2) + 3 * x * D(y x, x) + y x = 0 \bound{e5}\free{y}}
+}
+\xtc{
+}{
+\spadpaste{solve(deq, y, x) \free{e5}\free{y}}
+}
+
+Coefficients of differential equations can come from arbitrary
+constant fields.
+For example, coefficients can contain algebraic numbers.
+
+\xtc{
+This example has solutions
+whose logarithmic derivative is an algebraic function of
+degree two.
+}{
+\spadpaste{eq := 2*x**3 * D(y x,x,2) + 3*x**2 * D(y x,x) - 2 * y x\bound{eq}\free{y}}
+}
+\xtc{
+}{
+\spadpaste{solve(eq,y,x).basis\free{eq}}
+}
+
+\xtc{
+Here's another differential equation to solve.
+}{
+\spadpaste{deq := D(y x, x) = y(x) / (x + y(x) * log y x) \bound{deqi}\free{y}}
+}
+\xtc{
+}{
+\spadpaste{solve(deq, y, x) \free{deqi y}}
+}
+
+Rather than attempting to get a closed form solution of
+a differential equation, you instead might want to find an
+approximate solution in the form of a series.
+
+\xtc{
+Let's solve a system of nonlinear first order equations and get a
+solution in power series.
+Tell Axiom that \axiom{x} is also an operator.
+}{
+\spadpaste{x := operator 'x\bound{x}}
+}
+\xtc{
+Here are the two equations forming our system.
+}{
+\spadpaste{eq1 := D(x(t), t) = 1 + x(t)**2\free{x}\free{y}\bound{eq1}}
+}
+\xtc{
+}{
+\spadpaste{eq2 := D(y(t), t) = x(t) * y(t)\free{x}\free{y}\bound{eq2}}
+}
+\xtc{
+We can solve the system around \axiom{t = 0} with the initial conditions
+\axiom{x(0) = 0} and \axiom{y(0) = 1}.
+Notice that since we give the unknowns in the
+order \axiom{[x, y]}, the answer is a list of two series in the order
+\axiom{[series for x(t), series for y(t)]}.
+}{
+\spadpaste{seriesSolve([eq2, eq1], [x, y], t = 0, [y(0) = 1, x(0) = 0])\free{x}\free{y}\free{eq1}\free{eq2}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroSolutionTitle}{Solution of Equations}
+\newcommand{\ugIntroSolutionNumber}{1.15.}
+
+@
+\section{Solution of Equations}
+\label{ugIntroSolutionPage}
+\index{pages!ugIntroSolutionPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroSolutionPage}
+\index{ugIntroSolutionPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroSolutionPage}{1.15. Solution of Equations}
+\beginscroll
+%
+
+Axiom also has state-of-the-art algorithms for the solution
+of systems of polynomial equations.
+When the number of equations and unknowns is the same, and you
+have no symbolic coefficients, you can use \spadfun{solve} for
+real roots and \spadfun{complexSolve} for complex roots.
+In each case, you tell Axiom how accurate you want your
+result to be.
+All operations in the \spadfun{solve} family return answers in
+the form of a list of solution sets, where each solution set is a
+list of equations.
+
+\xtc{
+A system of two equations involving a symbolic
+parameter \axiom{t}.
+}{
+\spadpaste{S(t) == [x**2-2*y**2 - t,x*y-y-5*x + 5]\bound{S1}}
+}
+\xtc{
+Find the real roots of \spad{S(19)} with
+rational arithmetic, correct to within \smath{1/10^{20}}.
+}{
+\spadpaste{solve(S(19),1/10**20)\free{S1}}
+}
+\xtc{
+Find the complex roots of \spad{S(19)} with floating
+point coefficients to \spad{20} digits accuracy in the mantissa.
+}{
+\spadpaste{complexSolve(S(19),10.e-20)\free{S1}}
+}
+\xtc{
+If a system of equations has symbolic coefficients and you want
+a solution in radicals, try \spadfun{radicalSolve}.
+}{
+\spadpaste{radicalSolve(S(a),[x,y])\free{S1}}
+}
+For systems of equations with symbolic coefficients, you can
+apply \spadfun{solve}, listing the variables that you want
+Axiom to solve for.
+For polynomial equations, a solution cannot usually be expressed
+solely in terms of the other variables.
+Instead, the solution is presented as a ``triangular'' system of
+equations, where each polynomial has coefficients involving
+only the succeeding variables. This is analogous to converting  a linear system
+of equations to ``triangular form''.
+\xtc{
+A system of three equations in five variables.
+}{
+\spadpaste{eqns := [x**2 - y + z,x**2*z + x**4 - b*y, y**2 *z - a - b*x]\bound{e}}
+}
+\xtc{
+Solve the system for unknowns \smath{[x,y,z]},
+reducing the solution to triangular form.
+}{
+\spadpaste{solve(eqns,[x,y,z])\free{e}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug01.ht>>=
+\newcommand{\ugIntroSysCmmandsTitle}{System Commands}
+\newcommand{\ugIntroSysCmmandsNumber}{1.16.}
+
+@
+\section{System Commands}
+\label{ugIntroSysCmmandsPage}
+\begin{itemize}
+\item ugSysCmdPage \ref{ugSysCmdPage} on
+page~\pageref{ugSysCmdPage}
+\end{itemize}
+\index{pages!ugIntroSysCmmandsPage!ug01.ht}
+\index{ug01.ht!pages!ugIntroSysCmmandsPage}
+\index{ugIntroSysCmmandsPage!ug01.ht!pages}
+<<ug01.ht>>=
+\begin{page}{ugIntroSysCmmandsPage}{1.16. System Commands}
+\beginscroll
+%
+
+We conclude our tour of Axiom with a brief discussion
+of \spadgloss{system commands}.
+System commands are special statements that start with a
+closing parenthesis (\axiomSyntax{)}). They are used to control or
+display your Axiom environment, start the \HyperName{}
+system, issue operating system commands and leave Axiom.
+For example, \spadsys{)system} is used
+to issue commands to the operating system from Axiom.
+Here is a brief description of some of these commands.
+For more information on specific commands, see
+\downlink{``\ugSysCmdTitle''}{ugSysCmdPage} 
+in Appendix \ugSysCmdNumber\ignore{ugSysCmd}.
+
+Perhaps the most important user command is the \spadsys{)clear all}
+command that initializes your environment.
+Every section and subsection in this book has an invisible
+\spadsys{)clear all} that is read prior to the examples given in
+the section.
+\spadsys{)clear all} gives you a fresh, empty environment with no
+user variables defined and the step number reset to \axiom{1}.
+The \spadsys{)clear} command can also be used to selectively clear
+values and properties of system variables.
+
+Another useful system command is \spadsys{)read}.
+A preferred way to develop an application in Axiom is to put
+your interactive commands into a file, say {\bf my.input} file.
+To get Axiom to read this file, you use the system command
+\spadsys{)read my.input}.
+If you need to make changes to your approach or definitions, go
+into your favorite editor, change {\bf my.input}, then
+\spadsys{)read my.input} again.
+
+Other system commands include: \spadsys{)history}, to display
+previous input and/or output lines; \spadsys{)display}, to display
+properties and values of workspace variables; and \spadsys{)what}.
+
+\xtc{
+Issue \spadsys{)what} to get a list of Axiom objects that
+contain a given substring in their name.
+}{
+\spadpaste{)what operations integrate}
+}
+
+%\head{subsection}{Undo}{ugIntroUndo}
+
+A useful system command is \spadcmd{)undo}.
+Sometimes while computing interactively with Axiom, you make
+a mistake and enter an incorrect definition or assignment.
+Or perhaps you
+need to try one of several alternative approaches, one after
+another, to find the best way to approach an application.
+For this, you will find the \spadgloss{undo} facility of
+Axiom helpful.
+
+System command \spadsys{)undo n} means ``undo back to step \axiom{n}''; it
+restores the values of user variables to those that existed
+immediately after input expression \axiom{n} was evaluated.
+Similarly, \spadsys{)undo -n} undoes changes caused by the last
+\axiom{n} input expressions.
+Once you have done an \spadsys{)undo},
+you can continue on from there, or make a change and
+{\bf redo} all your input expressions from the point
+of the \spadsys{)undo} forward.
+The \spadsys{)undo} is completely general: it changes the environment
+like any user expression.
+Thus you can \spadsys{)undo} any previous undo.
+
+Here is a sample dialogue between user and Axiom.
+\xtc{
+``Let me define
+two mutually dependent functions \axiom{f} and \axiom{g} piece-wise.''
+}{
+\spadpaste{f(0) == 1; g(0) == 1\bound{u1}}
+}
+\xtc{
+``Here is the general term for \axiom{f}.''
+}{
+\spadpaste{f(n) == e/2*f(n-1) - x*g(n-1)\bound{u2}\free{u1}}
+}
+\xtc{
+``And here is the general term for \axiom{g}.''
+}{
+\spadpaste{g(n) == -x*f(n-1) + d/3*g(n-1)\bound{u3}\free{u2}}
+}
+\xtc{
+``What is value of \axiom{f(3)}?''
+}{
+\spadpaste{f(3)\bound{u4}\free{u3}}
+}
+\noOutputXtc{
+``Hmm, I think I want to define \axiom{f} differently.
+Undo to the environment right after I defined \axiom{f}.''
+}{
+\spadpaste{)undo 2\bound{u5}\free{u4}}
+}
+\xtc{
+``Here is how I think I want \axiom{f} to be defined instead.''
+}{
+\spadpaste{f(n) == d/3*f(n-1) - x*g(n-1)\bound{u6}\free{u5}}
+}
+\noOutputXtc{
+Redo the computation from expression \axiom{3} forward.
+}{
+\spadpaste{)undo )redo\bound{u7}\free{u6}}
+}
+\noOutputXtc{
+``I want my old definition of
+\axiom{f} after all. Undo the undo and restore
+the environment to that immediately after \axiom{(4)}.''
+}{
+\spadpaste{)undo 4\bound{u8}\free{u7}}
+}
+\xtc{
+``Check that the value of \axiom{f(3)} is restored.''
+}{
+\spadpaste{f(3)\bound{u9}\free{u8}}
+}
+
+After you have gone off on several tangents, then backtracked to
+previous points in your conversation using \spadsys{)undo}, you
+might want to save all the ``correct'' input commands you issued,
+disregarding those undone.
+The system command \spadsys{)history )write mynew.input} writes a
+clean straight-line program onto the file {\bf mynew.input} on
+your disk.
+
+This concludes your tour of Axiom.
+To disembark, issue the system command \spadsys{)quit} to leave Axiom
+and return to the operating system.
+\endscroll
+\autobuttons
+\end{page}
+%
+@
+\chapter{Users Guide Chapter 2 (ug02.ht)}
+<<ug02.ht>>=
+\newcommand{\ugTypesTitle}{Using Types and Modes}
+\newcommand{\ugTypesNumber}{2.}
+
+@
+\section{Using Types and Modes}
+\label{ugTypesPage}
+\begin{itemize}
+\item ugTypesBasicPage \ref{ugTypesBasicPage} on
+page~\pageref{ugTypesBasicPage}
+\item ugTypesWritingPage \ref{ugTypesWritingPage} on
+page~\pageref{ugTypesWritingPage}
+\item ugTypesDeclarePage \ref{ugTypesDeclarePage} on
+page~\pageref{ugTypesDeclarePage}
+\item ugTypesRecordsPage \ref{ugTypesRecordsPage} on
+page~\pageref{ugTypesRecordsPage}
+\item ugTypesUnionsPage \ref{ugTypesUnionsPage} on
+page~\pageref{ugTypesUnionsPage}
+\item ugTypesAnyNonePage \ref{ugTypesAnyNonePage} on
+page~\pageref{ugTypesAnyNonePage}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~\pageref{ugTypesConvertPage}
+\item ugTypesSubdomainsPage \ref{ugTypesSubdomainsPage} on
+page~\pageref{ugTypesSubdomainsPage}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\item ugTypesResolvePage \ref{ugTypesResolvePage} on
+page~\pageref{ugTypesResolvePage}
+\item ugTypesExposePage \ref{ugTypesExposePage} on
+page~\pageref{ugTypesExposePage}
+\item ugAvailSnoopPage \ref{ugAvailSnoopPage} on
+page~\pageref{ugAvailSnoopPage}
+\end{itemize}
+\index{pages!ugTypesPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesPage}
+\index{ugTypesPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesPage}{2. Using Types and Modes}
+\beginscroll
+
+In this chapter we look at the key notion of \spadgloss{type} and its
+generalization \spadgloss{mode}.
+We show that every Axiom object has a type that
+determines what you can do with the object.
+In particular, we explain how to use types to call specific functions
+from particular parts of the library and how types and modes can be used
+to create new objects from old.
+We also look at \pspadtype{Record} and \pspadtype{Union} types and
+the special type \axiomType{Any}.
+Finally, we give you an idea of how Axiom manipulates types and
+modes internally to resolve ambiguities.
+
+\beginmenu
+    \menudownlink{{2.1. The Basic Idea}}{ugTypesBasicPage}
+    \menudownlink{{2.2. Writing Types and Modes}}{ugTypesWritingPage}
+    \menudownlink{{2.3. Declarations}}{ugTypesDeclarePage}
+    \menudownlink{{2.4. Records}}{ugTypesRecordsPage}
+    \menudownlink{{2.5. Unions}}{ugTypesUnionsPage}
+    \menudownlink{{2.6. The ``Any'' Domain}}{ugTypesAnyNonePage}
+    \menudownlink{{2.7. Conversion}}{ugTypesConvertPage}
+    \menudownlink{{2.8. Subdomains Again}}{ugTypesSubdomainsPage}
+    \menudownlink{{2.9. Package Calling and Target Types}}{ugTypesPkgCallPage}
+    \menudownlink{{2.10. Resolving Types}}{ugTypesResolvePage}
+    \menudownlink{{2.11. Exposing Domains and Packages}}{ugTypesExposePage}
+    \menudownlink{{2.12. Commands for Snooping}}{ugAvailSnoopPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesBasicTitle}{The Basic Idea}
+\newcommand{\ugTypesBasicNumber}{2.1.}
+
+@
+\section{The Basic Idea}
+\label{ugTypesBasicPage}
+\begin{itemize}
+\item ugTypesBasicDomainConsPage \ref{ugTypesBasicDomainConsPage} on
+page~\pageref{ugTypesBasicDomainConsPage}
+\end{itemize}
+\index{pages!ugTypesBasicPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesBasicPage}
+\index{ugTypesBasicPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesBasicPage}{2.1. The Basic Idea}
+\beginscroll
+
+The Axiom world deals with many kinds of objects.
+There are mathematical objects such as numbers and polynomials,
+data structure objects such as lists and arrays, and graphics
+objects such as points and graphic images.
+Functions are objects too.
+
+Axiom organizes objects using the notion of \spadglossSee{domain of
+computation}{domain}, or simply \spadgloss{domain}.
+Each domain denotes a class of objects.
+The class of objects it denotes is usually given by the name of the
+domain: \axiomType{Integer} for the integers, \axiomType{Float} for
+floating-point numbers, and so on.
+The convention is that the first letter of a domain name is capitalized.
+Similarly, the domain \axiomType{Polynomial(Integer)} denotes ``polynomials
+with integer coefficients.''
+Also, \axiomType{Matrix(Float)} denotes ``matrices with floating-point
+entries.''
+
+Every basic Axiom object belongs to a unique domain.
+The integer \axiom{3} belongs to the domain \axiomType{Integer} and
+the polynomial \axiom{x + 3} belongs to the domain
+\axiomType{Polynomial(Integer)}.
+The domain of an object is also called its \spadgloss{type}.
+Thus we speak of ``the type \axiomType{Integer}''
+and ``the type \axiomType{Polynomial(Integer)}.''
+
+\xtc{
+After an Axiom computation, the type is displayed toward the
+right-hand side of the page (or screen).
+}{
+\spadpaste{-3}
+}
+\xtc{
+Here we create a rational number but it looks like the last result.
+The type however tells you it is different.
+You cannot identify the type of an object by how Axiom
+displays the object.
+}{
+\spadpaste{-3/1}
+}
+\xtc{
+When a computation produces a result of a simpler type, Axiom leaves
+the type unsimplified.
+Thus no information is lost.
+}{
+\spadpaste{x + 3 - x \bound{three}}
+}
+\xtc{
+This seldom matters since Axiom retracts the answer to the
+simpler type if it is necessary.
+}{
+\spadpaste{factorial(\%) \free{three}}
+}
+\xtc{
+When you issue a positive number, the type \axiomType{PositiveInteger} is
+printed.
+Surely, \axiom{3} also has type \axiomType{Integer}!
+The curious reader may now have two questions.
+First, is the type of an object not unique?
+Second, how is \axiomType{PositiveInteger} related to \axiomType{Integer}?
+Read on!
+}{
+\spadpaste{3}
+}
+
+Any domain can be refined to a \spadgloss{subdomain} by a membership
+\spadgloss{predicate}.\footnote{A predicate is a function that,
+when applied to an object of the domain, returns either
+\axiom{true} or \axiom{false}.}
+For example, the domain \axiomType{Integer} can be refined to the
+subdomain \axiomType{PositiveInteger}, the set of integers
+\axiom{x} such that \axiom{x > 0}, by giving the Axiom
+predicate \axiom{x +-> x > 0}.
+Similarly, Axiom can define subdomains such as ``the
+subdomain of diagonal matrices,'' ``the subdomain of lists of length
+two,'' ``the subdomain of monic irreducible polynomials in
+\axiom{x},'' and so on.
+Trivially, any domain is a subdomain of itself.
+
+While an object belongs to a unique domain, it can belong to any
+number of subdomains.
+Any subdomain of the domain of an object can be used as the
+{\it type} of that object.
+The type of \axiom{3} is indeed both \axiomType{Integer} and
+\axiomType{PositiveInteger} as well as any other subdomain of
+integer whose predicate is satisfied, such as ``the prime
+integers,'' ``the odd positive integers between 3 and 17,'' and so
+on.
+
+\beginmenu
+    \menudownlink{{2.1.1. Domain Constructors}}{ugTypesBasicDomainConsPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesBasicDomainConsTitle}{Domain Constructors}
+\newcommand{\ugTypesBasicDomainConsNumber}{2.1.1.}
+
+@
+\section{Domain Constructors}
+\label{ugTypesBasicDomainConsPage}
+\begin{itemize}
+\item ugCategoriesPage \ref{ugCategoriesPage} on
+page~\pageref{ugCategoriesPage}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~\pageref{ugTypesConvertPage}
+\end{itemize}
+\index{pages!ugTypesBasicDomainConsPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesBasicDomainConsPage}
+\index{ugTypesBasicDomainConsPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesBasicDomainConsPage}{2.1.1. Domain Constructors}
+\beginscroll
+
+In Axiom, domains are objects.
+You can create them, pass them to functions, and, as we'll see later, test
+them for certain properties.
+
+In Axiom, you ask for a value of a function by applying its name
+to a set of arguments.
+
+\xtc{
+To ask for ``the factorial of 7'' you enter this expression to
+Axiom.
+This applies the function \axiom{factorial} to the value \axiom{7}
+to compute the result.
+}{
+\spadpaste{factorial(7)}
+}
+\xtc{
+Enter the type \axiomType{Polynomial (Integer)} as an expression to
+Axiom.
+This looks much like a function call as well.
+It is!
+The result is appropriately stated to be of type
+\axiomType{Domain}, which
+according to our usual convention, denotes the class of all domains.
+}{
+\spadpaste{Polynomial(Integer)}
+}
+
+The most basic operation involving domains is that of building a new
+domain from a given one.
+To create the domain of ``polynomials over the integers,'' Axiom
+applies the function \axiomType{Polynomial} to the domain
+\axiomType{Integer}.
+A function like \axiomType{Polynomial} is called a \spadgloss{domain
+constructor} or,
+more simply, a
+\spadgloss{constructor}.
+A domain constructor is a function that creates a domain.
+An argument to a domain constructor can be another domain or, in general,
+an arbitrary kind of object.
+\axiomType{Polynomial} takes a single domain argument while
+\axiomType{SquareMatrix} takes a positive integer as an argument
+to give its dimension and
+a domain argument to give the type of its components.
+
+What kinds of domains can you use as the argument to
+\axiomType{Polynomial} or \axiomType{SquareMatrix} or
+\axiomType{List}?
+Well, the first two are mathematical in nature.
+You want to be able to perform algebraic operations like
+\axiomOp{+} and \axiomOp{*} on polynomials and square matrices,
+and operations such as \axiomFun{determinant} on square matrices.
+So you want to allow polynomials of integers {\it and} polynomials
+of square matrices with complex number coefficients and, in
+general, anything that ``makes sense.'' At the same time, you
+don't want Axiom to be able to build nonsense domains such
+as ``polynomials of strings!''
+
+In contrast to algebraic structures, data structures can hold any
+kind of object.
+Operations on lists such as \axiomFunFrom{insert}{List},
+\axiomFunFrom{delete}{List}, and \axiomFunFrom{concat}{List} just
+manipulate the list itself without changing or operating on its
+elements.
+Thus you can build \axiomType{List} over almost any datatype,
+including itself.
+\xtc{
+Create a complicated algebraic domain.
+}{
+\spadpaste{List (List (Matrix (Polynomial (Complex (Fraction (Integer))))))}
+}
+\xtc{
+Try to create a meaningless domain.
+}{
+\spadpaste{Polynomial(String)}
+}
+Evidently from our last example, Axiom has some mechanism
+that tells what a constructor can use as an argument.
+This brings us to the notion of \spadgloss{category}.
+As domains are objects, they too have a domain.
+The domain of a domain is a category.
+A category is simply a type whose members are domains.
+
+A common algebraic category is \axiomType{Ring}, the class of all domains
+that are ``rings.''
+A ring is an algebraic structure with constants \axiom{0} and \axiom{1} and
+operations \axiomOpFrom{+}{Ring}, \axiomOpFrom{-}{Ring}, and
+\axiomOpFrom{*}{Ring}.
+These operations are assumed ``closed'' with respect to the domain,
+meaning that they take two objects of the domain and produce a result
+object also in the domain.
+The operations are understood to satisfy certain ``axioms,'' certain
+mathematical principles providing the algebraic foundation for rings.
+For example, the {\it additive inverse axiom} for rings states:
+\centerline{{Every element \axiom{x} has an additive inverse \axiom{y} such}}
+\centerline{{that \axiom{x + y = 0}.}}
+The prototypical example of a domain that is a ring is the integers.
+Keep them in mind whenever we mention \axiomType{Ring}.
+
+Many algebraic domain constructors such as \axiomType{Complex},
+\axiomType{Polynomial}, \axiomType{Fraction}, take rings as
+arguments and return rings as values.
+You can use the infix operator ``\axiom{has}''
+\spadkey{has}
+to ask a domain if it belongs to a particular category.
+
+\xtc{
+All numerical types are rings.
+Domain constructor \axiomType{Polynomial} builds ``the ring of polynomials
+over any other ring.''
+}{
+\spadpaste{Polynomial(Integer) has Ring}
+}
+\xtc{
+Constructor \axiomType{List} never produces a ring.
+}{
+\spadpaste{List(Integer) has Ring}
+}
+\xtc{
+The constructor \axiomType{Matrix(R)} builds ``the domain of all matrices
+over the ring \axiom{R}.'' This domain is never a ring since the operations
+\axiomSyntax{+}, \axiomSyntax{-}, and \axiomSyntax{*} on matrices of arbitrary
+shapes are undefined.
+}{
+\spadpaste{Matrix(Integer) has Ring}
+}
+\xtc{
+Thus you can never build polynomials over matrices.
+}{
+\spadpaste{Polynomial(Matrix(Integer))}
+}
+\xtc{
+Use \axiomType{SquareMatrix(n,R)} instead.
+For any positive integer \axiom{n}, it builds ``the ring of \axiom{n} by
+\axiom{n} matrices over \axiom{R}.''
+}{
+\spadpaste{Polynomial(SquareMatrix(7,Complex(Integer)))}
+}
+
+Another common category is \axiomType{Field}, the class of all fields.
+A field is a ring with additional operations.
+For example, a field has commutative multiplication and
+a closed operation \axiomOpFrom{/}{Field} for the
+division of two elements.
+\axiomType{Integer} is not a field since, for example, \axiom{3/2} does not
+have an integer result.
+The prototypical example of a field is the rational numbers, that is, the
+domain \axiomType{Fraction(Integer)}.
+In general, the constructor \axiomType{Fraction} takes a ring as an
+argument and returns a field.\footnote{Actually,
+the argument domain must have some additional
+properties so as to belong to category \axiomType{IntegralDomain}.}
+Other domain constructors, such as \axiomType{Complex}, build fields only if
+their argument domain is a field.
+
+\xtc{
+The complex integers (often called the ``Gaussian integers'') do not form
+a field.
+}{
+\spadpaste{Complex(Integer) has Field}
+}
+\xtc{
+But fractions of complex integers do.
+}{
+\spadpaste{Fraction(Complex(Integer)) has Field}
+}
+\xtc{
+The algebraically equivalent domain of complex rational numbers is a field
+since domain constructor \axiomType{Complex} produces a field whenever its
+argument is a field.
+}{
+\spadpaste{Complex(Fraction(Integer)) has Field}
+}
+
+The most basic category is \axiomType{Type}.
+It denotes the class of all domains and
+subdomains.\footnote{\axiomType{Type} does not denote the class of
+all types.
+The type of all categories is \axiomType{Category}.
+The type of \axiomType{Type} itself is undefined.}
+Domain constructor \axiomType{List} is able to build ``lists of
+elements from domain \axiom{D}'' for arbitrary \axiom{D} simply by
+requiring that \axiom{D} belong to category \axiomType{Type}.
+
+Now, you may ask, what exactly is a category?
+Like domains, categories can be defined in the Axiom language.
+A category is defined by three components:
+%
+\indent{4}
+\beginitems
+\item[1. ] a name (for example, \axiomType{Ring}),
+used to refer to the class of domains that the category represents;
+\item[2. ] a set of operations, used to refer to the operations that
+the domains of this class support
+(for example, \axiomOp{+}, \axiomOp{-}, and \axiomOp{*} for rings); and
+\item[3. ] an optional list of other categories that this category extends.
+\enditems
+\indent{0}
+%
+This last component is a new idea.
+And it is key to the design of Axiom!
+Because categories can extend one another, they form hierarchies.
+\texht{Detailed charts showing the category hierarchies in Axiom are
+displayed in the endpages of this book.
+There you see that all categories are extensions of \axiomType{Type} and that
+\axiomType{Field} is an extension of \axiomType{Ring}.}{}
+
+The operations supported by the domains of a category are called the
+\spadglossSee{exports}{export} of that category because these are the
+operations made available for system-wide use.
+The exports of a domain of a given category are not only the ones
+explicitly mentioned by the category.
+Since a category extends other categories, the operations of these other
+categories---and all categories these other categories extend---are also
+exported by the domains.
+
+For example, polynomial domains belong to \axiomType{PolynomialCategory}.
+This category explicitly mentions some twenty-nine
+operations on polynomials, but it
+extends eleven other categories (including \axiomType{Ring}).
+As a result, the current system has over one hundred operations on polynomials.
+
+If a domain belongs to a category that extends, say, \axiomType{Ring}, it
+is convenient to say that the domain exports \axiomType{Ring}.
+The name of the category thus provides a convenient shorthand for the list
+of operations exported by the category.
+Rather than listing operations such as \axiomOpFrom{+}{Ring} and
+\axiomOpFrom{*}{Ring} of \axiomType{Ring} each time they are needed, the
+definition of a type simply asserts that it exports category
+\axiomType{Ring}.
+
+The category name, however, is more than a shorthand.
+The name \axiomType{Ring}, in fact, implies that the operations exported by
+rings are required to satisfy a set of ``axioms'' associated with the name
+\axiomType{Ring}.\footnote{This subtle
+but important feature distinguishes Axiom from
+other abstract datatype designs.}
+
+Why is it not correct to assume that some type is a ring if it exports all
+of the operations of \axiomType{Ring}?
+Here is why.
+Some languages such as {\bf APL}
+denote the \axiomType{Boolean} constants \axiom{true} and
+\axiom{false} by the integers \axiom{1} and \axiom{0}
+respectively, then use \axiomOp{+} and \axiomOp{*} to denote the
+logical operators \axiomFun{or} and \axiomFun{and}.
+But with these definitions
+\axiomType{Boolean} is not a ring since the additive inverse
+axiom is violated.\footnote{There is no inverse element \axiom{a}
+such that \axiom{1 + a = 0}, or, in the usual terms: \axiom{true
+or a = false}.}
+This alternative definition of \axiomType{Boolean} can be easily
+and correctly implemented in Axiom, since
+\axiomType{Boolean} simply does not assert that it is of category
+\axiomType{Ring}.
+This prevents the system from building meaningless domains such as
+\axiomType{Polynomial(Boolean)} and then wrongfully applying
+algorithms that presume that the ring axioms hold.
+
+
+Enough on categories. To learn more about them, see
+\downlink{``\ugCategoriesTitle''}{ugCategoriesPage} 
+in Chapter \ugCategoriesNumber\ignore{ugCategories}.
+We now return to our discussion of domains.
+
+Domains \spadgloss{export} a set of operations to make them
+available for system-wide use.
+\axiomType{Integer}, for example, exports the operations
+\axiomOpFrom{+}{Integer} and \axiomOpFrom{=}{Integer} given by
+the \spadglossSee{signatures}{signature}
+\axiomOpFrom{+}{Integer}: \spadsig{(Integer,Integer)}{Integer} and
+\axiomOpFrom{=}{Integer}: \spadsig{(Integer,Integer)}{Boolean},
+respectively.
+Each of these operations takes two \axiomType{Integer} arguments.
+The \axiomOpFrom{+}{Integer} operation also returns an \axiomType{Integer} but
+\axiomOpFrom{=}{Integer} returns a \axiomType{Boolean}: \axiom{true} or
+\axiom{false}.
+The operations exported by a domain usually manipulate objects of
+the domain---but not always.
+
+The operations of a domain may actually take as arguments, and return as
+values, objects from any domain.
+For example, \axiomType{Fraction (Integer)} exports the operations
+\axiomOpFrom{/}{Fraction}: \spadsig{(Integer,Integer)}{Fraction(Integer)}
+and \axiomFunFrom{characteristic}{Fraction}:
+\spadsig{}{NonNegativeInteger}.
+
+Suppose all operations of a domain take as arguments and return
+as values, only objects from {\it other} domains.
+This kind of domain
+is what Axiom calls a \spadgloss{package}.
+
+A package does not designate a class of objects at all.
+Rather, a package is just a collection of operations.
+Actually the bulk of the Axiom library of algorithms consists
+of packages.
+The facilities for factorization; integration; solution of linear,
+polynomial, and differential equations; computation of limits; and so
+on, are all defined in packages.
+Domains needed by algorithms can be passed to a package as arguments or
+used by name if they are not ``variable.''
+Packages are useful for defining operations that convert objects of one
+type to another, particularly when these types have different
+parameterizations.
+As an example, the package \axiomType{PolynomialFunction2(R,S)} defines
+operations that convert polynomials over a domain \axiom{R} to polynomials
+over \axiom{S}.
+To convert an object from \axiomType{Polynomial(Integer)} to
+\axiomType{Polynomial(Float)}, Axiom builds the package
+\axiomType{PolynomialFunctions2(Integer,Float)} in order to create the
+required conversion function.
+(This happens ``behind the scenes'' for you: see 
+\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} 
+in Section \ugTypesConvertNumber\ignore{ugTypesConvert}
+for details on how to convert objects.)
+
+Axiom categories, domains and packages and all their contained
+functions are written in the Axiom programming language and have
+been compiled into machine code.
+This is what comprises the Axiom \spadgloss{library}.
+In the rest of this book we show you how to use these domains and
+their functions and how to write your own functions.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesWritingTitle}{Writing Types and Modes}
+\newcommand{\ugTypesWritingNumber}{2.2.}
+
+@
+\section{Writing Types and Modes}
+\label{ugTypesWritingPage}
+\begin{itemize}
+\item ugTypesBasicPage \ref{ugTypesBasicPage} on
+page~\pageref{ugTypesBasicPage}
+\item ugTypesDeclarePage \ref{ugTypesDeclarePage} on
+page~\pageref{ugTypesDeclarePage}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~\pageref{ugTypesConvertPage}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\item ugTypesWritingZeroPage \ref{ugTypesWritingZeroPage} on
+page~\pageref{ugTypesWritingZeroPage}
+\item ugTypesWritingOnePage \ref{ugTypesWritingOnePage} on
+page~\pageref{ugTypesWritingOnePage}
+\item ugTypesWritingMorePage \ref{ugTypesWritingMorePage} on
+page~\pageref{ugTypesWritingMorePage}
+\item ugTypesWritingModesPage \ref{ugTypesWritingModesPage} on
+page~\pageref{ugTypesWritingModesPage}
+\item ugTypesWritingAbbrPage \ref{ugTypesWritingAbbrPage} on
+page~\pageref{ugTypesWritingAbbrPage}
+\end{itemize}
+\index{pages!ugTypesWritingPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesWritingPage}
+\index{ugTypesWritingPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesWritingPage}{2.2. Writing Types and Modes}
+\beginscroll
+%
+
+We have already seen in \texht{the last
+section}{\downlink{``\ugTypesBasicTitle''}{ugTypesBasicPage} 
+in Section \ugTypesBasicNumber\ignore{ugTypesBasic}} several examples of types.
+Most of these examples had either no arguments (for example,
+\axiomType{Integer}) or one argument (for example,
+\axiomType{Polynomial (Integer)}).
+In this section we give details about writing arbitrary types.
+We then define \spadglossSee{modes}{mode} and discuss how to write
+them.
+We conclude the section with a discussion on constructor
+abbreviations.
+
+\xtc{
+When might you need to write a type or mode?
+You need to do so when you declare variables.
+}{
+\spadpaste{a : PositiveInteger}
+}
+\xtc{
+You need to do so when you declare functions
+(\downlink{``\ugTypesDeclareTitle''}{ugTypesDeclarePage} 
+in Section \ugTypesDeclareNumber\ignore{ugTypesDeclare}),
+}{
+\spadpaste{f : Integer -> String}
+}
+\xtc{
+You need to do so when you convert an object from one type to another
+(\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} 
+in Section \ugTypesConvertNumber\ignore{ugTypesConvert}).
+}{
+\spadpaste{factor(2 :: Complex(Integer))}
+}
+\xtc{
+}{
+\spadpaste{(2 = 3)\$Integer}
+}
+\xtc{
+You need to do so when you give computation target type information
+(\downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} 
+in Section \ugTypesPkgCallNumber\ignore{ugTypesPkgCall}).
+}{
+\spadpaste{(2 = 3)@Boolean}
+}
+
+\beginmenu
+    \menudownlink{{2.2.1. Types with No Arguments}}{ugTypesWritingZeroPage}
+    \menudownlink{{2.2.2. Types with One Argument}}{ugTypesWritingOnePage}
+    \menudownlink{{2.2.3. Types with More Than One Argument}}
+{ugTypesWritingMorePage}
+    \menudownlink{{2.2.4. Modes}}{ugTypesWritingModesPage}
+    \menudownlink{{2.2.5. Abbreviations}}{ugTypesWritingAbbrPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesWritingZeroTitle}{Types with No Arguments}
+\newcommand{\ugTypesWritingZeroNumber}{2.2.1.}
+
+@
+\section{Types with No Arguments}
+\label{ugTypesWritingZeroPage}
+\index{pages!ugTypesWritingZeroPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesWritingZeroPage}
+\index{ugTypesWritingZeroPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesWritingZeroPage}{2.2.1. Types with No Arguments}
+\beginscroll
+
+A constructor with no arguments can be written either
+with or without
+trailing opening and closing parentheses (\axiomSyntax{()}).
+\texht{
+\centerline{{\begin{tabular}{ccc}}}
+\centerline{{\axiomType{Boolean()} is the same as \axiomType{Boolean} & \quad &}}
+\centerline{{\axiomType{Integer()} is the same as \axiomType{Integer} }}
+\centerline{{\axiomType{String()} is the same as \axiomType{String} & \quad &}}
+\centerline{{\axiomType{Void()} is the same as \axiomType{Void} }}
+\centerline{{\end{tabular}}}
+}{
+\centerline{{\axiomType{Boolean()} is the same as \axiomType{Boolean} }}
+\centerline{{\axiomType{Integer()} is the same as \axiomType{Integer} }}
+\centerline{{\axiomType{String()} is the same as \axiomType{String} }}
+\centerline{{\axiomType{Void()} is the same as \axiomType{Void} }}
+and so on.
+}
+It is customary to omit the parentheses.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesWritingOneTitle}{Types with One Argument}
+\newcommand{\ugTypesWritingOneNumber}{2.2.2.}
+
+@
+\section{Types with One Argument}
+\label{ugTypesWritingOnePage}
+\begin{itemize}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\end{itemize}
+\index{pages!ugTypesWritingOnePage!ug02.ht}
+\index{ug02.ht!pages!ugTypesWritingOnePage}
+\index{ugTypesWritingOnePage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesWritingOnePage}{2.2.2. Types with One Argument}
+\beginscroll
+
+A constructor with one argument can frequently be
+written with no
+parentheses.
+Types nest from right to left so that \axiomType{Complex Fraction
+Polynomial Integer} is the same as
+\axiomType{Complex (Fraction (Polynomial (Integer)))}.
+You need to use parentheses to force the application of a constructor
+to the correct argument, but you need not use any more than is
+necessary to remove ambiguities.
+
+Here are some guidelines for using parentheses (they are possibly slightly
+more restrictive than they need to be).
+\xtc{
+If the argument is an expression like \axiom{2 + 3}
+then you must enclose the argument in parentheses.
+}{
+\spadpaste{e : PrimeField(2 + 3)}
+}
+%
+\xtc{
+If the type is to be used with package calling
+then you must enclose the argument in parentheses.
+}{
+\spadpaste{content(2)\$Polynomial(Integer)}
+}
+\xtc{
+Alternatively, you can write the type without parentheses
+then enclose the whole type expression with parentheses.
+}{
+\spadpaste{content(2)\$(Polynomial Complex Fraction Integer)}
+}
+\xtc{
+If you supply computation target type information
+(\downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} 
+in Section \ugTypesPkgCallNumber\ignore{ugTypesPkgCall})
+then you should enclose the argument in parentheses.
+}{
+\spadpaste{(2/3)@Fraction(Polynomial(Integer))}
+}
+%
+\xtc{
+If the type itself has parentheses around it and we are
+not in the case of the first example above,
+then the parentheses can usually be omitted.
+}{
+\spadpaste{(2/3)@Fraction(Polynomial Integer)}
+}
+%
+\xtc{
+If the type is used in a declaration and the argument is a single-word
+type, integer or symbol,
+then the parentheses can usually be omitted.
+}{
+\spadpaste{(d,f,g) : Complex Polynomial Integer}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesWritingMoreTitle}{Types with More Than One Argument}
+\newcommand{\ugTypesWritingMoreNumber}{2.2.3.}
+
+@
+\section{Types with More Than One Argument}
+\label{ugTypesWritingMorePage}
+\index{pages!ugTypesWritingMorePage!ug02.ht}
+\index{ug02.ht!pages!ugTypesWritingMorePage}
+\index{ugTypesWritingMorePage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesWritingMorePage}{2.2.3. Types with More Than One Argument}
+\beginscroll
+
+If a constructor
+has more than
+one argument, you must use parentheses.
+Some examples are
+\centerline{{\axiomType{UnivariatePolynomial(x, Float)} }}
+\centerline{{\axiomType{MultivariatePolynomial([z,w,r], Complex Float)} }}
+\centerline{{\axiomType{SquareMatrix(3, Integer)} }}
+\centerline{{\axiomType{FactoredFunctions2(Integer,Fraction Integer)}}}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesWritingModesTitle}{Modes}
+\newcommand{\ugTypesWritingModesNumber}{2.2.4.}
+
+@
+\section{Modes}
+\label{ugTypesWritingModesPage}
+\begin{itemize}
+\item ugTypesDeclarePage \ref{ugTypesDeclarePage} on
+page~\pageref{ugTypesDeclarePage}
+\item ugTypesConvertPage \ref{ugTypesConvertPage} on
+page~\pageref{ugTypesConvertPage}
+\end{itemize}
+\index{pages!ugTypesWritingModesPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesWritingModesPage}
+\index{ugTypesWritingModesPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesWritingModesPage}{2.2.4. Modes}
+\beginscroll
+
+A \spadgloss{mode} is a type that possibly is a
+question mark (\axiomSyntax{?}) or contains one in an argument
+position.
+For example, the following are all modes.
+\texht{
+\centerline{{\begin{tabular}{ccc}}}
+\centerline{{\axiomType{?} & \quad &}}
+\centerline{{\axiomType{Polynomial ?} }}
+\centerline{{\axiomType{Matrix Polynomial ?} & \quad &}}
+\centerline{{\axiomType{SquareMatrix(3,?)} }}
+\centerline{{\axiomType{Integer} & \quad &}}
+\centerline{{\axiomType{OneDimensionalArray(Float)}}}
+\centerline{{\end{tabular}}}
+}{
+\centerline{{\axiomType{?} }}
+\centerline{{\axiomType{Polynomial ?} }}
+\centerline{{\axiomType{Matrix Polynomial ?} }}
+\centerline{{\axiomType{SquareMatrix(3,?)} }}
+\centerline{{\axiomType{Integer} }}
+\centerline{{\axiomType{OneDimensionalArray(Float)}}}
+}
+As is evident from these examples, a mode is a type with a
+part that is not specified (indicated by a question mark).
+Only one \axiomSyntax{?} is allowed per mode and it must appear in the
+most deeply nested argument that is a type. Thus
+\nonLibAxiomType{?(Integer)},
+\nonLibAxiomType{Matrix(? (Polynomial))},
+\nonLibAxiomType{SquareMatrix(?, Integer)} and
+\nonLibAxiomType{SquareMatrix(?, ?)} are all invalid.
+The question mark must take the place of a domain, not data (for example,
+the integer that is the dimension of a square matrix).
+This rules out, for example, the two \axiomType{SquareMatrix}
+expressions.
+
+Modes can be used for declarations
+(\downlink{``\ugTypesDeclareTitle''}{ugTypesDeclarePage} 
+in Section \ugTypesDeclareNumber\ignore{ugTypesDeclare})
+and conversions
+(\downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} 
+in Section \ugTypesConvertNumber\ignore{ugTypesConvert}).
+However, you cannot use a mode for package calling or giving target
+type information.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesWritingAbbrTitle}{Abbreviations}
+\newcommand{\ugTypesWritingAbbrNumber}{2.2.5.}
+
+@
+\section{Abbreviations}
+\label{ugTypesWritingAbbrPage}
+\begin{itemize}
+\item ugSysCmdwhatPage \ref{ugSysCmdwhatPage} on
+page~\pageref{ugSysCmdwhatPage}
+\end{itemize}
+\index{pages!ugTypesWritingAbbrPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesWritingAbbrPage}
+\index{ugTypesWritingAbbrPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesWritingAbbrPage}{2.2.5. Abbreviations}
+\beginscroll
+
+Every constructor has an abbreviation that
+you can freely
+substitute for the constructor name.
+In some cases, the abbreviation is nothing more than the
+capitalized version of the constructor name.
+
+\beginImportant
+Aside from allowing types to be written more concisely,
+abbreviations are used by Axiom to name various system
+files for constructors (such as library filenames, test input
+files and example files).
+Here are some common abbreviations.
+\texht{}{\table{
+{\axiomType{COMPLEX}    abbreviates \axiomType{Complex}              }
+{\axiomType{DFLOAT}     abbreviates \axiomType{DoubleFloat}          }
+{\axiomType{EXPR}       abbreviates \axiomType{Expression}           }
+{\axiomType{FLOAT}      abbreviates \axiomType{Float}                }
+{\axiomType{FRAC}       abbreviates \axiomType{Fraction}             }
+{\axiomType{INT}        abbreviates \axiomType{Integer}              }
+{\axiomType{MATRIX}     abbreviates \axiomType{Matrix}               }
+{\axiomType{NNI}        abbreviates \axiomType{NonNegativeInteger}   }
+{\axiomType{PI}         abbreviates \axiomType{PositiveInteger}      }
+{\axiomType{POLY}       abbreviates \axiomType{Polynomial}           }
+{\axiomType{STRING}     abbreviates \axiomType{String}               }
+{\axiomType{UP}         abbreviates \axiomType{UnivariatePolynomial} }
+}}
+\endImportant
+
+You can combine both full constructor names and abbreviations
+in a type expression.
+Here are some types using abbreviations.
+\centerline{{\axiomType{POLY INT} is the same as 
+\axiomType{Polynomial(INT)} }}
+\centerline{{\axiomType{POLY(Integer)} is the same 
+as \axiomType{Polynomial(Integer)} }}
+\centerline{{\axiomType{POLY(Integer)} is the same 
+as \axiomType{Polynomial(INT)} }}
+\centerline{{\axiomType{FRAC(COMPLEX(INT))} is the 
+same as \axiomType{Fraction Complex Integer} }}
+\centerline{{\axiomType{FRAC(COMPLEX(INT))} is the 
+same as \axiomType{FRAC(Complex Integer)} }}
+
+There are several ways of finding the names of constructors and
+their abbreviations.
+For a specific constructor, use \spadcmd{)abbreviation query}.
+You can also use the \spadcmd{)what} system command to see the names
+and abbreviations of constructors.
+For more information about \spadcmd{)what}, see
+\downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} 
+in Section \ugSysCmdwhatNumber\ignore{ugSysCmdwhat}.
+\xtc{
+\spadcmd{)abbreviation query} can be
+abbreviated (no pun intended) to \spadcmd{)abb q}.
+}{
+\spadpaste{)abb q Integer}
+}
+\xtc{
+The \spadcmd{)abbreviation query} command lists
+the constructor name if you give the abbreviation.
+Issue \spadcmd{)abb q} if you want to see the names and abbreviations
+of all Axiom constructors.
+}{
+\spadpaste{)abb q DMP}
+}
+\xtc{
+Issue this to see all packages whose names contain the string ``ode''.
+}{
+\spadpaste{)what packages ode}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesDeclareTitle}{Declarations}
+\newcommand{\ugTypesDeclareNumber}{2.3.}
+
+@
+\section{Declarations}
+\label{ugTypesDeclarePage}
+\begin{itemize}
+\item ugLangAssignPage \ref{ugLangAssignPage} on
+page~\pageref{ugLangAssignPage}
+\item ugUserDeclarePage \ref{ugUserDeclarePage} on
+page~\pageref{ugUserDeclarePage}
+\item ugTypesConvertPageugIntroAssignPage \ref{ugTypesConvertPageugIntroAssignPage} on
+page~\pageref{ugTypesConvertPageugIntroAssignPage}
+\end{itemize}
+\index{pages!ugTypesDeclarePage!ug02.ht}
+\index{ug02.ht!pages!ugTypesDeclarePage}
+\index{ugTypesDeclarePage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesDeclarePage}{2.3. Declarations}
+\beginscroll
+%
+A \spadgloss{declaration} is an expression used
+to restrict the type of values that can be assigned to variables.
+A colon (\axiomSyntax{:}) is always used after a variable or
+list of variables to be declared.
+
+\beginImportant
+For a single variable, the syntax for declaration is
+\centerline{{{\it variableName \axiom{:} typeOrMode}}}
+For multiple variables, the syntax is
+\centerline{{{\tt (\subscriptIt{variableName}{1}, \subscriptIt{variableName}{2}, \ldots \subscriptIt{variableName}{N}): {\it typeOrMode}}}}
+\endImportant
+
+You can always combine a declaration with an assignment.
+When you do, it is equivalent to first giving a declaration statement,
+then giving an assignment.
+For more information on assignment, see
+\downlink{``\ugIntroAssignTitle''}{ugIntroAssignPage} 
+in Section \ugIntroAssignNumber\ignore{ugIntroAssign} and
+\downlink{``\ugLangAssignTitle''}{ugLangAssignPage} 
+in Section \ugLangAssignNumber\ignore{ugLangAssign}.
+To see how to declare your own functions, see
+\downlink{``\ugUserDeclareTitle''}{ugUserDeclarePage} 
+in Section \ugUserDeclareNumber\ignore{ugUserDeclare}.
+
+\xtc{
+This declares one variable to have a type.
+}{
+\spadpaste{a : Integer \bound{a}}
+}
+\xtc{
+This declares several variables to have a type.
+}{
+\spadpaste{(b,c) : Integer \bound{b c}}
+}
+\xtc{
+\axiom{a, b} and \axiom{c} can only hold integer values.
+}{
+\spadpaste{a := 45 \free{a}}
+}
+\xtc{
+If a value cannot be converted to a declared type,
+an error message is displayed.
+}{
+\spadpaste{b := 4/5 \free{b}}
+}
+\xtc{
+This declares a variable with a mode.
+}{
+\spadpaste{n : Complex ? \bound{n}}
+}
+\xtc{
+This declares several variables with a mode.
+}{
+\spadpaste{(p,q,r) : Matrix Polynomial ? \bound{p q r}}
+}
+\xtc{
+This complex object has integer real and imaginary parts.
+}{
+\spadpaste{n := -36 + 9 * \%i \free{n}}
+}
+\xtc{
+This complex object has fractional symbolic real and imaginary parts.
+}{
+\spadpaste{n := complex(4/(x + y),y/x) \free{n}}
+}
+\xtc{
+This matrix has entries that are polynomials with integer
+coefficients.
+}{
+\spadpaste{p := [[1,2],[3,4],[5,6]] \free{p}}
+}
+\xtc{
+This matrix has a single entry that is a polynomial with
+rational number coefficients.
+}{
+\spadpaste{q := [[x - 2/3]] \free{q}}
+}
+\xtc{
+This matrix has entries that are polynomials with complex integer
+coefficients.
+}{
+\spadpaste{r := [[1-\%i*x,7*y+4*\%i]] \free{r}}
+}
+%
+\xtc{
+Note the difference between this and the next example.
+This is a complex object with polynomial real and imaginary parts.
+}{
+\spadpaste{f : COMPLEX POLY ? := (x + y*\%i)**2}
+}
+\xtc{
+This is a polynomial with complex integer coefficients.
+The objects are convertible from one to the other.
+See \downlink{``\ugTypesConvertTitle''}{ugTypesConvertPage} 
+in Section \ugTypesConvertNumber\ignore{ugTypesConvert} for more information.
+}{
+\spadpaste{g : POLY COMPLEX ? := (x + y*\%i)**2}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesRecordsTitle}{Records}
+\newcommand{\ugTypesRecordsNumber}{2.4.}
+
+@
+\section{Records}
+\label{ugTypesRecordsPage}
+\index{pages!ugTypesRecordsPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesRecordsPage}
+\index{ugTypesRecordsPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesRecordsPage}{2.4. Records}
+\beginscroll
+%
+A \pspadtype{Record} is an object composed of one or more other objects,
+each of which is referenced
+with
+a \spadgloss{selector}.
+Components can all belong to the same type or each can have a different type.
+
+\beginImportant
+The syntax for writing a \pspadtype{Record} type is
+\centerline{{{\tt Record(\subscriptIt{selector}{1}:\subscriptIt{type}{1}, \subscriptIt{selector}{2}:\subscriptIt{type}{2}, \ldots, \subscriptIt{selector}{N}:\subscriptIt{type}{N})}}}
+You must be careful if a selector has the same name as a variable in the
+workspace.
+If this occurs, precede the selector name by a single
+quote.
+\endImportant
+
+Record components are implicitly ordered.
+All the components of a record can
+be set at once by assigning the record a
+bracketed \spadgloss{tuple} of values of the proper length
+(for example, \axiom{r : Record(a: Integer, b: String) := [1, "two"]}).
+To access a component of a record \axiom{r},
+write the name \axiom{r}, followed by a period, followed by a selector.
+
+%
+\xtc{
+The object returned by this computation is a record with two components: a
+\axiom{quotient} part and a \axiom{remainder} part.
+}{
+\spadpaste{u := divide(5,2) \bound{u}}
+}
+%
+\xtc{
+This is the quotient part.
+}{
+\spadpaste{u.quotient \free{u}}
+}
+\xtc{
+This is the remainder part.
+}{
+\spadpaste{u.remainder \free{u}}
+}
+%
+\xtc{
+You can use selector expressions on the left-hand side of an assignment
+to change destructively the components of a record.
+}{
+\spadpaste{u.quotient := 8978 \free{u}\bound{u1}}
+}
+\xtc{
+The selected component \axiom{quotient} has the value \axiom{8978},
+which is what is returned by the assignment.
+Check that the value of \axiom{u} was modified.
+}{
+\spadpaste{u \free{u}\free{u1}}
+}
+\xtc{
+Selectors are evaluated.
+Thus you can use variables that evaluate to selectors instead of the
+selectors themselves.
+}{
+\spadpaste{s := 'quotient \bound{s}}
+}
+\xtc{
+Be careful!
+A selector could have the same name as a variable in the workspace.
+If this occurs, precede the selector name by a single quote, as in
+\axiom{u.'quotient}.
+}{
+\spadpaste{divide(5,2).s \free{s}}
+}
+\xtc{
+Here we declare that the value of \axiom{bd}
+has two components: a string,
+to be accessed via \axiom{name}, and an integer,
+to be accessed via \axiom{birthdayMonth}.
+}{
+\spadpaste{bd : Record(name : String, birthdayMonth : Integer) \bound{bddec}}
+}
+\xtc{
+You must initially set the value of the entire \pspadtype{Record}
+at once.
+}{
+\spadpaste{bd := ["Judith", 3] \free{bddec}\bound{bd}}
+}
+\xtc{
+Once set, you can change any of the individual components.
+}{
+\spadpaste{bd.name := "Katie" \free{bd}}
+}
+\xtc{
+Records may be nested and the selector names can be shared at
+different levels.
+}{
+\spadpaste{r : Record(a : Record(b: Integer, c: Integer), b: Integer) \bound{rdec}}
+}
+\xtc{
+The record \axiom{r} has a \axiom{b} selector at two different levels.
+Here is an initial value for \axiom{r}.
+}{
+\spadpaste{r := [[1,2],3] \bound{r}\free{rdec}}
+}
+\xtc{
+This extracts the \axiom{b} component from the \axiom{a} component of \axiom{r}.
+}{
+\spadpaste{r.a.b \free{r}}
+}
+\xtc{
+This extracts the \axiom{b} component from \axiom{r}.
+}{
+\spadpaste{r.b \free{r}}
+}
+%
+\xtc{
+You can also use spaces or parentheses to refer to \pspadtype{Record}
+components.
+This is the same as \axiom{r.a}.
+}{
+\spadpaste{r(a) \free{r}}
+}
+\xtc{
+This is the same as \axiom{r.b}.
+}{
+\spadpaste{r b \free{r}}
+}
+\xtc{
+This is the same as \axiom{r.b := 10}.
+}{
+\spadpaste{r(b) := 10 \free{r}\bound{r1}}
+}
+\xtc{
+Look at \axiom{r} to make sure it was modified.
+}{
+\spadpaste{r \free{r1}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesUnionsTitle}{Unions}
+\newcommand{\ugTypesUnionsNumber}{2.5.}
+
+@
+\section{Unions}
+\label{ugTypesUnionsPage}
+\begin{itemize}
+\item ugTypesUnionsWOSelPage \ref{ugTypesUnionsWOSelPage} on
+page~\pageref{ugTypesUnionsWOSelPage}
+\item ugTypesUnionsWSelPage \ref{ugTypesUnionsWSelPage} on
+page~\pageref{ugTypesUnionsWSelPage}
+\end{itemize}
+\index{pages!ugTypesUnionsPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesUnionsPage}
+\index{ugTypesUnionsPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesUnionsPage}{2.5. Unions}
+\beginscroll
+%
+Type \pspadtype{Union} is used for objects that
+can be of any of a specific finite set of types.
+Two versions of unions are available,
+one with selectors (like records) and one without.
+
+\beginmenu
+    \menudownlink{{2.5.1. Unions Without Selectors}}{ugTypesUnionsWOSelPage}
+    \menudownlink{{2.5.2. Unions With Selectors}}{ugTypesUnionsWSelPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesUnionsWOSelTitle}{Unions Without Selectors}
+\newcommand{\ugTypesUnionsWOSelNumber}{2.5.1.}
+
+@
+\section{Unions Without Selectors}
+\label{ugTypesUnionsWOSelPage}
+\index{pages!ugTypesUnionsWOSelPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesUnionsWOSelPage}
+\index{ugTypesUnionsWOSelPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesUnionsWOSelPage}{2.5.1. Unions Without Selectors}
+\beginscroll
+
+The declaration \axiom{x : Union(Integer, String, Float)}
+states that \axiom{x} can have values that are integers,
+strings or ``big'' floats.
+If, for example, the \pspadtype{Union} object is an integer, the object is
+said to belong to the \axiomType{Integer} {\it branch}
+of the \pspadtype{Union}.\footnote{
+Note that we are being a bit careless with the language here.
+Technically, the type of \axiom{x} is always
+\pspadtype{Union(Integer, String, Float)}.
+If it belongs to the \axiomType{Integer} branch, \axiom{x}
+may be converted to an object of type \axiomType{Integer}.}
+
+\beginImportant
+The syntax for writing a \pspadtype{Union} type without selectors is
+\centerline{{{\tt Union(\subscriptIt{type}{1}, \subscriptIt{type}{2}, \ldots, \subscriptIt{type}{N})}}}
+The types in a union without selectors must be distinct.
+\endImportant
+
+It is possible to create unions like
+\pspadtype{Union(Integer, PositiveInteger)} but they are
+difficult to work with because of the overlap in the branch
+types.
+See below for the rules Axiom uses for converting something
+into a union object.
+
+The \axiom{case} infix
+\spadkey{case}
+operator returns a \axiomType{Boolean}
+and can be used to determine the branch in which an object lies.
+
+\xtc{
+This function displays a message stating in which
+branch of the \pspadtype{Union} the object (defined as \axiom{x}
+above) lies.
+}{
+\begin{spadsrc}[\bound{sayBranch}]
+sayBranch(x : Union(Integer,String,Float)) : Void  ==
+  output
+    x case Integer => "Integer branch"
+    x case String  => "String branch"
+    "Float branch"
+\end{spadsrc}
+}
+%
+\xtc{
+This tries \userfun{sayBranch} with an integer.
+}{
+\spadpaste{sayBranch 1 \free{sayBranch}}
+}
+\xtc{
+This tries \userfun{sayBranch} with a string.
+}{
+\spadpaste{sayBranch "hello" \free{sayBranch}}
+}
+\xtc{
+This tries \userfun{sayBranch} with a floating-point number.
+}{
+\spadpaste{sayBranch 2.718281828 \free{sayBranch}}
+}
+%
+
+There are two things of interest about this particular
+example to which we would like to draw your attention.
+\indent{4}
+\beginitems
+%
+\item[1. ] Axiom normally converts a result to the target value
+before passing it to the function.
+If we left the declaration information out of this function definition
+then the \axiom{sayBranch} call would have been attempted with an
+\axiomType{Integer} rather than a \pspadtype{Union}, and an error would have
+resulted.
+%
+\item[2. ] The types in a \pspadtype{Union} are searched in the order given.
+So if the type were given as
+
+\noindent
+{\small\axiom{sayBranch(x: Union(String,Integer,Float,Any)): Void}}
+
+\noindent
+then the result would have been ``String branch'' because there
+is a conversion from \axiomType{Integer} to \axiomType{String}.
+\enditems
+\indent{0}
+
+Sometimes \pspadtype{Union} types can have extremely
+long names.
+Axiom therefore abbreviates the names of unions by printing
+the type of the branch first within the \pspadtype{Union} and then
+eliding the remaining types with an ellipsis (\axiomSyntax{...}).
+
+\xtc{
+Here the \axiomType{Integer} branch is displayed first.
+Use \axiomSyntax{::} to create a \pspadtype{Union} object from an object.
+}{
+\spadpaste{78 :: Union(Integer,String)}
+}
+\xtc{
+Here the \axiomType{String} branch is displayed first.
+}{
+\spadpaste{s := "string" :: Union(Integer,String) \bound{s}}
+}
+\xtc{
+Use \axiom{typeOf} to see the full and actual \pspadtype{Union} type.
+\spadkey{typeOf}
+}{
+\spadpaste{typeOf s}
+}
+\xtc{
+A common operation that returns a union is \axiomFunFrom{exquo}{Integer}
+which returns the ``exact quotient'' if the quotient is exact,...
+}{
+\spadpaste{three := exquo(6,2) \bound{three}}
+}
+\xtc{
+and \axiom{"failed"} if the quotient is not exact.
+}{
+\spadpaste{exquo(5,2)}
+}
+\xtc{
+A union with a \axiom{"failed"} is frequently used to indicate the failure
+or lack of applicability of an object.
+As another example, assign an integer a variable \axiom{r} declared to be a
+rational number.
+}{
+\spadpaste{r: FRAC INT := 3 \bound{r}\bound{rdec}}
+}
+\xtc{
+The operation \axiomFunFrom{retractIfCan}{Fraction} tries to retract the
+fraction to the underlying domain \axiomType{Integer}.
+It produces a union object.
+Here it succeeds.
+}{
+\spadpaste{retractIfCan(r) \free{r}}
+}
+\xtc{
+Assign it a rational number.
+}{
+\spadpaste{r := 3/2 \bound{r1}\free{rdec}}
+}
+\xtc{
+Here the retraction fails.
+}{
+\spadpaste{retractIfCan(r) \free{r1}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesUnionsWSelTitle}{Unions With Selectors}
+\newcommand{\ugTypesUnionsWSelNumber}{2.5.2.}
+
+@
+\section{Unions With Selectors}
+\label{ugTypesUnionsWSelPage}
+\begin{itemize}
+\item ugTypesRecordsPage \ref{ugTypesRecordsPage} on
+page~\pageref{ugTypesRecordsPage}
+\item ugTypesUnionsWOSelPage \ref{ugTypesUnionsWOSelPage} on
+page~\pageref{ugTypesUnionsWOSelPage}
+\end{itemize}
+\index{pages!ugTypesUnionsWSelPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesUnionsWSelPage}
+\index{ugTypesUnionsWSelPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesUnionsWSelPage}{2.5.2. Unions With Selectors}
+\beginscroll
+
+Like records (
+\downlink{``\ugTypesRecordsTitle''}{ugTypesRecordsPage} 
+in Section \ugTypesRecordsNumber\ignore{ugTypesRecords}),
+you can write \pspadtype{Union} types
+with selectors.
+
+\beginImportant
+The syntax for writing a \pspadtype{Union} type with selectors is
+\centerline{{{\tt Union(\subscriptIt{selector}{1}:\subscriptIt{type}{1}, \subscriptIt{selector}{2}:\subscriptIt{type}{2}, \ldots, \subscriptIt{selector}{N}:\subscriptIt{type}{N})}}}
+You must be careful if a selector has the same name as a variable in the
+workspace.
+If this occurs, precede the selector name by a single
+quote.
+It is an error to use a selector that does not correspond to the branch of
+the \pspadtype{Union} in which the element actually lies.
+\endImportant
+
+Be sure to understand the difference between records and unions
+with selectors.
+Records can have more than one component and the selectors are
+used to refer to the components.
+Unions always have one component but the type of that one
+component can vary.
+An object of type \pspadtype{Record(a: Integer, b: Float, c:
+String)} contains an integer {\it and} a float  {\it and} a
+string.
+An object of type \pspadtype{Union(a: Integer, b: Float, c:
+String)} contains an integer {\it or} a float  {\it or} a
+string.
+
+Here is a version of the \userfun{sayBranch} function (cf.
+\downlink{``\ugTypesUnionsWOSelTitle''}{ugTypesUnionsWOSelPage} 
+in Section \ugTypesUnionsWOSelNumber\ignore{ugTypesUnionsWOSel}) 
+that works with a union with selectors.
+It displays a message stating in which branch of the \pspadtype{Union} the
+object lies.
+\begin{verbatim}
+sayBranch(x:Union(i:Integer,s:String,f:Float)):Void==
+  output
+    x case i => "Integer branch"
+    x case s  => "String branch"
+    "Float branch"
+\end{verbatim}
+Note that \axiom{case} uses the selector name as its right-hand argument.
+\spadkey{case}
+If you accidentally use the branch type on the right-hand side of
+\axiom{case}, \axiom{false} will be returned.
+
+\xtc{
+Declare variable \axiom{u} to have a union type with selectors.
+}{
+\spadpaste{u : Union(i : Integer, s : String) \bound{undec}}
+}
+\xtc{
+Give an initial value to \axiom{u}.
+}{
+\spadpaste{u := "good morning" \bound{u}\free{undec}}
+}
+\xtc{
+Use \axiom{case} to determine in which
+branch of a \pspadtype{Union} an object lies.
+}{
+\spadpaste{u case i \free{u}}
+}
+\xtc{
+}{
+\spadpaste{u case s \free{u}}
+}
+\xtc{
+To access the element in a particular branch, use the selector.
+}{
+\spadpaste{u.s \free{u}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesAnyNoneTitle}{The ``Any'' Domain}
+\newcommand{\ugTypesAnyNoneNumber}{2.6.}
+
+@
+\section{The ``Any'' Domain}
+\label{ugTypesAnyNonePage}
+\index{pages!ugTypesAnyNonePage!ug02.ht}
+\index{ug02.ht!pages!ugTypesAnyNonePage}
+\index{ugTypesAnyNonePage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesAnyNonePage}{2.6. The ``Any'' Domain}
+\beginscroll
+
+With the exception of objects of type \pspadtype{Record}, all Axiom
+data structures are homogenous, that is, they hold objects all of the same
+type.
+If you need to get around this, you can use type \axiomType{Any}.
+Using \axiomType{Any}, for example, you can create lists whose
+elements are integers, rational numbers, strings, and even other lists.
+
+\xtc{
+Declare \axiom{u} to have type \axiomType{Any}.
+}{
+\spadpaste{u: Any\bound{uany}}
+}
+\xtc{
+Assign a list of mixed type values to \axiom{u}
+}{
+\spadpaste{u := [1, 7.2, 3/2, x**2, "wally"]\free{uany}\bound{u}}
+}
+\xtc{
+When we ask for the elements, Axiom displays these types.
+}{
+\spadpaste{u.1 \free{u}}
+}
+\xtc{
+Actually, these objects belong to \axiomType{Any} but Axiom
+automatically converts them to their natural types for you.
+}{
+\spadpaste{u.3 \free{u}}
+}
+\xtc{
+Since type \axiomType{Any} can be anything,
+it can only belong to type \axiomType{Type}.
+Therefore it cannot be used in algebraic domains.
+}{
+\spadpaste{v : Matrix(Any)}
+}
+
+Perhaps you are wondering how Axiom internally represents
+objects of type \axiomType{Any}.
+An object of type \axiomType{Any} consists not only a data part
+representing its normal value, but also a type part (a {\it badge}) giving
+its type.
+For example, the value \axiom{1} of type \axiomType{PositiveInteger} as an
+object of type \axiomType{Any} internally looks like
+\axiom{[1,\axiomType{PositiveInteger()}]}.
+
+%When should you use \axiomType{Any} instead of a \pspadtype{Union} type?
+%Can you plan ahead?
+%For a \pspadtype{Union}, you must know in advance exactly which types you
+%are
+%\index{union!vs. Any@{vs. \protect\nonLibAxiomType{Any}}}
+%going to allow.
+%For \axiomType{Any}, anything that comes along can be accommodated.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesConvertTitle}{Conversion}
+\newcommand{\ugTypesConvertNumber}{2.7.}
+
+@
+\section{Conversion}
+\label{ugTypesConvertPage}
+\begin{itemize}
+\item ugTypesBasicPage \ref{ugTypesBasicPage} on
+page~\pageref{ugTypesBasicPage}
+\end{itemize}
+\index{pages!ugTypesConvertPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesConvertPage}
+\index{ugTypesConvertPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesConvertPage}{2.7. Conversion}
+\beginscroll
+%
+\beginImportant
+\spadglossSee{Conversion}{conversion}
+is the process of changing an object of one type
+into an object of another type.
+The syntax for conversion is:
+\centerline{{{\it object} {\tt ::} {\it newType}}}
+\endImportant
+
+\xtc{
+By default, \axiom{3} has the type \axiomType{PositiveInteger}.
+}{
+\spadpaste{3}
+}
+\xtc{
+We can change this into an object of type \axiomType{Fraction Integer}
+by using \axiomSyntax{::}.
+}{
+\spadpaste{3 :: Fraction Integer}
+}
+
+A \spadgloss{coercion} is a special kind of conversion that Axiom is
+allowed to do automatically when you enter an expression.
+Coercions are usually somewhat safer than more general conversions.
+The Axiom library contains operations called
+\axiomFun{coerce} and \axiomFun{convert}.
+Only the \axiomFun{coerce} operations can be used by the
+interpreter to change an object into an object of another type unless
+you explicitly use a \axiomSyntax{::}.
+
+By now you will be quite familiar with what types and modes look like.
+It is useful to think of a type or mode as a pattern
+for what you want the result to be.
+\xtc{
+Let's start with a square matrix of polynomials with complex rational number
+coefficients.
+}{
+\spadpaste{m : SquareMatrix(2,POLY COMPLEX FRAC INT) \bound{mdec}}
+}
+\xtc{
+}{
+\spadpaste{m := matrix [[x-3/4*\%i,z*y**2+1/2],[3/7*\%i*y**4 - x,12-\%i*9/5]] \bound{m}\free{mdec}}
+}
+\xtc{
+We first want to interchange the \axiomType{Complex} and
+\axiomType{Fraction} layers.
+We do the conversion by doing the interchange in the type expression.
+}{
+\spadpaste{m1 := m :: SquareMatrix(2,POLY FRAC COMPLEX INT) \free{m}\bound{m1}}
+}
+\xtc{
+Interchange the \axiomType{Polynomial} and the
+\axiomType{Fraction} levels.
+}{
+\spadpaste{m2 := m1 :: SquareMatrix(2,FRAC POLY COMPLEX INT) \free{m1}\bound{m2}}
+}
+\xtc{
+Interchange the \axiomType{Polynomial} and the
+\axiomType{Complex} levels.
+}{
+\spadpaste{m3 := m2 :: SquareMatrix(2,FRAC COMPLEX POLY INT) \free{m2}\bound{m3}}
+}
+
+All the entries have changed types, although in comparing the
+last two results only the entry in the lower left corner looks different.
+We did all the intermediate steps to show you what Axiom can do.
+
+\xtc{
+In fact, we could have combined all these into one conversion.
+}{
+\spadpaste{m :: SquareMatrix(2,FRAC COMPLEX POLY INT) \free{m}}
+}
+
+There are times when Axiom is not be able to do the conversion
+in one step.
+You may need to break up the transformation into several conversions
+in order to get an object of the desired type.
+
+We cannot move either \axiomType{Fraction} or \axiomType{Complex}
+above (or to the left of, depending on how you look at it)
+\axiomType{SquareMatrix} because each of these levels requires that its
+argument type have commutative multiplication, whereas
+\axiomType{SquareMatrix} does not.\footnote{\axiomType{Fraction} requires
+that its argument belong to the category \axiomType{IntegralDomain} and
+\axiomType{Complex} requires that its argument belong to
+\axiomType{CommutativeRing}. See
+\downlink{``\ugTypesBasicTitle''}{ugTypesBasicPage} 
+in Section \ugTypesBasicNumber\ignore{ugTypesBasic}
+for a brief discussion of categories.}
+The \axiomType{Integer} level did not move anywhere
+because it does not allow any arguments.
+We also did not move the \axiomType{SquareMatrix} part anywhere, but
+we could have.
+\xtc{
+Recall that \axiom{m} looks like this.
+}{
+\spadpaste{m \free{m}}
+}
+\xtc{
+If we want a polynomial with matrix coefficients rather than a matrix
+with polynomial entries, we can just do the conversion.
+}{
+\spadpaste{m :: POLY SquareMatrix(2,COMPLEX FRAC INT) \free{m}}
+}
+\xtc{
+We have not yet used modes for any conversions.
+Modes are a great shorthand for indicating the type of the
+object you want.
+Instead of using the long type expression in the
+last example, we could have simply said this.
+}{
+\spadpaste{m :: POLY ? \free{m}}
+}
+\xtc{
+We can also indicate more structure if we want the entries
+of the matrices to be fractions.
+}{
+\spadpaste{m :: POLY SquareMatrix(2,FRAC ?) \free{m}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesSubdomainsTitle}{Subdomains Again}
+\newcommand{\ugTypesSubdomainsNumber}{2.8.}
+
+@
+\section{Subdomains Again}
+\label{ugTypesSubdomainsPage}
+\index{pages!ugTypesSubdomainsPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesSubdomainsPage}
+\index{ugTypesSubdomainsPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesSubdomainsPage}{2.8. Subdomains Again}
+\beginscroll
+
+A \spadgloss{subdomain} \axiom{S} of a domain \axiom{D} is a domain
+consisting of
+\indent{4}
+\beginitems
+\item[1. ] those elements of \axiom{D} that satisfy some
+\spadgloss{predicate} (that is, a test that returns \axiom{true} or
+\axiom{false}) and
+\item[2. ] a subset of the operations of \axiom{D}.
+\enditems
+\indent{0}
+Every domain is a subdomain of itself, trivially satisfying the
+membership test: \axiom{true}.
+
+Currently, there are only two system-defined subdomains in Axiom that receive
+substantial use.
+\axiomType{PositiveInteger} and
+\axiomType{NonNegativeInteger} are subdomains of \axiomType{Integer}.
+An element \axiom{x} of \axiomType{NonNegativeInteger} is an integer
+that is greater than or equal to zero, that is, satisfies
+\axiom{x >= 0.}
+An element \axiom{x} of \axiomType{PositiveInteger} is a nonnegative integer
+that is, in fact, greater than zero, that is, satisfies \axiom{x > 0.}
+Not all operations from \axiomType{Integer} are available for these
+subdomains.
+For example, negation and subtraction are not provided since the subdomains
+are not closed under those operations.
+When you use an integer in an expression, Axiom assigns to it the
+type that is the most specific subdomain whose predicate is satisfied.
+\xtc{
+This is a positive integer.
+}{
+\spadpaste{5}
+}
+\xtc{
+This is a nonnegative integer.
+}{
+\spadpaste{0}
+}
+\xtc{
+This is neither of the above.
+}{
+\spadpaste{-5}
+}
+\xtc{
+Furthermore, unless you are assigning an integer to a declared variable
+or using a conversion, any integer result has as type the most
+specific subdomain.
+}{
+\spadpaste{(-2) - (-3)}
+}
+\xtc{
+}{
+\spadpaste{0 :: Integer}
+}
+\xtc{
+}{
+\spadpaste{x : NonNegativeInteger := 5}
+}
+
+When necessary, Axiom converts an integer object into one belonging
+to a less specific subdomain.
+For example, in \axiom{3-2}, the arguments to \axiomOpFrom{-}{Integer} are both
+elements of \axiomType{PositiveInteger}, but this type does not provide
+a subtraction operation.
+Neither does \axiomType{NonNegativeInteger}, so \axiom{3} and \axiom{2}
+are viewed as elements of \axiomType{Integer}, where their difference
+can be calculated.
+The result is \axiom{1}, which Axiom then automatically assigns
+the type \axiomType{PositiveInteger}.
+
+\xtc{
+Certain operations are very sensitive to the subdomains to which their
+arguments belong.
+This is an element of \axiomType{PositiveInteger}.
+}{
+\spadpaste{2 ** 2}
+}
+\xtc{
+This is an element of \axiomType{Fraction Integer}.
+}{
+\spadpaste{2 ** (-2)}
+}
+\xtc{
+It makes sense then that this
+is a list of elements of \axiomType{PositiveInteger}.
+}{
+\spadpaste{[10**i for i in 2..5]}
+}
+What should the type of \axiom{[10**(i-1) for i in 2..5]} be?
+On one hand, \axiom{i-1} is always an integer greater than zero
+as \axiom{i} ranges from \axiom{2} to \axiom{5} and so \axiom{10**i}
+is also always a positive integer.
+On the other, \axiom{i-1} is a very simple function of \axiom{i}.
+Axiom does not try to analyze every such function over the
+index's range of values to determine whether it is always positive
+or nowhere negative.
+For an arbitrary Axiom function, this analysis is not possible.
+
+\xtc{
+So, to be consistent no such analysis is done and we get this.
+}{
+\spadpaste{[10**(i-1) for i in 2..5]}
+}
+\xtc{
+To get a list of elements of \axiomType{PositiveInteger} instead, you
+have two choices.
+You can use a conversion.
+}{
+\spadpaste{[10**((i-1) :: PI) for i in 2..5]}
+}
+\xtc{
+Or you can use \axiom{pretend}.
+\spadkey{pretend}
+}{
+\spadpaste{[10**((i-1) pretend PI) for i in 2..5]}
+}
+
+The operation \axiom{pretend} is used to defeat the Axiom
+type system.
+The expression \axiom{object pretend D} means ``make a new object
+(without copying) of type \axiom{D} from \axiom{object}.''
+If \axiom{object} were an integer and you told Axiom
+to pretend it was a list, you would probably see a message about a
+fatal error being caught and memory possibly being damaged.
+Lists do not have the same internal representation as integers!
+
+You use \axiom{pretend} at your peril.
+
+\xtc{
+Use \axiom{pretend} with great care!
+Axiom trusts you that the value is of the specified type.
+}{
+\spadpaste{(2/3) pretend Complex Integer}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesPkgCallTitle}{Package Calling and Target Types}
+\newcommand{\ugTypesPkgCallNumber}{2.9.}
+
+@
+\section{Package Calling and Target Types}
+\label{ugTypesPkgCallPage}
+\begin{itemize}
+\item ugTypesDeclarePage \ref{ugTypesDeclarePage} on
+page~\pageref{ugTypesDeclarePage}
+\item ugUserUsePage \ref{ugUserUsePage} on
+page~\pageref{ugUserUsePage}
+\end{itemize}
+\index{pages!ugTypesPkgCallPage!ug02.ht}
+\index{ug02.ht!pages!ugTypesPkgCallPage}
+\index{ugTypesPkgCallPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesPkgCallPage}{2.9. Package Calling and Target Types}
+\beginscroll
+
+Axiom works hard to figure out what you mean by an
+expression without your having to qualify it with type
+information.
+Nevertheless, there are times when you need to help it along by
+providing hints (or even orders!) to get Axiom to do what
+you want.
+
+We saw in \downlink{``\ugTypesDeclareTitle''}{ugTypesDeclarePage} 
+in Section \ugTypesDeclareNumber\ignore{ugTypesDeclare} that 
+declarations using types
+and modes control the type of the results produced.
+For example, we can either produce a complex object with
+polynomial real and imaginary parts or a polynomial with complex
+integer coefficients, depending on the declaration.
+
+\spadglossSee{Package calling}{package call} is how you tell
+Axiom to use a particular function from a particular part of
+the library.
+
+\xtc{
+Use the \axiomOpFrom{/}{Fraction} from \axiomType{Fraction Integer}
+to create a fraction of two integers.
+}{
+\spadpaste{2/3}
+}
+\xtc{
+If we wanted a floating point number, we can say ``use the
+\axiomOpFrom{/}{Float} in \axiomType{Float}.''
+}{
+\spadpaste{(2/3)\$Float}
+}
+\xtc{
+Perhaps we actually wanted a fraction of complex integers.
+}{
+\spadpaste{(2/3)\$Fraction(Complex Integer)}
+}
+
+In each case, Axiom used the indicated operations, sometimes
+first needing to convert the two integers into objects of an
+appropriate type.
+In these examples, \axiomOpFrom{/}{Fraction} is written as an
+infix operator.
+
+\beginImportant
+To use package calling with an infix operator, use the
+following syntax:
+\centerline{{{\tt ( \subscriptIt{arg}{1} {\it op} \subscriptIt{arg}{1} )\${\it type} }}}
+\endImportant
+
+We used, for example, \axiom{(2/3)\$Float}.
+The expression \axiom{2 + 3 + 4} is equivalent to \axiom{(2+3) + 4.}
+Therefore in the expression
+\axiom{(2 + 3 + 4)\$Float} the second
+\axiomOp{+} comes from the \axiomType{Float} domain.
+Can you guess whether the first \axiomOp{+} comes from
+\axiomType{Integer} or \axiomType{Float}?\footnote{\axiomType{Float},
+because the package call causes Axiom to convert
+\axiom{(2 + 3)} and \axiom{4} to type \axiomType{Float}.
+Before the sum is converted, it is given a target type (see below) of
+\axiomType{Float} by Axiom and then evaluated.
+The target type causes the \axiomOp{+} from \axiomType{Float} to be used.}
+
+\beginImportant
+For an operator written before its arguments, you must use
+parentheses around the arguments (even if there is only one),
+and follow the closing parenthesis by a \axiomSyntax{\$}
+and then the type.
+\centerline{{{\tt {\it fun} ( \subscriptIt{arg}{1}, \subscriptIt{arg}{1}, \ldots, \subscriptIt{arg}{N} )\${\it type}}}}
+\endImportant
+
+For example, to call the ``minimum'' function from \axiomType{DoubleFloat}
+on two integers, you could write \axiom{min(4,89)\$DoubleFloat}.
+Another use of package calling is to tell Axiom to use a library
+function rather than a function you defined.
+We discuss this in \downlink{``\ugUserUseTitle''}{ugUserUsePage} 
+in Section \ugUserUseNumber\ignore{ugUserUse}.
+
+Sometimes rather than specifying where an operation comes from, you just
+want to say what type the result should be.
+We say that you provide
+a
+\spadglossSee{target type}{target} for the expression.
+Instead of using a \axiomSyntax{\$}, use a \axiomSyntax{@} to specify
+the requested target type.
+Otherwise, the syntax is the same.
+Note that giving a target type is not the same as explicitly doing a
+conversion.
+The first says ``try to pick operations so that the result has
+such-and-such a type.''
+The second says ``compute the result and then convert to an object of
+such-and-such a type.''
+
+\xtc{
+Sometimes it makes sense, as in this expression,
+to say ``choose the operations in this expression so that
+the final result is a \axiomType{Float}.''
+}{
+\spadpaste{(2/3)@Float}
+}
+
+Here we used \axiomSyntax{@} to say that the target type of the
+left-hand side was \axiomType{Float}.
+In this simple case, there was no real difference
+between using \axiomSyntax{\$} and \axiomSyntax{@}.
+You can see the difference if you try the following.
+\xtc{
+This says to try to choose \axiomOp{+} so that the result is
+a string.
+Axiom cannot do this.
+}{
+\spadpaste{(2 + 3)@String}
+}
+\xtc{
+This says to get the \axiomOp{+} from \axiomType{String} and apply
+it to the two integers.
+Axiom also cannot do this because there is no \axiomOp{+}
+exported by \axiomType{String}.
+}{
+\spadpaste{(2 + 3)\$String}
+}
+(By the way, the operation \axiomFunFrom{concat}{String} or juxtaposition
+is used to concatenate two strings.)
+
+When we have more than one operation in an expression, the
+difference is even more evident.
+The following two expressions show that Axiom uses the
+target type to create different objects.
+The \axiomOp{+}, \axiomOp{*} and \axiomOp{**} operations are all
+chosen so that an object of the correct final type is created.
+
+\xtc{
+This says that the operations should be chosen so
+that the result is a \axiomType{Complex} object.
+}{
+\spadpaste{((x + y * \%i)**2)@(Complex Polynomial Integer)}
+}
+\xtc{
+This says that the operations should be chosen so
+that the result is a \axiomType{Polynomial} object.
+}{
+\spadpaste{((x + y * \%i)**2)@(Polynomial Complex Integer)}
+}
+\xtc{
+What do you think might happen if we left off all
+target type and package call information in this last example?
+}{
+\spadpaste{(x + y * \%i)**2 \bound{prevC}}
+}
+\xtc{
+We can convert it to \axiomType{Complex} as an afterthought.
+But this is more work than just saying making what we want in the first
+place.
+}{
+\spadpaste{\% :: Complex ? \free{prevC}}
+}
+
+Finally, another use of package calling is to qualify fully an
+operation that is passed as an argument to a function.
+
+\xtc{
+Start with a small matrix of integers.
+}{
+\spadpaste{h := matrix [[8,6],[-4,9]] \bound{h}}
+}
+%
+\xtc{
+We want to produce a new matrix that has for entries the multiplicative
+inverses of the entries of \axiom{h}.
+One way to do this is by calling
+\axiomFunFrom{map}{MatrixCategoryFunctions2} with the
+\axiomFunFrom{inv}{Fraction} function from \axiomType{Fraction (Integer)}.
+}{
+\spadpaste{map(inv\$Fraction(Integer),h) \free{h}}
+}
+\xtc{
+We could have been a bit less verbose and used abbreviations.
+}{
+\spadpaste{map(inv\$FRAC(INT),h) \free{h}\bound{h1}}
+}
+%
+\xtc{
+As it turns out, Axiom is smart enough to know what we mean
+anyway.
+We can just say this.
+}{
+\spadpaste{map(inv,h) \free{h}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesResolveTitle}{Resolving Types}
+\newcommand{\ugTypesResolveNumber}{2.10.}
+
+@
+\section{Resolving Types}
+\label{ugTypesResolvePage}
+\index{pages!ugTypesResolvePage!ug02.ht}
+\index{ug02.ht!pages!ugTypesResolvePage}
+\index{ugTypesResolvePage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesResolvePage}{2.10. Resolving Types}
+\beginscroll
+
+In this section we briefly describe an internal process by which
+Axiom determines a type to which two objects of possibly
+different types can be converted.
+We do this to give you further insight into how Axiom takes
+your input, analyzes it, and produces a result.
+
+What happens when you enter \axiom{x + 1} to Axiom?
+Let's look at what you get from the two terms of this expression.
+
+\xtc{
+This is a symbolic object whose type indicates the name.
+}{
+\spadpaste{x}
+}
+\xtc{
+This is a positive integer.
+}{
+\spadpaste{1}
+}
+
+There are no operations in \axiomType{PositiveInteger} that add
+positive integers to objects of type \axiomType{Variable(x)} nor
+are there any in \axiomType{Variable(x)}.
+Before it can add the two parts, Axiom must come up with
+a common type to which both \axiom{x} and \axiom{1} can be
+converted.
+We say that Axiom must {\it resolve} the two types
+into a common type.
+In this example, the common type is \axiomType{Polynomial(Integer)}.
+
+\xtc{
+Once this is determined, both parts are converted into polynomials,
+and the addition operation from \axiomType{Polynomial(Integer)} is used to
+get the answer.
+}{
+\spadpaste{x + 1}
+}
+\xtc{
+Axiom can always resolve two types: if nothing resembling
+the original types can be found, then \axiomType{Any} is be used.
+This is fine and useful in some cases.
+}{
+\spadpaste{["string",3.14159]}
+}
+\xtc{
+In other cases objects of type \axiomType{Any} can't be used
+by the operations you specified.
+}{
+\spadpaste{"string" + 3.14159}
+}
+Although this example was contrived, your expressions may need
+to be qualified slightly to help Axiom resolve the
+types involved.
+You may need to declare a few variables, do some package calling,
+provide some target type information or do some explicit
+conversions.
+
+We suggest that you just enter the expression you want evaluated and
+see what Axiom does.
+We think you will be impressed with its ability to ``do what I
+mean.''
+If Axiom is still being obtuse, give it some hints.
+As you work with Axiom, you will learn where it needs a
+little help to analyze quickly and perform your computations.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugTypesExposeTitle}{Exposing Domains and Packages}
+\newcommand{\ugTypesExposeNumber}{2.11.}
+
+@
+\section{Exposing Domains and Packages}
+\label{ugTypesExposePage}
+\begin{itemize}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\item ugUserTrianglePage \ref{ugUserTrianglePage} on
+page~\pageref{ugUserTrianglePage}
+\item ugSysCmdframePage \ref{ugSysCmdframePage} on
+page~\pageref{ugSysCmdframePage}
+\end{itemize}
+\index{pages!ugTypesExposePage!ug02.ht}
+\index{ug02.ht!pages!ugTypesExposePage}
+\index{ugTypesExposePage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugTypesExposePage}{2.11. Exposing Domains and Packages}
+\beginscroll
+
+In this section we discuss how Axiom makes some operations
+available to you while hiding others that are meant to be used by
+developers or only in rare cases.
+If you are a new user of Axiom, it is likely that everything
+you need is available by default and you may want
+to skip over this section on first reading.
+
+Every
+domain and package in the Axiom library
+is
+either
+\spadglossSee{exposed}{expose} (meaning that you can use its 
+operations without doing
+anything special) or it is {\it hidden} (meaning you have to either
+package call
+(see \downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} 
+in Section \ugTypesPkgCallNumber\ignore{ugTypesPkgCall})
+the operations it contains or explicitly expose it to use the
+operations).
+The initial exposure status for a constructor is set in the
+file {\bf exposed.lsp} (see the {\it Installer's Note}
+for Axiom
+if you need to know the location of this file).
+Constructors are collected together in
+{\it exposure groups}.
+Categories are all in the exposure group ``categories'' and the
+bulk of the basic set of packages and domains that are exposed
+are in the exposure group ``basic.''
+Here is an abbreviated sample of the file (without the Lisp parentheses):
+\begin{verbatim}
+basic
+        AlgebraicNumber                          AN
+        AlgebraGivenByStructuralConstants        ALGSC
+        Any                                      ANY
+        AnyFunctions1                            ANY1
+        BinaryExpansion                          BINARY
+        Boolean                                  BOOLEAN
+        CardinalNumber                           CARD
+        CartesianTensor                          CARTEN
+        Character                                CHAR
+        CharacterClass                           CCLASS
+        CliffordAlgebra                          CLIF
+        Color                                    COLOR
+        Complex                                  COMPLEX
+        ContinuedFraction                        CONTFRAC
+        DecimalExpansion                         DECIMAL
+        ...
+\end{verbatim}
+\begin{verbatim}
+categories
+        AbelianGroup                             ABELGRP
+        AbelianMonoid                            ABELMON
+        AbelianMonoidRing                        AMR
+        AbelianSemiGroup                         ABELSG
+        Aggregate                                AGG
+        Algebra                                  ALGEBRA
+        AlgebraicallyClosedField                 ACF
+        AlgebraicallyClosedFunctionSpace         ACFS
+        ArcHyperbolicFunctionCategory            AHYP
+        ...
+\end{verbatim}
+For each constructor in a group, the full name and the abbreviation
+is given.
+There are other groups in {\bf exposed.lsp} but initially only the
+constructors in exposure groups ``basic'' ``categories'' ``naglink'' 
+and ``anna'' are exposed.
+
+As an interactive user of Axiom, you do not need to modify
+this file.
+Instead, use \spadcmd{)set expose} to expose, hide or query the exposure
+status of an individual constructor or exposure group.
+The reason for having exposure groups is to be able to expose or hide
+multiple constructors with a single command.
+For example, you might group together into exposure group ``quantum'' a
+number of domains and packages useful for quantum mechanical computations.
+These probably should not be available to every user, but you want an easy
+way to make the whole collection visible to Axiom when it is looking
+for operations to apply.
+
+If you wanted to hide all the basic constructors available by default, you
+would issue \spadcmd{)set expose drop group basic}.
+If, however, you discover that you have hidden all the basic constructors,
+you should issue \spadcmd{)set expose add group basic} to restore your
+default environment.
+
+It is more likely that you would want to expose or hide individual
+constructors.
+In \downlink{``\ugUserTriangleTitle''}{ugUserTrianglePage} 
+in Section \ugUserTriangleNumber\ignore{ugUserTriangle} we 
+use several operations from
+\axiomType{OutputForm}, a domain usually hidden.
+To avoid package calling every operation from \axiomType{OutputForm}, we
+expose the domain and let Axiom conclude that those operations should
+be used.
+Use \spadcmd{)set expose add constructor} and \spadcmd{)set expose drop
+constructor} to expose and hide a constructor, respectively.
+You should use the constructor name, not the abbreviation.
+The \spadcmd{)set expose} command guides you through these options.
+
+If you expose a previously hidden constructor, Axiom
+exhibits new behavior (that was your intention) though you might not
+expect the results that you get.
+\axiomType{OutputForm} is, in fact, one of the worst offenders in this
+regard.
+This domain is meant to be used by other domains for creating a
+structure that Axiom knows how to display.
+It has functions like \axiomOpFrom{+}{OutputForm} that form output
+representations rather than do mathematical calculations.
+Because of the order in which Axiom looks at constructors
+when it is deciding what operation to apply, \axiomType{OutputForm}
+might be used instead of what you expect.
+\xtc{
+This is a polynomial.
+}{
+\spadpaste{x + x}
+}
+\xtc{
+Expose \axiomType{OutputForm}.
+}{
+\spadpaste{)set expose add constructor OutputForm \bound{setexposeadd}}
+}
+\xtc{
+This is what we get when \axiomType{OutputForm} is automatically
+available.
+}{
+\spadpaste{x + x \free{setexposeadd}}
+}
+\xtc{
+Hide \axiomType{OutputForm} so we don't run into problems
+with any later examples!
+}{
+\spadpaste{)set expose drop constructor OutputForm \bound{setexposedrop}}
+}
+
+Finally, exposure is done on a frame-by-frame basis.
+A \spadgloss{frame} (see 
+\downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} 
+in Section \ugSysCmdframeNumber\ignore{ugSysCmdframe})
+is one of possibly several
+logical Axiom workspaces within a physical one, each having
+its own environment (for example, variables and function definitions).
+If you have several Axiom workspace windows on your screen, they
+are all different frames, automatically created for you by \HyperName{}.
+Frames can be manually created, made active and destroyed by the
+\spadcmd{)frame} system command.
+They do not share exposure information, so you need to use
+\spadcmd{)set expose} in each one to add or drop constructors from view.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug02.ht>>=
+\newcommand{\ugAvailSnoopTitle}{Commands for Snooping}
+\newcommand{\ugAvailSnoopNumber}{2.12.}
+
+@
+\section{Commands for Snooping}
+\label{ugAvailSnoopPage}
+\begin{itemize}
+\item ugBrowsePage \ref{ugBrowsePage} on
+page~\pageref{ugBrowsePage}
+\item ComplexXmpPage \ref{ComplexXmpPage} on
+page~\pageref{ComplexXmpPage}
+\item ugUserDeclarePage \ref{ugUserDeclarePage} on
+page~\pageref{ugUserDeclarePage}
+\end{itemize}
+\index{pages!ugAvailSnoopPage!ug02.ht}
+\index{ug02.ht!pages!ugAvailSnoopPage}
+\index{ugAvailSnoopPage!ug02.ht!pages}
+<<ug02.ht>>=
+\begin{page}{ugAvailSnoopPage}{2.12. Commands for Snooping}
+\beginscroll
+
+To conclude this chapter, we introduce you to some system commands
+that you can use for getting more information about domains,
+packages, categories, and operations.
+The most powerful Axiom facility for getting information about
+constructors and operations is the \Browse{} component of \HyperName{}.
+This is discussed in \downlink{``\ugBrowseTitle''}{ugBrowsePage} 
+in Chapter \ugBrowseNumber\ignore{ugBrowse}.
+
+Use the \spadsys{)what} system command to see lists of system objects
+whose name contain a particular substring (uppercase or lowercase is
+not significant).
+
+\xtc{
+Issue this to see a list of all operations with
+``{\tt complex}'' in their names.
+}{
+\spadpaste{)what operation complex}
+}
+\xtc{
+If you want to see all domains with ``{\tt matrix}'' in their names, issue
+this.
+}{
+\spadpaste{)what domain matrix}
+}
+\xtc{
+Similarly, if you wish to see all packages whose names contain
+``{\tt gauss}'', enter this.
+}{
+\spadpaste{)what package gauss}
+}
+\xtc{
+This command shows all
+the operations that \axiomType{Any} provides.
+Wherever \axiomSyntax{\$} appears, it means ``\axiomType{Any}''.
+}{
+\spadpaste{)show Any}
+}
+\xtc{
+This displays all operations with the name \axiomFun{complex}.
+}{
+\spadpaste{)display operation complex}
+}
+Let's analyze this output.
+\xtc{
+First we find out what some of the abbreviations mean.
+}{
+\spadpaste{)abbreviation query COMPCAT}
+}
+\xtc{
+}{
+\spadpaste{)abbreviation query COMRING}
+}
+
+So if \axiom{D1} is a commutative ring (such as the integers or
+floats) and \axiom{D} belongs to \axiomType{ComplexCategory
+D1}, then there is an operation called \axiomFun{complex} that
+takes two elements of \axiom{D1} and creates an element of
+\axiom{D}.
+The primary example of a constructor implementing domains
+belonging to \axiomType{ComplexCategory} is \axiomType{Complex}.
+See \downlink{`Complex'}{ComplexXmpPage}\ignore{Complex} 
+for more information on that and see
+\downlink{``\ugUserDeclareTitle''}{ugUserDeclarePage} in 
+Section \ugUserDeclareNumber\ignore{ugUserDeclare} 
+for more information on function types.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\chapter{Users Guide Chapter 3 (ug03.ht)}
+<<ug03.ht>>=
+\newcommand{\ugHyperTitle}{Using \HyperName{}}
+\newcommand{\ugHyperNumber}{3.}
+
+@
+\section{Using \HyperName{}}
+\label{ugHyperPage}
+\begin{itemize}
+\item YouTriedIt \ref{YouTriedIt} on
+page~\pageref{YouTriedIt}
+\item ugHyperHeadingsPage \ref{ugHyperHeadingsPage} on
+page~\pageref{ugHyperHeadingsPage}
+\item ugHyperKeysPage \ref{ugHyperKeysPage} on
+page~\pageref{ugHyperKeysPage}
+\item ugHyperScrollPage \ref{ugHyperScrollPage} on
+page~\pageref{ugHyperScrollPage}
+\item ugHyperInputPage \ref{ugHyperInputPage} on
+page~\pageref{ugHyperInputPage}
+\item ugHyperButtonsPage \ref{ugHyperButtonsPage} on
+page~\pageref{ugHyperButtonsPage}
+\item ugHyperSearchPage \ref{ugHyperSearchPage} on
+page~\pageref{ugHyperSearchPage}
+\item ugHyperExamplePage \ref{ugHyperExamplePage} on
+page~\pageref{ugHyperExamplePage}
+\item ugHyperResourcesPage \ref{ugHyperResourcesPage} on
+page~\pageref{ugHyperResourcesPage}
+\end{itemize}
+\index{pages!ugHyperPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperPage}
+\index{ugHyperPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperPage}{3. Using \HyperName{}}
+\beginscroll
+
+
+\HyperName{} is the gateway to Axiom.
+It's both an on-line tutorial and an on-line reference manual.
+It also enables you to use Axiom simply by using the mouse and
+filling in templates.
+\HyperName{} is available to you if you are running Axiom under the
+X Window System.
+
+Pages usually have active areas, marked in
+\texht{{\bf this font} (bold face).}{\downlink{this font.}{YouTriedIt}}
+As you move the mouse pointer to an active area, the pointer changes from
+a filled dot to an open circle.
+The active areas are usually linked to other pages.
+When you click on an active area, you move to the linked page.
+\texht{}{Try clicking \downlink{here}{YouTriedIt} now.}
+
+We suggest that you learn more about other features of
+\HyperName{} by clicking on an active area in the menu below.
+
+\beginmenu
+    \menudownlink{{3.1. Headings}}{ugHyperHeadingsPage}
+    \menudownlink{{3.2. Key Definitions}}{ugHyperKeysPage}
+    \menudownlink{{3.3. Scroll Bars}}{ugHyperScrollPage}
+    \menudownlink{{3.4. Input Areas}}{ugHyperInputPage}
+    \menudownlink{{3.5. Radio Buttons and Toggles}}{ugHyperButtonsPage}
+    \menudownlink{{3.6. Search Strings}}{ugHyperSearchPage}
+    \menudownlink{{3.7. Example Pages}}{ugHyperExamplePage}
+    \menudownlink{{3.8. X Window Resources for \HyperName{}}}{ugHyperResourcesPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperHeadingsTitle}{Headings}
+\newcommand{\ugHyperHeadingsNumber}{3.1.}
+
+@
+\section{Headings}
+\label{ugHyperHeadingsPage}
+\index{pages!ugHyperHeadingsPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperHeadingsPage}
+\index{ugHyperHeadingsPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperHeadingsPage}{3.1. Headings}
+\beginscroll
+%
+Most pages have a standard set of buttons at the top of the page.
+This is what they mean:
+
+\indent{0}
+\beginitems
+\item[\StdHelpButton{}] Click on this to get help.
+The button only appears if there is specific help for the page you are
+viewing.
+You can get {\it general} help for \HyperName{} by clicking the help
+button on the home page.
+
+\item[\UpButton{}] Click here to go back one page.
+By clicking on this button repeatedly, you can go back several pages and
+then take off in a new direction.
+
+\item[\ReturnButton{}] Go back to the home page, that is,
+the page on which you started.
+Use \HyperName{} to explore, to make forays into new topics.
+Don't worry about how to get back.
+\HyperName{} remembers where you came from.
+Just click on this button to return.
+
+\item[\StdExitButton{}] From the root window (the one that is displayed when
+you start the system) this button leaves the \HyperName{} program, and it
+must be restarted if you want to use it again.
+From any other \HyperName{} window, it just makes that one window go away.
+You {\it must} use this button to get rid of a window.
+If you use the window manager ``Close'' button, then all of \HyperName{}
+goes away.
+\enditems
+\indent{0}
+%
+The buttons are not displayed if they are not applicable to the page
+you are viewing.
+For example, there is no \ReturnButton{} button on the top-level menu.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperKeysTitle}{Key Definitions}
+\newcommand{\ugHyperKeysNumber}{3.2.}
+
+@
+\section{Key Definitions}
+\label{ugHyperKeysPage}
+\begin{itemize}
+\item ugHyperScrollPage \ref{ugHyperScrollPage} on
+page~\pageref{ugHyperScrollPage}
+\item ugHyperInputPage \ref{ugHyperInputPage} on
+page~\pageref{ugHyperInputPage}
+\end{itemize}
+\index{pages!ugHyperKeysPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperKeysPage}
+\index{ugHyperKeysPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperKeysPage}{3.2. Key Definitions}
+\beginscroll
+
+The following keyboard definitions are in effect throughout
+\HyperName{}.
+See \downlink{``\ugHyperScrollTitle''}{ugHyperScrollPage} 
+in Section \ugHyperScrollNumber\ignore{ugHyperScroll} and
+\downlink{``\ugHyperInputTitle''}{ugHyperInputPage} 
+in Section \ugHyperInputNumber\ignore{ugHyperInput}
+for some contextual key definitions.
+%
+\indent{0}
+\beginitems
+\item[F1] Display the main help page.
+\item[F3] Same as \StdExitButton{}, makes the window go away if you are 
+not at the top-level window or quits the \HyperName{} facility if you are 
+at the top-level.
+\item[F5] Rereads the \HyperName{} database, if necessary (for system 
+developers).
+\item[F9] Displays this information about key definitions.
+\item[F12] Same as {\bf F3}.
+\item[Up Arrow] Scroll up one line.
+\item[Down Arrow] Scroll down one line.
+\item[Page Up] Scroll up one page.
+\item[Page Down] Scroll down one page.
+\enditems
+\indent{0}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperScrollTitle}{Scroll Bars}
+\newcommand{\ugHyperScrollNumber}{3.3.}
+
+@
+\section{Scroll Bars}
+\label{ugHyperScrollPage}
+\begin{itemize}
+\item ugHyperInputPage \ref{ugHyperInputPage} on
+page~\pageref{ugHyperInputPage}
+\end{itemize}
+\index{pages!ugHyperScrollPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperScrollPage}
+\index{ugHyperScrollPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperScrollPage}{3.3. Scroll Bars}
+\beginscroll
+%
+
+Whenever there is too much text to fit on a page, a {\it scroll
+bar} automatically appears along the right side.
+
+With a scroll bar, your page becomes an aperture, that is, a
+window into a larger amount of text than can be displayed at one
+time.
+The scroll bar lets you move up and down in the text to see
+different parts.
+It also shows where the aperture is relative to the whole text.
+The aperture is indicated by a strip on the scroll bar.
+
+Move the cursor with the mouse to the ``down-arrow'' at the bottom
+of the scroll bar and click.
+See that the aperture moves down one line.
+Do it several times.
+Each time you click, the aperture moves down one line.
+Move the mouse to the ``up-arrow'' at the top of the scroll bar and
+click.
+The aperture moves up one line each time you click.
+
+Next move the mouse to any position along the middle of the scroll bar and
+click.
+\HyperName{} attempts to move the top of the aperture to this point in
+the text.
+
+You cannot make the aperture go off the bottom edge.
+When the aperture is about half the size of text, the lowest you can move
+the aperture is halfway down.
+
+To move up or down one screen at a time, use the
+\texht{\fbox{\bf PageUp}}{{\bf PageUp}} and \texht{\fbox{\bf PageDown}}{{\bf
+PageDown}} keys on your keyboard.
+They move the visible part of the region up and down one page each time you
+press them.
+
+If the \HyperName{} page does not contain an input area
+(see \downlink{``\ugHyperInputTitle''}{ugHyperInputPage} 
+in Section \ugHyperInputNumber\ignore{ugHyperInput}), you can also use the
+\texht{\fbox{\bf Home}}{{\bf Home}} and
+\texht{\fbox{$\uparrow$}}{up} and
+\texht{\fbox{$\downarrow$}}{down} arrow keys to navigate.
+When you press the \texht{\fbox{\bf Home}}{{\bf Home}} key,
+the screen is positioned at the very top of the page.
+Use the \texht{\fbox{$\uparrow$}}{up} and
+\texht{\fbox{$\downarrow$}}{down} arrow keys to move the screen up
+and down one line at a time, respectively.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperInputTitle}{Input Areas}
+\newcommand{\ugHyperInputNumber}{3.4.}
+
+@
+\section{Input Areas}
+\label{ugHyperInputPage}
+\index{pages!ugHyperInputPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperInputPage}
+\index{ugHyperInputPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperInputPage}{3.4. Input Areas}
+\beginscroll
+%
+Input areas are boxes where you can put data.
+Here is one:
+\centerline{\inputstring{one}{40}{some text}}
+\newline As you can see, the input area has some initial text {\it some text}
+followed by an underscore cursor (the character {\it _}).
+
+To enter characters, first
+move your mouse cursor to somewhere within the \HyperName{} page.
+Characters that you type are inserted in front of the underscore.
+This means that when you type characters at your keyboard, they
+go into this first input area.
+
+The input area grows to accommodate as many characters as you type.
+Use the \texht{\fbox{\bf Backspace}}{{\bf Backspace}}
+key to erase characters to the left.
+To modify what you type, use the right-arrow \texht{\fbox{$\rightarrow$}}{}
+and left-arrow keys \texht{\fbox{$\leftarrow$}}{} and the
+keys \texht{\fbox{\bf Insert}}{{\bf Insert}},
+\texht{\fbox{\bf Delete}}{{\bf Delete}},
+\texht{\fbox{\bf Home}}{{\bf Home}} and
+\texht{\fbox{\bf End}}{{\bf End}}.
+These keys are found immediately on the right of the standard IBM keyboard.
+
+If you press the
+\texht{\fbox{\bf Home}}{{\bf Home}}
+key, the cursor moves to the beginning of the line and if you press the
+\texht{\fbox{\bf End}}{{\bf End}}
+key, the cursor moves to the end of the line.
+Pressing
+\texht{\fbox{\bf Ctrl}--\fbox{\bf End}}{{\bf Ctrl-End}}
+deletes all the text from the cursor to the end of the line.
+
+A page may have more than one input area.
+Only one input area has an underscore cursor.
+When you first see apage, the top-most input area contains the
+cursor.
+To type information into another input area,
+use the \texht{\fbox{\bf Enter}}{{\bf Enter}} or
+\texht{\fbox{\bf Tab}}{{\bf Tab}} key to move
+from one input area to another.
+To move in the reverse order, use
+\texht{\fbox{\bf Shift}--\fbox{\bf Tab}}{{\bf Shift-Tab}}.
+
+You can also move from one input area to another using your mouse.
+Notice that each input area is active. Click on one of the areas.
+As you can see, the underscore cursor moves to that window.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperButtonsTitle}{Radio Buttons and Toggles}
+\newcommand{\ugHyperButtonsNumber}{3.5.}
+
+@
+\section{Radio Buttons and Toggles}
+\label{ugHyperButtonsPage}
+\index{pages!ugHyperButtonsPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperButtonsPage}
+\index{ugHyperButtonsPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperButtonsPage}{3.5. Radio Buttons and Toggles}
+\beginscroll
+%
+Some pages have {\it radio buttons} and {\it toggles}.
+Radio buttons are a group of buttons like those on car radios: you can
+select only one at a time.
+\radioboxes{sample}{\htbmfile{pick}}{\htbmfile{unpick}}
+Here are three radio buttons:
+\centerline{
+{\em\radiobox[1]{rone}{sample}\space{}\ First one}\space{3}
+{\em\radiobox[0]{rtwo}{sample}\space{}\ Second one}\space{3}
+{\em\radiobox[0]{rthree}{sample}\space{}\ Third one}
+}
+\newline
+Once you have selected a button, it appears to be inverted and
+contains a checkmark.
+To change the selection, move the cursor with the mouse to a different radio
+button and click.
+\texht{}{Try it now.}
+
+A toggle is an independent button that displays some on/off
+state.
+When ``on'', the button appears to be inverted and
+contains a checkmark.
+When ``off'', the button is raised.
+%
+Unlike radio buttons, you can set a group of them any way you like.
+Here are three:
+\centerline{
+{\em\inputbox[1]{one}{\htbmfile{pick}}{\htbmfile{unpick}}\space{}\ First one}
+\space{3}
+{\em\inputbox[0]{two}{\htbmfile{pick}}{\htbmfile{unpick}}\space{}\ Second one}
+\space{3}
+{\em\inputbox[1]{three}{\htbmfile{pick}}{\htbmfile{unpick}}\space{}\ Third one}
+}
+\newline
+To change toggle the selection, move the cursor with the mouse
+to the button and click.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperSearchTitle}{Search Strings}
+\newcommand{\ugHyperSearchNumber}{3.6.}
+
+@
+\section{Search Strings}
+\label{ugHyperSearchPage}
+\begin{itemize}
+\item ugLogicalSearchesPage \ref{ugLogicalSearchesPage} on
+page~\pageref{ugLogicalSearchesPage}
+\end{itemize}
+\index{pages!ugHyperSearchPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperSearchPage}
+\index{ugHyperSearchPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperSearchPage}{3.6. Search Strings}
+\beginscroll
+%
+A {\it search string} is used for searching some database.
+To learn about search strings, we suggest that
+you bring up the \HyperName{} glossary.
+To do this from the top-level page of \HyperName{}:
+\indent{4}
+\beginitems
+\item[1. ] Click on \windowlink{Reference}{TopReferencePage},
+bringing up the Axiom Reference page.
+\item[2. ] Click on \windowlink{Glossary}{GlossaryPage}, bringing up the glossary.
+\texht{}{(You can also just click on the word ``Glossary'' in the
+last sentence.)}
+\enditems
+\indent{0}
+Once you get the window containing the glossary, move it so that
+it and this window are both visible.
+
+The glossary has an input area at its bottom.
+We review the various kinds of search strings
+you can enter to search the glossary.
+
+The simplest search string is a word, for example, {\tt operation}.
+A word only matches an entry having exactly that spelling.
+Enter the word {\tt operation} into the input area above then click on
+{\bf Search}.
+As you can see, {\tt operation} matches only one entry, namely with {\tt
+operation} itself.
+
+Normally matching is insensitive to whether the alphabetic characters of your
+search string are in uppercase or lowercase.
+Thus {\tt operation} and {\tt OperAtion} both have the same effect.
+%If you prefer that matching be case-sensitive, issue the command
+%\spadsys{set HHyperName mixedCase} command to the interpreter.
+
+You will very often want to use the wildcard \spadSyntax{*} in your search
+string so as to match multiple entries in the list.
+The search key \spadSyntax{*}  matches every entry in the list.
+You can also use \spadSyntax{*} anywhere within a search string to match an
+arbitrary substring.
+Try {\tt cat*} for example:
+enter {\tt cat*} into the input area and click on {\bf Search}.
+This matches several entries.
+
+You use any number of wildcards in a search string as long as they are
+not adjacent.
+Try search strings such as {\tt *dom*}.
+As you see, this search string  matches {\tt domain}, {\tt domain
+constructor}, {\tt subdomain}, and so on.
+
+\beginmenu
+    \menudownlink{{3.6.1. Logical Searches}}{ugLogicalSearchesPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugLogicalSearchesTitle}{Logical Searches}
+\newcommand{\ugLogicalSearchesNumber}{3.6.1.}
+
+@
+\section{Logical Searches}
+\label{ugLogicalSearchesPage}
+\index{pages!ugLogicalSearchesPage!ug03.ht}
+\index{ug03.ht!pages!ugLogicalSearchesPage}
+\index{ugLogicalSearchesPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugLogicalSearchesPage}{3.6.1. Logical Searches}
+\beginscroll
+
+For more complicated searches, you can use
+\spadSyntax{and}, \spadSyntax{or}, and \spadSyntax{not}
+with basic search strings;
+write logical expressions using these three operators just as
+in the Axiom language.
+For example, {\tt domain or package}  matches the two
+entries {\tt domain} and {\tt package}.
+Similarly, {\tt dom* and *con*} matches {\tt domain constructor}
+and others.
+Also {\tt not *a*} matches every entry that does not contain
+the letter {\tt a} somewhere.
+
+Use parentheses for grouping.
+For example, {\tt dom* and (not *con*)}
+matches {\tt domain} but not {\tt domain constructor}.
+
+There is no limit to how complex your logical expression can be.
+For example,
+\centerline{{{\tt a* or b* or c* or d* or e* and (not *a*)}}}
+is a valid expression.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperExampleTitle}{Example Pages}
+\newcommand{\ugHyperExampleNumber}{3.7.}
+
+@
+\section{Example Pages}
+\label{ugHyperExamplePage}
+\index{pages!ugHyperExamplePage!ug03.ht}
+\index{ug03.ht!pages!ugHyperExamplePage}
+\index{ugHyperExamplePage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperExamplePage}{3.7. Example Pages}
+\beginscroll
+%
+Many pages have Axiom example commands.
+%
+Here are two:
+\spadpaste{a:= x**2 + 1 \bound{a}} 
+\spadpaste{(a - 2)**2 \free{a}} 
+%
+Each command has an active ``button'' along the left margin.
+When you click on this button, the output for the command is
+``pasted-in.''
+Click again on the button and you see that the pasted-in output
+disappears.
+
+Maybe you would like to run an example?
+To do so, just click on any part of its text!
+When you do, the example line is copied into a new interactive
+Axiom buffer for this \HyperName{} page.
+
+Sometimes one example line cannot be run before you run an earlier one.
+Don't worry---\HyperName{} automatically runs all the necessary
+lines in the right order!
+For instance, the second example line above refers to \spad{a} which is
+assigned in the first example line.
+What happens if you first click on the second example line?
+Axiom first issues the first line (to assign \spad{a}), then the
+second (to do the computation using \spad{a}).
+
+The new interactive Axiom buffer disappears when you leave
+\HyperName{}.
+If you want to get rid of it beforehand,
+use the {\bf Cancel} button of the X Window manager
+or issue the Axiom system command \spadsys{)close.}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug03.ht>>=
+\newcommand{\ugHyperResourcesTitle}{X Window Resources for \HyperName{}}
+\newcommand{\ugHyperResourcesNumber}{3.8.}
+
+@
+\section{X Window Resources for \HyperName{}}
+\label{ugHyperResourcesPage}
+\index{pages!ugHyperResourcesPage!ug03.ht}
+\index{ug03.ht!pages!ugHyperResourcesPage}
+\index{ugHyperResourcesPage!ug03.ht!pages}
+<<ug03.ht>>=
+\begin{page}{ugHyperResourcesPage}{3.8. X Window Resources for \HyperName{}}
+\beginscroll
+%
+You can control the appearance of \HyperName{} while running under Version 11
+of the X Window System by placing the following resources
+in the file {\bf .Xdefaults} in your home directory.
+In what follows, {\it font} is any valid X11 font name
+(for example, {\tt Rom14}) and {\it color} is any valid X11 color
+specification (for example, {\tt NavyBlue}).
+For more information about fonts and colors, refer to the
+X Window documentation for your system.
+\indent{0}
+\beginitems
+\item[{\tt Axiom.hyperdoc.RmFont:} {\it font}] \ \newline
+This is the standard text font.  \xdefault{Rom14}
+\item[{\tt Axiom.hyperdoc.RmColor:} {\it color}] \ \newline
+This is the standard text color.  \xdefault{black}
+\item[{\tt Axiom.hyperdoc.ActiveFont:} {\it font}] \ \newline
+This is the font used for \HyperName{} link buttons.  \xdefault{Bld14}
+\item[{\tt Axiom.hyperdoc.ActiveColor:} {\it color}] \ \newline
+This is the color used for \HyperName{} link buttons.  \xdefault{black}
+\item[{\tt Axiom.hyperdoc.AxiomFont:} {\it font}] \ \newline
+This is the font used for active Axiom commands.\footnote{
+This was called {\tt Axiom.hyperdoc.SpadFont} in early versions
+of Axiom.}
+\xdefault{Bld14}
+\item[{\tt Axiom.hyperdoc.AxiomColor:} {\it color}] \ \newline
+This is the color used for active Axiom commands.\footnote{
+This was called {\tt Axiom.hyperdoc.SpadColor} in early versions
+of Axiom.}
+\xdefault{black}
+\item[{\tt Axiom.hyperdoc.BoldFont:} {\it font}] \ \newline
+This is the font used for bold face.  \xdefault{Bld14}
+\item[{\tt Axiom.hyperdoc.BoldColor:} {\it color}] \ \newline
+This is the color used for bold face.  \xdefault{black}
+\item[{\tt Axiom.hyperdoc.TtFont:} {\it font}] \ \newline
+This is the font used for Axiom output in \HyperName{}.
+This font must be fixed-width.  \xdefault{Rom14}
+\item[{\tt Axiom.hyperdoc.TtColor:} {\it color}] \ \newline
+This is the color used for Axiom output in \HyperName{}.
+\xdefault{black}
+\item[{\tt Axiom.hyperdoc.EmphasizeFont:} {\it font}] \ \newline
+This is the font used for italics.  \xdefault{Itl14}
+\item[{\tt Axiom.hyperdoc.EmphasizeColor:} {\it color}] \ \newline
+This is the color used for italics.  \xdefault{black}
+\item[{\tt Axiom.hyperdoc.InputBackground:} {\it color}] \ \newline
+This is the color used as the background for input areas.
+\xdefault{black}
+\item[{\tt Axiom.hyperdoc.InputForeground:} {\it color}] \ \newline
+This is the color used as the foreground for input areas.
+\xdefault{white}
+\item[{\tt Axiom.hyperdoc.BorderColor:} {\it color}] \ \newline
+This is the color used for drawing border lines.
+\xdefault{black}
+\item[{\tt Axiom.hyperdoc.Background:} {\it color}] \ \newline
+This is the color used for the background of all windows.
+\xdefault{white}
+\enditems
+\indent{0}
+\endscroll
+\autobuttons
+\end{page}
+@
+\chapter{Users Guide Chapter 4 (ug04.ht)}
+<<ug04.ht>>=
+\newcommand{\ugInOutTitle}{Input Files and Output Styles}
+\newcommand{\ugInOutNumber}{4.}
+
+@
+\section{Input Files and Output Styles}
+\label{ugInOutPage}
+\begin{itemize}
+\item ugInOutInPage \ref{ugInOutInPage} on
+page~\pageref{ugInOutInPage}
+\item ugInOutSpadprofPage \ref{ugInOutSpadprofPage} on
+page~\pageref{ugInOutSpadprofPage}
+\item ugInOutOutPage \ref{ugInOutOutPage} on
+page~\pageref{ugInOutOutPage}
+\item ugInOutAlgebraPage \ref{ugInOutAlgebraPage} on
+page~\pageref{ugInOutAlgebraPage}
+\item ugInOutTeXPage \ref{ugInOutTeXPage} on
+page~\pageref{ugInOutTeXPage}
+\item ugInOutScriptPage \ref{ugInOutScriptPage} on
+page~\pageref{ugInOutScriptPage}
+\item ugInOutFortranPage \ref{ugInOutFortranPage} on
+page~\pageref{ugInOutFortranPage}
+\end{itemize}
+\index{pages!ugInOutPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutPage}
+\index{ugInOutPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutPage}{4. Input Files and Output Styles}
+\beginscroll
+
+In this chapter we discuss how to collect Axiom statements
+and commands into files and then read the contents into the
+workspace.
+We also show how to display the results of your computations in
+several different styles including \texht{\TeX}{TeX}, FORTRAN and
+monospace two-dimensional format.\footnote{\texht{\TeX}{TeX} is a
+trademark of the American Mathematical Society.}
+
+The printed version of this book uses the Axiom
+\texht{\TeX}{TeX} output formatter.
+When we demonstrate a particular output style, we will need to
+turn \texht{\TeX}{TeX} formatting off and the output style on so
+that the correct output is shown in the text.
+
+\beginmenu
+    \menudownlink{{4.1. Input Files}}{ugInOutInPage}
+    \menudownlink{{4.2. The axiom.input File}}{ugInOutSpadprofPage}
+    \menudownlink{{4.3. Common Features of Using Output Formats}}
+{ugInOutOutPage}
+    \menudownlink{{4.4. Monospace Two-Dimensional Mathematical Format}}
+{ugInOutAlgebraPage}
+    \menudownlink{{4.5. TeX Format}}{ugInOutTeXPage}
+    \menudownlink{{4.6. IBM Script Formula Format}}{ugInOutScriptPage}
+    \menudownlink{{4.7. FORTRAN Format}}{ugInOutFortranPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutInTitle}{Input Files}
+\newcommand{\ugInOutInNumber}{4.1.}
+
+@
+\section{Input Files}
+\label{ugInOutInPage}
+\begin{itemize}
+\item ugLangBlocksPage \ref{ugLangBlocksPage} on
+page~\pageref{ugLangBlocksPage}
+\end{itemize}
+\index{pages!ugInOutInPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutInPage}
+\index{ugInOutInPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutInPage}{4.1. Input Files}
+\beginscroll
+%
+In this section we explain what an {\it input file} is and
+why you would want to know about it.
+We discuss where Axiom looks for input files and how you can
+direct it to look elsewhere.
+We also show how to read the contents of an input file into the
+\spadgloss{workspace} and how to use the \spadgloss{history}
+facility to generate an input file from the statements you have
+entered directly into the workspace.
+
+An {\it input} file contains Axiom expressions and system
+commands.
+Anything that you can enter directly to Axiom can be put
+into an input file.
+This is how you save input functions and expressions that you wish
+to read into Axiom more than one time.
+
+To read an input file into Axiom, use the \spadcmd{)read}
+system command.
+For example, you can read a file in a particular directory by issuing
+\begin{verbatim}
+)read /spad/src/input/matrix.input
+\end{verbatim}
+The ``{\bf .input}'' is optional; this also works:
+\begin{verbatim}
+)read /spad/src/input/matrix
+\end{verbatim}
+What happens if you just enter
+\spadcmd{)read matrix.input} or even \spadcmd{)read matrix}?
+Axiom looks in your current working directory for input files
+that are not qualified by a directory name.
+Typically, this directory is the directory from which you invoked
+Axiom.
+To change the current working directory, use the \spadcmd{)cd} system command.
+The command \spadsys{)cd} by itself shows the current
+working
+directory.
+To change it to
+the \spadsys{src/input} subdirectory for user ``babar'',
+issue
+\begin{verbatim}
+)cd /u/babar/src/input
+\end{verbatim}
+Axiom looks first in this directory for an input file.
+If it is not found, it looks in the system's directories, assuming
+you meant some input file that was provided with Axiom.
+
+\beginImportant
+If you have the Axiom history facility turned on (which it is
+by default), you can save all the lines you have entered into the
+workspace by entering
+\begin{verbatim}
+)history )write
+\end{verbatim}
+
+Axiom tells you what input file to edit to see your
+statements.
+The file is in your home directory or in the directory you
+specified with \spadsys{)cd}.
+\endImportant
+
+In \downlink{``\ugLangBlocksTitle''}{ugLangBlocksPage} 
+in Section \ugLangBlocksNumber\ignore{ugLangBlocks}
+we discuss using indentation in input files to group statements
+into {\it blocks.}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutSpadprofTitle}{The axiom.input File}
+\newcommand{\ugInOutSpadprofNumber}{4.2.}
+
+@
+\section{The axiom.input File}
+\label{ugInOutSpadprofPage}
+\index{pages!ugInOutSpadprofPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutSpadprofPage}
+\index{ugInOutSpadprofPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutSpadprofPage}{4.2. The axiom.input File}
+\beginscroll
+
+When Axiom starts up, it tries to read the input file
+{\bf axiom.input} from your home
+directory.
+It there is no {\bf axiom.input} in your home directory, it reads the copy
+located in its own {\bf src/input} directory.
+The file usually contains
+system commands to personalize your Axiom environment.
+In the remainder of this section we mention a few things
+that users frequently place in their
+{\bf axiom.input} files.
+
+In order to have FORTRAN output always produced from your
+computations, place the system command
+\spadcmd{)set output fortran on}
+in {\bf axiom.input}.
+If you do not want to be prompted for confirmation when you issue
+the \spadcmd{)quit} system command, place
+\spadcmd{)set quit unprotected}
+in {\bf axiom.input}.
+If you then decide that you do want to be prompted, issue
+\spadcmd{)set quit protected}.
+This is the default setting
+so that new users do not leave Axiom
+inadvertently.\footnote{The
+system command \spadsys{)pquit} always prompts you for
+confirmation.}
+
+To see the other system variables you can set, issue \spadsys{)set}
+or use the \HyperName{} {\bf Settings} facility to view and change
+Axiom system variables.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutOutTitle}{Common Features of Using Output Formats}
+\newcommand{\ugInOutOutNumber}{4.3.}
+
+@
+\section{Common Features of Using Output Formats}
+\label{ugInOutOutPage}
+\index{pages!ugInOutOutPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutOutPage}
+\index{ugInOutOutPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutOutPage}{4.3. Common Features of Using Output Formats}
+\beginscroll
+
+In this section we discuss how to start and stop the display
+of the different output formats and how to send the output to the
+screen or to a file.
+To fix ideas, we use FORTRAN output format for most of the
+examples.
+
+You can use the \spadcmd{)set output}
+system
+command to
+toggle or redirect the different kinds of output.
+The name of the kind of output follows ``output'' in the command.
+The names are
+
+\indent{0}
+\beginitems
+\item[fortran]  for FORTRAN output.
+\item[algebra]  for monospace two-dimensional mathematical output.
+\item[tex]      for \texht{\TeX}{TeX} output.
+\item[script]   for IBM Script Formula Format output.
+\enditems
+\indent{0}
+
+For example, issue \spadsys{)set output fortran on} to turn on
+FORTRAN format and
+issue \spadsys{)set output fortran off} to turn it off.
+By default, {\tt algebra} is {\tt on} and all others are {\tt off}.
+When output is started, it is sent to the screen.
+To send the output to a file, give the file name without
+directory or extension.
+Axiom appends a file extension depending on the kind of
+output being produced.
+\xtc{
+Issue this to redirect FORTRAN output to, for example, the file
+{\bf linalg.sfort}.
+}{
+\spadpaste{)set output fortran linalg}
+}
+\noOutputXtc{
+You must {\it also} turn on the creation of FORTRAN output.
+The above just says where it goes if it is created.
+}{
+\spadpaste{)set output fortran on}
+}
+In what directory is this output placed?
+It goes into the directory from which you started Axiom,
+or if you have used the \spadsys{)cd} system command, the one
+that you specified with \spadsys{)cd}.
+You should use \spadcmd{)cd} before you send the output to the file.
+
+\noOutputXtc{
+You can always direct output back to the screen by issuing this.
+}{
+\spadpaste{)set output fortran console}
+}
+\noOutputXtc{
+Let's make sure FORTRAN formatting is off so that nothing we
+do from now on produces FORTRAN output.
+}{
+\spadpaste{)set output fortran off}
+}
+\noOutputXtc{
+We also delete the demonstrated output file we created.
+}{
+\spadpaste{)system rm linalg.sfort}
+}
+
+You can abbreviate the words ``\spad{on},'' ``\spad{off}'' and
+``\spad{console}'' to the minimal number
+of characters needed to distinguish them.
+Because of this, you cannot send output to files called
+{\bf on.sfort, off.sfort, of.sfort,
+console.sfort, consol.sfort} and so on.
+
+The width of the output on the page is set by
+\spadcmd{)set output length}
+for all formats except FORTRAN.
+Use \spadcmd{)set fortran fortlength} to
+change the FORTRAN line length from its default value of \spad{72}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutAlgebraTitle}{Monospace Two-Dimensional Mathematical Format}
+\newcommand{\ugInOutAlgebraNumber}{4.4.}
+
+@
+\section{Monospace Two-Dimensional Mathematical Format}
+\label{ugInOutAlgebraPage}
+\index{pages!ugInOutAlgebraPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutAlgebraPage}
+\index{ugInOutAlgebraPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutAlgebraPage}
+{4.4. Monospace Two-Dimensional Mathematical Format}
+\beginscroll
+
+This is the default output format for Axiom.
+It is usually on when you start the system.
+
+\texht{\vskip 4pc}{}
+\noOutputXtc{
+If it is not, issue this.
+}{
+\spadpaste{)set output algebra on \bound{algon}}
+}
+\noOutputXtc{
+Since the printed version of this book
+(as opposed to the \HyperName{} version)
+shows output produced by the
+\texht{\TeX}{TeX}{} output formatter,
+let us temporarily turn off
+\texht{\TeX}{TeX}{} output.
+}{
+\spadpaste{)set output tex off \bound{texoff}}
+}
+\xtc{
+Here is an example of what it looks like.
+}{
+\spadpaste{matrix [[i*x**i + j*\%i*y**j for i in 1..2] for j in 3..4] \free{algon texoff}}
+}
+\noOutputXtc{
+Issue this to turn off this kind of formatting.
+}{
+\spadpaste{)set output algebra off}
+}
+\noOutputXtc{
+Turn \texht{\TeX}{TeX}{} output on again.
+}{
+\spadpaste{)set output tex on}
+}
+
+The characters used for the matrix brackets above are rather ugly.
+You get this character set when you issue
+\spadcmd{)set output characters plain}.
+This character set should be used when you are running on a machine
+that does not support the IBM extended ASCII character set.
+If you are running on an IBM workstation, for example, issue
+\spadcmd{)set output characters default}
+to get better looking output.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutTeXTitle}{TeX Format}
+\newcommand{\ugInOutTeXNumber}{4.5.}
+
+@
+\section{TeX Format}
+\label{ugInOutTeXPage}
+\index{pages!ugInOutTeXPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutTeXPage}
+\index{ugInOutTeXPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutTeXPage}{4.5. TeX Format}
+\beginscroll
+
+Axiom can produce \texht{\TeX}{TeX}{} output for your
+expressions.
+The output is produced using macros from the
+\texht{\LaTeX}{LaTeX} document preparation system by
+Leslie Lamport.\footnote{See Leslie Lamport, {\it LaTeX: A Document
+Preparation System,} Reading, Massachusetts: Addison-Wesley
+Publishing Company, Inc., 1986.}
+The printed version of this book was produced using this formatter.
+
+\noOutputXtc{
+To turn on \texht{\TeX}{TeX}{} output formatting, issue this.
+}{
+\spadpaste{)set output tex on \bound{texon}}
+}
+Here is an example of its output.
+\begin{verbatim}
+matrix [[i*x**i + j*\%i*y**j for i in 1..2] for j in 3..4]
+
+\[
+\left[
+\begin{array}{cc}
+\displaystyle {{3 \  \%i \  {y \sp 3}}+x}&
+\displaystyle {{3 \  \%i \  {y \sp 3}}+{2 \  {x \sp 2}}} \\
+\displaystyle {{4 \  \%i \  {y \sp 4}}+x}&
+\displaystyle {{4 \  \%i \  {y \sp 4}}+{2 \  {x \sp 2}}}
+\end{array}
+\right]
+\leqno(3)
+\]
+%Axiom STEP NUMBER: 3
+\end{verbatim}
+To turn \texht{\TeX}{TeX}{} output formatting off, issue \spadsys{)set
+output tex off}.
+The \texht{\LaTeX}{LaTeX} macros in the output generated by Axiom
+are all standard except for the following definitions:
+\begin{verbatim}
+\def\csch{\mathop{\rm csch}\nolimits}
+
+\def\erf{\mathop{\rm erf}\nolimits}
+
+\def\zag#1#2{
+  {{\hfill \left. {#1} \right|}
+   \over
+   {\left| {#2} \right. \hfill}
+  }
+}
+\end{verbatim}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutScriptTitle}{IBM Script Formula Format}
+\newcommand{\ugInOutScriptNumber}{4.6.}
+
+@
+\section{IBM Script Formula Format}
+\label{ugInOutScriptPage}
+\index{pages!ugInOutScriptPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutScriptPage}
+\index{ugInOutScriptPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutScriptPage}{4.6. IBM Script Formula Format}
+\beginscroll
+
+Axiom can
+produce IBM Script Formula Format output for your
+expressions.
+
+\texht{\vskip 2pc}{}
+\noOutputXtc{
+To turn IBM Script Formula Format on, issue this.
+}{
+\spadpaste{)set output script on}
+}
+Here is an example of its output.
+\begin{verbatim}
+matrix [[i*x**i + j*%i*y**j for i in 1..2] for j in 3..4]
+
+.eq set blank @
+:df.
+<left lb < < < <3 @@ %i @@ <y sup 3>>+x> here < <3 @@ %i @@
+<y sup 3>>+<2 @@ <x sup 2>>>> habove < < <4 @@ %i @@
+<y sup 4>>+x> here < <4 @@ %i @@ <y sup 4>>+<2 @@
+<x up 2>>>>> right rb>
+:edf.
+\end{verbatim}
+\noOutputXtc{
+To turn IBM Script Formula Format output formatting off, issue this.
+}{
+\spadpaste{)set output script off}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug04.ht>>=
+\newcommand{\ugInOutFortranTitle}{FORTRAN Format}
+\newcommand{\ugInOutFortranNumber}{4.7.}
+
+@
+\section{FORTRAN Format}
+\label{ugInOutFortranPage}
+\index{pages!ugInOutFortranPage!ug04.ht}
+\index{ug04.ht!pages!ugInOutFortranPage}
+\index{ugInOutFortranPage!ug04.ht!pages}
+<<ug04.ht>>=
+\begin{page}{ugInOutFortranPage}{4.7. FORTRAN Format}
+\beginscroll
+
+In addition to turning FORTRAN output on and off and stating where the
+output should be placed, there are many options that control the
+appearance of the generated code.
+In this section we describe some of the basic options.
+Issue \spadcmd{)set fortran} to see a full list with their current
+settings.
+
+The output FORTRAN expression usually begins in column 7.
+If the expression needs more than one line, the ampersand character
+\spadSyntax{\&} is used in column 6.
+Since some versions of FORTRAN have restrictions on the number of lines
+per statement, Axiom breaks long expressions into segments with
+a maximum of 1320 characters (20 lines of 66 characters) per segment.
+If you want to change this, say, to 660 characters,
+issue the system command
+\spadcmd{)set fortran explength 660}.
+You can turn off the line breaking by issuing
+\spadcmd{)set fortran segment off}.
+Various code optimization levels are available.
+%
+\noOutputXtc{
+FORTRAN output is produced after you issue this.
+}{
+\spadpaste{)set output fortran on \bound{forton}}
+}
+\noOutputXtc{
+For the initial examples, we set the optimization level to 0, which is the
+lowest level.
+}{
+\spadpaste{)set fortran optlevel 0 \bound{opt0}\free{forton}}
+}
+\noOutputXtc{
+The output is usually in columns 7 through 72, although fewer columns
+are used in the following examples so that the output
+fits nicely on the page.
+}{
+\spadpaste{)set fortran fortlength 60}
+}
+\xtc{
+By default, the output goes to the screen and is displayed
+before the standard Axiom two-dimensional output.
+In this example, an
+assignment to the variable \spad{R1} was generated because this is
+the result of step 1.
+}{
+\spadpaste{(x+y)**3 \free{opt0}}
+}
+\xtc{
+Here is an example that illustrates the line breaking.
+}{
+\spadpaste{(x+y+z)**3 \free{opt0}}
+}
+
+Note in the above examples that integers are generally converted to
+floating point numbers, except in exponents.
+This is the default behavior but can be turned off by issuing
+\spadcmd{)set fortran ints2floats off}.
+The rules governing when the conversion is done are:
+\indent{4}
+\beginitems
+\item[1. ] If an integer is an exponent, convert it to a floating point
+number if it is greater than 32767 in absolute value, otherwise leave it
+as an integer.
+\item[2. ] Convert all other integers in an expression to floating
+point numbers.
+\enditems
+\indent{0}
+These rules only govern integers in expressions.
+Numbers generated by Axiom for \spad{DIMENSION} statements are also
+integers.
+
+To set the type of generated FORTRAN data,
+use one of the following:
+\begin{verbatim}
+)set fortran defaulttype REAL
+)set fortran defaulttype INTEGER
+)set fortran defaulttype COMPLEX
+)set fortran defaulttype LOGICAL
+)set fortran defaulttype CHARACTER
+\end{verbatim}
+
+\xtc{
+When temporaries are created, they are given a default type of
+{\tt REAL.}
+Also, the {\tt REAL} versions of functions are used by default.
+}{
+\spadpaste{sin(x) \free{opt1}}
+}
+\noOutputXtc{
+At optimization level 1, Axiom removes common subexpressions.
+}{
+\spadpaste{)set fortran optlevel 1 \bound{opt1}\free{forton}}
+}
+\xtc{
+}{
+\spadpaste{(x+y+z)**3 \free{opt1}}
+}
+\noOutputXtc{
+This changes the precision to {\tt DOUBLE}.
+Substitute \spad{single} for \spad{double}
+to return to single precision.
+}{
+\spadpaste{)set fortran precision double \free{opt1}\bound{double1}}
+}
+\xtc{
+Complex constants display the precision.
+}{
+\spadpaste{2.3 + 5.6*\%i  \free{double1}}
+}
+\xtc{
+The function names that Axiom generates depend on the chosen
+precision.
+}{
+\spadpaste{sin \%e  \free{double1}}
+}
+\noOutputXtc{
+Reset the precision to \spad{single} and look at these two
+examples again.
+}{
+\spadpaste{)set fortran precision single \free{opt1}\bound{single1}}
+}
+\xtc{
+}{
+\spadpaste{2.3 + 5.6*\%i  \free{single1}}
+}
+\xtc{
+}{
+\spadpaste{sin \%e  \free{single1}}
+}
+\xtc{
+Expressions that look like lists, streams, sets or matrices cause
+array code to be generated.
+}{
+\spadpaste{[x+1,y+1,z+1] \free{opt1}}
+}
+\xtc{
+A temporary variable is generated to be the name of the array.
+This may have to be changed in your particular application.
+}{
+\spadpaste{set[2,3,4,3,5] \free{opt1}}
+}
+\xtc{
+By default, the starting index for generated FORTRAN arrays is \spad{0}.
+}{
+\spadpaste{matrix [[2.3,9.7],[0.0,18.778]] \free{opt1}}
+}
+\noOutputXtc{
+To change the starting index for generated FORTRAN arrays to be \spad{1},
+issue this.
+This value can only be \spad{0} or \spad{1}.
+}{
+\spadpaste{)set fortran startindex 1 \free{opt1}\bound{start1}}
+}
+\xtc{
+Look at the code generated for the matrix again.
+}{
+\spadpaste{matrix [[2.3,9.7],[0.0,18.778]] \free{start1}}
+}
+\endscroll
+\autobuttons
+\end{page}
+@
+\chapter{Users Guide Chapter 5 (ug05.ht)}
+<<ug05.ht>>=
+\newcommand{\ugLangTitle}{Introduction to the Axiom Interactive Language}
+\newcommand{\ugLangNumber}{5.}
+
+@
+\section{Introduction to the Axiom Interactive Language}
+\label{ugLangPage}
+\begin{itemize}
+\item ugLangAssignPage \ref{ugLangAssignPage} on
+page~\pageref{ugLangAssignPage}
+\item ugLangBlocksPage \ref{ugLangBlocksPage} on
+page~\pageref{ugLangBlocksPage}
+\item ugLangIfPage \ref{ugLangIfPage} on
+page~\pageref{ugLangIfPage}
+\item ugLangLoopsPage \ref{ugLangLoopsPage} on
+page~\pageref{ugLangLoopsPage}
+\item ugLangItsPage \ref{ugLangItsPage} on
+page~\pageref{ugLangItsPage}
+\item ugLangStreamsPrimesPage \ref{ugLangStreamsPrimesPage} on
+page~\pageref{ugLangStreamsPrimesPage}
+\end{itemize}
+\index{pages!ugLangPage!ug05.ht}
+\index{ug05.ht!pages!ugLangPage}
+\index{ugLangPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangPage}{5. Introduction to the Axiom Interactive Language}
+\beginscroll
+
+In this chapter we look at some of the basic components of the
+Axiom language that you can use interactively.
+We show how to create a \spadgloss{block} of expressions,
+how to form loops and list iterations, how to modify the sequential
+evaluation of a block and how to use {\tt if-then-else} to
+evaluate parts of your program conditionally.
+We suggest you first read the boxed material in each section and then
+proceed to a more thorough reading of the chapter.
+
+\beginmenu
+    \menudownlink{{5.1. Immediate and Delayed Assignments}}{ugLangAssignPage}
+    \menudownlink{{5.2. Blocks}}{ugLangBlocksPage}
+    \menudownlink{{5.3. if-then-else}}{ugLangIfPage}
+    \menudownlink{{5.4. Loops}}{ugLangLoopsPage}
+    \menudownlink{{5.5. Creating Lists and Streams with Iterators}}
+{ugLangItsPage}
+    \menudownlink{{5.6. An Example: Streams of Primes}}
+{ugLangStreamsPrimesPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangAssignTitle}{Immediate and Delayed Assignments}
+\newcommand{\ugLangAssignNumber}{5.1.}
+
+@
+\section{Immediate and Delayed Assignments}
+\label{ugLangAssignPage}
+\begin{itemize}
+\item ugUserDelayPage \ref{ugUserDelayPage} on
+page~\pageref{ugUserDelayPage}
+\end{itemize}
+\index{pages!ugLangAssignPage!ug05.ht}
+\index{ug05.ht!pages!ugLangAssignPage}
+\index{ugLangAssignPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangAssignPage}{5.1. Immediate and Delayed Assignments}
+\beginscroll
+
+A \spadgloss{variable} in Axiom refers to a value.
+A variable has a name beginning with an uppercase or lowercase alphabetic
+character, \axiomSyntax{\%}, or \axiomSyntax{!}.
+Successive characters (if any) can be any of the above, digits, or
+\axiomSyntax{?}.
+Case is distinguished.
+The following are all examples of valid, distinct variable names:
+\begin{verbatim}
+a             tooBig?    a1B2c3%!?
+A             %j         numberOfPoints
+beta6         %J         numberofpoints
+\end{verbatim}
+
+The \axiomSyntax{:=} operator is the immediate \spadgloss{assignment}
+operator.
+Use it to associate a value with a variable.
+
+\beginImportant
+The syntax for immediate assignment for a single variable is
+\centerline{{{\it variable} \axiom{:=} {\it expression}}}
+The value returned by an immediate assignment is the value of {\it expression}.
+\endImportant
+
+\xtc{
+The right-hand side of the expression is evaluated,
+yielding \axiom{1}.  This value is then assigned to \axiom{a}.
+}{
+\spadpaste{a := 1 \bound{a}}
+}
+\xtc{
+The right-hand side of the expression is evaluated,
+yielding \axiom{1}.  This value is then assigned to \axiom{b}.
+Thus \axiom{a} and \axiom{b} both have the value \axiom{1} after the sequence
+of assignments.
+}{
+\spadpaste{b := a \free{a}\bound{b}}
+}
+\xtc{
+What is the value of \axiom{b} if \axiom{a} is
+assigned the value \axiom{2}?
+}{
+\spadpaste{a := 2 \bound{a2}}
+}
+\xtc{
+As you see, the value of \axiom{b} is left unchanged.
+}{
+\spadpaste{b \free{b}}
+}
+This is what we mean when we say this kind of assignment is
+{\it immediate};
+\axiom{b} has no dependency on \axiom{a} after the initial assignment.
+This is the usual notion of assignment found in programming
+languages such as C,
+PASCAL
+and FORTRAN.
+
+Axiom provides delayed assignment with \axiomSyntax{==}.
+This implements a
+delayed evaluation of the right-hand side and dependency
+checking.
+
+\beginImportant
+The syntax for delayed assignment is
+\centerline{{{\it variable} \axiom{==} {\it expression}}}
+The value returned by a delayed assignment is \void{}.
+\endImportant
+
+\xtc{
+Using \axiom{a} and \axiom{b} as above, these are the corresponding delayed
+assignments.
+}{
+\spadpaste{a == 1 \bound{ad}}
+}
+\xtc{
+}{
+\spadpaste{b == a \free{ad}\bound{bd}}
+}
+\xtc{
+The right-hand side of each delayed assignment
+is left unevaluated until the
+variables on the left-hand sides are evaluated.
+Therefore this evaluation and \ldots
+}{
+\spadpaste{a \free{ad}}
+}
+\xtc{
+this evaluation seem the same as before.
+}{
+\spadpaste{b \free{bd}}
+}
+\xtc{
+If we change \axiom{a} to \axiom{2}
+}{
+\spadpaste{a == 2 \bound{ad2}}
+}
+\xtc{
+then
+\axiom{a} evaluates to \axiom{2}, as expected, but
+}{
+\spadpaste{a \free{ad2}}
+}
+\xtc{
+the value of \axiom{b} reflects the change to \axiom{a}.
+}{
+\spadpaste{b \free{bd ad2}}
+}
+
+It is possible to set several variables at the same time
+by using
+a \spadgloss{tuple} of variables and a tuple of expressions.\footnote{A
+\spadgloss{tuple} is a collection of things separated by commas, often
+surrounded by parentheses.}
+
+\beginImportant
+The syntax for multiple immediate assignments is
+\centerline{{{\tt ( \subscriptIt{var}{1}, \subscriptIt{var}{2}, \ldots, \subscriptIt{var}{N} ) := ( \subscriptIt{expr}{1}, \subscriptIt{expr}{2}, \ldots, \subscriptIt{expr}{N} ) }}}
+The value returned by an immediate assignment is the value of
+\subscriptIt{expr}{N}.
+\endImportant
+
+\xtc{
+This sets \axiom{x} to \axiom{1} and \axiom{y} to \axiom{2}.
+}{
+\spadpaste{(x,y) := (1,2) \bound{x}\bound{y}}
+}
+Multiple immediate assigments are parallel in the sense that the
+expressions on the right are all evaluated before any assignments
+on the left are made.
+However, the order of evaluation of these expressions is undefined.
+\xtc{
+You can use multiple immediate assignment to swap the
+values held by variables.
+}{
+\spadpaste{(x,y) := (y,x) \free{x y}\bound{swap}}
+}
+\xtc{
+\axiom{x} has the previous value of \axiom{y}.
+}{
+\spadpaste{x \free{swap}}
+}
+\xtc{
+\axiom{y} has the previous value of \axiom{x}.
+}{
+\spadpaste{y \free{swap}}
+}
+
+There is no syntactic form for multiple delayed assignments.
+See the discussion in
+\downlink{``\ugUserDelayTitle''}{ugUserDelayPage} 
+in Section \ugUserDelayNumber\ignore{ugUserDelay}
+about how Axiom differentiates between delayed assignments and
+user functions of no arguments.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangBlocksTitle}{Blocks}
+\newcommand{\ugLangBlocksNumber}{5.2.}
+
+@
+\section{Blocks}
+\label{ugLangBlocksPage}
+\begin{itemize}
+\item ugLangIfPage \ref{ugLangIfPage} on
+page~\pageref{ugLangIfPage}
+\end{itemize}
+\index{pages!ugLangBlocksPage!ug05.ht}
+\index{ug05.ht!pages!ugLangBlocksPage}
+\index{ugLangBlocksPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangBlocksPage}{5.2. Blocks}
+\beginscroll
+
+%%
+%% We should handle tabs in pile correctly but so far we do not.
+%%
+
+A \spadgloss{block} is a sequence of expressions evaluated
+in the order that they appear, except as modified by control expressions
+such as \axiom{break},
+\spadkey{break}
+\axiom{return},
+\spadkey{return}
+\axiom{iterate} and
+\spadkey{iterate}
+\axiom{if-then-else} constructions.
+The value of a block is the value of the expression last evaluated
+in the block.
+
+To leave a block early, use \axiomSyntax{=>}.
+For example, \axiom{i < 0 => x}.
+The expression before the \axiomSyntax{=>} must evaluate to
+\axiom{true} or \axiom{false}.
+The expression following the \axiomSyntax{=>} is the return value
+for the block.
+
+A block can be constructed in two ways:
+\indent{4}
+\beginitems
+\item[1. ] the expressions can be separated by semicolons
+and the resulting expression surrounded by parentheses, and
+\item[2. ] the expressions can be written on succeeding lines with each line
+indented the same number of spaces (which must be greater than zero).
+A block entered in this form is
+called a \spadgloss{pile}.
+\enditems
+\indent{0}
+Only the first form is available if you are entering expressions
+directly to Axiom.
+Both forms are available in {\bf .input} files.
+
+\beginImportant
+The syntax for a simple block of expressions entered interactively is
+\centerline{{{\tt ( \subscriptIt{expression}{1}; \subscriptIt{expression}{2}; \ldots; \subscriptIt{expression}{N} )}}}
+The value returned by a block is the value of an
+\axiomSyntax{=>} expression, or \subscriptIt{expression}{N}
+if no \axiomSyntax{=>} is encountered.
+\endImportant
+
+In {\bf .input} files, blocks can also be written using
+\spadglossSee{piles}{pile}.
+The examples throughout this book are assumed to come from {\bf .input} files.
+
+\xtc{
+In this example, we assign a rational number to \axiom{a} using a block
+consisting of three expressions.
+This block is written as a pile.
+Each expression in the pile has the same indentation, in this case two
+spaces to the right of the first line.
+}{
+\begin{spadsrc}
+a :=
+  i := gcd(234,672)
+  i := 3*i**5 - i + 1
+  1 / i
+\end{spadsrc}
+}
+\xtc{
+Here is the same block written on one line.
+This is how you are required to enter it at the input prompt.
+}{
+\spadpaste{a := (i := gcd(234,672); i := 3*i**5 - i + 1; 1 / i)}
+}
+\xtc{
+Blocks can be used to put several expressions on one line.
+The value returned is that of the last expression.
+}{
+\spadpaste{(a := 1; b := 2; c := 3; [a,b,c]) \bound{a b c}}
+}
+
+Axiom gives you two ways of writing a block and the
+preferred way in an {\bf .input} file is to use a pile.
+Roughly speaking, a pile is
+a block whose constituent expressions are indented the same amount.
+You begin a pile by starting a new line for the first expression,
+indenting it to the right of the previous line.
+You then enter the second expression on a new line, vertically aligning
+it with the first line. And so on.
+If you need to enter an inner pile, further indent its lines to the right
+of the outer pile.
+Axiom knows where a pile ends.
+It ends when a subsequent line is indented to the left of the pile or
+the end of the file.
+
+\xtc{
+Blocks can be used to perform several steps before an assignment
+(immediate or delayed) is made.
+}{
+\begin{spadsrc}[\free{a b}]
+d :=
+   c := a**2 + b**2
+   sqrt(c * 1.3)
+\end{spadsrc}
+}
+\xtc{
+Blocks can be used in the arguments to functions.
+(Here \axiom{h} is assigned \axiom{2.1 + 3.5}.)
+}{
+\begin{spadsrc}[\bound{h}]
+h := 2.1 +
+   1.0
+   3.5
+\end{spadsrc}
+}
+\xtc{
+Here the second argument to \axiomFun{eval} is \axiom{x = z}, where
+the value of \axiom{z} is computed in the first line of the block
+starting on the second line.
+}{
+\begin{spadsrc}
+eval(x**2 - x*y**2,
+     z := %pi/2.0 - exp(4.1)
+     x = z
+   )
+\end{spadsrc}
+}
+\xtc{
+Blocks can be used in the clauses of \axiom{if-then-else}
+expressions (see \downlink{``\ugLangIfTitle''}{ugLangIfPage} 
+in Section \ugLangIfNumber\ignore{ugLangIf}).
+}{
+\spadpaste{if h > 3.1 then 1.0 else (z := cos(h); max(z,0.5)) \free{h}}
+}
+\xtc{
+This is the pile version of the last block.
+}{
+\begin{spadsrc}[\free{h}]
+if h > 3.1 then
+    1.0
+  else
+    z := cos(h)
+    max(z,0.5)
+\end{spadsrc}
+}
+\xtc{
+Blocks can be nested.
+}{
+\spadpaste{a := (b := factorial(12); c := (d := eulerPhi(22); factorial(d));b+c)}
+}
+\xtc{
+This is the pile version of the last block.
+}{
+\begin{spadsrc}
+a :=
+  b := factorial(12)
+  c :=
+    d := eulerPhi(22)
+    factorial(d)
+  b+c
+\end{spadsrc}
+}
+
+\xtc{
+Since \axiom{c + d} does equal \axiom{3628855}, \axiom{a} has the value
+of \axiom{c} and the last line is never evaluated.
+}{
+\begin{spadsrc}
+a :=
+  c := factorial 10
+  d := fibonacci 10
+  c + d = 3628855 => c
+  d
+\end{spadsrc}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangIfTitle}{if-then-else}
+\newcommand{\ugLangIfNumber}{5.3.}
+
+@
+\section{if-then-else}
+\label{ugLangIfPage}
+\begin{itemize}
+\item ugTypesResolvePage \ref{ugTypesResolvePage} on
+page~\pageref{ugTypesResolvePage}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\end{itemize}
+\index{pages!ugLangIfPage!ug05.ht}
+\index{ug05.ht!pages!ugLangIfPage}
+\index{ugLangIfPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangIfPage}{5.3. if-then-else}
+\beginscroll
+
+Like many other programming languages, Axiom uses the three
+keywords \spadkey{if} \axiom{if, then} \spadkey{then} and \axiom{else}
+\spadkey{else} to form
+conditional expressions.
+The \axiom{else} part of the conditional is optional.
+The expression between the \axiom{if} and \axiom{then} keywords
+is a
+\spadgloss{predicate}: an expression that evaluates to or is convertible to
+either {\tt true} or {\tt false}, that is,
+a \axiomType{Boolean}.
+
+\beginImportant
+The syntax for conditional expressions is
+\centerline{{{\tt if {\it predicate} then \subscriptIt{expression}{1} else \subscriptIt{expression}{2}}}}
+where the \axiom{else} \subscriptIt{\it expression}{2} part is optional.
+The value returned from a conditional expression is
+\subscriptIt{\it expression}{1} if the predicate evaluates to \axiom{true}
+and \subscriptIt{\it expression}{2} otherwise.
+If no \axiom{else} clause is given, the value is always \void{}.
+\endImportant
+
+An \axiom{if-then-else} expression always returns a value.
+If the
+\axiom{else} clause is missing then the entire expression returns
+\void{}.
+If both clauses are present, the type of the value returned by \axiom{if}
+is obtained by resolving the types of the values of the two clauses.
+See \downlink{``\ugTypesResolveTitle''}{ugTypesResolvePage} 
+in Section \ugTypesResolveNumber\ignore{ugTypesResolve}
+for more information.
+
+The predicate must evaluate to, or be convertible to, an object of type
+\axiomType{Boolean}: {\tt true} or {\tt false}.
+By default, the equal sign \spadopFrom{=}{Equation} creates
+an equation.
+\xtc{
+This is an equation.
+In particular, it is an object of type \axiomType{Equation Polynomial Integer}.
+}{
+\spadpaste{x + 1 = y}
+}
+However, for predicates in \axiom{if} expressions, Axiom
+places a default target type of \axiomType{Boolean} on the
+predicate and equality testing is performed.
+Thus you need not qualify the \axiomSyntax{=} in any way.
+In other contexts you may need to tell Axiom that you want
+to test for equality rather than create an equation.
+In those cases, use \axiomSyntax{@} and a target type of
+\axiomType{Boolean}.
+See \downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} in Section 
+\ugTypesPkgCallNumber\ignore{ugTypesPkgCall} for more information.
+
+The compound symbol meaning ``not equal'' in Axiom is
+``\texht{$\sim =$}{\axiom{~=}}''.
+This can be used directly without a package call or a target specification.
+The expression
+\axiom{a} \texht{$\sim =$}{\axiom{~=}} \axiom{b} is directly translated into
+\axiom{not (a = b)}.
+
+Many other functions have return values of type \axiomType{Boolean}.
+These include \axiom{<}, \axiom{<=}, \axiom{>},
+\axiom{>=}, \texht{$\sim =$}{\axiom{~=}} and \axiom{member?}.
+By convention, operations with names ending in \axiomSyntax{?}
+return \axiomType{Boolean} values.
+
+The usual rules for piles are suspended for conditional expressions.
+In {\bf .input} files, the \axiom{then} and
+\axiom{else} keywords can begin in the same column as the corresponding
+\axiom{if} but may also appear to the right.
+Each of the following styles of writing \axiom{if-then-else}
+expressions is acceptable:
+\begin{verbatim}
+if i>0 then output("positive") else output("nonpositive")
+
+if i > 0 then output("positive")
+  else output("nonpositive")
+
+if i > 0 then output("positive")
+else output("nonpositive")
+
+if i > 0
+then output("positive")
+else output("nonpositive")
+
+if i > 0
+  then output("positive")
+  else output("nonpositive")
+\end{verbatim}
+
+A block can follow the \axiom{then} or \axiom{else} keywords.
+In the following two assignments to \axiom{a}, 
+the \axiom{then} and \axiom{else}
+clauses each are followed by two-line piles.
+The value returned in each is the value of the second line.
+
+\begin{verbatim}
+a :=
+  if i > 0 then
+    j := sin(i * pi())
+    exp(j + 1/j)
+  else
+    j := cos(i * 0.5 * pi())
+    log(abs(j)**5 + 1)
+
+a :=
+  if i > 0
+    then
+      j := sin(i * pi())
+      exp(j + 1/j)
+    else
+      j := cos(i * 0.5 * pi())
+      log(abs(j)**5 + 1)
+\end{verbatim}
+These are both equivalent to the following:
+\begin{verbatim}
+a :=
+  if i > 0 then (j := sin(i * pi()); exp(j + 1/j))
+  else (j := cos(i * 0.5 * pi()); log(abs(j)**5 + 1))
+\end{verbatim}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsTitle}{Loops}
+\newcommand{\ugLangLoopsNumber}{5.4.}
+
+@
+\section{Loops}
+\label{ugLangLoopsPage}
+\begin{itemize}
+\item ugLangLoopsCompIntPage \ref{ugLangLoopsCompIntPage} on
+page~\pageref{ugLangLoopsCompIntPage}
+\item ugLangLoopsReturnPage \ref{ugLangLoopsReturnPage} on
+page~\pageref{ugLangLoopsReturnPage}
+\item ugLangLoopsBreakPage \ref{ugLangLoopsBreakPage} on
+page~\pageref{ugLangLoopsBreakPage}
+\item ugLangLoopsBreakVsPage \ref{ugLangLoopsBreakVsPage} on
+page~\pageref{ugLangLoopsBreakVsPage}
+\item ugLangLoopsBreakMorePage \ref{ugLangLoopsBreakMorePage} on
+page~\pageref{ugLangLoopsBreakMorePage}
+\item ugLangLoopsIteratePage \ref{ugLangLoopsIteratePage} on
+page~\pageref{ugLangLoopsIteratePage}
+\item ugLangLoopsWhilePage \ref{ugLangLoopsWhilePage} on
+page~\pageref{ugLangLoopsWhilePage}
+\item ugLangLoopsForInPage \ref{ugLangLoopsForInPage} on
+page~\pageref{ugLangLoopsForInPage}
+\item ugLangLoopsForInNMPage \ref{ugLangLoopsForInNMPage} on
+page~\pageref{ugLangLoopsForInNMPage}
+\item ugLangLoopsForInNMSPage \ref{ugLangLoopsForInNMSPage} on
+page~\pageref{ugLangLoopsForInNMSPage}
+\item ugLangLoopsForInNPage \ref{ugLangLoopsForInNPage} on
+page~\pageref{ugLangLoopsForInNPage}
+\item ugLangLoopsForInXLPage \ref{ugLangLoopsForInXLPage} on
+page~\pageref{ugLangLoopsForInXLPage}
+\item ugLangLoopsForInPredPage \ref{ugLangLoopsForInPredPage} on
+page~\pageref{ugLangLoopsForInPredPage}
+\item ugLangLoopsParPage \ref{ugLangLoopsParPage} on
+page~\pageref{ugLangLoopsParPage}
+\end{itemize}
+\index{pages!ugLangLoopsPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsPage}
+\index{ugLangLoopsPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsPage}{5.4. Loops}
+\beginscroll
+
+A \spadgloss{loop} is an expression that contains another expression,
+called the {\it loop body}, which is to be evaluated zero or more
+times.
+All loops contain the \axiom{repeat} keyword and return \void{}.
+Loops can contain inner loops to any depth.
+
+\beginImportant
+The most basic loop is of the form
+\centerline{{\axiom{repeat} {\it loopBody}}}
+Unless {\it loopBody} contains a \axiom{break} or \axiom{return} expression,
+the loop repeats forever.
+The value returned by the loop is \void{}.
+\endImportant
+
+\beginmenu
+    \menudownlink{{5.4.1. Compiling vs. Interpreting Loops}}
+{ugLangLoopsCompIntPage}
+    \menudownlink{{5.4.2. return in Loops}}{ugLangLoopsReturnPage}
+    \menudownlink{{5.4.3. break in Loops}}{ugLangLoopsBreakPage}
+    \menudownlink{{5.4.4. break vs. {\tt =>} in Loop Bodies}}
+{ugLangLoopsBreakVsPage}
+    \menudownlink{{5.4.5. More Examples of break}}{ugLangLoopsBreakMorePage}
+    \menudownlink{{5.4.6. iterate in Loops}}{ugLangLoopsIteratePage}
+    \menudownlink{{5.4.7. while Loops}}{ugLangLoopsWhilePage}
+    \menudownlink{{5.4.8. for Loops}}{ugLangLoopsForInPage}
+    \menudownlink{{5.4.9. for i in n..m repeat}}{ugLangLoopsForInNMPage}
+    \menudownlink{{5.4.10. for i in n..m by s repeat}}{ugLangLoopsForInNMSPage}
+    \menudownlink{{5.4.11. for i in n.. repeat}}{ugLangLoopsForInNPage}
+    \menudownlink{{5.4.12. for x in l repeat}}{ugLangLoopsForInXLPage}
+    \menudownlink{{5.4.13. ``Such that'' Predicates}}{ugLangLoopsForInPredPage}
+    \menudownlink{{5.4.14. Parallel Iteration}}{ugLangLoopsParPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsCompIntTitle}{Compiling vs. Interpreting Loops}
+\newcommand{\ugLangLoopsCompIntNumber}{5.4.1.}
+
+@
+\section{Compiling vs. Interpreting Loops}
+\label{ugLangLoopsCompIntPage}
+\begin{itemize}
+\item ugUserCompIntPage \ref{ugUserCompIntPage} on
+page~\pageref{ugUserCompIntPage}
+\end{itemize}
+\index{pages!ugLangLoopsCompIntPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsCompIntPage}
+\index{ugLangLoopsCompIntPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsCompIntPage}{5.4.1. Compiling vs. Interpreting Loops}
+\beginscroll
+
+Axiom tries to determine completely the type of every
+object in a loop and then to translate the loop body to LISP or even to
+machine code.
+This translation is called \spadglossSee{compilation}{compiler}.
+
+If Axiom decides that it cannot compile the loop, it issues a
+message stating the problem and then the following message:
+%
+\centerline{{{\bf We will attempt to step through and interpret the code.}}}
+%
+It is still possible that Axiom can evaluate the loop but in
+\spadgloss{interpret-code mode}.
+See \downlink{``\ugUserCompIntTitle''}{ugUserCompIntPage} 
+in Section \ugUserCompIntNumber\ignore{ugUserCompInt} where 
+this is discussed in terms
+of compiling versus interpreting functions.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsReturnTitle}{return in Loops}
+\newcommand{\ugLangLoopsReturnNumber}{5.4.2.}
+
+@
+\section{return in Loops}
+\label{ugLangLoopsReturnPage}
+\begin{itemize}
+\item ugUserBlocksPage \ref{ugUserBlocksPage} on
+page~\pageref{ugUserBlocksPage}
+\end{itemize}
+\index{pages!ugLangLoopsReturnPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsReturnPage}
+\index{ugLangLoopsReturnPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsReturnPage}{5.4.2. return in Loops}
+\beginscroll
+
+A \axiom{return} expression is used to exit a function with
+a particular value.
+In particular, if a \axiom{return} is in a loop within the
+\spadkey{return}
+function, the loop is terminated whenever the \axiom{return}
+is evaluated.
+%> This is a bug! The compiler should never accept allow
+%> Void to be the return type of a function when it has to use
+%> resolve to determine it.
+\xtc{
+Suppose we start with this.
+}{
+\begin{spadsrc}[\bound{f}]
+f() ==
+  i := 1
+  repeat
+    if factorial(i) > 1000 then return i
+    i := i + 1
+\end{spadsrc}
+}
+\xtc{
+When \axiom{factorial(i)} is big enough, control passes from
+inside the loop all the way outside the function, returning the
+value of \axiom{i} (or so we think).
+}{
+\spadpaste{f() \free{f}}
+}
+
+What went wrong?
+Isn't it obvious that this function should return an integer?
+Well, Axiom makes no attempt to analyze the structure of a
+loop to determine if it always returns a value because, in
+general, this is impossible.
+So Axiom has this simple rule: the type of the function is
+determined by the type of its body, in this case a block.
+The normal value of a block is the value of its last expression,
+in this case, a loop.
+And the value of every loop is \void{}!
+So the return type of \userfun{f} is \axiomType{Void}.
+
+There are two ways to fix this.
+The best way is for you to tell Axiom what the return type
+of \axiom{f} is.
+You do this by giving \axiom{f} a declaration \axiom{f: () ->
+Integer} prior to calling for its value.
+This tells Axiom: ``trust me---an integer is returned.''
+We'll explain more about this in the next chapter.
+Another clumsy way is to add a dummy expression as follows.
+
+\xtc{
+Since we want an integer, let's stick in a dummy final expression that is
+an integer and will never be evaluated.
+}{
+\begin{spadsrc}[\bound{f1}]
+f() ==
+  i := 1
+  repeat
+    if factorial(i) > 1000 then return i
+    i := i + 1
+  0
+\end{spadsrc}
+}
+\xtc{
+When we try \userfun{f} again we get what we wanted.
+See
+\downlink{``\ugUserBlocksTitle''}{ugUserBlocksPage} 
+in Section \ugUserBlocksNumber\ignore{ugUserBlocks}
+for more information.
+}{
+\spadpaste{f() \free{f1}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsBreakTitle}{break in Loops}
+\newcommand{\ugLangLoopsBreakNumber}{5.4.3.}
+
+@
+\section{break in Loops}
+\label{ugLangLoopsBreakPage}
+\begin{itemize}
+\item ugLangLoopsReturnPage \ref{ugLangLoopsReturnPage} on
+page~\pageref{ugLangLoopsReturnPage}
+\end{itemize}
+\index{pages!ugLangLoopsBreakPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsBreakPage}
+\index{ugLangLoopsBreakPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsBreakPage}{5.4.3. break in Loops}
+\beginscroll
+
+The \axiom{break} keyword is often more useful
+\spadkey{break}
+in terminating
+a loop.
+%>  and more in keeping with the ideas of structured programming.
+A \axiom{break} causes control to transfer to the expression
+immediately following the loop.
+As loops always return \void{},
+you cannot return a value with \axiom{break}.
+That is, \axiom{break} takes no argument.
+
+\xtc{
+This example is a modification of the last example in
+\texht{the previous section}{
+\downlink{``\ugLangLoopsReturnTitle''}{ugLangLoopsReturnPage} 
+in Section \ugLangLoopsReturnNumber\ignore{ugLangLoopsReturn}}.
+Instead of using \axiom{return}, we'll use \axiom{break}.
+}{
+\begin{spadsrc}[\bound{f1}]
+f() ==
+  i := 1
+  repeat
+    if factorial(i) > 1000 then break
+    i := i + 1
+  i
+\end{spadsrc}
+}
+\xtc{
+The loop terminates when \axiom{factorial(i)} gets big enough,
+the last line of the function evaluates to the corresponding ``good''
+value of \axiom{i}, and the function terminates, returning that value.
+}{
+\spadpaste{f() \free{f1}}
+}
+\xtc{
+You can only use \axiom{break} to terminate the evaluation of one loop.
+Let's consider a loop within a loop, that is, a loop with a nested loop.
+First, we initialize two counter variables.
+}{
+\spadpaste{(i,j) := (1, 1) \bound{i}\bound{j}}
+}
+\xtc{
+Nested loops must have multiple \axiom{break}
+expressions at the appropriate nesting level.
+How would you rewrite this so \axiom{(i + j) > 10} is only evaluated once?
+}{
+\begin{spadsrc}[\free{i j}]
+repeat
+  repeat
+    if (i + j) > 10 then break
+    j := j + 1
+  if (i + j) > 10 then break
+  i := i + 1
+\end{spadsrc}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsBreakVsTitle}{break vs. {\tt =>} in Loop Bodies}
+\newcommand{\ugLangLoopsBreakVsNumber}{5.4.4.}
+
+@
+\section{break vs. {\tt =>} in Loop Bodies}
+\label{ugLangLoopsBreakVsPage}
+\index{pages!ugLangLoopsBreakVsPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsBreakVsPage}
+\index{ugLangLoopsBreakVsPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsBreakVsPage}{5.4.4. break vs. {\tt =>} in Loop Bodies}
+\beginscroll
+
+Compare the following two loops:
+
+\begin{verbatim}
+i := 1                            i := 1
+repeat                            repeat
+  i := i + 1                        i := i + 1
+  i > 3 => i                        if i > 3 then break
+  output(i)                         output(i)
+\end{verbatim}
+
+In the example on the left, the values
+\mathOrSpad{2} and \mathOrSpad{3} for \axiom{i} are displayed
+but then the \axiomSyntax{=>} does not allow control to reach the call to
+\axiomFunFrom{output}{OutputForm} again.
+The loop will not terminate
+until you run out of space or interrupt the execution.
+The variable \axiom{i} will continue to be incremented because
+the \axiomSyntax{=>} only means to leave the {\it block,} not the loop.
+
+In the example on the right,
+upon reaching \mathOrSpad{4}, the \axiom{break} will be
+executed, and both the block and the loop will terminate.
+This is one of the reasons why both \axiomSyntax{=>} and \axiom{break} are
+provided.
+Using a \axiom{while} clause (see below) with the \axiomSyntax{=>}
+\spadkey{while}
+lets you simulate the action of \axiom{break}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsBreakMoreTitle}{More Examples of break}
+\newcommand{\ugLangLoopsBreakMoreNumber}{5.4.5.}
+
+@
+\section{More Examples of break}
+\label{ugLangLoopsBreakMorePage}
+\begin{itemize}
+\item ugLangLoopsForInPage \ref{ugLangLoopsForInPage} on
+page~\pageref{ugLangLoopsForInPage}
+\end{itemize}
+\index{pages!ugLangLoopsBreakMorePage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsBreakMorePage}
+\index{ugLangLoopsBreakMorePage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsBreakMorePage}{5.4.5. More Examples of break}
+\beginscroll
+
+Here we give four examples of \axiom{repeat} loops that
+terminate when a value exceeds a given bound.
+
+\texht{\vskip 1pc}{}
+\xtc{
+First, initialize \axiom{i} as the loop counter.
+}{
+\spadpaste{i := 0 \bound{i}}
+}
+\xtc{
+Here is the first loop.
+When the square of \axiom{i} exceeds \axiom{100}, the loop terminates.
+}{
+\begin{spadsrc}[\free{i}\bound{i1}]
+repeat
+  i := i + 1
+  if i**2 > 100 then break
+\end{spadsrc}
+}
+\xtc{
+Upon completion, \axiom{i} should have the value \axiom{11}.
+}{
+\spadpaste{i \free{i1}}
+}
+%
+%
+\xtc{
+Do the same thing except use \axiomSyntax{=>} instead
+an \axiom{if-then} expression.
+}{
+\spadpaste{i := 0 \bound{i2}}
+}
+\xtc{
+}{
+\begin{spadsrc}[\free{i2}\bound{i3}]
+repeat
+  i := i + 1
+  i**2 > 100 => break
+\end{spadsrc}
+}
+\xtc{
+}{
+\spadpaste{i \free{i3}}
+}
+%
+%
+\xtc{
+As a third example, we use a simple loop to compute \axiom{n!}.
+}{
+\spadpaste{(n, i, f) := (100, 1, 1) \bound{n}\bound{i4}\bound{f}}
+}
+\xtc{
+Use \axiom{i} as the iteration variable and \axiom{f}
+to compute the factorial.
+}{
+\begin{spadsrc}[\bound{f1}\bound{i5}\free{f i4 n}]
+repeat
+  if i > n then break
+  f := f * i
+  i := i + 1
+\end{spadsrc}
+}
+\xtc{
+Look at the value of \axiom{f}.
+}{
+\spadpaste{f \free{f1}}
+}
+%
+%
+\xtc{
+Finally, we show an example of nested loops.
+First define a four by four matrix.
+}{
+\spadpaste{m := matrix [[21,37,53,14], [8,-24,22,-16], [2,10,15,14], [26,33,55,-13]] \bound{m2}}
+}
+\xtc{
+Next, set row counter \axiom{r} and column counter \axiom{c} to
+\mathOrSpad{1}.
+Note: if we were writing a function, these would all be local
+variables rather than global workspace variables.
+}{
+\spadpaste{(r, c) := (1, 1) \bound{r}\bound{c}}
+}
+\xtc{
+Also, let \axiom{lastrow} and
+\axiom{lastcol} be the final row and column index.
+}{
+\spadpaste{(lastrow, lastcol) := (nrows(m), ncols(m)) \bound{lastrow}\bound{lastcol}\free{m2}}
+}
+%
+\xtc{
+Scan the rows looking for the first negative element.
+We remark that you can reformulate this example in a better, more
+concise form by using a \axiom{for} clause with \axiom{repeat}.
+See
+\downlink{``\ugLangLoopsForInTitle''}{ugLangLoopsForInPage} 
+in Section \ugLangLoopsForInNumber\ignore{ugLangLoopsForIn}
+for more information.
+}{
+\begin{spadsrc}[\free{m2 r c lastrow lastcol}]
+repeat
+  if r > lastrow then break
+  c := 1
+  repeat
+    if c > lastcol then break
+    if elt(m,r,c) < 0 then
+      output [r, c, elt(m,r,c)]
+      r := lastrow
+      break     -- don't look any further
+    c := c + 1
+  r := r + 1
+\end{spadsrc}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsIterateTitle}{iterate in Loops}
+\newcommand{\ugLangLoopsIterateNumber}{5.4.6.}
+
+@
+\section{iterate in Loops}
+\label{ugLangLoopsIteratePage}
+\index{pages!ugLangLoopsIteratePage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsIteratePage}
+\index{ugLangLoopsIteratePage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsIteratePage}{5.4.6. iterate in Loops}
+\beginscroll
+
+Axiom provides an \axiom{iterate} expression that
+\spadkey{iterate}
+skips over the remainder of a loop body and starts the next loop iteration.
+\xtc{
+We first initialize a counter.
+}{
+\spadpaste{i := 0 \bound{i}}
+}
+\xtc{
+Display the even integers from \axiom{2} to \axiom{5}.
+}{
+\begin{spadsrc}[\free{i}]
+repeat
+  i := i + 1
+  if i > 5 then break
+  if odd?(i) then iterate
+  output(i)
+\end{spadsrc}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsWhileTitle}{while Loops}
+\newcommand{\ugLangLoopsWhileNumber}{5.4.7.}
+
+@
+\section{while Loops}
+\label{ugLangLoopsWhilePage}
+\index{pages!ugLangLoopsWhilePage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsWhilePage}
+\index{ugLangLoopsWhilePage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsWhilePage}{5.4.7. while Loops}
+\beginscroll
+
+The \axiom{repeat} in a loop can be modified by adding one or
+more \axiom{while} clauses.
+\spadkey{while}
+Each clause contains a \spadgloss{predicate}
+immediately following the \axiom{while} keyword.
+The predicate is tested {\it before}
+the evaluation of the body of the loop.
+The loop body is evaluated whenever the predicates in a \axiom{while}
+clause are all \axiom{true}.
+
+\beginImportant
+The syntax for a simple loop using \axiom{while} is
+\centerline{{\axiom{while} {\it predicate} \axiom{repeat} {\it loopBody}}}
+The {\it predicate} is evaluated before {\it loopBody} is evaluated.
+A \axiom{while} loop terminates immediately when {\it predicate}
+evaluates to \axiom{false} or when a \axiom{break} or \axiom{return}
+expression is evaluated in {\it loopBody}.
+The value returned by the loop is \void{}.
+\endImportant
+
+\xtc{
+Here is a simple example of using \axiom{while} in a loop.
+We first initialize the counter.
+}{
+\spadpaste{i := 1 \bound{i}}
+}
+\xtc{
+The steps involved in computing this example are
+(1) set \axiom{i} to \axiom{1}, (2) test the condition \axiom{i < 1} and
+determine that it is not true, and (3) do not evaluate the
+loop body and therefore do not display \axiom{"hello"}.
+}{
+\begin{spadsrc}[\free{i}]
+while i < 1 repeat
+  output "hello"
+  i := i + 1
+\end{spadsrc}
+}
+\xtc{
+If you have multiple predicates to be tested use the
+logical \axiom{and} operation to separate them.
+Axiom evaluates these predicates from left to right.
+}{
+\spadpaste{(x, y) := (1, 1) \bound{x}\bound{y}}
+}
+\xtc{
+}{
+\begin{spadsrc}[\free{x y}]
+while x < 4 and y < 10 repeat
+  output [x,y]
+  x := x + 1
+  y := y + 2
+\end{spadsrc}
+}
+\xtc{
+A \axiom{break} expression can be included in a loop body to terminate a
+loop even if the predicate in any \axiom{while} clauses are not \axiom{false}.
+}{
+\spadpaste{(x, y) := (1, 1) \bound{x1}\bound{y1}}
+}
+\xtc{
+This loop has multiple \axiom{while} clauses and the loop terminates
+before any one of their conditions evaluates to \axiom{false}.
+}{
+\begin{spadsrc}[\free{x1 y1}]
+while x < 4 while y < 10 repeat
+  if x + y > 7 then break
+  output [x,y]
+  x := x + 1
+  y := y + 2
+\end{spadsrc}
+}
+\xtc{
+Here's a different version of the nested loops that looked
+for the first negative element in a matrix.
+}{
+\spadpaste{m := matrix [[21,37,53,14], [8,-24,22,-16], [2,10,15,14], [26,33,55,-13]] \bound{m2}}
+}
+\xtc{
+Initialized the row index to \axiom{1} and
+get the number of rows and columns.
+If we were writing a function, these would all be
+local variables.
+}{
+\spadpaste{r := 1 \bound{r}}
+}
+\xtc{
+}{
+\spadpaste{(lastrow, lastcol) := (nrows(m), ncols(m)) \bound{lastrow}\bound{lastcol}\free{m2}}
+}
+%
+\xtc{
+Scan the rows looking for the first negative element.
+}{
+\begin{spadsrc}[\free{m2 r lastrow lastcol}]
+while r <= lastrow repeat
+  c := 1  -- index of first column
+  while c <= lastcol repeat
+    if elt(m,r,c) < 0 then
+      output [r, c, elt(m,r,c)]
+      r := lastrow
+      break     -- don't look any further
+    c := c + 1
+  r := r + 1
+\end{spadsrc}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsForInTitle}{for Loops}
+\newcommand{\ugLangLoopsForInNumber}{5.4.8.}
+
+@
+\section{for Loops}
+\label{ugLangLoopsForInPage}
+\index{pages!ugLangLoopsForInPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsForInPage}
+\index{ugLangLoopsForInPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsForInPage}{5.4.8. for Loops}
+\beginscroll
+
+Axiom provides the \axiom{for}
+\spadkey{for}
+and \axiom{in}
+\spadkey{in}
+keywords in \axiom{repeat} loops,
+allowing you to iterate across all
+elements of a list, or to have a variable take on integral values
+from a lower bound to an upper bound.
+We shall refer to these modifying clauses of \axiom{repeat} loops as
+\axiom{for} clauses.
+These clauses can be present in addition to \axiom{while} clauses.
+As with all other types of \axiom{repeat} loops, \axiom{break} can
+\spadkey{break}
+be used to prematurely terminate the evaluation of the loop.
+
+\beginImportant
+The syntax for a simple loop using \axiom{for} is
+\centerline{{\axiom{for} {\it iterator} \axiom{repeat} {\it loopBody}}}
+The {\it iterator} has several forms.
+Each form has an end test which is evaluated
+before {\it loopBody} is evaluated.
+A \axiom{for} loop terminates immediately when the end test
+succeeds (evaluates to \axiom{true}) or when a \axiom{break} or \axiom{return}
+expression is evaluated in {\it loopBody}.
+The value returned by the loop is \void{}.
+\endImportant
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsForInNMTitle}{for i in n..m repeat}
+\newcommand{\ugLangLoopsForInNMNumber}{5.4.9.}
+
+@
+\section{for i in n..m repeat}
+\label{ugLangLoopsForInNMPage}
+\begin{itemize}
+\item SegmentXmpPage \ref{SegmentXmpPage} on
+page~\pageref{SegmentXmpPage}
+\end{itemize}
+\index{pages!ugLangLoopsForInNMPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsForInNMPage}
+\index{ugLangLoopsForInNMPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsForInNMPage}{5.4.9. for i in n..m repeat}
+\beginscroll
+
+If \axiom{for}
+\spadkey{for}
+is followed by a variable name, the \axiom{in}
+\spadkey{in}
+keyword and then an integer segment of the form \axiom{n..m},
+the end test for this loop is the predicate \axiom{i > m}.
+The body of the loop is evaluated \axiom{m-n+1} times if this
+number is greater than 0.
+If this number is less than or equal to 0, the loop body is not evaluated
+at all.
+
+The variable \axiom{i} has the value
+\axiom{n, n+1, ..., m} for successive iterations
+of the loop body.
+The loop variable is a \spadgloss{local variable}
+within the loop body: its value is not available outside the loop body
+and its value and type within the loop body completely mask any outer
+definition of a variable with the same name.
+
+%
+\xtc{
+This loop prints the values of
+\texht{${10}^3$, ${11}^3$, and $12^3$}{\axiom{10**3, 11**3, and 12**3}}:
+}{
+\spadpaste{for i in 10..12 repeat output(i**3)}
+}
+%
+\xtc{
+Here is a sample list.
+}{
+\spadpaste{a := [1,2,3] \bound{a}}
+}
+\xtc{
+Iterate across this list, using \axiomSyntax{.} to access the elements of a list and
+the \axiomFun{\#} operation to count its elements.
+}{
+\spadpaste{for i in 1..\#a repeat output(a.i) \free{a}}
+}
+%
+This type of iteration is applicable to anything that uses \axiomSyntax{.}.
+You can also use it with functions that use indices to extract elements.
+%
+\xtc{
+Define \axiom{m} to be a matrix.
+}{
+\spadpaste{m := matrix [[1,2],[4,3],[9,0]] \bound{m}}
+}
+\xtc{
+Display the rows of \axiom{m}.
+}{
+\spadpaste{for i in 1..nrows(m) repeat output row(m,i) \free{m}}
+}
+%
+You can use \axiom{iterate} with \axiom{for}-loops.
+\spadkey{iterate}
+\xtc{
+Display the even integers in a segment.
+}{
+\begin{spadsrc}
+for i in 1..5 repeat
+  if odd?(i) then iterate
+  output(i)
+\end{spadsrc}
+}
+
+See \downlink{`Segment'}{SegmentXmpPage}\ignore{Segment} 
+for more information about segments.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsForInNMSTitle}{for i in n..m by s repeat}
+\newcommand{\ugLangLoopsForInNMSNumber}{5.4.10.}
+
+@
+\section{for i in n..m by s repeat}
+\label{ugLangLoopsForInNMSPage}
+\index{pages!ugLangLoopsForInNMSPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsForInNMSPage}
+\index{ugLangLoopsForInNMSPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsForInNMSPage}{5.4.10. for i in n..m by s repeat}
+\beginscroll
+
+By default, the difference between values taken on by a variable in loops
+such as \axiom{for i in n..m repeat ...} is \mathOrSpad{1}.
+It is possible to supply another, possibly negative, step value by using
+the \axiom{by}
+\spadkey{by}
+keyword along with \axiom{for} and \axiom{in}.
+Like the upper and lower bounds, the step value following the
+\axiom{by} keyword must be an integer.
+Note that the loop
+\axiom{for i in 1..2 by 0 repeat output(i)}
+will not terminate by itself, as the step value does not change the index
+from its initial value of \mathOrSpad{1}.
+
+\xtc{
+This expression displays the odd integers between two bounds.
+}{
+\spadpaste{for i in 1..5 by 2 repeat output(i)}
+}
+\xtc{
+Use this to display the numbers in reverse order.
+}{
+\spadpaste{for i in 5..1 by -2 repeat output(i)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsForInNTitle}{for i in n.. repeat}
+\newcommand{\ugLangLoopsForInNNumber}{5.4.11.}
+
+@
+\section{for i in n.. repeat}
+\label{ugLangLoopsForInNPage}
+\index{pages!ugLangLoopsForInNPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsForInNPage}
+\index{ugLangLoopsForInNPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsForInNPage}{5.4.11. for i in n.. repeat}
+\beginscroll
+
+If the value after the \axiomSyntax{..}
+is omitted, the loop has no end test.
+A potentially infinite loop is thus created.
+The variable is given the successive values \axiom{n, n+1, n+2, ...}
+and the loop is terminated only if a \axiom{break} or \axiom{return}
+expression is evaluated in the loop body.
+However you may also add some other modifying clause on the
+\axiom{repeat} (for example, a \axiom{while} clause) to stop the loop.
+
+\xtc{
+This loop displays the integers greater than or equal to \axiom{15}
+and less than the first prime greater than \axiom{15}.
+}{
+\spadpaste{for i in 15.. while not prime?(i) repeat output(i)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsForInXLTitle}{for x in l repeat}
+\newcommand{\ugLangLoopsForInXLNumber}{5.4.12.}
+
+@
+\section{for x in l repeat}
+\label{ugLangLoopsForInXLPage}
+\index{pages!ugLangLoopsForInXLPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsForInXLPage}
+\index{ugLangLoopsForInXLPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsForInXLPage}{5.4.12. for x in l repeat}
+\beginscroll
+
+Another variant of the \axiom{for} loop has the form:
+\centerline{{{\it \axiom{for} x \axiom{in} list \axiom{repeat} loopBody}}}
+This form is used when you want to iterate directly over the
+elements of a list.
+In this form of the \axiom{for} loop, the variable
+\axiom{x} takes on the value of each successive element in \axiom{l}.
+The end test is most simply stated in English: ``are there no more
+\axiom{x} in \axiom{l}?''
+
+\xtc{
+If \axiom{l} is this list,
+}{
+\spadpaste{l := [0,-5,3] \bound{l}}
+}
+\xtc{
+display all elements of \axiom{l}, one per line.
+}{
+\spadpaste{for x in l repeat output(x) \free{l}}
+}
+
+Since the list constructing expression \axiom{expand [n..m]} creates the
+list \axiom{[n, n+1, ..., m]}\footnote{This list is empty if \axiom{n >
+m}.}, you might be tempted to think that the loops
+\begin{verbatim}
+for i in n..m repeat output(i)
+\end{verbatim}
+and
+\begin{verbatim}
+for x in expand [n..m] repeat output(x)
+\end{verbatim}
+are equivalent.
+The second form first creates the list
+\axiom{expand [n..m]} (no matter how large it might be) and
+then does the iteration.
+The first form potentially runs in much less space, as the index variable
+\axiom{i} is simply incremented once per loop and the list is not actually
+created.
+Using the first form is much more efficient.
+%
+\xtc{
+Of course, sometimes you really want to iterate across a specific list.
+This displays each of the factors of \axiom{2400000}.
+}{
+\spadpaste{for f in factors(factor(2400000)) repeat output(f)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsForInPredTitle}{``Such that'' Predicates}
+\newcommand{\ugLangLoopsForInPredNumber}{5.4.13.}
+
+@
+\section{``Such that'' Predicates}
+\label{ugLangLoopsForInPredPage}
+\index{pages!ugLangLoopsForInPredPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsForInPredPage}
+\index{ugLangLoopsForInPredPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsForInPredPage}{5.4.13. ``Such that'' Predicates}
+\beginscroll
+
+A \axiom{for} loop can be followed by a \axiomSyntax{|} and then a
+predicate.
+The predicate qualifies the use of the values from the iterator following
+the \axiom{for}.
+Think of the vertical bar
+\axiomSyntax{|} as the phrase ``such that.''
+\xtc{
+This loop expression
+prints out the integers \axiom{n} in the given segment
+such that \axiom{n} is odd.
+}{
+\spadpaste{for n in 0..4 | odd? n repeat output n}
+}
+
+\beginImportant
+A \axiom{for} loop can also be written
+\centerline{{\axiom{for} {\it iterator} \axiom{|} {\it predicate}  \axiom{repeat} {\it loopBody}}}
+which is equivalent to:
+\centerline{{\axiom{for} {\it iterator} \axiom{repeat if}}}
+\centerline{{{\it predicate} \axiom{then} {\it loopBody} \axiom{else} \axiom{iterate}}}
+\endImportant
+
+The predicate need not refer only to the variable in the \axiom{for} clause:
+any variable in an outer scope can be part of the predicate.
+\xtc{
+In this example, the predicate on the inner \axiom{for} loop uses
+\axiom{i} from the outer loop and the \axiom{j} from the \axiom{for}
+clause that it directly modifies.
+}{
+\begin{spadsrc}
+for i in 1..50 repeat
+  for j in 1..50 | factorial(i+j) < 25 repeat
+    output [i,j]
+\end{spadsrc}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangLoopsParTitle}{Parallel Iteration}
+\newcommand{\ugLangLoopsParNumber}{5.4.14.}
+
+@
+\section{Parallel Iteration}
+\label{ugLangLoopsParPage}
+\begin{itemize}
+\item ugLangLoopsForInPredPage \ref{ugLangLoopsForInPredPage} on
+page~\pageref{ugLangLoopsForInPredPage}
+\end{itemize}
+\index{pages!ugLangLoopsParPage!ug05.ht}
+\index{ug05.ht!pages!ugLangLoopsParPage}
+\index{ugLangLoopsParPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangLoopsParPage}{5.4.14. Parallel Iteration}
+\beginscroll
+
+The last example of
+\texht{the previous section}{
+\downlink{``\ugLangLoopsForInPredTitle''}{ugLangLoopsForInPredPage} 
+in Section \ugLangLoopsForInPredNumber\ignore{ugLangLoopsForInPred}}
+gives an example of
+\spadgloss{nested iteration}: a loop is contained
+in another loop.
+Sometimes you want to iterate across two lists in parallel, or perhaps
+you want to traverse a list while incrementing a variable.
+
+\beginImportant
+The general syntax of a repeat loop is
+\centerline{{{\tt \subscriptIt{iterator}{1} \subscriptIt{iterator}{2} \ldots \subscriptIt{iterator}{N} repeat {\it loopBody}}}}
+where each {\it iterator} is either a \axiom{for} or a \axiom{while} clause.
+The loop terminates immediately when the end test of any {\it iterator}
+succeeds or when a \axiom{break} or \axiom{return} expression is evaluated
+in {\it loopBody}.
+The value returned by the loop is \void{}.
+\endImportant
+
+\xtc{
+Here we write a loop to iterate across
+two lists, computing the sum of the pairwise product
+of elements. Here is the first list.
+}{
+\spadpaste{l := [1,3,5,7] \bound{l}}
+}
+\xtc{
+And the second.
+}{
+\spadpaste{m := [100,200] \bound{m}}
+}
+\xtc{
+The initial value of the sum counter.
+}{
+\spadpaste{sum := 0 \bound{sum}}
+}
+\xtc{
+The last two elements of \axiom{l} are not used in the calculation
+because \axiom{m} has two fewer elements than \axiom{l}.
+}{
+\begin{spadsrc}[\bound{doit}\free{sum l m}]
+for x in l for y in m repeat
+    sum := sum + x*y
+\end{spadsrc}
+}
+\xtc{
+Display the ``dot product.''
+}{
+\spadpaste{sum \free{doit}}
+}
+
+\xtc{
+Next, we write a loop to compute the sum of the products of the loop 
+elements with
+their positions in the loop.
+}{
+\spadpaste{l := [2,3,5,7,11,13,17,19,23,29,31,37] \bound{l1}}
+}
+\xtc{
+The initial sum.
+}{
+\spadpaste{sum := 0 \bound{sum1}}
+}
+\xtc{
+Here looping stops when the list \axiom{l} is exhausted, even though
+the \axiom{for i in 0..} specifies no terminating condition.
+}{
+\spadpaste{for i in 0.. for x in l repeat sum := i * x \bound{doit1}\free{sum1 l1}}
+}
+\xtc{
+Display this weighted sum.
+}{
+\spadpaste{sum \free{doit1}}
+}
+
+When \axiomSyntax{|} is used to qualify any of the \axiom{for} clauses in a
+parallel iteration, the variables in the predicates can be from an outer
+scope or from a \axiom{for} clause in or to the left of a modified clause.
+
+This is correct:
+\begin{verbatim}
+for i in 1..10 repeat
+  for j in 200..300 | odd? (i+j) repeat
+    output [i,j]
+\end{verbatim}
+This is not correct since the variable \axiom{j} has not been
+defined outside the inner loop.
+\begin{verbatim}
+for i in 1..10 | odd? (i+j) repeat  -- wrong, j not defined
+  for j in 200..300 repeat
+    output [i,j]
+\end{verbatim}
+
+%>% *********************************************************************
+%>\head{subsection}{Mixing Loop Modifiers}{ugLangLoopsMix}
+%>% *********************************************************************
+
+\xtc{
+This example shows that it is possible to mix several of the
+forms of \axiom{repeat} modifying clauses on a loop.
+}{
+\begin{spadsrc}
+for i in 1..10
+    for j in 151..160 | odd? j
+      while i + j < 160 repeat
+        output [i,j]
+\end{spadsrc}
+}
+%
+Here are useful rules for composing loop expressions:
+\indent{4}
+\beginitems
+\item[1. ] \axiom{while} predicates can only refer to variables that
+are global (or in an outer scope)
+or that are defined in \axiom{for} clauses to the left of the
+predicate.
+\item[2. ] A ``such that'' predicate (something following \axiomSyntax{|})
+must directly follow a \axiom{for} clause and can only refer to
+variables that are global (or in an outer scope)
+or defined in the modified \axiom{for} clause
+or any \axiom{for} clause to the left.
+\enditems
+\indent{0}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangItsTitle}{Creating Lists and Streams with Iterators}
+\newcommand{\ugLangItsNumber}{5.5.}
+
+@
+\section{Creating Lists and Streams with Iterators}
+\label{ugLangItsPage}
+\begin{itemize}
+\item ugLangLoopsPage \ref{ugLangLoopsPage} on
+page~\pageref{ugLangLoopsPage}
+\item ListXmpPage \ref{ListXmpPage} on
+page~\pageref{ListXmpPage}
+\item StreamXmpPage \ref{StreamXmpPage} on
+page~\pageref{StreamXmpPage}
+\end{itemize}
+\index{pages!ugLangItsPage!ug05.ht}
+\index{ug05.ht!pages!ugLangItsPage}
+\index{ugLangItsPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangItsPage}{5.5. Creating Lists and Streams with Iterators}
+\beginscroll
+
+All of what we did for loops in 
+\downlink{``\ugLangLoopsTitle''}{ugLangLoopsPage} 
+in Section \ugLangLoopsNumber\ignore{ugLangLoops}
+can be transformed into expressions that create lists
+and streams.
+The \axiom{repeat,} \axiom{break} or \axiom{iterate} words are not used but
+all the other ideas carry over.
+Before we give you the general rule, here are some examples which
+give you the idea.
+
+\xtc{
+This creates a simple list of the integers from \axiom{1} to \axiom{10}.
+}{
+\spadpaste{list := [i for i in 1..10] \bound{list}}
+}
+\xtc{
+Create a stream of the integers greater than or equal to \axiom{1}.
+}{
+\spadpaste{stream := [i for i in 1..] \bound{stream}}
+}
+\xtc{
+This is a list of the prime integers between \axiom{1} and \axiom{10},
+inclusive.
+}{
+\spadpaste{[i for i in 1..10 | prime? i]}
+}
+\xtc{
+This is a stream of the prime integers greater than or equal to \axiom{1}.
+}{
+\spadpaste{[i for i in 1..   | prime? i]}
+}
+\xtc{
+This is a list of the integers between \axiom{1} and \axiom{10},
+inclusive, whose squares are less than \axiom{700}.
+}{
+\spadpaste{[i for i in 1..10 while i*i < 700]}
+}
+\xtc{
+This is a stream of the integers greater than or equal to \axiom{1}
+whose squares are less than \axiom{700}.
+}{
+\spadpaste{[i for i in 1..   while i*i < 700]}
+}
+
+Got the idea?
+Here is the general rule.
+
+\beginImportant
+The general syntax of a collection is
+\centerline{{{\tt [ {\it collectExpression} \subscriptIt{iterator}{1}  \subscriptIt{iterator}{2}  \ldots  \subscriptIt{iterator}{N} ]}}}
+where each \subscriptIt{iterator}{i} is either a \axiom{for} or a
+\axiom{while} clause.
+The loop terminates immediately when the end test of any
+\subscriptIt{iterator}{i} succeeds or when a \axiom{return} expression is
+evaluated in {\it collectExpression}.
+The value returned by the collection is either a list or a stream of
+elements, one for each iteration of the {\it collectExpression}.
+\endImportant
+
+Be careful when you use \axiom{while}
+to create a stream.
+By default, Axiom tries to compute and display the first ten elements
+of a stream.
+If the \axiom{while} condition is not satisfied quickly, Axiom
+can spend a long (possibly infinite) time trying to compute
+the elements.
+Use \spadcmd{)set streams calculate} to change the default
+to something else.
+This also affects the number of terms computed and displayed for power
+series.
+For the purposes of this book, we have used this system
+command to display fewer than ten terms.
+\xtc{
+Use nested iterators to create lists of
+lists which can then be given as an argument to \axiomFun{matrix}.
+}{
+\spadpaste{matrix [[x**i+j for i in 1..3] for j in 10..12]}
+}
+\xtc{
+You can also create lists of streams, streams of lists and
+streams of streams.
+Here is a stream of streams.
+}{
+\spadpaste{[[i/j for i in j+1..] for j in 1..]}
+}
+\xtc{
+You can use parallel iteration across lists and streams to create
+new lists.
+}{
+\spadpaste{[i/j for i in 3.. by 10 for j in 2..]}
+}
+\xtc{
+Iteration stops if the end of a list or stream is reached.
+}{
+\spadpaste{[i**j for i in 1..7 for j in 2.. ]}
+}
+%\xtc{
+%or a while condition fails.
+%}{
+%\spadcommand{[i**j for i in 1..  for j in 2.. while i + j < 5 ]}
+%}
+\xtc{
+As with loops, you can combine these modifiers to make very
+complicated conditions.
+}{
+\spadpaste{[[[i,j] for i in 10..15 | prime? i] for j in 17..22 | j = squareFreePart j]}
+}
+
+See \downlink{`List'}{ListXmpPage}\ignore{List} and 
+\downlink{`Stream'}{StreamXmpPage}\ignore{Stream} 
+for more information on creating and
+manipulating lists and streams, respectively.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug05.ht>>=
+\newcommand{\ugLangStreamsPrimesTitle}{An Example: Streams of Primes}
+\newcommand{\ugLangStreamsPrimesNumber}{5.6.}
+
+@
+\section{An Example: Streams of Primes}
+\label{ugLangStreamsPrimesPage}
+\index{pages!ugLangStreamsPrimesPage!ug05.ht}
+\index{ug05.ht!pages!ugLangStreamsPrimesPage}
+\index{ugLangStreamsPrimesPage!ug05.ht!pages}
+<<ug05.ht>>=
+\begin{page}{ugLangStreamsPrimesPage}{5.6. An Example: Streams of Primes}
+\beginscroll
+
+We conclude this chapter with an example of the creation and manipulation
+of infinite streams of prime integers.
+This might be useful for experiments with numbers or other applications
+where you are using sequences of primes over and over again.
+As for all streams, the stream of primes is only computed as far out as you
+need.
+Once computed, however, all the primes up to that point are saved for
+future reference.
+
+Two useful operations provided by the Axiom library are
+\axiomFunFrom{prime?}{IntegerPrimesPackage} and
+\axiomFunFrom{nextPrime}{IntegerPrimesPackage}.
+A straight-forward way to create a stream of
+prime numbers is to start with the stream of positive integers \axiom{[2,..]} and
+filter out those that are prime.
+\xtc{
+Create a stream of primes.
+}{
+\spadpaste{primes : Stream Integer := [i for i in 2.. | prime? i]}
+}
+A more elegant way, however, is to use the \axiomFunFrom{generate}{Stream}
+operation from \axiomType{Stream}.
+Given an initial value \axiom{a} and a function \axiom{f},
+\axiomFunFrom{generate}{Stream}
+constructs the stream \axiom{[a, f(a), f(f(a)), ...]}.
+This function gives you the quickest method of getting the stream of primes.
+\xtc{
+This is how you use
+\axiomFunFrom{generate}{Stream} to
+generate an infinite stream of primes.
+}{
+\spadpaste{primes := generate(nextPrime,2)}
+}
+\xtc{
+Once the stream is generated, you might only be interested in
+primes starting at a particular value.
+}{
+\spadpaste{smallPrimes := [p for p in primes | p > 1000] \bound{smallPrimes}}
+}
+\xtc{
+Here are the first 11 primes greater than 1000.
+}{
+\spadpaste{[p for p in smallPrimes for i in 1..11] \free{smallPrimes}}
+}
+\xtc{
+Here is a stream of primes between 1000 and 1200.
+}{
+\spadpaste{[p for p in smallPrimes while p < 1200] \free{smallPrimes}}
+}
+\xtc{
+To get these expanded into a finite stream,
+you call \axiomFunFrom{complete}{Stream} on the stream.
+}{
+\spadpaste{complete \%}
+}
+\xtc{
+Twin primes are consecutive odd number pairs which are prime.
+Here is the stream of twin primes.
+}{
+\spadpaste{twinPrimes := [[p,p+2] for p in primes | prime?(p + 2)]}
+}
+\xtc{
+Since we already have the primes computed we can
+avoid the call to \axiomFunFrom{prime?}{IntegerPrimesPackage}
+by using a double iteration.
+This time we'll just generate a stream of the first of the twin primes.
+}{
+\spadpaste{firstOfTwins:= [p for p in primes for q in rest primes | q=p+2]}
+}
+
+Let's try to compute the infinite stream of triplet primes,
+the set of primes \axiom{p} such that \axiom{[p,p+2,p+4]}
+are primes. For example, \axiom{[3,5,7]} is a triple prime.
+We could do this by a triple \axiom{for} iteration.
+A more economical way is to use \userfun{firstOfTwins}.
+This time however, put a semicolon at the end of the line.
+
+\xtc{Create the stream of firstTriplets.
+Put a semicolon at the end so that no
+elements are computed.
+}{
+\spadpaste{firstTriplets := [p for p in firstOfTwins for q in rest firstOfTwins | q = p+2];}
+}
+
+What happened?
+As you know, by default
+Axiom displays the first ten
+elements of a stream when you first display it.
+And, therefore, it needs to compute them!
+If you want {\it no} elements computed, just terminate the expression by a
+semicolon (\axiomSyntax{;}).\footnote{
+Why does this happen? The semi-colon prevents the display of the
+result of evaluating the expression.
+Since no stream elements are needed for display (or anything else, so far),
+none are computed.
+}
+
+\xtc{
+Compute the first triplet prime.
+}{
+\spadpaste{firstTriplets.1}
+}
+
+If you want to compute another, just ask for it.
+But wait a second!
+Given three consecutive odd integers, one of them must be divisible
+by 3. Thus there is only one triplet prime.
+But suppose that you did not know this and wanted to know what was the
+tenth triplet prime.
+\begin{verbatim}
+firstTriples.10
+\end{verbatim}
+To compute the tenth triplet prime, Axiom first must compute the second,
+the third, and so on.
+But since there isn't even a second triplet prime, Axiom will
+compute forever.
+Nonetheless, this effort can produce a useful result.
+After waiting a bit, hit
+\texht{\fbox{\bf Ctrl}--\fbox{\bf c}}{{\bf Ctrl-c}}.
+The system responds as follows.
+\begin{verbatim}
+   >> System error:
+   Console interrupt.
+   You are being returned to the top level of
+   the interpreter.
+\end{verbatim}
+Let's say that you want to know how many primes have been computed.
+Issue
+\begin{verbatim}
+numberOfComputedEntries primes
+\end{verbatim}
+and, for this discussion, let's say that the result is \axiom{2045.}
+\xtc{
+How big is the \eth{\axiom{2045}} prime?
+}{
+\spadpaste{primes.2045}
+}
+
+What you have learned is that there are no triplet primes between 5 and
+17837.
+Although this result is well known (some might even say trivial), there
+are many experiments you could make where the result is not known.
+What you see here is a paradigm for testing of hypotheses.
+Here our hypothesis could have been: ``there is more than one triplet
+prime.''
+We have tested this hypothesis for 17837 cases.
+With streams, you can let your machine run, interrupt it to see how far
+it has progressed,
+then start it up and let it continue from where it left off.
+
+%> RDJ note to RSS:
+%> Expressions not statements or lines--
+%>   By an expression I mean any syntactically correct program fragment.
+%>   Everything in Axiom is an expression since every fragment has a value and a type.
+%>   In most languages including LISP, a "statement" is different from an expression:
+%>   it is executed for side-effect only and an error is incurred if you assign it a value.
+%>   This "gimmick" takes care of incomplete expressions such as "if x > 0 then y" in blocks.
+%>   In LISP, "u := (if x > 0 then y)" is illegal but in Axiom it is legal.
+%>   Also, in Axiom the value of a repeat loop is void even though you might be
+%>   be able to prove that it always returns a valid value (you have an example of this)!
+%>   This will be considered a bug not a feature. But it is how things stand.
+%>   In any case---this point should be in a box somewhere since it is key
+%>   to a user's understanding to the language. I am not sure where. You only
+%>   gain an appreciation for it after are awhile in chapter 5.
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\chapter{Users Guide Chapter 6 (ug06.ht)}
+<<ug06.ht>>=
+\newcommand{\pred}[1]{\subscriptIt{pred}{#1}}
+\newcommand{\expr}[1]{\subscriptIt{expression}{#1}}
+\newcommand{\ugUserTitle}{User-Defined Functions, Macros and Rules}
+\newcommand{\ugUserNumber}{6.}
+
+@
+\section{User-Defined Functions, Macros and Rules}
+\label{ugUserPage}
+\begin{itemize}
+\item ugUserFunMacPage \ref{ugUserFunMacPage} on
+page~\pageref{ugUserFunMacPage}
+\item ugUserMacrosPage \ref{ugUserMacrosPage} on
+page~\pageref{ugUserMacrosPage}
+\item ugUserIntroPage \ref{ugUserIntroPage} on
+page~\pageref{ugUserIntroPage}
+\item ugUserDeclarePage \ref{ugUserDeclarePage} on
+page~\pageref{ugUserDeclarePage}
+\item ugUserOnePage \ref{ugUserOnePage} on
+page~\pageref{ugUserOnePage}
+\item ugUserDecUndecPage \ref{ugUserDecUndecPage} on
+page~\pageref{ugUserDecUndecPage}
+\item ugUserDecOpersPage \ref{ugUserDecOpersPage} on
+page~\pageref{ugUserDecOpersPage}
+\item ugUserDelayPage \ref{ugUserDelayPage} on
+page~\pageref{ugUserDelayPage}
+\item ugUserUsePage \ref{ugUserUsePage} on
+page~\pageref{ugUserUsePage}
+\item ugUserCompIntPage \ref{ugUserCompIntPage} on
+page~\pageref{ugUserCompIntPage}
+\item ugUserPiecePage \ref{ugUserPiecePage} on
+page~\pageref{ugUserPiecePage}
+\item ugUserCachePage \ref{ugUserCachePage} on
+page~\pageref{ugUserCachePage}
+\item ugUserRecurPage \ref{ugUserRecurPage} on
+page~\pageref{ugUserRecurPage}
+\item ugUserMakePage \ref{ugUserMakePage} on
+page~\pageref{ugUserMakePage}
+\item ugUserBlocksPage \ref{ugUserBlocksPage} on
+page~\pageref{ugUserBlocksPage}
+\item ugUserFreeLocalPage \ref{ugUserFreeLocalPage} on
+page~\pageref{ugUserFreeLocalPage}
+\item ugUserAnonPage \ref{ugUserAnonPage} on
+page~\pageref{ugUserAnonPage}
+\item ugUserDatabasePage \ref{ugUserDatabasePage} on
+page~\pageref{ugUserDatabasePage}
+\item ugUserTrianglePage \ref{ugUserTrianglePage} on
+page~\pageref{ugUserTrianglePage}
+\item ugUserPalPage \ref{ugUserPalPage} on
+page~\pageref{ugUserPalPage}
+\item ugUserRulesPage \ref{ugUserRulesPage} on
+page~\pageref{ugUserRulesPage}
+\end{itemize}
+\index{pages!ugUserPage!ug06.ht}
+\index{ug06.ht!pages!ugUserPage}
+\index{ugUserPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserPage}{6. User-Defined Functions, Macros and Rules}
+\beginscroll
+
+In this chapter we show you how to write functions and macros,
+and we explain how Axiom looks for and applies them.
+We show some simple one-line examples of functions, together
+with larger ones that are defined piece-by-piece or through the use of
+piles.
+
+\beginmenu
+    \menudownlink{{6.1. Functions vs. Macros}}{ugUserFunMacPage}
+    \menudownlink{{6.2. Macros}}{ugUserMacrosPage}
+    \menudownlink{{6.3. Introduction to Functions}}{ugUserIntroPage}
+    \menudownlink{{6.4. Declaring the Type of Functions}}{ugUserDeclarePage}
+    \menudownlink{{6.5. One-Line Functions}}{ugUserOnePage}
+    \menudownlink{{6.6. Declared vs. Undeclared Functions}}{ugUserDecUndecPage}
+    \menudownlink{{6.7. Functions vs. Operations}}{ugUserDecOpersPage}
+    \menudownlink{{6.8. Delayed Assignments vs. Functions with No Arguments}}
+{ugUserDelayPage}
+    \menudownlink{{6.9. How Axiom Determines What Function to Use}}
+{ugUserUsePage}
+    \menudownlink{{6.10. Compiling vs. Interpreting}}{ugUserCompIntPage}
+    \menudownlink{{6.11. Piece-Wise Function Definitions}}{ugUserPiecePage}
+    \menudownlink{{6.12. Caching Previously Computed Results}}{ugUserCachePage}
+    \menudownlink{{6.13. Recurrence Relations}}{ugUserRecurPage}
+    \menudownlink{{6.14. Making Functions from Objects}}{ugUserMakePage}
+    \menudownlink{{6.15. Functions Defined with Blocks}}{ugUserBlocksPage}
+    \menudownlink{{6.16. Free and Local Variables}}{ugUserFreeLocalPage}
+    \menudownlink{{6.17. Anonymous Functions}}{ugUserAnonPage}
+    \menudownlink{{6.18. Example: A Database}}{ugUserDatabasePage}
+    \menudownlink{{6.19. Example: A Famous Triangle}}{ugUserTrianglePage}
+    \menudownlink{{6.20. Example: Testing for Palindromes}}{ugUserPalPage}
+    \menudownlink{{6.21. Rules and Pattern Matching}}{ugUserRulesPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserFunMacTitle}{Functions vs. Macros}
+\newcommand{\ugUserFunMacNumber}{6.1.}
+
+@
+\section{Functions vs. Macros}
+\label{ugUserFunMacPage}
+\begin{itemize}
+\item ugUserAnonPage \ref{ugUserAnonPage} on
+page~\pageref{ugUserAnonPage}
+\item ExitXmpPage \ref{ExitXmpPage} on
+page~\pageref{ExitXmpPage}
+\item VoidXmpPage \ref{VoidXmpPage} on
+page~\pageref{VoidXmpPage}
+\end{itemize}
+\index{pages!ugUserFunMacPage!ug06.ht}
+\index{ug06.ht!pages!ugUserFunMacPage}
+\index{ugUserFunMacPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserFunMacPage}{6.1. Functions vs. Macros}
+\beginscroll
+
+A function is a program to perform some
+computation.
+Most functions have names so that it is easy to refer to them.
+A simple example of a function is one named
+\axiomFunFrom{abs}{Integer} which
+computes the absolute value of an integer.
+%
+\xtc{
+This is a use of the ``absolute value'' library function for integers.
+}{
+\spadpaste{abs(-8)}
+}
+\xtc{
+This is an unnamed function that does the same thing, using the
+``maps-to'' syntax \axiomSyntax{+->} that we discuss in
+\downlink{``\ugUserAnonTitle''}{ugUserAnonPage} 
+in Section \ugUserAnonNumber\ignore{ugUserAnon}.
+}{
+\spadpaste{(x +-> if x < 0 then -x else x)(-8)}
+}
+%
+Functions can be used alone or serve as the building blocks for larger
+programs.
+Usually they return a value that you might want to use in the next stage
+of a computation, but not always (for example, see
+\downlink{`Exit'}{ExitXmpPage}\ignore{Exit} and 
+\downlink{`Void'}{VoidXmpPage}\ignore{Void}).
+They may also read data from your keyboard, move information from one
+place to another, or format and display results on your screen.
+
+In Axiom, as in mathematics, functions
+are usually \spadglossSee{parameterized}{parameterized form}.
+Each time you {\it call} (some people say \spadgloss{apply} or
+\spadglossSee{invoke}{invocation}) a function, you give
+values to the parameters (variables).
+Such a value is called an \spadgloss{argument} of
+the function.
+Axiom uses the arguments for the computation.
+In this way you get different results depending on what you ``feed'' the
+function.
+
+Functions can have local variables or refer to global variables in the
+workspace.
+Axiom can often \spadglossSee{compile}{compiler} functions so that
+they execute very efficiently.
+Functions can be passed as arguments to other functions.
+
+Macros are textual substitutions.
+They are used to clarify the meaning of constants or expressions and to be
+templates for frequently used expressions.
+Macros can be parameterized but they are not objects that can be passed as
+arguments to functions.
+In effect, macros are extensions to the Axiom expression parser.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserMacrosTitle}{Macros}
+\newcommand{\ugUserMacrosNumber}{6.2.}
+
+@
+\section{Macros}
+\label{ugUserMacrosPage}
+\index{pages!ugUserMacrosPage!ug06.ht}
+\index{ug06.ht!pages!ugUserMacrosPage}
+\index{ugUserMacrosPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserMacrosPage}{6.2. Macros}
+\beginscroll
+
+A \spadgloss{macro} provides general textual substitution of
+an Axiom expression for a name.
+You can think of a macro as being a generalized abbreviation.
+You can only have one macro in your workspace with
+a given name, no matter how many arguments it has.
+
+\beginImportant
+The two general forms for macros are
+\centerline{{{\tt macro} {\it name} {\tt ==} {\it body} }}
+\centerline{{{\tt macro} {\it name(arg1,...)} {\tt ==} {\it body}}}
+where the body of the macro can be any Axiom expression.
+\endImportant
+
+%
+\xtc{
+For example, suppose you decided that you
+like to use \axiom{df} for \axiomFun{D}.
+You define the macro \axiom{df} like this.
+}{
+\spadpaste{macro df == D \bound{df}}
+}
+\xtc{
+Whenever you type \axiom{df}, the system expands it to
+\axiomFun{D}.
+}{
+\spadpaste{df(x**2 + x + 1,x) \free{df}}
+}
+\xtc{
+Macros can be parameterized and so can be used for many different
+kinds of objects.
+}{
+\spadpaste{macro ff(x) == x**2 + 1 \bound{ff}}
+}
+\xtc{
+Apply it to a number, a symbol, or an expression.
+}{
+\spadpaste{ff z \free{ff}}
+}
+\xtc{
+Macros can also be nested, but you get an error message if you
+run out of space because of an infinite nesting loop.
+}{
+\spadpaste{macro gg(x) == ff(2*x - 2/3) \bound{gg}\free{ff}}
+}
+\xtc{
+This new macro is fine as it does not produce a loop.
+}{
+\spadpaste{gg(1/w) \free{gg}}
+}
+%
+\xtc{
+This, however, loops since \axiom{gg} is
+defined in terms of \axiom{ff}.
+}{
+\spadpaste{macro ff(x) == gg(-x) \free{gg}}
+}
+\xtc{
+The body of a macro can be a block.
+}{
+\spadpaste{macro next == (past := present; present := future; future := past + present) \bound{next}}
+}
+\xtc{
+Before entering \axiom{next}, we need
+values for \axiom{present} and \axiom{future}.
+}{
+\spadpaste{present : Integer := 0 \bound{present}}
+}
+\xtc{
+}{
+\spadpaste{future : Integer := 1 \bound{future}}
+}
+\xtc{
+Repeatedly evaluating \axiom{next} produces the next Fibonacci number.
+}{
+\spadpaste{next \free{future}\free{present}}
+}
+\xtc{
+And the next one.
+}{
+\spadpaste{next \free{future}\free{present}}
+}
+\xtc{
+Here is the infinite stream of the rest of the Fibonacci numbers.
+}{
+\spadpaste{[next for i in 1..] \free{future}\free{present}}
+}
+\xtc{
+Bundle all the above lines into a single macro.
+}{
+\begin{spadsrc}[\bound{fibstr}]
+macro fibStream ==
+  present : Integer := 1
+  future : Integer := 1
+  [next for i in 1..] where
+    macro next ==
+      past := present
+      present := future
+      future := past + present
+\end{spadsrc}
+}
+\xtc{
+Use \axiomFunFrom{concat}{Stream} to start with the first two
+Fibonacci numbers.
+}{
+\spadpaste{concat([0,1],fibStream) \free{fibstr}}
+}
+\xtc{
+An easier way to compute these numbers is to
+use the library operation \axiomFun{fibonacci}.
+}{
+\spadpaste{[fibonacci i for i in 1..]}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserIntroTitle}{Introduction to Functions}
+\newcommand{\ugUserIntroNumber}{6.3.}
+
+@
+\section{Introduction to Functions}
+\label{ugUserIntroPage}
+\begin{itemize}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\item ugUserAnonPage \ref{ugUserAnonPage} on
+page~\pageref{ugUserAnonPage}
+\end{itemize}
+\index{pages!ugUserIntroPage!ug06.ht}
+\index{ug06.ht!pages!ugUserIntroPage}
+\index{ugUserIntroPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserIntroPage}{6.3. Introduction to Functions}
+\beginscroll
+
+Each name in your workspace can refer to a single object.
+This may be any kind of object including a function.
+You can use interactively any function from the library or any that you
+define in the workspace.
+In the library the same name can have very many functions, but you
+can have only one function with a given name, although it can have any
+number of arguments that you choose.
+
+If you define a function in the workspace that has the same name and number
+of arguments as one in the library, then your definition takes precedence.
+In fact, to get the library function you must
+\spadglossSee{package-call}{package call} it (see 
+\downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} 
+in Section \ugTypesPkgCallNumber\ignore{ugTypesPkgCall}).
+
+To use a function in Axiom, you apply it to its arguments.
+Most functions are applied by entering the name of the function followed by
+its argument or arguments.
+\xtc{
+}{
+\spadpaste{factor(12)}
+}
+%
+\xtc{
+Some functions like 
+\axiomOp{+} have {\it infix} \spadgloss{operators} as names.
+}{
+\spadpaste{3 + 4}
+}
+\xtc{
+The function \axiomOp{+} has two arguments.
+When you give it more than two arguments,
+Axiom groups the arguments to the left.
+This expression is equivalent to \axiom{(1 + 2) + 7}.
+}{
+\spadpaste{1 + 2 + 7}
+}
+
+All operations, including infix operators, can be written in prefix form,
+that is, with the operation name followed by the arguments
+in parentheses.
+For example, \axiom{2 + 3} can alternatively be written as \axiom{+(2,3)}.
+But \axiom{+(2,3,4)} is an error since \axiomOp{+}
+takes only two arguments.
+
+Prefix operations are generally applied before the infix operation.
+Thus \axiom{factorial 3 + 1} means \axiom{factorial(3) + 1} producing
+\axiom{7}, and
+\axiom{- 2 + 5} means \axiom{(-2) + 5} producing \axiom{3}.
+An example of a prefix operator is prefix \axiomOp{-}.
+For example, \axiom{- 2 + 5} converts to \axiom{(- 2) + 5} producing
+the value \axiom{3}.
+Any prefix function taking two arguments can be written in
+an infix manner by putting an
+ampersand (\axiomSyntax{\&}) before the name.
+Thus \axiom{D(2*x,x)} can be written as
+\axiom{2*x \&D x} returning \axiom{2}.
+
+Every function in Axiom is identified by
+a \spadgloss{name} and \spadgloss{type}.\footnote{An exception is
+an ``anonymous function''
+discussed in
+\downlink{``\ugUserAnonTitle''}{ugUserAnonPage} 
+in Section \ugUserAnonNumber\ignore{ugUserAnon}.}
+The type of a function is always a mapping of the form
+\spadsig{Source}{Target}
+where \axiom{Source} and \axiom{Target} are types.
+To enter a type from the keyboard, enter the arrow by using
+a hyphen \axiomSyntax{-} followed by a greater-than sign
+\axiomSyntax{>}, e.g. {\tt Integer -> Integer}.
+
+Let's go back to \axiomOp{+}.
+There are many \axiomOp{+} functions in the
+Axiom library: one for integers, one for floats, another for
+rational numbers, and so on.
+These \axiomOp{+} functions have different types and thus are
+different functions.
+You've seen examples of this \spadgloss{overloading}
+before---using the same name for different functions.
+Overloading is the rule rather than the exception.
+You can add two integers, two polynomials, two matrices or
+two power series.
+These are all done with the same function name
+but with different functions.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserDeclareTitle}{Declaring the Type of Functions}
+\newcommand{\ugUserDeclareNumber}{6.4.}
+
+@
+\section{Declaring the Type of Functions}
+\label{ugUserDeclarePage}
+\begin{itemize}
+\item ugTypesDeclarePage \ref{ugTypesDeclarePage} on
+page~\pageref{ugTypesDeclarePage}
+\end{itemize}
+\index{pages!ugUserDeclarePage!ug06.ht}
+\index{ug06.ht!pages!ugUserDeclarePage}
+\index{ugUserDeclarePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserDeclarePage}{6.4. Declaring the Type of Functions}
+\beginscroll
+
+In \downlink{``\ugTypesDeclareTitle''}{ugTypesDeclarePage} 
+in Section \ugTypesDeclareNumber\ignore{ugTypesDeclare} we 
+discussed how to declare a variable
+to restrict the kind of values that can be assigned to it.
+In this section we show how to declare a variable that refers to
+function objects.
+
+\beginImportant
+A function is an object of type
+\centerline{{\spadsig{Source}{Type}}}
+where \axiom{Source} and \axiom{Target} can be any type.
+A common type for \axiom{Source} is
+\axiomType{Tuple}(\subscriptIt{T}{1}, \ldots, \subscriptIt{T}{n}),
+usually written
+(\subscriptIt{T}{1}, \ldots, \subscriptIt{T}{n}),
+to indicate a function of \axiom{n} arguments.
+\endImportant
+
+\xtc{
+If \axiom{g} takes an \axiomType{Integer}, a \axiomType{Float} and
+another \axiomType{Integer}, and returns a
+\axiomType{String}, the declaration is written this way.
+}{
+\spadpaste{g: (Integer,Float,Integer) -> String}
+}
+\xtc{
+The types need not be written fully; using abbreviations, the above
+declaration is:
+}{
+\spadpaste{g: (INT,FLOAT,INT) -> STRING}
+}
+\xtc{
+It is possible for a function to take no arguments.
+If \axiom{ h} takes no arguments
+but returns a \axiomType{Polynomial} \axiomType{Integer}, any
+of the following declarations is acceptable.
+}{
+\spadpaste{h: () -> POLY INT}
+}
+\xtc{
+}{
+\spadpaste{h: () -> Polynomial INT}
+}
+\xtc{
+}{
+\spadpaste{h: () -> POLY Integer}
+}
+
+
+\beginImportant
+Functions can also be declared when they are being defined.
+The syntax for combined declaration/definition is:
+\centerline{{\frenchspacing{\tt {\it functionName}(\subscriptIt{parm}{1}: \subscriptIt{parmType}{1}, \ldots, \subscriptIt{parm}{N}: \subscriptIt{parmType}{N}): {\it functionReturnType}}}}
+\endImportant
+
+The following definition fragments show how this can be done for
+the functions \axiom{g} and \axiom{h} above.
+\begin{verbatim}
+g(arg1: INT, arg2: FLOAT, arg3: INT): STRING == ...
+
+h(): POLY INT == ...
+\end{verbatim}
+
+A current restriction on function declarations is that they must
+involve fully specified types (that is, cannot include modes involving
+explicit or implicit \axiomSyntax{?}).
+For more information on declaring things in general, see
+\downlink{``\ugTypesDeclareTitle''}{ugTypesDeclarePage} 
+in Section \ugTypesDeclareNumber\ignore{ugTypesDeclare}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserOneTitle}{One-Line Functions}
+\newcommand{\ugUserOneNumber}{6.5.}
+
+@
+\section{One-Line Functions}
+\label{ugUserOnePage}
+\index{pages!ugUserOnePage!ug06.ht}
+\index{ug06.ht!pages!ugUserOnePage}
+\index{ugUserOnePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserOnePage}{6.5. One-Line Functions}
+\beginscroll
+
+As you use Axiom, you will find that you will write many short functions
+to codify sequences of operations that you often perform.
+In this section we write some simple one-line functions.
+
+\xtc{
+This is a simple recursive factorial function for positive integers.
+}{
+\spadpaste{fac n == if n < 3 then n else n * fac(n-1) \bound{fac}}
+}
+\xtc{
+}{
+\spadpaste{fac 10 \free{fac}}
+}
+%>> Thankfully, the $ is no longer needed in the next example.
+\xtc{
+This function computes \axiom{1 + 1/2 + 1/3 + ... + 1/n}.
+}{
+\spadpaste{s n == reduce(+,[1/i for i in 1..n]) \bound{s}}
+}
+\xtc{
+}{
+\spadpaste{s 50 \free{s}}
+}
+\xtc{
+This function computes a Mersenne number, several of which are prime.
+}{
+\spadpaste{mersenne i == 2**i - 1 \bound{mersenne}}
+}
+\xtc{
+If you type \axiom{mersenne}, Axiom shows you
+the function definition.
+}{
+\spadpaste{mersenne \free{mersenne}}
+}
+\xtc{
+Generate a stream of Mersenne numbers.
+}{
+\spadpaste{[mersenne i for i in 1..] \free{mersenne}}
+}
+\xtc{
+Create a stream of those values of \axiom{i} such that
+\axiom{mersenne(i)} is prime.
+}{
+\spadpaste{mersenneIndex := [n for n in 1.. | prime?(mersenne(n))] \bound{mersenneIndex}\free{mersenne}}
+}
+\xtc{
+Finally, write a function that returns the \eth{\axiom{n}} Mersenne
+prime.
+}{
+\spadpaste{mersennePrime n == mersenne mersenneIndex(n) \free{mersenne mersenneIndex}\bound{mersennePrime}}
+}
+\xtc{
+}{
+\spadpaste{mersennePrime 5 \free{mersennePrime}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserDecUndecTitle}{Declared vs. Undeclared Functions}
+\newcommand{\ugUserDecUndecNumber}{6.6.}
+
+@
+\section{Declared vs. Undeclared Functions}
+\label{ugUserDecUndecPage}
+\begin{itemize}
+\item ugCategoriesPage \ref{ugCategoriesPage} on
+page~\pageref{ugCategoriesPage}
+\end{itemize}
+\index{pages!ugUserDecUndecPage!ug06.ht}
+\index{ug06.ht!pages!ugUserDecUndecPage}
+\index{ugUserDecUndecPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserDecUndecPage}{6.6. Declared vs. Undeclared Functions}
+\beginscroll
+
+If you declare the type of a function, you can apply
+it to any data that can be converted to the source type
+of the function.
+
+\labelSpace{2pc}
+\xtc{
+Define \userfun{f} with type \spadsig{Integer}{Integer}.
+}{
+\spadpaste{f(x: Integer): Integer == x + 1 \bound{f}}
+}
+\xtc{
+The function
+\userfun{f} can be applied to integers, \ldots
+}{
+\spadpaste{f 9 \free{f}}
+}
+\xtc{
+and to values that convert to integers, \ldots
+}{
+\spadpaste{f(-2.0) \free{f}}
+}
+\xtc{
+but not to values that cannot be converted to integers.
+}{
+\spadpaste{f(2/3) \free{f}}
+}
+
+To make the function over a wide range of types, do not
+declare its type.
+\xtc{
+Give the same definition with no declaration.
+}{
+\spadpaste{g x == x + 1 \bound{g}}
+}
+\xtc{
+If \axiom{x + 1} makes sense, you can apply \userfun{g} to \axiom{x}.
+}{
+\spadpaste{g 9 \free{g}}
+}
+\xtc{
+A version of \userfun{g} with different argument types
+get compiled for each new kind of argument used.
+}{
+\spadpaste{g(2/3)  \free{g}}
+}
+\xtc{
+Here \axiom{x+1} for \axiom{x = "axiom"} makes no sense.
+}{
+\spadpaste{g("axiom")\free{g}}
+}
+
+As you will see in \downlink{``\ugCategoriesTitle''}{ugCategoriesPage} 
+in Chapter \ugCategoriesNumber\ignore{ugCategories},
+Axiom has a formal idea of categories for what ``makes sense.''
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserDecOpersTitle}{Functions vs. Operations}
+\newcommand{\ugUserDecOpersNumber}{6.7.}
+
+@
+\section{Functions vs. Operations}
+\label{ugUserDecOpersPage}
+\begin{itemize}
+\item MappingPackageOneXmpPage \ref{MappingPackageOneXmpPage} on
+page~\pageref{MappingPackageOneXmpPage}
+\item ugPackagesAbstractPage \ref{ugPackagesAbstractPage} on
+page~\pageref{ugPackagesAbstractPage}
+\item ugPackagesPage \ref{ugPackagesPage} on
+page~\pageref{ugPackagesPage}
+\item ugCategoriesPage \ref{ugCategoriesPage} on
+page~\pageref{ugCategoriesPage}
+\end{itemize}
+\index{pages!ugUserDecOpersPage!ug06.ht}
+\index{ug06.ht!pages!ugUserDecOpersPage}
+\index{ugUserDecOpersPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserDecOpersPage}{6.7. Functions vs. Operations}
+\beginscroll
+
+A function is an object that you can create, manipulate, pass to,
+and return from functions (for some interesting examples of
+library functions that manipulate functions, see
+\downlink{`MappingPackage1'}{MappingPackageOneXmpPage}
+\ignore{MappingPackage1}).
+Yet, we often seem to use the term \spadgloss{operation} and
+function interchangeably in Axiom.
+What is the distinction?
+
+First consider values and types associated with some variable \axiom{n} in
+your workspace.
+You can make the declaration \axiom{n : Integer}, then assign \axiom{n} an
+integer value.
+You then speak of the integer \axiom{n}.
+However, note that the integer is not the name \axiom{n} itself, but
+the value that you assign to \axiom{n}.
+
+Similarly, you can declare a variable \axiom{f} in your workspace to have
+type \spadsig{Integer}{Integer}, then assign \axiom{f}, through a definition
+or an assignment of an anonymous function.
+You then speak of the function \axiom{f}.
+However, the function is not \axiom{f}, but the value that you
+assign to \axiom{f}.
+
+A function is a value, in fact, some machine code for doing something.
+Doing what?
+Well, performing some \spadgloss{operation}.
+Formally, an operation consists of the constituent parts of \axiom{f} in your
+workspace, excluding the value; thus an operation has a name and a type.
+An operation is what domains and packages export.
+Thus \axiomType{Ring} exports one operation \axiomOp{+}.
+Every ring also exports this operation.
+Also, the author of every ring in the system is obliged under contract
+(see \downlink{``\ugPackagesAbstractTitle''}{ugPackagesAbstractPage} 
+in Section \ugPackagesAbstractNumber\ignore{ugPackagesAbstract})
+to provide an implementation for this operation.
+
+This chapter is all about functions---how you create them interactively and
+how you apply them to meet your needs.
+In \downlink{``\ugPackagesTitle''}{ugPackagesPage} in 
+Chapter \ugPackagesNumber\ignore{ugPackages} you will 
+learn how to create them for the
+Axiom library.
+Then in \downlink{``\ugCategoriesTitle''}{ugCategoriesPage} 
+in Chapter \ugCategoriesNumber\ignore{ugCategories}, you will 
+learn about categories and
+exported operations.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserDelayTitle}{Delayed Assignments vs. Functions with No Arguments}
+\newcommand{\ugUserDelayNumber}{6.8.}
+
+@
+\section{Delayed Assignments vs. Functions with No Arguments}
+\label{ugUserDelayPage}
+\begin{itemize}
+\item ugLangAssignPage \ref{ugLangAssignPage} on
+page~\pageref{ugLangAssignPage}
+\end{itemize}
+\index{pages!ugUserDelayPage!ug06.ht}
+\index{ug06.ht!pages!ugUserDelayPage}
+\index{ugUserDelayPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserDelayPage}
+{6.8. Delayed Assignments vs. Functions with No Arguments}
+\beginscroll
+
+In \downlink{``\ugLangAssignTitle''}{ugLangAssignPage} in Section 
+\ugLangAssignNumber\ignore{ugLangAssign} we discussed the difference 
+between immediate and
+delayed assignments.
+In this section we show the difference between delayed
+assignments and functions of no arguments.
+
+\labelSpace{2pc}
+\xtc{
+A function of no arguments is sometimes called a {\it nullary function.}
+}{
+\spadpaste{sin24() == sin(24.0) \bound{sin24}}
+}
+\xtc{
+You must use the parentheses (\axiomSyntax{()}) to evaluate it.
+Like a delayed assignment, the right-hand-side of a function evaluation
+is not evaluated until the left-hand-side is used.
+}{
+\spadpaste{sin24() \free{sin24}}
+}
+\xtc{
+If you omit the parentheses, you just get the function definition.
+%(Note how the explicit floating point number in the definition
+%has been translated into a function call involving a mantissa,
+%exponent and radix.)
+}{
+\spadpaste{sin24 \free{sin24}}
+}
+\xtc{
+You do not use the parentheses \axiomSyntax{()} in a delayed assignment\ldots
+}{
+\spadpaste{cos24 == cos(24.0) \bound{cos24}}
+}
+\xtc{
+nor in the evaluation.
+}{
+\spadpaste{cos24 \free{cos24}}
+}
+The only syntactic difference between delayed assignments
+and nullary functions is that you use \axiomSyntax{()} in the latter case.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserUseTitle}{How Axiom Determines What Function to Use}
+\newcommand{\ugUserUseNumber}{6.9.}
+
+@
+\section{How Axiom Determines What Function to Use}
+\label{ugUserUsePage}
+\begin{itemize}
+\item ugTypesPkgCallPage \ref{ugTypesPkgCallPage} on
+page~\pageref{ugTypesPkgCallPage}
+\item ugTypesResolvePage \ref{ugTypesResolvePage} on
+page~\pageref{ugTypesResolvePage}
+\end{itemize}
+\index{pages!ugUserUsePage!ug06.ht}
+\index{ug06.ht!pages!ugUserUsePage}
+\index{ugUserUsePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserUsePage}{6.9. How Axiom Determines What Function to Use}
+\beginscroll
+
+What happens if you define a function that has the same name as a library
+function?
+Well, if your function has the same name and number of arguments (we
+sometimes say \spadgloss{arity}) as another function
+in the library, then your function covers up the library function.
+If you want then to call the library function, you will have to package-call
+it.
+Axiom can use both the functions you write and those that come
+from the library.
+Let's do a simple example to illustrate this.
+\xtc{
+Suppose you (wrongly!) define \userfun{sin} in this way.
+}{
+\spadpaste{sin x == 1.0 \bound{sin}}
+}
+\xtc{
+The value \axiom{1.0} is returned for any argument.
+}{
+\spadpaste{sin 4.3 \free{sin}}
+}
+\xtc{
+If you want the library operation, we have to package-call it
+(see \downlink{``\ugTypesPkgCallTitle''}{ugTypesPkgCallPage} 
+in Section \ugTypesPkgCallNumber\ignore{ugTypesPkgCall}
+for more information).
+}{
+\spadpaste{sin(4.3)\$Float}
+}
+\xtc{
+}{
+\spadpaste{sin(34.6)\$Float}
+}
+\xtc{
+Even worse, say we accidentally used the same name as a library
+function in the function.
+}{
+\spadpaste{sin x == sin x \bound{sin1}}
+}
+\xtc{
+Then Axiom definitely does not understand us.
+}{
+\spadpaste{sin 4.3 \free{sin1}}
+}
+\xtc{
+Again, we could package-call the inside function.
+}{
+\spadpaste{sin x == sin(x)\$Float \bound{sin2}}
+}
+\xtc{
+}{
+\spadpaste{sin 4.3 \free{sin2}}
+}
+Of course, you are unlikely to make such obvious errors.
+It is more probable that you would write a function and in the body use a
+function that you think is a library function.
+If you had also written a function by that same name, the library function
+would be invisible.
+
+How does Axiom determine what library function to call?
+It very much depends on the particular example, but the simple case of
+creating the polynomial
+\axiom{x + 2/3} will give you an idea.
+\indent{4}
+\beginitems
+\item[1. ] The \axiom{x} is analyzed and its default type is
+\axiomType{Variable(x)}.
+\item[2. ] The \axiom{2} is analyzed and its default type is
+\axiomType{PositiveInteger}.
+\item[3. ] The \axiom{3} is analyzed and its default type is
+\axiomType{PositiveInteger}.
+\item[4. ] Because the arguments to \axiomOp{/} are integers, Axiom
+gives the expression \axiom{2/3} a default target type of
+\axiomType{Fraction(Integer)}.
+\item[5. ] Axiom looks in \axiomType{PositiveInteger} for \axiomOp{/}.
+It is not found.
+\item[6. ] Axiom looks in \axiomType{Fraction(Integer)} for \axiomOp{/}.
+It is found for arguments of type \axiomType{Integer}.
+\item[7. ] The \axiom{2} and \axiom{3} are converted to objects of type
+\axiomType{Integer} (this is trivial) and \axiomOp{/} is applied,
+creating an object of type \axiomType{Fraction(Integer)}.
+\item[8. ] No \axiomOp{+} for arguments of types \axiomType{Variable(x)} and
+\axiomType{Fraction(Integer)} are found in either domain.
+\item[9. ] Axiom resolves
+(see \downlink{``\ugTypesResolveTitle''}{ugTypesResolvePage} 
+in Section \ugTypesResolveNumber\ignore{ugTypesResolve})
+the types and gets \axiomType{Polynomial (Fraction (Integer))}.
+\item[10. ] The \axiom{x} and the \axiom{2/3} are converted to objects of this
+type and \axiomOp{+} is applied, yielding the answer, an object of type
+\axiomType{Polynomial (Fraction (Integer))}.
+\enditems
+\indent{0}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserCompIntTitle}{Compiling vs. Interpreting}
+\newcommand{\ugUserCompIntNumber}{6.10.}
+
+@
+\section{Compiling vs. Interpreting}
+\label{ugUserCompIntPage}
+\begin{itemize}
+\item ugTypesSubdomainsPage \ref{ugTypesSubdomainsPage} on
+page~\pageref{ugTypesSubdomainsPage}
+\end{itemize}
+\index{pages!ugUserCompIntPage!ug06.ht}
+\index{ug06.ht!pages!ugUserCompIntPage}
+\index{ugUserCompIntPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserCompIntPage}{6.10. Compiling vs. Interpreting}
+\beginscroll
+
+When possible, Axiom completely determines the type of every object in
+a function, then translates the function definition to \Lisp{} or
+to machine code (see next section).
+This translation,
+called \spadglossSee{compilation}{compiler}, happens the first time you call
+the function and results in a computational delay.
+Subsequent function calls with the same argument types use the compiled
+version of the code without delay.
+
+If Axiom cannot determine the type of everything, the
+function may still be executed
+but
+in \spadglossSee{interpret-code mode}{interpreter} :
+each statement in the function is analyzed and executed as the control
+flow indicates.
+This process is slower than executing a compiled function, but it
+allows the execution of code that may involve objects whose types
+change.
+
+\beginImportant
+If Axiom decides that it cannot compile the code, it
+issues a message stating the problem and then the following
+message:
+%
+\centerline{{{\bf We will attempt to step through and interpret the code.}}}
+%
+This is not a time to panic.
+Rather, it just means that what you gave to Axiom
+is somehow ambiguous: either it is not specific enough to be analyzed
+completely, or it is beyond Axiom's present interactive
+compilation abilities.
+\endImportant
+
+\xtc{
+This function runs in interpret-code mode, but it does not compile.
+}{
+\begin{spadsrc}[\bound{varPolys}]
+varPolys(vars) ==
+  for var in vars repeat
+    output(1 :: UnivariatePolynomial(var,Integer))
+\end{spadsrc}
+}
+\xtc{
+For \axiom{vars} equal to \axiom{['x, 'y, 'z]}, this function displays
+\axiom{1} three times.
+}{
+\spadpaste{varPolys ['x,'y,'z] \free{varPolys}}
+}
+\xtc{
+The type of the argument to \axiomFun{output} changes in each iteration,
+so Axiom cannot compile the function.
+In this case, even the inner loop by itself would have a problem:
+}{
+\begin{spadsrc}
+for var in ['x,'y,'z] repeat
+  output(1 :: UnivariatePolynomial(var,Integer))
+\end{spadsrc}
+}
+
+Sometimes you can help a function to compile by using an extra conversion
+or by using \axiom{pretend}.
+\spadkey{pretend}
+See \downlink{``\ugTypesSubdomainsTitle''}{ugTypesSubdomainsPage} 
+in Section \ugTypesSubdomainsNumber\ignore{ugTypesSubdomains} for details.
+
+When a function is compilable, you have the choice of whether it is
+compiled to \Lisp{} and then interpreted by the \Lisp{}
+interpreter or then further compiled from \Lisp{} to machine code.
+The option is controlled via \spadcmd{)set functions compile}.
+Issue \spadcmd{)set functions compile on} to compile all the way to
+machine code.
+With
+the default setting \spadcmd{)set functions compile off},
+Axiom has its \Lisp{} code interpreted
+because the overhead of further compilation is larger than the run-time
+of most of the functions our users have defined.
+You may find that selectively turning this option on and off will
+give you the best performance in your particular application.
+For example, if you are writing functions for graphics applications
+where hundreds of points are being computed, it is almost certainly true
+that you will get the best performance by issuing
+\spadcmd{)set functions compile on}.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserPieceTitle}{Piece-Wise Function Definitions}
+\newcommand{\ugUserPieceNumber}{6.11.}
+
+@
+\section{Piece-Wise Function Definitions}
+\label{ugUserPiecePage}
+\begin{itemize}
+\item ugUserPieceBasicPage \ref{ugUserPieceBasicPage} on
+page~\pageref{ugUserPieceBasicPage}
+\item ugUserPiecePickingPage \ref{ugUserPiecePickingPage} on
+page~\pageref{ugUserPiecePickingPage}
+\item ugUserPiecePredPage \ref{ugUserPiecePredPage} on
+page~\pageref{ugUserPiecePredPage}
+\end{itemize}
+\index{pages!ugUserPiecePage!ug06.ht}
+\index{ug06.ht!pages!ugUserPiecePage}
+\index{ugUserPiecePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserPiecePage}{6.11. Piece-Wise Function Definitions}
+\beginscroll
+
+To move beyond functions defined in one line, we introduce in this section
+functions that are defined piece-by-piece.
+That is, we say ``use this definition when the argument is such-and-such and
+use this other definition when the argument is that-and-that.''
+
+\beginmenu
+    \menudownlink{{6.11.1. A Basic Example}}{ugUserPieceBasicPage}
+    \menudownlink{{6.11.2. Picking Up the Pieces}}{ugUserPiecePickingPage}
+    \menudownlink{{6.11.3. Predicates}}{ugUserPiecePredPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserPieceBasicTitle}{A Basic Example}
+\newcommand{\ugUserPieceBasicNumber}{6.11.1.}
+
+@
+\section{A Basic Example}
+\label{ugUserPieceBasicPage}
+\index{pages!ugUserPieceBasicPage!ug06.ht}
+\index{ug06.ht!pages!ugUserPieceBasicPage}
+\index{ugUserPieceBasicPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserPieceBasicPage}{6.11.1. A Basic Example}
+\beginscroll
+
+There are many other ways to define a factorial function for nonnegative
+integers.
+You might
+say
+factorial of \axiom{0} is \axiom{1,} otherwise factorial of \axiom{n} is
+\axiom{n} times factorial of \axiom{n-1}.
+Here is one way to do this in Axiom.
+%
+\xtc{
+Here is the value for \axiom{n = 0}.
+}{
+\spadpaste{fact(0) == 1 \bound{fact0}}
+}
+\xtc{
+Here is the value for \axiom{n > 0}.
+The vertical bar \axiomSyntax{|} means
+``such that''.
+}{
+\spadpaste{fact(n | n > 0) == n * fact(n - 1) \free{fact0}\bound{factn}}
+}
+%>> am moving this back
+%The vertical bar \axiomSyntax{|} is read as ``such that'' and so
+%\index{such that}
+%the second line means that that part of the definition for \userfun{fact}
+%is for any \axiom{n} such that \axiom{n} is greater than 0.
+%In fact, the first line is really just a shorthand expression for
+%\axiom{fact(n | n = 0) == 1}.
+%>> prefer scratching next 4 lines
+%We are implicitly using a \spadgloss{predicate} with a \axiomSyntax{|} in
+%this line (see \downlink{``\ugUserPiecePredTitle''}{ugUserPiecePredPage} 
+%in Section \ugUserPiecePredNumber\ignore{ugUserPiecePred} for more 
+%on predicates).
+%So this piece of the function is applicable to all (the not so many!)
+%values of \axiom{n} that are equal to zero.
+\xtc{
+What is the value for \axiom{n = 3}?
+}{
+\spadpaste{fact(3) \free{factn}}
+}
+\xtc{
+What is the value for \axiom{n = -3}?
+}{
+\spadpaste{fact(-3) \free{factn}}
+}
+\xtc{
+Now for a second definition.
+Here is the value for \axiom{n = 0}.
+}{
+\spadpaste{facto(0) == 1 \bound{facto0}}
+}
+\xtc{
+Give an error message if \axiom{n < 0}.
+}{
+\spadpaste{facto(n | n < 0) == error "arguments to facto must be non-negative" \free{facto0}\bound{factop}}
+}
+\xtc{
+Here is the value otherwise.
+}{
+\spadpaste{facto(n) == n * facto(n - 1) \free{factop}\bound{facton}}
+}
+\xtc{
+What is the value for \axiom{n = 7}?
+}{
+\spadpaste{facto(3) \free{facton}}
+}
+\xtc{
+What is the value for \axiom{n = -7}?
+}{
+\spadpaste{facto(-7) \free{facton}}
+}
+\xtc{
+To see the current piece-wise definition of a function,
+use \spadsys{)display value}.
+}{
+\spadpaste{)display value facto \free{facton}}
+}
+
+In general a {\it piece-wise definition} of a function consists of two or
+more parts.
+Each part gives a ``piece'' of the entire definition.
+Axiom collects the pieces of a function as you enter them.
+When you ask for a value of the function, it then ``glues''
+the pieces together to form a function.
+
+The two piece-wise definitions for the factorial function
+are examples of recursive functions, that is, functions that
+are defined in terms of themselves.
+Here is an interesting doubly-recursive function.
+This function returns the value \axiom{11} for all positive integer arguments.
+\xtc{
+Here is the first of two pieces.
+}{
+\spadpaste{eleven(n | n < 1) == n + 11\bound{ff0}}
+}
+\xtc{
+And the general case.
+}{
+\spadpaste{eleven(m) == eleven(eleven(m - 12))\bound{ff1}\free{ff0}}
+}
+\xtc{
+Compute \axiom{elevens}, the infinite stream
+of values of \axiom{eleven}.
+}{
+\spadpaste{elevens := [eleven(i) for i in 0..]\bound{ff2}\free{ff1}}
+}
+\xtc{
+What is the value at \axiom{n = 200}?
+}{
+\spadpaste{elevens 200\free{ff2}}
+}
+\xtc{
+What is the Axiom's definition of \axiom{eleven}?
+}{
+\spadpaste{)display value eleven\free{ff2}}
+}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserPiecePickingTitle}{Picking Up the Pieces}
+\newcommand{\ugUserPiecePickingNumber}{6.11.2.}
+
+@
+\section{Picking Up the Pieces}
+\label{ugUserPiecePickingPage}
+\begin{itemize}
+\item ugUserPieceBasicPage \ref{ugUserPieceBasicPage} on
+page~\pageref{ugUserPieceBasicPage}
+\end{itemize}
+\index{pages!ugUserPiecePickingPage!ug06.ht}
+\index{ug06.ht!pages!ugUserPiecePickingPage}
+\index{ugUserPiecePickingPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserPiecePickingPage}{6.11.2. Picking Up the Pieces}
+\beginscroll
+
+Here are the details about how Axiom creates a function from its
+pieces.
+Axiom converts the \eth{\axiom{i}} piece of a function definition into a
+conditional expression of the form: \axiom{if} \pred{i} \axiom{then}
+\expr{i}.
+If any new piece has a \pred{i} that is identical\footnote{after all
+variables are uniformly named} to an earlier \pred{j}, the earlier piece is
+removed.
+Otherwise, the new piece is always added at the end.
+
+\beginImportant
+If there are \axiom{n} pieces to a function definition for \axiom{f},
+the function defined \axiom{f} is: \newline
+%
+\texht{\hspace*{3pc}}{\tab{6}}
+{\tt if} \pred{1} {\tt then} \expr{1} {\tt else}\newline
+\texht{\hspace*{6pc}}{\tab{12}}. . . \newline
+\texht{\hspace*{3pc}}{\tab{6}}
+{\tt if} \pred{n} {\tt then} \expr{n} {\tt else}\newline
+\texht{\hspace*{3pc}}{\tab{6}}
+{\tt  error "You did not define f for argument <arg>."}
+%
+\endImportant
+
+You can give definitions of any number of mutually recursive function
+definitions, piece-wise or otherwise.
+No computation is done until you ask for a value.
+When you do ask for a value, all the relevant definitions are gathered,
+analyzed, and translated into separate functions and compiled.
+
+\xtc{
+Let's recall the definition of \userfun{eleven} from
+\texht{the previous section}{
+\downlink{``\ugUserPieceBasicTitle''}{ugUserPieceBasicPage} 
+in Section \ugUserPieceBasicNumber\ignore{ugUserPieceBasic}}.
+}{
+\spadpaste{eleven(n | n < 1) == n + 11\bound{ff0}}
+}
+\xtc{
+}{
+\spadpaste{eleven(m) == eleven(eleven(m - 12))\bound{ff1}\free{ff0}}
+}
+
+A similar doubly-recursive function below produces \axiom{-11} for all
+negative positive integers.
+If you haven't worked out why or how \userfun{eleven} works,
+the structure of this definition gives a clue.
+\xtc{
+This definition we write as a block.
+}{
+\begin{spadsrc}[\bound{rf1}]
+minusEleven(n) ==
+  n >= 0 => n - 11
+  minusEleven (5 + minusEleven(n + 7))
+\end{spadsrc}
+}
+\xtc{
+Define \axiom{s(n)} to be the
+sum of plus and minus ``eleven'' functions divided by \axiom{n}.
+Since \axiom{11 - 11 = 0}, we define \axiom{s(0)} to be \axiom{1}.
+}{
+\spadpaste{s(0) == 1\bound{rf2}}
+}
+\xtc{
+And the general term.
+}{
+\spadpaste{s(n) == (eleven(n) + minusEleven(n))/n\bound{rf3}\free{rf2 rf1 ff1}}
+}
+\xtc{
+What are the first ten values of \axiom{s}?
+}{
+\spadpaste{[s(n) for n in 0..]\free{rf3}}
+}
+%% interpreter puts the rule at the end - should fix
+Axiom can create infinite streams in the positive direction (for
+example, for index values \axiom{0,1, \ldots}) or negative direction (for
+example, for index values \axiom{0,-1,-2, \ldots}).
+Here we would like a stream of values of \axiom{s(n)} that is infinite in
+both directions.
+The function \axiom{t(n)} below returns the \eth{\axiom{n}} term of the infinite
+stream \axiom{[s(0), s(1), s(-1), s(2), s(-2), \ldots].}
+Its definition has three pieces.
+\xtc{
+Define the initial term.
+}{
+\spadpaste{t(1) == s(0)\bound{t1}\free{rf4}}
+}
+\xtc{
+The even numbered terms are the \axiom{s(i)} for positive \axiom{i}.
+We use \axiomOp{quo} rather than \axiomOp{/}
+since we want the result to be an integer.
+}{
+\spadpaste{t(n | even?(n)) == s(n quo 2)\free{t1}\bound{t2}}
+}
+\xtc{
+Finally, the odd numbered terms are the
+\axiom{s(i)} for negative \axiom{i}.
+In piece-wise definitions, you can use different variables
+to define different pieces. Axiom will not get confused.
+}{
+\spadpaste{t(p) == s(- p quo 2)\free{t2}\bound{t3}}
+}
+\xtc{
+Look at the definition of \axiom{t}.
+In the first piece, the variable \axiom{n}
+was used; in the second piece, \axiom{p}.
+Axiom always uses
+your last variable to display your definitions
+back to you.
+}{
+\spadpaste{)display value t\free{t2}}
+}
+\xtc{
+Create a series of values of \axiom{s} applied to
+alternating positive and negative arguments.
+}{
+\spadpaste{[t(i) for i in 1..]\free{t3}\bound{t4}}
+}
+\xtc{
+Evidently \axiom{t(n) = 1} for all \axiom{i.}
+Check it at \axiom{n= 100}.
+}{
+\spadpaste{t(100)\free{t4}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserPiecePredTitle}{Predicates}
+\newcommand{\ugUserPiecePredNumber}{6.11.3.}
+
+@
+\section{Predicates}
+\label{ugUserPiecePredPage}
+\begin{itemize}
+\item ugUserPieceBasicPage \ref{ugUserPieceBasicPage} on
+page~\pageref{ugUserPieceBasicPage}
+ugLangItsPage
+\end{itemize}
+\index{pages!ugUserPiecePredPage!ug06.ht}
+\index{ug06.ht!pages!ugUserPiecePredPage}
+\index{ugUserPiecePredPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserPiecePredPage}{6.11.3. Predicates}
+\beginscroll
+
+We have already seen some examples of
+predicates
+(\downlink{``\ugUserPieceBasicTitle''}{ugUserPieceBasicPage} 
+in Section \ugUserPieceBasicNumber\ignore{ugUserPieceBasic}).
+Predicates are \axiomType{Boolean}-valued expressions and Axiom uses them
+for filtering collections
+(see \downlink{``\ugLangItsTitle''}{ugLangItsPage} 
+in Section \ugLangItsNumber\ignore{ugLangIts})
+and for placing
+constraints on function arguments.
+In this section we discuss their latter usage.
+
+\xtc{
+The simplest use of a predicate is one you don't see at all.
+}{
+\spadpaste{opposite 'right == 'left}
+}
+\xtc{
+Here is a longer way to give the ``opposite definition.''
+}{
+\spadpaste{opposite (x | x = 'left) == 'right}
+}
+\xtc{
+Try it out.
+}{
+\spadpaste{for x in ['right,'left,'inbetween] repeat output opposite x}
+}
+
+Explicit predicates tell Axiom that the given function definition
+piece is to be applied if the predicate evaluates to {\tt true} for the
+arguments to the function.
+You can use such ``constant'' arguments for integers,
+strings, and quoted symbols.
+The \axiomType{Boolean} values \axiom{true} and \axiom{false} can also be used
+if qualified with ``\spad{@}'' or ``\spad{\$}'' and \axiomType{Boolean}.
+The following are all valid function definition fragments using
+constant arguments.
+\begin{verbatim}
+a(1) == ...
+b("unramified") == ...
+c('untested) == ...
+d(true@Boolean) == ...
+\end{verbatim}
+
+If a function has more than one argument,
+each argument can have its own predicate.
+However, if a predicate involves two or more arguments, it must be given
+{\it after} all the arguments mentioned in the predicate have been given.
+You are always safe to give
+a single predicate at the end of the argument list.
+\xtc{
+A function involving predicates on two arguments.
+}{
+\spadpaste{inFirstHalfQuadrant(x | x > 0,y | y < x) == true}
+}
+\xtc{
+This is incorrect as it gives a predicate on \axiom{y}
+before the argument \axiom{y} is given.
+}{
+\spadpaste{inFirstHalfQuadrant(x | x > 0 and y < x,y) == true}
+}
+\xtc{
+It is always correct to write the predicate at the end.
+}{
+\spadpaste{inFirstHalfQuadrant(x,y | x > 0 and y < x) == true \bound{ifq1a}}
+}
+\xtc{
+Here is the rest of the definition.
+}{
+\spadpaste{inFirstHalfQuadrant(x,y) == false \bound{ifq1b}}
+}
+\xtc{
+Try it out.
+}{
+\spadpaste{[inFirstHalfQuadrant(i,3) for i in 1..5]\bound{ifq1b}}
+}
+
+{\bf Remark:} Very old versions of Axiom allowed predicates
+to be given after a {\tt when} keyword as in
+{\tt inFirstHalfQuadrant(x ,y) == true when x >0 and y < x}.
+This is no longer supported, is WRONG, and will cause a syntax
+error or strange behavior.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserCacheTitle}{Caching Previously Computed Results}
+\newcommand{\ugUserCacheNumber}{6.12.}
+
+@
+\section{Caching Previously Computed Results}
+\label{ugUserCachePage}
+\begin{itemize}
+\item ugUserFreeLocalPage \ref{ugUserFreeLocalPage} on
+page~\pageref{ugUserFreeLocalPage}
+\end{itemize}
+\index{pages!ugUserCachePage!ug06.ht}
+\index{ug06.ht!pages!ugUserCachePage}
+\index{ugUserCachePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserCachePage}{6.12. Caching Previously Computed Results}
+\beginscroll
+
+By default, Axiom does not save the values of any function.
+You can cause it to save values and not to recompute unnecessarily
+by using \spadcmd{)set functions cache}.
+This should be used before the functions are defined or, at least, before
+they are executed.
+The word following ``cache'' should be \axiom{0} to turn off
+caching, a positive integer \axiom{n} to save the last \axiom{n}
+computed values or ``all'' to save all computed values.
+If you then give a list of names of functions, the caching
+only affects those functions.
+Use no list of names or ``all'' when you want to define the default
+behavior for functions not specifically mentioned in other
+\spadcmd{)set functions cache} statements.
+If you give no list of names, all functions will have the caching behavior.
+If you explicitly turn on caching for one or more names, you must
+explicitly turn off caching for those names when you want to stop
+saving their values.
+
+\xtc{
+This causes the functions \userfun{f} and \userfun{g} to have
+the last three computed values saved.
+}{
+\spadpaste{)set functions cache 3 f g \bound{cache}}
+}
+\xtc{
+This is a sample definition for \userfun{f}.
+}{
+\spadpaste{f x == factorial(2**x) \bound{fdef}\free{cache}}
+}
+\xtc{
+A message is displayed stating what \userfun{f} will cache.
+}{
+\spadpaste{f(4) \free{}\free{cache}}
+}
+\xtc{
+This causes all other functions to have all computed values saved by
+default.
+}{
+\spadpaste{)set functions cache all}
+}
+\xtc{
+This causes all functions that have not been specifically cached in some way
+to have no computed values saved.
+}{
+\spadpaste{)set functions cache 0}
+}
+\xtc{
+We also make \userfun{f} and \userfun{g} uncached.
+}{
+\spadpaste{)set functions cache 0 f g}
+}
+
+\beginImportant
+Be careful about caching functions that have
+\spadglossSee{side effects}{side effect}.
+Such a function might destructively modify the elements of an array or
+issue a \axiomFun{draw} command, for example.
+A function that you expect to execute every time it is called should
+not be cached.
+Also, it is highly unlikely that a function with no arguments should
+be cached.
+\endImportant
+
+You should also be careful about caching functions that depend on
+free variables.
+See \downlink{``\ugUserFreeLocalTitle''}{ugUserFreeLocalPage} in 
+Section \ugUserFreeLocalNumber\ignore{ugUserFreeLocal}
+for an example.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserRecurTitle}{Recurrence Relations}
+\newcommand{\ugUserRecurNumber}{6.13.}
+
+@
+\section{Recurrence Relations}
+\label{ugUserRecurPage}
+\begin{itemize}
+\item ugUserFreeLocalPage \ref{ugUserFreeLocalPage} on
+page~\pageref{ugUserFreeLocalPage}
+\item ugUserCachePage \ref{ugUserCachePage} on
+page~\pageref{ugUserCachePage}
+\end{itemize}
+\index{pages!ugUserRecurPage!ug06.ht}
+\index{ug06.ht!pages!ugUserRecurPage}
+\index{ugUserRecurPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserRecurPage}{6.13. Recurrence Relations}
+\beginscroll
+
+One of the most useful classes of function are those defined via a
+``recurrence relation.''
+A {\it recurrence relation} makes each successive
+value depend on some or all of the previous values.
+A simple example is the ordinary ``factorial'' function:
+\begin{verbatim}
+fact(0) == 1
+fact(n | n > 0) == n * fact(n-1)
+\end{verbatim}
+
+The value of
+\axiom{fact(10)} depends on the value of \axiom{fact(9)}, \axiom{fact(9)}
+on \axiom{fact(8)}, and so on.
+Because it depends on only one previous value, it is usually called a
+{\it first order recurrence relation.}
+You can easily imagine a function based on two, three or more previous
+values.
+The Fibonacci numbers are probably the most famous function defined by a
+second order recurrence relation.
+\xtc{
+The library function \axiomFun{fibonacci} computes Fibonacci numbers.
+It is obviously optimized for speed.
+}{
+\spadpaste{[fibonacci(i) for i in 0..]}
+}
+\xtc{
+Define the
+Fibonacci numbers ourselves using a piece-wise definition.
+}{
+\spadpaste{fib(1) == 1 \bound{fib0}}
+}
+\xtc{
+}{
+\spadpaste{fib(2) == 1 \bound{fib1}\free{fib0}}
+}
+\xtc{
+}{
+\spadpaste{fib(n) == fib(n-1) + fib(n-2) \bound{fibn}\free{fib1}}
+}
+
+As defined, this recurrence relation is obviously doubly-recursive.
+To compute \axiom{fib(10)}, we need to compute \axiom{fib(9)} and
+\axiom{fib(8)}.
+And to  \axiom{fib(9)}, we need to compute \axiom{fib(8)} and
+\axiom{fib(7)}.
+And so on.
+It seems that to compute \axiom{fib(10)} we need to compute
+\axiom{fib(9)} once, \axiom{fib(8)} twice, \axiom{fib(7)} three times.
+Look familiar?
+The number of function calls needed to compute {\it any} second order
+recurrence relation in the obvious way is exactly \axiom{fib(n)}.
+These numbers grow!
+For example, if Axiom actually did this, then \axiom{fib(500)}
+requires more than \texht{$10^{104}$}{\axiom{10**104}} function calls.
+And, given all this, our definition of \userfun{fib} obviously could not be
+used to calculate the five-hundredth Fibonacci number.
+\xtc{
+Let's try it anyway.
+}{
+\spadpaste{fib(500) \free{fibn}}
+}
+
+Since this takes a short time to compute, it obviously didn't do
+as many as \texht{$10^{104}$}{\axiom{10**104}} operations!
+By default, Axiom transforms any recurrence relation it recognizes
+into an iteration.
+Iterations are efficient.
+To compute the value of the \eth{\axiom{n}}
+term of a recurrence relation using an iteration requires only
+\axiom{n} function calls.\footnote{If
+you compare the speed of our \userfun{fib} function
+to the library function, our version is still slower.
+This is because the library
+\axiomFunFrom{fibonacci}{IntegerNumberTheoryFunctions}
+uses a ``powering algorithm'' with a computing time
+proportional to \texht{$\log^3(n)$}{\axiom{log(n)**3}} to compute
+\axiom{fibonacci(n).}}
+
+To turn off this special recurrence relation compilation, issue
+\begin{verbatim}
+)set functions recurrence off
+\end{verbatim}
+To turn it back on, substitute ``{\tt on}'' for ``{\tt off}''.
+
+The transformations that Axiom uses for \userfun{fib} caches the
+last two values.\footnote{For a more general \eth{\axiom{k}} order recurrence
+relation, Axiom caches the last \axiom{k} values.}
+If, after computing a value for \userfun{fib}, you ask
+for some larger value, Axiom picks up the cached values
+and continues computing from there.
+See \downlink{``\ugUserFreeLocalTitle''}{ugUserFreeLocalPage} 
+in Section \ugUserFreeLocalNumber\ignore{ugUserFreeLocal}
+for an example of a function definition that has this same behavior.
+Also see \downlink{``\ugUserCacheTitle''}{ugUserCachePage} 
+in Section \ugUserCacheNumber\ignore{ugUserCache}
+for a more general discussion of how you can cache function values.
+
+Recurrence relations can be used for defining recurrence relations
+involving polynomials, rational functions, or anything you like.
+Here we compute the infinite stream of Legendre polynomials.
+\xtc{
+The Legendre polynomial of degree \axiom{0.}
+}{
+\spadpaste{p(0) == 1\bound{p0}}
+}
+\xtc{
+The Legendre polynomial of degree \axiom{1.}
+}{
+\spadpaste{p(1) == x\bound{p1}}
+}
+
+\xtc{
+The Legendre polynomial of degree \axiom{n}.
+}{
+\spadpaste{p(n) == ((2*n-1)*x*p(n-1) - (n-1)*p(n-2))/n\bound{pn}\free{p1}}
+}
+\xtc{
+Compute the Legendre polynomial of degree \axiom{6.}
+}{
+\spadpaste{p(6)\free{pn}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserMakeTitle}{Making Functions from Objects}
+\newcommand{\ugUserMakeNumber}{6.14.}
+
+@
+\section{Making Functions from Objects}
+\label{ugUserMakePage}
+\begin{itemize}
+\item MakeFunctionXmpPage \ref{MakeFunctionXmpPage} on
+page~\pageref{MakeFunctionXmpPage}
+\end{itemize}
+\index{pages!ugUserMakePage!ug06.ht}
+\index{ug06.ht!pages!ugUserMakePage}
+\index{ugUserMakePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserMakePage}{6.14. Making Functions from Objects}
+\beginscroll
+
+There are many times when you compute a complicated expression
+and then wish to use that expression as the body of a function.
+Axiom provides an operation called \axiomFun{function} to do
+this.
+It creates a function object and places it into the workspace.
+There are several versions, depending on how many arguments the function
+has.
+The first argument to \axiomFun{function} is always the expression to be
+converted into the function body, and the second is always the name to be
+used for the function.
+For more information, see \downlink{`MakeFunction'}{MakeFunctionXmpPage}
+\ignore{MakeFunction}.
+
+\xtc{
+Start with a simple example of a polynomial in three variables.
+}{
+\spadpaste{p := -x + y**2 - z**3 \bound{p}}
+}
+\xtc{
+To make this into a function of no arguments that
+simply returns the polynomial, use the two argument form of
+\axiomFun{function}.
+}{
+\spadpaste{function(p,'f0) \free{p}\bound{f0}}
+}
+\xtc{
+To avoid possible conflicts (see below), it is a good idea to
+quote always this second argument.
+}{
+\spadpaste{f0 \free{f0}}
+}
+\xtc{
+This is what you get when you evaluate the function.
+}{
+\spadpaste{f0() \free{f0}}
+}
+\xtc{
+To make a function in \axiom{x}, use a version of
+\axiomFun{function} that takes three arguments.
+The last argument is the name of the variable to use as the parameter.
+Typically, this variable occurs in the expression and, like the function
+name, you should quote it to avoid possible confusion.
+}{
+\spadpaste{function(p,'f1,'x) \free{p}\bound{f1}}
+}
+\xtc{
+This is what the new function looks like.
+}{
+\spadpaste{f1 \free{f1}}
+}
+\xtc{
+This is the value of \userfun{f1} at \axiom{x = 3}.
+Notice that the return type of the function is
+\axiomType{Polynomial (Integer)}, the same as \axiom{p}.
+}{
+\spadpaste{f1(3) \free{f1}}
+}
+\xtc{
+To use \axiom{x} and \axiom{y} as parameters, use the
+four argument form of \axiomFun{function}.
+}{
+\spadpaste{function(p,'f2,'x,'y) \free{p}\bound{f2}}
+}
+\xtc{
+}{
+\spadpaste{f2 \free{f2}}
+}
+\xtc{
+Evaluate \axiom{f2} at \axiom{x = 3} and \axiom{y = 0}.
+The return type of \userfun{f2} is still
+\axiomType{Polynomial(Integer)} because the variable \axiom{z}
+is still present and not one of the parameters.
+}{
+\spadpaste{f2(3,0) \free{f2}}
+}
+\xtc{
+Finally, use all three variables as parameters.
+There is no five argument form of \axiomFun{function}, so use the one with
+three arguments, the third argument being a list of the parameters.
+}{
+\spadpaste{function(p,'f3,['x,'y,'z]) \free{p}\bound{f3}}
+}
+\xtc{
+Evaluate this using the same values for \axiom{x} and \axiom{y}
+as above, but let \axiom{z} be \axiom{-6}.
+The result type of \userfun{f3} is \axiomType{Integer}.
+}{
+\spadpaste{f3 \free{f3}}
+}
+\xtc{
+}{
+\spadpaste{f3(3,0,-6) \free{f3}}
+}
+
+The four functions we have defined via \axiom{p} have been undeclared.
+To declare a function whose body is to be generated by
+\axiomFun{function}, 
+issue the declaration {\it before} the function is created.
+\xtc{
+}{
+\spadpaste{g: (Integer, Integer) -> Float \bound{g}}
+}
+\xtc{
+}{
+\spadpaste{D(sin(x-y)/cos(x+y),x) \bound{prev}}
+}
+\xtc{
+}{
+\spadpaste{function(\%,'g,'x,'y) \free{g}\free{prev}}
+}
+\xtc{
+}{
+\spadpaste{g \free{g}}
+}
+It is an error to use \axiom{g} without the quote in the
+penultimate expression since \axiom{g} had been declared but did not have
+a value.
+Similarly, since it is common to overuse variable names like \axiom{x},
+\axiom{y}, and so on,
+you avoid problems if you always quote the variable names
+for \axiomFun{function}.
+In general,
+if \axiom{x} has a value and you use \axiom{x} without a quote in a call to
+\axiomFun{function}, then
+Axiom does not know what you are trying to do.
+
+What kind of object is allowable as the first argument to \axiomFun{function}?
+Let's use the \Browse{} facility of \HyperName{} to find out.
+At the main \Browse{} menu, enter the string {\tt function} and then
+click on {\bf Operations.}
+The exposed operations called \axiomFun{function} all take an object
+whose type belongs to category \axiomType{ConvertibleTo InputForm}.
+What domains are those?
+Go back to the main \Browse{} menu, erase {\tt function},
+enter {\tt ConvertibleTo} in the
+input area, and click on {\bf categories} on the {\bf Constructors} line.
+At the bottom of the page, enter {\tt InputForm} in the input area
+following {\bf S =}.
+Click on {\bf Cross Reference} and then on {\bf Domains}.
+The list you see contains over forty domains that belong to the
+category \axiomType{ConvertibleTo InputForm}.
+Thus you can use \axiomFun{function} for \axiomType{Integer},
+\axiomType{Float},
+\axiomType{String},
+\axiomType{Complex},
+\axiomType{Expression}, and so on.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserBlocksTitle}{Functions Defined with Blocks}
+\newcommand{\ugUserBlocksNumber}{6.15.}
+
+@
+\section{Functions Defined with Blocks}
+\label{ugUserBlocksPage}
+\begin{itemize}
+\item ugLangBlocksPage \ref{ugLangBlocksPage} on
+page~\pageref{ugLangBlocksPage}
+\end{itemize}
+\index{pages!ugUserBlocksPage!ug06.ht}
+\index{ug06.ht!pages!ugUserBlocksPage}
+\index{ugUserBlocksPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserBlocksPage}{6.15. Functions Defined with Blocks}
+\beginscroll
+
+You need not restrict yourself to functions that only fit on one line
+or are written in a piece-wise manner.
+The body of the function can be a block, as discussed in
+\downlink{``\ugLangBlocksTitle''}{ugLangBlocksPage} 
+in Section \ugLangBlocksNumber\ignore{ugLangBlocks}.
+
+\labelSpace{1pc}
+\xtc{
+Here is a short function that swaps two elements of a list,
+array or vector.
+}{
+\begin{spadsrc}[\bound{swap}]
+swap(m,i,j) ==
+  temp := m.i
+  m.i := m.j
+  m.j := temp
+\end{spadsrc}
+}
+\xtc{
+The significance of \userfun{swap} is that it has a destructive
+effect on its first argument.
+}{
+\spadpaste{k := [1,2,3,4,5] \bound{k}}
+}
+\xtc{
+}{
+\spadpaste{swap(k,2,4) \free{l swap}\bound{swapk}}
+}
+\xtc{
+You see that the second and fourth elements are interchanged.
+}{
+\spadpaste{k \free{swapk}}
+}
+
+\xtc{
+Using this, we write a couple of different sort functions.
+First, a simple bubble sort.
+The operation \axiomOpFrom{\#}{List} returns the number of elements in
+an aggregate.
+}{
+\begin{spadsrc}[\bound{bubbleSort}]
+bubbleSort(m) ==
+  n := #m
+  for i in 1..(n-1) repeat
+    for j in n..(i+1) by -1 repeat
+      if m.j < m.(j-1) then swap(m,j,j-1)
+  m
+\end{spadsrc}
+}
+\xtc{
+Let this be the list we want to sort.
+}{
+\spadpaste{m := [8,4,-3,9] \bound{m}}
+}
+\xtc{
+This is the result of sorting.
+}{
+\spadpaste{bubbleSort(m) \free{m swap bubbleSort}\bound{sortm}}
+}
+\xtc{
+Moreover, \axiom{m} is destructively changed to be the sorted version.
+}{
+\spadpaste{m \free{sortm}}
+}
+
+\xtc{
+This function implements an insertion sort.
+The basic idea is to traverse the list and insert the \eth{\axiom{i}}
+element in its correct position among the \axiom{i-1} previous
+elements.
+Since we start at the beginning of the list, the list elements before the
+\eth{\axiom{i}} element have already been placed in ascending order.
+}{
+\begin{spadsrc}[\bound{insertionSort}]
+insertionSort(m) ==
+  for i in 2..#m repeat
+    j := i
+    while j > 1 and m.j < m.(j-1) repeat
+      swap(m,j,j-1)
+      j := j - 1
+  m
+\end{spadsrc}
+}
+\xtc{
+As with our bubble sort, this is a destructive function.
+}{
+\spadpaste{m := [8,4,-3,9] \bound{m1}}
+}
+\xtc{
+}{
+\spadpaste{insertionSort(m) \free{m1 swap insertionSort}\bound{sortm1}}
+}
+\xtc{
+}{
+\spadpaste{m \free{sortm1}}
+}
+
+Neither of the above functions is efficient for sorting large lists since
+they reference elements by asking for the \eth{\axiom{j}} element of the
+structure \axiom{m}.
+%For lists, compute \axiom{m.(j+1) = rest(m,j).first}, and thus, starting at
+%the first node of \axiom{m}, walk down to the \eth{\axiom{j}} node, then call
+%\axiomFun{first}.
+
+\xtc{
+Here is a more efficient bubble sort for lists.
+}{
+\begin{spadsrc}[\bound{bubbleSort2}]
+bubbleSort2(m: List Integer): List Integer ==
+  null m => m
+  l := m
+  while not null (r := l.rest) repeat
+     r := bubbleSort2 r
+     x := l.first
+     if x < r.first then
+       l.first := r.first
+       r.first := x
+     l.rest := r
+     l := l.rest
+  m
+\end{spadsrc}
+}
+\xtc{
+Try it out.
+}{
+\spadpaste{bubbleSort2 [3,7,2]\free{bubbleSort2}}
+}
+
+This definition is both recursive and iterative, and is tricky!
+Unless you are {\it really} curious about this definition,
+we suggest you skip immediately to the next section.
+
+Here are the key points in the definition.
+First notice that if you are sorting a list with less than two elements,
+there is nothing to do: just return the list.
+This definition returns immediately if there are zero elements, and skips
+the entire \axiom{while} loop if there is just one element.
+
+The second point to realize is that on each outer iteration, the bubble sort
+ensures that the minimum element is propagated leftmost.
+Each iteration of the \axiom{while} loop calls \userfun{bubbleSort2}
+recursively to sort all but the first element.
+When finished, the minimum element is either in the first or second position.
+The conditional expression ensures that it comes first.
+If it is in the second, then a swap occurs.
+In any case, the \axiomFun{rest} of the original list must be updated to hold
+the result of the recursive call.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserFreeLocalTitle}{Free and Local Variables}
+\newcommand{\ugUserFreeLocalNumber}{6.16.}
+
+@
+\section{Free and Local Variables}
+\label{ugUserFreeLocalPage}
+\begin{itemize}
+\item ugUserCachePage \ref{ugUserCachePage} on
+page~\pageref{ugUserCachePage}
+\item ugUserRecurPage \ref{ugUserRecurPage} on
+page~\pageref{ugUserRecurPage}
+\end{itemize}
+\index{pages!ugUserFreeLocalPage!ug06.ht}
+\index{ug06.ht!pages!ugUserFreeLocalPage}
+\index{ugUserFreeLocalPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserFreeLocalPage}{6.16. Free and Local Variables}
+\beginscroll
+
+When you want to refer to a variable that is not local to your
+function, use a ``\axiom{free}'' declaration.
+\spadkey{free}
+Variables declared to be \axiom{free}
+are assumed to be defined globally
+in the
+workspace.
+
+\labelSpace{1pc}
+\xtc{
+This is a global workspace variable.
+}{
+\spadpaste{counter := 0 \bound{counter}}
+}
+\xtc{
+This function refers to the global \axiom{counter}.
+}{
+\begin{spadsrc}[\free{counter}\bound{f}]
+f() ==
+  free counter
+  counter := counter + 1
+\end{spadsrc}
+}
+\xtc{
+The global \axiom{counter} is incremented by \axiom{1}.
+}{
+\spadpaste{f() \free{f}\bound{f1}}
+}
+\xtc{
+}{
+\spadpaste{counter \free{f1}}
+}
+
+Usually Axiom can tell that you mean to refer to a global
+variable and so \axiom{free} isn't always necessary.
+However, for clarity and the sake of self-documentation, we encourage
+you to use it.
+
+Declare a variable to be ``\axiom{local}'' when you do not want to refer to
+a global variable by the same name.
+
+\xtc{
+This function uses \axiom{counter} as a local variable.
+}{
+\begin{spadsrc}[\bound{g}]
+g() ==
+  local counter
+  counter := 7
+\end{spadsrc}
+}
+\xtc{
+Apply the function.
+}{
+\spadpaste{g() \free{g}}
+}
+\xtc{
+Check that the global value of \axiom{counter} is unchanged.
+}{
+\spadpaste{counter\free{g f1}}
+}
+
+Parameters to a function are local variables in the function.
+Even if you issue a \axiom{free} declaration for a parameter, it is
+still local.
+
+What happens if you do not declare that a variable \axiom{x} in
+the body of your function is \axiom{local} or \axiom{free}?
+Well, Axiom decides on this basis:
+
+\indent{4}
+\beginitems
+\item[1. ] Axiom scans your function line-by-line, from top-to-bottom.
+The right-hand side of an assignment is looked at before the left-hand
+side.
+\item[2. ] If \axiom{x} is referenced before it is assigned a value, it is a
+\axiom{free} (global) variable.
+\item[3. ] If \axiom{x} is assigned a value before it is referenced, it is a
+\axiom{local} variable.
+\enditems
+\indent{0}
+
+\xtc{
+Set two global variables to 1.
+}{
+\spadpaste{a := b := 1\bound{ab1}}
+}
+\xtc{
+Refer to \axiom{a} before it is assigned a value, but
+assign a value to \axiom{b} before it is referenced.
+}{
+\begin{spadsrc}[\bound{hh}]
+h() ==
+  b := a + 1
+  a := b + a
+\end{spadsrc}
+}
+\xtc{
+Can you predict this result?
+}{
+\spadpaste{h() \free{ab1 hh}\bound{hhh}}
+}
+\xtc{
+How about this one?
+}{
+\spadpaste{[a, b] \free{hhh}}
+}
+
+What happened?
+In the first line of the function body for \axiom{h}, \axiom{a} is
+referenced on the right-hand side of the assignment.
+Thus \axiom{a} is a free variable.
+The variable \axiom{b} is not referenced in that line, but it is
+assigned a value.
+Thus \axiom{b} is a local variable and is given the value
+\axiom{a + 1 = 2}.
+In the second line, the free variable \axiom{a} is assigned the value
+\axiom{b + a}which equals \axiom{2 + 1 = 3.}
+This is the value returned by the function.
+Since \axiom{a} was free in \userfun{h}, the global variable \axiom{a}
+has value \axiom{3.}
+Since \axiom{b} was local in \userfun{h}, the global variable \axiom{b}
+is unchanged---it still has the value \axiom{1.}
+
+It is good programming practice always to declare global variables.
+However, by far the most common situation is to have local variables in
+your functions.
+No declaration is needed for this situation, but be sure to
+initialize their values.
+
+Be careful if you use free variables and you cache the value of
+your function (see \downlink{``\ugUserCacheTitle''}{ugUserCachePage} 
+in Section \ugUserCacheNumber\ignore{ugUserCache}).
+Caching {\it only} checks if the values of the function arguments
+are the same as in a function call previously seen.
+It does not check if any of the free variables on which the
+function depends have changed between function calls.
+\xtc{
+Turn on caching for \userfun{p}.
+}{
+\spadpaste{)set fun cache all p \bound{pcache}}
+}
+\xtc{
+Define \userfun{p} to depend on the free variable \axiom{N}.
+}{
+\spadpaste{p(i,x) == ( free N; reduce( + , [ (x-i)**n for n in 1..N ] ) ) \free{pcache}\bound{pdef}}
+}
+\xtc{
+Set the value of \axiom{N}.
+}{
+\spadpaste{N := 1 \bound{Nass}}
+}
+\xtc{
+Evaluate \userfun{p} the first time.
+}{
+\spadpaste{p(0, x) \free{pdef Nass}\bound{pfirst}}
+}
+\xtc{
+Change the value of \axiom{N}.
+}{
+\spadpaste{N := 2 \bound{Nass2}}
+}
+\xtc{
+Evaluate \userfun{p} the second time.
+}{
+\spadpaste{p(0, x) \free{pfirst Nass2}}
+}
+If caching had been turned off, the second evaluation would have
+reflected the changed value of \axiom{N}.
+\xtc{
+Turn off caching for \userfun{p}.
+}{
+\spadpaste{)set fun cache 0 p}
+}
+
+Axiom does not allow {\it fluid variables}, that is, variables
+\spadglossSee{bound}{binding} by a function \spad{f} that can be referenced by
+functions called by \spad{f}.
+
+Values are passed to functions by \spadgloss{reference}: a pointer
+to the value is passed rather than a copy of the value or a pointer to
+a copy.
+
+\xtc{
+This is a global variable that is bound to a record object.
+}{
+\spadpaste{r : Record(i : Integer) := [1] \free{r}}
+}
+\xtc{
+This function first modifies the one component of its
+record argument and then rebinds the parameter to another
+record.
+}{
+\begin{spadsrc}[\bound{resetRecord}]
+resetRecord rr ==
+  rr.i := 2
+  rr := [10]
+\end{spadsrc}
+}
+\xtc{
+Pass \axiom{r} as an argument to \userfun{resetRecord}.
+}{
+\spadpaste{resetRecord r \free{r resetRecord}\bound{rr}}
+}
+\xtc{
+The value of \axiom{r} was changed by the expression
+\axiom{rr.i := 2} but not by \axiom{rr := [10]}.
+}{
+\spadpaste{r \free{rr}}
+}
+
+To conclude this section, we give an iterative definition of
+a function that computes Fibonacci numbers.
+This definition approximates the definition into which Axiom
+transforms the recurrence relation definition of \userfun{fib} in
+\downlink{``\ugUserRecurTitle''}{ugUserRecurPage} 
+in Section \ugUserRecurNumber\ignore{ugUserRecur}.
+
+\xtc{
+Global variables
+\axiom{past} and \axiom{present} are used
+to hold the last computed Fibonacci numbers.
+}{
+\spadpaste{past := present := 1\bound{f0}}
+}
+\xtc{
+Global variable \axiom{index} gives the
+current index of \axiom{present}.
+}{
+\spadpaste{index := 2\bound{f1}\free{f0}}
+}
+\xtc{
+Here is a recurrence relation defined in terms
+of these three global variables.
+}{
+\begin{spadsrc}[\bound{f3}\free{f2}]
+fib(n) ==
+  free past, present, index
+  n < 3 => 1
+  n = index - 1 => past
+  if n < index-1 then
+    (past,present) := (1,1)
+    index := 2
+  while (index < n) repeat
+    (past,present) := (present, past+present)
+    index := index + 1
+  present
+\end{spadsrc}
+}
+\xtc{
+Compute the infinite stream of Fibonacci numbers.
+}{
+\spadpaste{fibs := [fib(n) for n in 1..] \bound{fibs}\free{f3}}
+}
+\xtc{
+What is the 1000th Fibonacci number?
+}{
+\spadpaste{fibs 1000 \free{fibs}}
+}
+
+As an exercise, we suggest you write a function in an iterative
+style that computes the value of the recurrence relation
+\texht{$p(n) = p(n-1) - 2 \, p(n-2) + 4 \, p(n-3)$}{\axiom{p(n) = p(n-1) - 2*p(n-2) + 4*p(n-3)}}
+having the initial values
+\texht{$p(1) = 1,\, p(2) = 3 \hbox{ and } p(3) = 9.$}{\axiom{p(1) = 1, p(2) = 3 {\rm and} p(3) = 9.}}
+How would you write the function using an element
+\axiomType{OneDimensionalArray} or \axiomType{Vector}
+to hold the previously computed values?
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserAnonTitle}{Anonymous Functions}
+\newcommand{\ugUserAnonNumber}{6.17.}
+
+@
+\section{Anonymous Functions}
+\label{ugUserAnonPage}
+\begin{itemize}
+\item ugUserAnonExampPage \ref{ugUserAnonExampPage} on
+page~\pageref{ugUserAnonExampPage}
+\item ugUserAnonDeclarePage \ref{ugUserAnonDeclarePage} on
+page~\pageref{ugUserAnonDeclarePage}
+\end{itemize}
+\index{pages!ugUserAnonPage!ug06.ht}
+\index{ug06.ht!pages!ugUserAnonPage}
+\index{ugUserAnonPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserAnonPage}{6.17. Anonymous Functions}
+\beginscroll
+
+\beginImportant
+An {\it anonymous function} is a function that is
+defined
+by giving a list of parameters, the ``maps-to'' compound
+symbol \axiomSyntax{+->} \texht{(from the mathematical symbol
+$\mapsto$)}{},
+and by an expression involving the parameters, the evaluation of
+which determines the return value of the function.
+
+\centerline{{{\tt ( \subscriptIt{parm}{1}, \subscriptIt{parm}{2}, \ldots, \subscriptIt{parm}{N} ) +-> {\it expression}}}}
+\endImportant
+
+You can apply an anonymous function in several ways.
+\indent{4}
+\beginitems
+\item[1. ] Place the anonymous function definition in parentheses
+directly followed by a list of arguments.
+\item[2. ] Assign the anonymous function to a variable and then
+use the variable name when you would normally use a function name.
+\item[3. ] Use \axiomSyntax{==} to use the anonymous function definition as
+the arguments and body of a regular function definition.
+\item[4. ] Have a named function contain a declared anonymous function and
+use the result returned by the named function.
+\enditems
+\indent{0}
+
+\beginmenu
+    \menudownlink{{6.17.1. Some Examples}}{ugUserAnonExampPage}
+    \menudownlink{{6.17.2. Declaring Anonymous Functions}}
+{ugUserAnonDeclarePage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserAnonExampTitle}{Some Examples}
+\newcommand{\ugUserAnonExampNumber}{6.17.1.}
+
+@
+\section{Some Examples}
+\label{ugUserAnonExampPage}
+\index{pages!ugUserAnonExampPage!ug06.ht}
+\index{ug06.ht!pages!ugUserAnonExampPage}
+\index{ugUserAnonExampPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserAnonExampPage}{6.17.1. Some Examples}
+\beginscroll
+
+Anonymous functions are particularly useful for defining functions
+``on the fly.'' That is, they are handy for simple functions that
+are used only in one place.
+In the following examples, we show how to write some simple
+anonymous functions.
+
+\xtc{
+This is a simple absolute value function.
+}{
+\spadpaste{x +-> if x < 0 then -x else x \bound{anon0}}
+}
+\xtc{
+}{
+\spadpaste{abs1 := \% \free{anon0}\bound{abs1}}
+}
+\xtc{
+This function returns {\tt true} if the absolute value of
+the first argument is greater than the absolute value of the
+second, {\tt false} otherwise.
+}{
+\spadpaste{(x,y) +-> abs1(x) > abs1(y) \bound{anon1}\free{abs1}}
+}
+\xtc{
+We use the above function to ``sort'' a list of integers.
+}{
+\spadpaste{sort(\%,[3,9,-4,10,-3,-1,-9,5]) \free{anon1}}
+}
+
+\xtc{
+This function returns \axiom{1} if \axiom{i + j} is even, \axiom{-1} otherwise.
+}{
+\spadpaste{ev := ( (i,j) +-> if even?(i+j) then 1 else -1) \bound{ev}}
+}
+\xtc{
+We create a four-by-four matrix containing \axiom{1} or \axiom{-1}
+depending on whether the row plus the column index is even or not.
+}{
+\spadpaste{matrix([[ev(row,col) for row in 1..4] for col in 1..4]) \free{ev}}
+}
+
+\xtc{
+This function returns {\tt true} if a polynomial in \axiom{x} has multiple
+roots, {\tt false} otherwise.
+It is defined and applied in the same expression.
+}{
+\spadpaste{( p +-> not one?(gcd(p,D(p,x))) )(x**2+4*x+4)}
+}
+
+\xtc{
+This and the next expression are equivalent.
+}{
+\spadpaste{g(x,y,z) == cos(x + sin(y + tan(z)))}
+}
+\xtc{
+The one you use is a matter of taste.
+}{
+\spadpaste{g == (x,y,z) +-> cos(x + sin(y + tan(z)))}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserAnonDeclareTitle}{Declaring Anonymous Functions}
+\newcommand{\ugUserAnonDeclareNumber}{6.17.2.}
+
+@
+\section{Declaring Anonymous Functions}
+\label{ugUserAnonDeclarePage}
+\index{pages!ugUserAnonDeclarePage!ug06.ht}
+\index{ug06.ht!pages!ugUserAnonDeclarePage}
+\index{ugUserAnonDeclarePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserAnonDeclarePage}{6.17.2. Declaring Anonymous Functions}
+\beginscroll
+
+If you declare any of the arguments you must declare all of them.
+Thus,
+\begin{verbatim}
+(x: INT,y): FRAC INT +-> (x + 2*y)/(y - 1)
+\end{verbatim}
+is not legal.
+
+\xtc{
+This is an example of a fully declared anonymous
+function.
+The output shown just indicates that the object you created is a
+particular kind of map, that is, function.
+}{
+\spadpaste{(x: INT,y: INT): FRAC INT +-> (x + 2*y)/(y - 1)}
+}
+\xtc{
+Axiom allows you to declare the arguments and not declare
+the return type.
+}{
+\spadpaste{(x: INT,y: INT) +-> (x + 2*y)/(y - 1)}
+}
+The return type is computed from the types of the arguments and the
+body of the function.
+You cannot declare the return type if you do not declare the arguments.
+Therefore,
+\begin{verbatim}
+(x,y): FRAC INT +-> (x + 2*y)/(y - 1)
+\end{verbatim}
+is not legal.
+
+\xtc{
+This and the next expression are equivalent.
+}{
+\spadpaste{h(x: INT,y: INT): FRAC INT == (x + 2*y)/(y - 1)}
+}
+\xtc{
+The one you use is a matter of taste.
+}{
+\spadpaste{h == (x: INT,y: INT): FRAC INT +-> (x + 2*y)/(y - 1)}
+}
+
+When should you declare an anonymous function?
+\indent{4}
+\beginitems
+\item[1. ] If you use an anonymous function and Axiom can't figure
+out what you are trying to do, declare the function.
+\item[2. ] If the function has nontrivial argument types or a
+nontrivial return type that
+Axiom may be able to determine eventually, but you are not
+willing to wait that long, declare the function.
+\item[3. ] If the function will only be used for arguments of specific
+types and it is not too much trouble to declare the function, do so.
+\item[4. ] If you are using the anonymous function as an argument to
+another function (such as \axiomFun{map} or \axiomFun{sort}),
+consider declaring the function.
+\item[5. ] If you define an anonymous function inside a named function,
+you {\it must} declare the anonymous function.
+\enditems
+\indent{0}
+
+\xtc{
+This is an example of a named function for integers that returns a
+function.
+}{
+\spadpaste{addx x == ((y: Integer): Integer +-> x + y) \bound{addx}}
+}
+\xtc{
+We define \userfun{g} to be a function that adds \axiom{10} to its
+argument.
+}{
+\spadpaste{g := addx 10 \free{addx}\bound{g}}
+}
+\xtc{
+Try it out.
+}{
+\spadpaste{g 3 \free{g}}
+}
+\xtc{
+}{
+\spadpaste{g(-4) \free{g}}
+}
+
+An anonymous function cannot be recursive: since it does not have a
+name, you cannot even call it within itself!
+If you place an anonymous function inside a named function, the
+anonymous function must be declared.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserDatabaseTitle}{Example: A Database}
+\newcommand{\ugUserDatabaseNumber}{6.18.}
+
+@
+\section{Example: A Database}
+\label{ugUserDatabasePage}
+\index{pages!ugUserDatabasePage!ug06.ht}
+\index{ug06.ht!pages!ugUserDatabasePage}
+\index{ugUserDatabasePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserDatabasePage}{6.18. Example: A Database}
+\beginscroll
+
+This example shows how you can use Axiom to organize a database of
+lineage data and then query the database for relationships.
+
+\labelSpace{1.5pc}
+\xtc{
+The database is entered as ``assertions'' that are really
+pieces of a function definition.
+}{
+\spadpaste{children("albert") == ["albertJr","richard","diane"]\bound{d1}}
+}
+\xtc{
+Each piece
+\axiom{children(x) == y} means
+``the children of \axiom{x} are \axiom{y}''.
+}{
+\spadpaste{children("richard") == ["douglas","daniel","susan"]\free{d1}\bound{d2}}
+}
+\xtc{
+This family tree thus spans four generations.
+}{
+\spadpaste{children("douglas") == ["dougie","valerie"]\free{d2}\bound{d3}}
+}
+\xtc{
+Say ``no one else has children.''
+}{
+\spadpaste{children(x) == []\free{d3}\bound{d4}}
+}
+
+\xtc{
+We need some functions for computing lineage.
+Start with \axiom{childOf}.
+}{
+\spadpaste{childOf(x,y) == member?(x,children(y))\bound{d9}\free{d10}}
+}
+\xtc{
+To find the \axiom{parentOf} someone,
+you have to scan the database of
+people applying \axiom{children}.
+}{
+\begin{spadsrc}[\bound{d8a}\free{d9}]
+parentOf(x) ==
+  for y in people repeat
+    (if childOf(x,y) then return y)
+  "unknown"
+\end{spadsrc}
+}
+\xtc{
+And a grandparent of \axiom{x} is just a parent of a parent of \axiom{x}.
+}{
+\spadpaste{grandParentOf(x) == parentOf parentOf x\bound{d8}\free{d8a}}
+}
+\xtc{
+The grandchildren of \axiom{x}
+are the people \axiom{y} such that
+\axiom{x} is a grandparent of \axiom{y}.
+}{
+\spadpaste{grandchildren(x) == [y for y in people | grandParentOf(y) = x]\free{d7}\bound{d8}}
+}
+\xtc{
+Suppose you want to make a list of all great-grandparents.
+Well, a great-grandparent is a grandparent of a person who has children.
+}{
+\begin{spadsrc}[\free{d6}\bound{d7}]
+greatGrandParents == [x for x in people |
+  reduce(_or,[not empty? children(y) for y in grandchildren(x)],false)]
+\end{spadsrc}
+}
+\xtc{
+Define \axiom{descendants} to include the parent as well.
+}{
+\begin{spadsrc}[\free{d5}\bound{d6}]
+descendants(x) ==
+  kids := children(x)
+  null kids => [x]
+  concat(x,reduce(concat,[descendants(y)
+    for y in kids],[]))
+\end{spadsrc}
+}
+\xtc{
+Finally, we need a list of people.
+Since all people are descendants of ``albert'', let's say so.
+}{
+\spadpaste{people == descendants "albert"\free{d4}\bound{d5}}
+}
+
+We have used \axiomSyntax{==} to define the database and some functions to
+query the database.
+But no computation is done until we ask for some information.
+Then, once and for all, the functions are analyzed and compiled to machine
+code for run-time efficiency.
+Notice that no types are given anywhere in this example.
+They are not needed.
+
+\xtc{
+Who are the grandchildren of ``richard''?
+}{
+\spadpaste{grandchildren "richard"\bound{d10}\free{d11}}
+}
+\xtc{
+Who are the great-grandparents?
+}{
+\spadpaste{greatGrandParents\bound{d11}\free{d12}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserTriangleTitle}{Example: A Famous Triangle}
+\newcommand{\ugUserTriangleNumber}{6.19.}
+
+@
+\section{Example: A Famous Triangle}
+\label{ugUserTrianglePage}
+\begin{itemize}
+\item ugTypesExposePage \ref{ugTypesExposePage} on
+page~\pageref{ugTypesExposePage}
+\end{itemize}
+\index{pages!ugUserTrianglePage!ug06.ht}
+\index{ug06.ht!pages!ugUserTrianglePage}
+\index{ugUserTrianglePage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserTrianglePage}{6.19. Example: A Famous Triangle}
+\beginscroll
+
+In this example we write some functions that display
+Pascal's triangle.
+It demonstrates the use of piece-wise definitions and some output
+operations you probably haven't seen before.
+
+\labelSpace{1pc}
+\xtc{
+To make these output operations
+available, we have to \spadgloss{expose} the domain
+\axiomType{OutputForm}.
+See \downlink{``\ugTypesExposeTitle''}{ugTypesExposePage} 
+in Section \ugTypesExposeNumber\ignore{ugTypesExpose} for 
+more information about exposing domains
+and packages.
+}{
+\spadpaste{)set expose add constructor OutputForm \bound{expose}}
+}
+\xtc{
+Define the values along the first
+row and any column \axiom{i}.
+}{
+\spadpaste{pascal(1,i) == 1 \bound{pas1}}
+}
+\xtc{
+Define the values for when the row
+and column index \axiom{i} are equal.
+Repeating the argument name indicates that
+the two index values are equal.
+}{
+\spadpaste{pascal(n,n) == 1 \bound{pas2}\free{pas1}}
+}
+\xtc{
+}{
+\begin{spadsrc}[\bound{pas3}\free{pas1 pas2}]
+pascal(i,j | 1 < i and i < j) ==
+   pascal(i-1,j-1)+pascal(i,j-1)
+\end{spadsrc}
+}
+Now that we have defined the coefficients in Pascal's triangle,
+let's write a couple of one-liners to display it.
+\xtc{
+First, define a function that gives the \eth{\axiom{n}} row.
+}{
+\spadpaste{pascalRow(n) == [pascal(i,n) for i in 1..n] \bound{pascalRow}\free{pas3}}
+}
+\xtc{
+Next, we write the function \userfun{displayRow}
+to display the row, separating entries by blanks and centering.
+}{
+\spadpaste{displayRow(n) == output center blankSeparate pascalRow(n) \free{pascalRow}\bound{displayRow}\free{expose}}
+}
+%
+Here we have used three output operations.
+Operation \axiomFunFrom{output}{OutputForm}
+displays the printable form of objects on the screen,
+\axiomFunFrom{center}{OutputForm} centers a printable form in the
+width of the screen, and \axiomFunFrom{blankSeparate}{OutputForm} takes a list of
+printable forms and inserts a blank between successive elements.
+\xtc{
+Look at the result.
+}{
+\spadpaste{for i in 1..7 repeat displayRow i \free{displayRow}}
+}
+Being purists, we find this less than satisfactory.
+Traditionally, elements of Pascal's triangle are centered between
+the left and right elements on the line above.
+%
+\xtc{
+To fix this misalignment, we go back and
+redefine \userfun{pascalRow} to right adjust the entries within the
+triangle within a width of four characters.
+}{
+\spadpaste{pascalRow(n) == [right(pascal(i,n),4) for i in 1..n] \bound{pascalRow2}}
+}
+%
+\xtc{
+Finally let's look at our purely reformatted triangle.
+}{
+\spadpaste{for i in 1..7 repeat displayRow i \free{pascalRow2}\free{displayRow}}
+}
+\xtc{
+Unexpose \axiomType{OutputForm} so we don't get unexpected
+results later.
+}{
+\spadpaste{)set expose drop constructor OutputForm}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserPalTitle}{Example: Testing for Palindromes}
+\newcommand{\ugUserPalNumber}{6.20.}
+
+@
+\section{Example: Testing for Palindromes}
+\label{ugUserPalPage}
+\begin{itemize}
+\item ugUserTrianglePage \ref{ugUserTrianglePage} on
+page~\pageref{ugUserTrianglePage}
+\end{itemize}
+\index{pages!ugUserPalPage!ug06.ht}
+\index{ug06.ht!pages!ugUserPalPage}
+\index{ugUserPalPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserPalPage}{6.20. Example: Testing for Palindromes}
+\beginscroll
+
+
+In this section we define a function \userfun{pal?} that tests whether its
+argument is a {\it palindrome}, that is, something that reads the same
+backwards and forwards.
+For example, the string ``Madam I'm Adam'' is a palindrome (excluding blanks
+and punctuation) and so is the number \axiom{123454321.}
+The definition works for any datatype that has \axiom{n} components that
+are accessed by the indices \axiom{1\ldots n}.
+
+\xtc{
+Here is the definition for \userfun{pal?}.
+It is simply a call to an auxiliary function called
+\userfun{palAux?}.
+We are following the convention of ending a function's name with
+\axiomSyntax{?} if the function returns a \axiomType{Boolean} value.
+}{
+\spadpaste{pal? s ==  palAux?(s,1,\#s) \bound{pal}}
+}
+\xtc{
+Here is \userfun{palAux?}.
+It works by comparing elements that are equidistant from the start and end
+of the object.
+}{
+\begin{spadsrc}[\bound{palAux}]
+palAux?(s,i,j) ==
+  j > i =>
+    (s.i = s.j) and palAux?(s,i+1,i-1)
+  true
+\end{spadsrc}
+}
+\xtc{
+Try \userfun{pal?} on some examples.
+First, a string.
+}{
+\spadpaste{pal? "Oxford"  \free{pal palAux}}
+}
+\xtc{
+A list of polynomials.
+}{
+\spadpaste{pal? [4,a,x-1,0,x-1,a,4]  \free{pal palAux}}
+}
+\xtc{
+A list of integers from the example in
+\texht{the last section.}{\downlink{``\ugUserTriangleTitle''}
+{ugUserTrianglePage} in Section \ugUserTriangleNumber
+\ignore{ugUserTriangle}.}
+}{
+\spadpaste{pal? [1,6,15,20,15,6,1] \free{pal palAux}}
+}
+\xtc{
+To use \userfun{pal?} on an integer, first convert it to a string.
+}{
+\spadpaste{pal?(1441::String)\free{pal palAux}}
+}
+\xtc{
+Compute an infinite stream of decimal numbers,
+each of which is an obvious palindrome.
+}{
+\spadpaste{ones := [reduce(+,[10**j for j in 0..i]) for i in 1..]\free{pal palAux}\bound{pal5}}
+}
+\xtc{
+How about their squares?
+}{
+\spadpaste{squares := [x**2 for x in ones]\free{pal5}\bound{pal6}}
+}
+\xtc{
+Well, let's test them all!
+}{
+\spadpaste{[pal?(x::String) for x in squares]\free{pal6}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug06.ht>>=
+\newcommand{\ugUserRulesTitle}{Rules and Pattern Matching}
+\newcommand{\ugUserRulesNumber}{6.21.}
+
+@
+\section{Rules and Pattern Matching}
+\label{ugUserRulesPage}
+\index{pages!ugUserRulesPage!ug06.ht}
+\index{ug06.ht!pages!ugUserRulesPage}
+\index{ugUserRulesPage!ug06.ht!pages}
+<<ug06.ht>>=
+\begin{page}{ugUserRulesPage}{6.21. Rules and Pattern Matching}
+\beginscroll
+
+A common mathematical formula is
+\texht{\narrowDisplay{%
+\log(x) + \log(y) = \log(x y) \quad\forall \, x \hbox{\ and\ } y.}}{
+\axiom{log(x) + log(y) == log(x * y)} for any \axiom{x} and \axiom{y}.}
+The presence of
+\texht{``$\forall$''}{the word ``any''}
+indicates that \axiom{x} and \axiom{y} can stand for arbitrary mathematical
+expressions in the above formula.
+You can use such mathematical formulas in Axiom to specify ``rewrite
+rules''.
+Rewrite rules are objects in Axiom that can be assigned to variables for
+later use, often for the purpose of simplification.
+Rewrite rules look like ordinary function definitions except that they are
+preceded by the reserved word \axiom{rule}.
+\spadkey{rule}
+For example, a rewrite rule for the above formula is:
+\begin{verbatim}
+rule log(x) + log(y) == log(x * y)
+\end{verbatim}
+Like function definitions, no action is taken when a rewrite rule is issued.
+Think of rewrite rules as functions that take one argument.
+When a rewrite rule \axiom{A = B} is applied to an argument \axiom{f}, its
+meaning is: ``rewrite every subexpression of \axiom{f} that {\it matches}
+\axiom{A} by \axiom{B.}''
+The left-hand side of a rewrite rule is called a \spadgloss{pattern}; its
+right-side side is called its \spadgloss{substitution}.
+
+\xtc{
+Create a rewrite rule named \userfun{logrule}.
+The generated symbol beginning with a \axiomSyntax{\%} is a place-holder
+for any other terms that might occur in the sum.
+}{
+\spadpaste{logrule := rule log(x) + log(y) == log(x * y) \bound{logrule}}
+}
+\xtc{
+Create an expression with logarithms.
+}{
+\spadpaste{f := log sin x + log x \bound{f}}
+}
+\xtc{
+Apply \userfun{logrule} to \axiom{f}.
+}{
+\spadpaste{logrule f \free{f}\free{logrule}}
+}
+
+The meaning of our example rewrite rule is:
+``for all expressions \axiom{x} and \axiom{y}, rewrite
+\axiom{log(x) + log(y)} by \axiom{log(x * y)}.''
+Patterns generally have both operation names
+(here, \axiomFun{log} and \axiomOp{+})
+and variables (here, \axiom{x} and \axiom{y}).
+By default, every operation name stands for itself.
+Thus \axiomFun{log}  matches only ``\axiom{log}'' and not any
+other operation such as \axiomFun{sin}.
+On the other hand, variables do not stand for themselves.
+Rather, a variable denotes a
+{\it pattern variable} that is free to match any expression whatsoever.
+
+When a rewrite rule is applied, a process called
+\spadgloss{pattern matching} goes to work by systematically
+scanning
+the subexpressions of the argument.
+When a subexpression is found that ``matches'' the pattern, the subexpression
+is replaced by the right-hand side of the rule.
+The details of what happens will be covered later.
+
+The customary Axiom notation for patterns is actually a shorthand for a
+longer, more general notation.
+Pattern variables can be made explicit by using a percent
+(\axiomSyntax{\%}) as the first character of the variable name.
+To say that a name stands for itself, you can prefix that name with a quote
+operator (\axiomSyntax{'}).
+Although the current Axiom parser does not let you quote an operation
+name, this more general notation gives you an alternate way of giving the same
+rewrite rule:
+\begin{verbatim}
+rule log(%x) + log(%y) == log(x * y)
+\end{verbatim}
+This longer notation gives you patterns that the
+standard notation won't handle.
+For example, the rule
+\texht{\typeout{check this example}}{}
+\begin{verbatim}
+rule %f(c * 'x) ==  c*%f(x)
+\end{verbatim}
+means ``for all \axiom{f} and \axiom{c}, replace \axiom{f(y)} by
+\axiom{c * f(x)} when \axiom{y} is the product of \axiom{c}
+and the explicit variable \axiom{x}.''
+
+Thus the pattern can have several adornments on the names that appear there.
+Normally, all these adornments are dropped in the substitution on the
+right-hand side.
+
+To summarize:
+
+\beginImportant
+To enter a single rule in Axiom, use the following syntax:
+\spadkey{rule}
+\centerline{{{\tt rule {\it leftHandSide} == {\it rightHandSide}}}}
+The {\it leftHandSide} is a pattern to be matched and
+the {\it rightHandSide} is its substitution.
+The rule is an object of type \axiomType{RewriteRule} that can be
+assigned to a variable and applied to expressions to transform them.
+\endImportant
+
+Rewrite rules can be collected
+into rulesets so that a set of rules can be applied at once.
+Here is another simplification rule for logarithms.
+\texht{\narrowDisplay{y \log(x) = \log(x^y) \quad\forall \, x \hbox{\ and\ } y.}}{
+\axiom{y * log(x) == log(x ** y)} for any \axiom{x} and \axiom{y}.}
+If instead of giving a single rule following the reserved word \axiom{rule}
+you give a ``pile'' of rules, you create
+what is called a {\it ruleset.}
+Like rules, rulesets are objects in Axiom and
+can be assigned to variables.
+You will find it useful to group commonly used rules into input files, and read
+them in as needed.
+\xtc{
+Create a ruleset named \axiom{logrules}.
+}{
+\begin{spadsrc}[\bound{logrules}]
+logrules := rule
+  log(x) + log(y) == log(x * y)
+  y * log x       == log(x ** y)
+\end{spadsrc}
+}
+\xtc{
+Again, create an expression \axiom{f} containing logarithms.
+}{
+\spadpaste{f := a * log(sin x) - 2 * log x \bound{f1}}
+}
+\xtc{
+Apply the ruleset \userfun{logrules} to \axiom{f}.
+}{
+\spadpaste{logrules f \free{f1}\free{logrules}}
+}
+
+We have allowed pattern variables to match arbitrary expressions in the
+above examples.
+Often you want a variable only to match expressions
+satisfying some predicate.
+For example, we may want to apply the transformation
+\texht{\narrowDisplay{y \log(x) = \log(x^y)}}{\axiom{y * log(x) == log(x ** y)}}
+only when \axiom{y} is an integer.
+%
+The way to restrict a pattern variable \axiom{y} by a predicate \axiom{f(y)}
+is by using a vertical bar \axiomSyntax{|}, which means ``such that,'' in
+much the same way it is used in function definitions.
+You do this only once, but at the earliest
+(meaning deepest and leftmost) part of the pattern.
+\xtc{
+This restricts the logarithmic rule to create integer exponents only.
+}{
+\begin{spadsrc}[\bound{logrules2}]
+logrules2 := rule
+  log(x) + log(y)          == log(x * y)
+  (y | integer? y) * log x == log(x ** y)
+\end{spadsrc}
+}
+\xtc{
+Compare this with the result of applying the previous set of rules.
+}{
+\spadpaste{f \free{f1}}
+}
+\xtc{
+}{
+\spadpaste{logrules2 f \free{f1}\free{logrules2}}
+}
+You should be aware that you might need to apply a function like
+\spadfun{integer} within your predicate expression to actually apply
+the test function.
+\xtc{
+Here we use \spadfun{integer} because \spad{n} has
+type \spadtype{Expression Integer} but \spadfun{even?} is an operation
+defined on integers.
+}{
+\spadpaste{evenRule := rule cos(x)**(n | integer? n and even? integer n)==(1-sin(x)**2)**(n/2) \bound{evenRule}}
+}
+\xtc{
+Here is the application of the rule.
+}{
+\spadpaste{evenRule( cos(x)**2 ) \free{evenRule}}
+}
+\xtc{
+This is an example of some of the usual identities involving products of
+sines and cosines.
+}{
+\begin{spadsrc}[\bound{sinCosProducts}]
+sinCosProducts == rule
+  sin(x) * sin(y) == (cos(x-y) - cos(x + y))/2
+  cos(x) * cos(y) == (cos(x-y) + cos(x+y))/2
+  sin(x) * cos(y) == (sin(x-y) + sin(x + y))/2
+\end{spadsrc}
+}
+\xtc{
+}{
+\spadpaste{g := sin(a)*sin(b) + cos(b)*cos(a) + sin(2*a)*cos(2*a) \bound{g}}
+}
+\xtc{
+}{
+\spadpaste{sinCosProducts g \free{sinCosProducts g}}
+}
+
+Another qualification you will often want to use is to allow a pattern to
+match an identity element.
+Using the pattern \axiom{x + y}, for example, neither \axiom{x} nor \axiom{y}
+matches the expression \axiom{0}.
+Similarly, if a pattern contains a product \axiom{x*y} or an exponentiation
+\axiom{x**y}, then neither \axiom{x} or \axiom{y} matches \axiom{1}.
+%
+\xtc{
+If identical elements were matched, pattern matching would generally loop.
+Here is an expansion rule for exponentials.
+}{
+\spadpaste{exprule := rule exp(a + b) == exp(a) * exp(b)\bound{exprule}}
+}
+\xtc{
+This rule would cause infinite rewriting on this if either \axiom{a} or
+\axiom{b} were allowed to match \axiom{0}.
+}{
+\spadpaste{exprule exp x \free{exprule}}
+}
+%
+There are occasions when you do want a pattern variable in a sum or
+product to match \axiom{0} or \axiom{1}.
+If so, prefix its name
+with a \axiomSyntax{?} whenever it appears in a left-hand side of a rule.
+For example, consider the following rule for the exponential integral:
+\texht{\narrowDisplay{\int \left(\frac{y+e^x}{x}\right)\: dx = \int \frac{y}{x}\: dx + \hbox{\rm Ei}(x)
+\quad\forall \, x \hbox{\ and\ } y.}}{
+\axiom{integral((y + exp x)/x, x) == integral(y/x, x) + Ei x}
+for any \axiom{x} and \axiom{y}.}
+This rule is valid for \axiom{y = 0}.
+One solution is to create a \axiomType{Ruleset} with two
+rules, one with and one without \axiom{y}.
+A better solution is to use an ``optional'' pattern variable.
+%
+\xtc{
+Define rule \axiom{eirule} with
+a pattern variable \axiom{?y} to indicate
+that an expression may or may not occur.
+}{
+\spadpaste{eirule := rule integral((?y + exp x)/x,x) == integral(y/x,x) + Ei x \bound{eirule}}
+}
+\xtc{
+Apply rule \axiom{eirule} to an integral without this term.
+}{
+\spadpaste{eirule integral(exp u/u, u) \free{eirule}}
+}
+\xtc{
+Apply rule \axiom{eirule} to an integral with this term.
+}{
+\spadpaste{eirule integral(sin u + exp u/u, u) \free{eirule}}
+}
+
+Here is one final adornment you will find useful.
+When matching a pattern of the form \axiom{x + y} to an expression containing a
+long sum of the form \axiom{a +\ldots+ b}, there is no way to predict in
+advance which subset of the sum  matches \axiom{x} and which matches
+\axiom{y}.
+Aside from efficiency, this is generally unimportant since the rule holds for
+any possible combination of matches for \axiom{x} and \axiom{y}.
+In some situations, however, you may want to say which pattern variable is a sum
+(or product) of several terms, and which should match only a single term.
+To do this, put a prefix colon \axiomSyntax{:} before the pattern variable
+that you want to match multiple terms.
+%
+\xtc{
+The remaining rules involve operators \axiom{u} and \axiom{v}.
+}{
+\spadpaste{u := operator 'u \bound{u}}
+}
+\xtc{
+These definitions tell Axiom that
+\axiom{u} and \axiom{v} are formal operators to be used in expressions.
+}{
+\spadpaste{v := operator 'v \bound{v}}
+}
+\xtc{
+First define \axiom{myRule}
+with no restrictions on the pattern variables
+\axiom{x} and \axiom{y}.
+}{
+\spadpaste{myRule := rule u(x + y) == u x + v y \free{u v}\bound{m}}
+}
+\xtc{
+Apply \axiom{myRule} to an expression.
+}{
+\spadpaste{myRule u(a + b + c + d) \free{m}}
+}
+\xtc{
+Define \axiom{myOtherRule} to match several terms
+so that the rule gets applied recursively.
+}{
+\spadpaste{myOtherRule := rule u(:x + y) == u x + v y \free{u v}\bound{m2}}
+}
+\xtc{
+Apply \axiom{myOtherRule} to the same expression.
+}{
+\spadpaste{myOtherRule u(a + b + c + d) \free{m2}}
+}
+
+
+Here are some final remarks on pattern matching.
+Pattern matching provides a very useful paradigm for solving
+certain classes of problems, namely, those that involve
+transformations of one form to another and back.
+However, it is important to recognize its limitations.
+
+First, pattern matching slows down as the number of rules you have to apply
+increases.
+Thus it is good practice to organize the sets of rules you use optimally so
+that irrelevant rules are never included.
+
+Second, careless use of pattern matching can lead to wrong answers.
+You should avoid using pattern matching to handle hidden algebraic
+relationships that can go undetected by other programs.
+As a simple example, a symbol such as ``J'' can easily be used to represent
+the square root of \axiom{-1} or some other important algebraic quantity.
+Many algorithms branch on whether an expression is zero or not, then divide by
+that expression if it is not.
+If you fail to simplify an expression involving powers of
+\axiom{J} to \axiom{-1,}
+algorithms may incorrectly assume an expression is non-zero, take a wrong
+branch, and produce a meaningless result.
+
+Pattern matching should also not be used as a substitute for a domain.
+In Axiom, objects of one domain are transformed to objects of other
+domains using well-defined \axiomFun{coerce} operations.
+Pattern matching should be used on objects that are all the same type.
+Thus if your application can be handled by type \axiomType{Expression} in
+Axiom and you think you need pattern matching, consider this choice
+carefully.
+You may well be better served by extending an existing domain
+or by building a new domain of objects for your application.
+\endscroll
+\autobuttons
+\end{page}
+@
+\chapter{Users Guide Chapter 7 (ug07.ht)}
+<<ug07.ht>>=
+\newcommand{\optArg}[1]{{{\tt [}{#1}{\tt ]}}}
+\newcommand{\argDef}[1]{{\tt ({#1})}}
+\newcommand{\funSyntax}[2]{\axiomFun{#1}{\tt ({\small\it{#2}})}}
+\newcommand{\funArgs}[1]{{\tt ({\small\it {#1}})}\newline}
+\newcommand{\ugGraphTitle}{Graphics}
+\newcommand{\ugGraphNumber}{7.}
+
+@
+\section{Graphics}
+\label{ugGraphPage}
+\begin{itemize}
+\item ugGraphTwoDPage \ref{ugGraphTwoDPage} on
+page~\pageref{ugGraphTwoDPage}
+\item ugGraphThreeDPage \ref{ugGraphThreeDPage} on
+page~\pageref{ugGraphThreeDPage}
+\end{itemize}
+\index{pages!ugGraphPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphPage}
+\index{ugGraphPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphPage}{7. Graphics}
+\beginscroll
+
+%
+
+This chapter shows how to use the Axiom graphics facilities
+under the X Window System.
+Axiom has \twodim{} and \threedim{} drawing and rendering
+packages that allow the drawing, coloring, transforming, mapping,
+clipping, and combining of graphic output from Axiom
+computations.
+This facility is particularly useful for investigating problems in
+areas such as topology.
+The graphics package is capable of plotting functions of one or
+more variables or plotting parametric surfaces and curves.
+Various coordinate systems are also available, such as polar and
+spherical.
+
+A graph is displayed in a viewport window and it has a
+control-panel that uses interactive mouse commands.
+PostScript and other output forms are available so that Axiom
+images can be printed or used by other programs.\footnote{PostScript
+is a trademark of Adobe Systems Incorporated, registered in the United
+States.}
+
+\beginmenu
+    \menudownlink{{7.1. Two-Dimensional Graphics}}{ugGraphTwoDPage}
+    \menudownlink{{7.2. Three-Dimensional Graphics}}{ugGraphThreeDPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDTitle}{Two-Dimensional Graphics}
+\newcommand{\ugGraphTwoDNumber}{7.1.}
+
+@
+\section{Two-Dimensional Graphics}
+\label{ugGraphTwoDPage}
+\begin{itemize}
+\item ugGraphTwoDPlotPage \ref{ugGraphTwoDPlotPage} on
+page~\pageref{ugGraphTwoDPlotPage}
+\item ugGraphTwoDParPage \ref{ugGraphTwoDParPage} on
+page~\pageref{ugGraphTwoDParPage}
+\item ugGraphTwoDPlanePage \ref{ugGraphTwoDPlanePage} on
+page~\pageref{ugGraphTwoDPlanePage}
+\item ugGraphTwoDOptionsPage \ref{ugGraphTwoDOptionsPage} on
+page~\pageref{ugGraphTwoDOptionsPage}
+\item ugGraphColorPage \ref{ugGraphColorPage} on
+page~\pageref{ugGraphColorPage}
+\item ugGraphColorPalettePage \ref{ugGraphColorPalettePage} on
+page~\pageref{ugGraphColorPalettePage}
+\item ugGraphTwoDControlPage \ref{ugGraphTwoDControlPage} on
+page~\pageref{ugGraphTwoDControlPage}
+\item ugGraphTwoDopsPage \ref{ugGraphTwoDopsPage} on
+page~\pageref{ugGraphTwoDopsPage}
+\item ugGraphTwoDbuildPage \ref{ugGraphTwoDbuildPage} on
+page~\pageref{ugGraphTwoDbuildPage}
+\item ugGraphTwoDappendPage \ref{ugGraphTwoDappendPage} on
+page~\pageref{ugGraphTwoDappendPage}
+\end{itemize}
+\index{pages!ugGraphTwoDPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDPage}
+\index{ugGraphTwoDPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDPage}{7.1. Two-Dimensional Graphics}
+\beginscroll
+%
+The Axiom \twodim{} graphics package provides the ability to
+display
+%
+\indent{4}
+\beginitems
+%
+\item[-] curves defined by functions of a single real variable
+%
+\item[-] curves defined by parametric equations
+%
+\item[-] implicit non-singular curves defined by polynomial equations
+%
+\item[-] planar graphs generated from lists of point components.
+\enditems
+\indent{0}
+These graphs
+can be modified by specifying various options, such as
+calculating points in the polar
+coordinate system or changing the size of the graph viewport window.
+
+\beginmenu
+    \menudownlink{{7.1.1. Plotting Two-Dimensional Functions of One Variable}}
+{ugGraphTwoDPlotPage}
+    \menudownlink{{7.1.2. Plotting Two-Dimensional Parametric Plane Curves}}
+{ugGraphTwoDParPage}
+    \menudownlink{{7.1.3. Plotting Plane Algebraic Curves}}
+{ugGraphTwoDPlanePage}
+    \menudownlink{{7.1.4. Two-Dimensional Options}}{ugGraphTwoDOptionsPage}
+    \menudownlink{{7.1.5. Color}}{ugGraphColorPage}
+    \menudownlink{{7.1.6. Palette}}{ugGraphColorPalettePage}
+    \menudownlink{{7.1.7. Two-Dimensional Control-Panel}}
+{ugGraphTwoDControlPage}
+    \menudownlink{{7.1.8. Operations for Two-Dimensional Graphics}}
+{ugGraphTwoDopsPage}
+    \menudownlink{{7.1.9. Addendum: Building Two-Dimensional Graphs}}
+{ugGraphTwoDbuildPage}
+    \menudownlink{
+{7.1.10. Addendum: Appending a Graph to a Viewport Window Containing a Graph}}
+{ugGraphTwoDappendPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDPlotTitle}{Plotting Two-Dimensional Functions of One Variable}
+\newcommand{\ugGraphTwoDPlotNumber}{7.1.1.}
+
+@
+\section{Plotting Two-Dimensional Functions of One Variable}
+\label{ugGraphTwoDPlotPage}
+\begin{itemize}
+\item ugGraphTwoDOptionsPage \ref{ugGraphTwoDOptionsPage} on
+page~\pageref{ugGraphTwoDOptionsPage}
+\end{itemize}
+\index{pages!ugGraphTwoDPlotPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDPlotPage}
+\index{ugGraphTwoDPlotPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDPlotPage}{7.1.1. Plotting Two-Dimensional Functions of One Variable}
+\beginscroll
+
+The first kind of \twodim{} graph is that of a curve defined by a function
+\axiom{y = f(x)} over a finite interval of the \axiom{x} axis.
+
+%
+\beginImportant
+The general format for drawing a function defined by a formula
+\axiom{f(x)} is:
+%
+\centerline{{{\tt draw(f(x), x = a..b, {\it options})}}}
+where \axiom{a..b} defines the range of \axiom{x}, and where
+{\it options} prescribes zero or more options as described in
+\downlink{``\ugGraphTwoDOptionsTitle''}{ugGraphTwoDOptionsPage} 
+in Section \ugGraphTwoDOptionsNumber\ignore{ugGraphTwoDOptions}.
+An example of an option is \axiom{curveColor == bright red().}
+An alternative format involving functions \axiom{f} and \axiom{g}
+is also available.
+\endImportant
+
+A simple way to plot a function is to use a formula.
+The first argument is the formula.
+For the second argument, write the name of the independent variable (here, \axiom{x}),
+followed by an \spadSyntax{=}, and the range of values.
+
+\psXtc{
+Display this formula over the range
+\texht{$0 \leq x \leq 6$}{0 <= x <= 6}.
+Axiom converts your formula to a compiled
+function so that the results can be computed
+quickly and efficiently.
+}{
+\graphpaste{draw(sin(tan(x)) - tan(sin(x)),x = 0..6)}
+}{
+\epsffile[0 0 295 295]{../ps/2d1vara.ps}
+}
+
+Notice that Axiom compiled the function before the graph was put
+on the screen.
+
+\psXtc{
+Here is the same graph on a different interval.
+This time we give the graph a title.
+}{
+\graphpaste{draw(sin(tan(x)) - tan(sin(x)),x = 10..16)}
+}{
+%window was 300 x 300
+\epsffile[0 0 295 295]{../ps/2d1varb.ps}
+}
+%
+Once again the formula is converted to a compiled function before
+any points were computed.
+If you want to graph the same function on several intervals, it is
+a good idea to define the function first so that the function has
+to be compiled only once.
+\xtc{
+This time we first define the function.
+}{
+\spadpaste{f(x) == (x-1)*(x-2)*(x-3) \bound{f}}
+}
+\psXtc{
+To draw the function, the first argument is its name
+and the second is just the range with no independent variable.
+}{
+\graphpaste{draw(f, 0..4) \free{f}}
+}{
+\epsffile[0 0 295 295]{../ps/2d1vard.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDParTitle}{Plotting Two-Dimensional Parametric Plane Curves}
+\newcommand{\ugGraphTwoDParNumber}{7.1.2.}
+
+@
+\section{Plotting Two-Dimensional Parametric Plane Curves}
+\label{ugGraphTwoDParPage}
+\begin{itemize}
+\item ugGraphThreeDOptionsPage \ref{ugGraphThreeDOptionsPage} on
+page~\pageref{ugGraphThreeDOptionsPage}
+\end{itemize}
+\index{pages!ugGraphTwoDParPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDParPage}
+\index{ugGraphTwoDParPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDParPage}
+{7.1.2. Plotting Two-Dimensional Parametric Plane Curves}
+\beginscroll
+
+The second kind of \twodim{} graph is that of
+curves produced by parametric equations.
+Let \axiom{x = f(t)} and \axiom{y = g(t)} be formulas or two
+functions \axiom{f} and \axiom{g} as the parameter \axiom{t} ranges
+over an interval \axiom{[a,b]}.
+The function \axiomFun{curve} takes the two functions \axiom{f} and
+\axiom{g} as its parameters.
+
+\beginImportant
+The general format for drawing a \twodim{} plane curve defined by
+parametric formulas \axiom{x = f(t)} and \axiom{y = g(t)} is:
+%
+\centerline{{{\tt draw(curve(f(t), g(t)), t = a..b, {\it options})}}}
+where \axiom{a..b} defines the range of the independent variable \axiom{t},
+and where {\it options} prescribes zero or more options as
+described in 
+\downlink{``\ugGraphThreeDOptionsTitle''}{ugGraphThreeDOptionsPage} 
+in Section \ugGraphThreeDOptionsNumber\ignore{ugGraphThreeDOptions}.
+An example of an option is \axiom{curveColor == bright red().}
+\endImportant
+
+Here's an example:
+
+\psXtc{
+Define a parametric curve using a range involving
+\axiom{\%pi}, Axiom's way of saying \texht{$\pi$}{``pi''}.
+For parametric curves, Axiom compiles two
+functions, one for each of the functions \axiom{f} and \axiom{g}.
+}{
+\graphpaste{draw(curve(sin(t)*sin(2*t)*sin(3*t), sin(4*t)*sin(5*t)*sin(6*t)), t = 0..2*\%pi)}
+}{
+\epsffile[0 0 295 295]{../ps/2dppca.ps}
+}
+%
+%
+\psXtc{
+The title may be an arbitrary string and is an
+optional argument to the \axiomFun{draw} command.
+}{
+\graphpaste{draw(curve(cos(t), sin(t)), t = 0..2*\%pi)}
+}{
+\epsffile[0 0 295 295]{../ps/2dppcb.ps}
+}
+%
+If you plan on plotting \axiom{x = f(t)}, \axiom{y = g(t)} as \axiom{t} 
+ranges over several intervals, you may want to define functions 
+\axiom{f} and \axiom{g} first, so
+that they need not be recompiled every time you create a new graph.
+Here's an example:
+\xtc{
+As before, you can first define the functions you wish to draw.
+}{
+\spadpaste{f(t:DFLOAT):DFLOAT == sin(3*t/4) \bound{f}}
+}
+\xtc{
+Axiom compiles them to map \axiomType{DoubleFloat}
+values to \axiomType{DoubleFloat} values.
+}{
+\spadpaste{g(t:DFLOAT):DFLOAT == sin(t) \bound{g}}
+}
+
+\psXtc{
+Give to {\tt curve} the names of the functions,
+then write the range without the name of the
+independent variable.
+}{
+\graphpaste{draw(curve(f,g),0..\%pi) \free{f g}}
+}{
+\epsffile[0 0 295 295]{../ps/2dppcc.ps}
+}
+%
+%
+\psXtc{
+Here is another look at the same curve but over a different
+range. Notice that \axiom{f} and \axiom{g} are not recompiled.
+Also note that Axiom provides a default title based on
+the first function specified in \axiomFun{curve}.
+}{
+\graphpaste{draw(curve(f,g),-4*\%pi..4*\%pi) \free{f g}}
+}{
+\epsffile[0 0 295 295]{../ps/2dppce.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDPlaneTitle}{Plotting Plane Algebraic Curves}
+\newcommand{\ugGraphTwoDPlaneNumber}{7.1.3.}
+
+@
+\section{Plotting Plane Algebraic Curves}
+\label{ugGraphTwoDPlanePage}
+\begin{itemize}
+\item ugGraphTwoDOptionsPage \ref{ugGraphTwoDOptionsPage} on
+page~\pageref{ugGraphTwoDOptionsPage}
+\end{itemize}
+\index{pages!ugGraphTwoDPlanePage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDPlanePage}
+\index{ugGraphTwoDPlanePage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDPlanePage}{7.1.3. Plotting Plane Algebraic Curves}
+\beginscroll
+
+A third kind of \twodim{} graph is a non-singular ``solution curve''
+in a rectangular region of the plane.
+A solution curve is a curve defined by a polynomial equation
+\axiom{p(x,y) = 0}.
+Non-singular means that the curve is ``smooth'' in that it does not
+cross itself or come to a point (cusp).
+Algebraically, this means that for any point \axiom{(x,y)} on the curve,
+that is, a point such that \axiom{p(x,y) = 0}, the partial derivatives
+\texht{${{\partial p}\over{\partial x}}(x,y)$ and
+${{\partial p}\over{\partial y}}(x,y)$}{\axiom{dp/dx(x,y)}
+and \axiom{dp/dy(a,b)}}
+are not both zero.
+
+%
+\beginImportant
+The general format for drawing a non-singular solution curve
+given by a polynomial of the form \axiom{p(x,y) = 0} is:
+%
+\centerline{{{\tt draw(p(x,y) = 0, x, y, range == [a..b, c..d], {\it options})}}}
+where the second and third arguments name the first and second
+independent variables of \axiom{p}.
+A {\tt range} option is always given to designate a bounding
+rectangular region of the plane \texht{$a \leq x \leq b, c \leq y
+\leq d$}{a <= x <= b, c <= y <= d}.
+Zero or more additional options as described in
+\downlink{``\ugGraphTwoDOptionsTitle''}{ugGraphTwoDOptionsPage} 
+in Section \ugGraphTwoDOptionsNumber\ignore{ugGraphTwoDOptions} 
+may be given.
+\endImportant
+
+\xtc{
+We require that the polynomial has rational or integral coefficients.
+Here is an algebraic curve example (``Cartesian ovals''):
+}{
+\spadpaste{p := ((x**2 + y**2 + 1) - 8*x)**2 - (8*(x**2 + y**2 + 1)-4*x-1) \bound{p}}
+}
+
+\psXtc{
+The first argument is always expressed as an equation of the form 
+\axiom{p = 0} where \axiom{p} is a polynomial.
+}{
+\graphpaste{draw(p = 0, x, y, range == [-1..11, -7..7]) \free{p}}
+}{
+\epsffile[0 0 295 295]{../ps/2dpaca.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDOptionsTitle}{Two-Dimensional Options}
+\newcommand{\ugGraphTwoDOptionsNumber}{7.1.4.}
+
+@
+\section{Two-Dimensional Options}
+\label{ugGraphTwoDOptionsPage}
+\begin{itemize}
+\item ugGraphColorPage \ref{ugGraphColorPage} on
+page~\pageref{ugGraphColorPage}
+\item ugGraphColorPalettePage \ref{ugGraphColorPalettePage} on
+page~\pageref{ugGraphColorPalettePage}
+\item ugGraphColorPage \ref{ugGraphColorPage} on
+page~\pageref{ugGraphColorPage}
+\item ugGraphColorPalettePage \ref{ugGraphColorPalettePage} on
+page~\pageref{ugGraphColorPalettePage}
+\end{itemize}
+\index{pages!ugGraphTwoDOptionsPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDOptionsPage}
+\index{ugGraphTwoDOptionsPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDOptionsPage}{7.1.4. Two-Dimensional Options}
+\beginscroll
+
+The \axiomFun{draw} commands take an optional list of options,
+such as {\tt title} shown above.
+Each option is given by the syntax: {\it name} {\tt ==} {\it value}.
+Here is a list of the available options in the order that they are
+described below.
+
+\table{ {adaptive} {clip} {unit} {clip} {curveColor} {range}
+{toScale} {pointColor} {coordinates}}
+
+The \axiom{adaptive} option turns adaptive plotting on or off.
+Adaptive plotting uses an algorithm that traverses a graph and computes
+more points for those parts of the graph with high curvature.
+The higher the curvature of a region is, the more points the algorithm
+computes.
+%
+%
+\psXtc{
+The {\tt adaptive} option is normally on.
+Here we turn it off.
+}{
+\graphpaste{draw(sin(1/x),x=-2*\%pi..2*\%pi, adaptive == false)}
+}{
+\epsffile[0 0 295 295]{../ps/2doptad.ps}
+}
+%
+%
+\psXtc{
+The {\tt clip} option turns clipping on or off.
+If on, large values are cut off according to
+\axiomFunFrom{clipPointsDefault}{GraphicsDefaults}.
+}{
+\graphpaste{draw(tan(x),x=-2*\%pi..2*\%pi, clip == true)}
+}{
+\epsffile[0 0 295 295]{../ps/2doptcp.ps}
+}
+%
+%
+\psXtc{
+Option {\tt toScale} does plotting to scale if {\tt true} or uses
+the entire viewport if {\tt false}.
+The default can be determined using
+\axiomFunFrom{drawToScale}{GraphicsDefaults}.
+}{
+\graphpaste{draw(sin(x),x=-\%pi..\%pi, toScale == true, unit == [1.0,1.0])}
+}{
+\epsffile[0 0 295 295]{../ps/2doptsc.ps}
+}
+%
+%
+\psXtc{
+Option {\tt clip} with a range sets point clipping of a graph within the
+ranges specified in the list \axiom{[x range,y range]}.
+If only one range is specified, clipping applies to the y-axis.
+}{
+\graphpaste{draw(sec(x),x=-2*\%pi..2*\%pi, clip == [-2*\%pi..2*\%pi,-\%pi..\%pi], unit == [1.0,1.0])}
+}{
+\epsffile[0 0 295 295]{../ps/2doptcpr.ps}
+}
+%
+\psXtc{
+Option {\tt curveColor} sets the color of the graph curves or lines to be the
+indicated palette color
+(see \downlink{``\ugGraphColorTitle''}{ugGraphColorPage} in Section 
+\ugGraphColorNumber\ignore{ugGraphColor} and 
+\downlink{``\ugGraphColorPaletteTitle''}{ugGraphColorPalettePage} 
+in Section \ugGraphColorPaletteNumber\ignore{ugGraphColorPalette}).
+}{
+\graphpaste{draw(sin(x),x=-\%pi..\%pi, curveColor == bright red())}
+}{
+\epsffile[0 0 295 295]{../ps/2doptcvc.ps}
+}
+%
+\psXtc{
+Option {\tt pointColor}
+sets the color of the graph points to the indicated
+palette color
+(see \downlink{``\ugGraphColorTitle''}{ugGraphColorPage} 
+in Section \ugGraphColorNumber\ignore{ugGraphColor} and 
+\downlink{``\ugGraphColorPaletteTitle''}{ugGraphColorPalettePage} 
+in Section \ugGraphColorPaletteNumber\ignore{ugGraphColorPalette}).
+}{
+\graphpaste{draw(sin(x),x=-\%pi..\%pi, pointColor == pastel yellow())}
+}{
+\epsffile[0 0 295 295]{../ps/2doptptc.ps}
+}
+%
+\psXtc{
+Option {\tt unit} sets the intervals at which the axis units are plotted
+according to the indicated steps [\axiom{x} interval, \axiom{y} interval].
+}{
+\graphpaste{draw(curve(9*sin(3*t/4),8*sin(t)), t = -4*\%pi..4*\%pi, unit == [2.0,1.0])}
+}{
+\epsffile[0 0 295 295]{../ps/2doptut.ps}
+}
+%
+%
+\psXtc{
+Option {\tt range} sets the range of variables in a graph to be
+within the ranges
+for solving plane algebraic curve plots.
+}{
+\graphpaste{draw(y**2 + y - (x**3 - x) = 0, x, y, range == [-2..2,-2..1], unit==[1.0,1.0])}
+}{
+\epsffile[0 0 295 295]{../ps/2doptrga.ps}
+}
+%
+%
+\psXtc{
+A second example of a solution plot.
+}{
+\graphpaste{draw(x**2 + y**2 = 1, x, y, range == [-3/2..3/2,-3/2..3/2], unit==[0.5,0.5])}
+}{
+\epsffile[0 0 295 295]{../ps/2doptrgb.ps}
+}
+%
+%
+\psXtc{
+Option \axiom{coordinates} indicates the coordinate system
+in which the graph
+is plotted.
+The default is to use the Cartesian coordinate system.
+For more details, see \downlink{``\ugGraphCoordTitle''}{ugGraphCoordPage} in Section \ugGraphCoordNumber\ignore{ugGraphCoord} \texht{.}{or
+\axiomType{CoordinateSystems}.}
+}{
+\graphpaste{draw(curve(sin(5*t),t),t=0..2*\%pi, coordinates == polar)}
+}{
+\epsffile[0 0 295 295]{../ps/2doptplr.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphColorTitle}{Color}
+\newcommand{\ugGraphColorNumber}{7.1.5.}
+
+@
+\section{Color}
+\label{ugGraphColorPage}
+\index{pages!ugGraphColorPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphColorPage}
+\index{ugGraphColorPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphColorPage}{7.1.5. Color}
+\beginscroll
+
+The domain \axiomType{Color}
+provides operations for manipulating
+colors in \twodim{} graphs.
+Colors are objects of \axiomType{Color}.
+Each color has a {\it hue} and a {\it weight}.
+Hues are represented by integers that range from \axiom{1} to the
+\axiomFunFrom{numberOfHues()}{Color}, normally
+\axiom{27}.
+%\footnote{Use \axiomFun{colorDef} to
+%change these values to any range you want for a given \threedim{} viewport}
+Weights are floats and  have the value \axiom{1.0} by default.
+%
+\indent{0}
+\beginitems
+%
+\item[\axiomFun{color}]\funArgs{integer}
+creates a color of hue {\it integer} and weight \axiom{1.0}.
+%
+\item[\axiomFun{hue}]\funArgs{color}
+returns the hue of {\it color} as an integer.
+%
+\item[\axiomFun{red}]\funArgs{},
+\funSyntax{blue}{},
+\funSyntax{green}{}, and \funSyntax{yellow}{}
+create colors of that hue with weight \axiom{1.0}.
+%
+\item[\subscriptIt{color}{1} {\tt +} \subscriptIt{color}{2}] returns the
+color that results from additively combining the indicated
+\subscriptIt{color}{1} and \subscriptIt{color}{2}.
+Color addition is not commutative: changing the order of the arguments
+produces different results.
+%
+\item[{\it integer} {\tt *} {\it color}]
+changes the weight of {\it color} by {\it integer}
+without affecting its hue.
+For example,
+\axiom{red() + 3*yellow()} produces a color closer to yellow than to red.
+Color multiplication is not associative: changing the order of grouping
+produces different results.
+\enditems
+\indent{0}
+%
+\psXtc{
+These functions can be used to change the point and curve colors
+for two- and \threedim{} graphs.
+Use the {\tt pointColor} option for points.
+}{
+\graphpaste{draw(x**2,x=-1..1,pointColor == green())}
+}{
+\epsffile[0 0 295 295]{../ps/23dcola.ps}
+}
+%
+\psXtc{
+Use the {\tt curveColor} option for curves.
+}{
+\graphpaste{draw(x**2,x=-1..1,curveColor == color(13) + 2*blue())}
+}{
+\epsffile[0 0 295 295]{../ps/23dcolb.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphColorPaletteTitle}{Palette}
+\newcommand{\ugGraphColorPaletteNumber}{7.1.6.}
+
+@
+\section{Palette}
+\label{ugGraphColorPalettePage}
+\index{pages!ugGraphColorPalettePage!ug07.ht}
+\index{ug07.ht!pages!ugGraphColorPalettePage}
+\index{ugGraphColorPalettePage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphColorPalettePage}{7.1.6. Palette}
+\beginscroll
+
+Domain \axiomType{Palette} is the domain of shades of colors:
+\axiomFun{dark}, \axiomFun{dim}, \axiomFun{bright}, \axiomFun{pastel}, and \axiomFun{light},
+designated by the integers \axiom{1} through \axiom{5}, respectively.
+\xtc{
+Colors are normally ``bright.''
+}{
+\spadpaste{shade red()}
+}
+\xtc{
+To change the shade of a color, apply the name of a shade to it.
+}{
+\spadpaste{myFavoriteColor := dark blue() \bound{mfc}}
+}
+\xtc{
+The expression \axiom{shade(color)}
+returns the value of a shade of \axiom{color}.
+}{
+\spadpaste{shade myFavoriteColor \free{mfc}}
+}
+\xtc{
+The expression \axiom{hue(color)} returns its hue.
+}{
+\spadpaste{hue myFavoriteColor \free{mfc}}
+}
+\psXtc{
+Palettes can be used in specifying colors in \twodim{} graphs.
+}{
+\graphpaste{draw(x**2,x=-1..1,curveColor == dark blue())}
+}{
+\epsffile[0 0 295 295]{../ps/23dpal.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDControlTitle}{Two-Dimensional Control-Panel}
+\newcommand{\ugGraphTwoDControlNumber}{7.1.7.}
+
+@
+\section{Two-Dimensional Control-Panel}
+\label{ugGraphTwoDControlPage}
+\index{pages!ugGraphTwoDControlPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDControlPage}
+\index{ugGraphTwoDControlPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDControlPage}{7.1.7. Two-Dimensional Control-Panel}
+\beginscroll
+Once you have created a viewport, move your mouse to the viewport and click
+with your left mouse button to display a control-panel.
+The panel is displayed on the side of the viewport closest to
+where you clicked.  Each of the buttons which toggle on and off show the
+current state of the graph.
+
+
+\subsubsection{Transformations}
+
+Object transformations are executed from the control-panel by mouse-activated
+potentiometer windows.
+%
+\indent{0}
+\beginitems
+%
+\item[Scale:] To scale a graph, click on a mouse button
+within the {\bf Scale} window in the upper left corner of the control-panel.
+The axes along which the scaling is to occur are indicated by setting the
+toggles above the arrow.
+With {\tt X On} and {\tt Y On} appearing, both axes are selected and scaling
+is uniform.
+If either is not selected, for example, if {\tt X Off} appears, scaling is
+non-uniform.
+%
+\item[Translate:] To translate a graph, click the mouse in the
+{\bf Translate} window in the direction you wish the graph to move.
+This window is located in the upper right corner of the control-panel.
+Along the top of the {\bf Translate} window are two buttons for selecting
+the direction of translation.
+Translation along both coordinate axes results when {\tt X On} and {\tt Y
+On} appear or along one axis when one is on, for example, {\tt X On} and
+{\tt Y Off} appear.
+\enditems
+\indent{0}
+
+\subsubsection{Messages}
+
+The window directly below the transformation potentiometer windows is
+used to display system messages relating to the viewport and the control-panel.
+The following format is displayed: \newline
+%
+\centerline{{[scaleX, scaleY] \axiom{>}graph\axiom{<} [translateX, translateY] \newline}}
+The two values to the left show the scale factor along the {\tt X} and
+{\tt Y} coordinate axes.  The two values to the right show the distance of
+translation from the center in the {\tt X} and {\tt Y} directions.  The number
+in the center shows which graph in the viewport this data pertains to.
+When multiple graphs exist in the same viewport,
+the graph must be selected (see ``Multiple Graphs,'' below) in
+order for its transformation data to be shown, otherwise the number
+is 1.
+
+\subsubsection{Multiple Graphs}
+
+The {\bf Graphs} window contains buttons that allow the placement
+of \twodim{} graphs into one of nine available slots in any other
+\twodim{} viewport.
+In the center of the window are numeral buttons from one to nine
+that show whether a graph is displayed in the viewport.
+Below each number button is a button showing whether a graph
+that is present is selected for application of some
+transformation.
+When the caret symbol is displayed, then the graph in that slot
+will be manipulated.
+Initially, the graph for which the viewport is created occupies
+the first slot, is displayed, and is selected.
+%
+%
+\indent{0}
+\beginitems
+%
+\item[Clear:]  The {\bf Clear} button deselects every viewport graph slot.
+A graph slot is reselected by selecting the button below its number.
+%
+\item[Query:]  The {\bf Query} button is used to display the scale and
+translate data for the indicated graph.  When this button is selected the
+message ``Click on the graph to query'' appears.  Select a slot
+number button from the {\bf Graphs} window. The scaling factor and translation
+offset of the graph are then displayed in the message window.
+%
+\item[Pick:]  The {\bf Pick} button is used to select a graph
+to be placed or dropped into the indicated viewport.  When this button is
+selected, the message ``Click on the graph to pick'' appears.
+Click on the slot with the graph number of the desired
+graph.  The graph information is held waiting for
+you to execute a {\bf Drop} in some other graph.
+%
+\item[Drop:]  Once a graph has been picked up using the {\bf Pick} button,
+the {\bf Drop} button places it into a new viewport slot.
+The message ``Click on the graph to drop'' appears in the message
+window when the {\bf Drop} button is selected.
+By selecting one of the slot number buttons in the {\bf Graphs}
+window, the graph currently being held is dropped into this slot
+and displayed.
+\enditems
+\indent{0}
+
+\subsubsection{Buttons}
+
+%
+\indent{0}
+\beginitems
+%
+\item[Axes] turns the coordinate axes on or off.
+%
+\item[Units] turns the units along the {\tt x}
+and {\tt y} axis on or off.
+%
+\item[Box] encloses the area of the viewport graph
+in a bounding box, or removes the box if already enclosed.
+%
+\item[Pts] turns on or off the display of points.
+%
+\item[Lines] turns on or off the display
+of lines connecting points.
+%
+\item[PS] writes the current viewport contents to
+a file {\bf axiom2D.ps} or to a name specified in the user's {\bf
+.Xdefaults} file.
+The file is placed in the directory from which Axiom or the {\bf
+viewalone} program was invoked.
+%
+\item[Reset] resets the object transformation
+characteristics and attributes back to their initial states.
+%
+\item[Hide] makes the control-panel disappear.
+%
+\item[Quit] queries whether the current viewport
+session should be terminated.
+\enditems
+\indent{0}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDopsTitle}{Operations for Two-Dimensional Graphics}
+\newcommand{\ugGraphTwoDopsNumber}{7.1.8.}
+
+@
+\section{Operations for Two-Dimensional Graphics}
+\label{ugGraphTwoDopsPage}
+\index{pages!ugGraphTwoDopsPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDopsPage}
+\index{ugGraphTwoDopsPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDopsPage}
+{7.1.8. Operations for Two-Dimensional Graphics}
+\beginscroll
+
+Here is a summary of useful Axiom operations for \twodim{}
+graphics.
+Each operation name is followed by a list of arguments.
+Each argument is written as a variable informally named according
+to the type of the argument (for example, {\it integer}).
+If appropriate, a default value for an argument is given in
+parentheses immediately following the name.
+
+%
+\texht{\bgroup\hbadness = 10001\sloppy}{}
+\indent{0}
+\beginitems
+%
+\item[\axiomFun{adaptive}]\funArgs{\optArg{boolean\argDef{true}}}
+sets or indicates whether graphs are plotted
+according to the adaptive refinement algorithm.
+%
+\item[\axiomFun{axesColorDefault}]\funArgs{\optArg{color\argDef{dark blue()}}}
+sets or indicates the default color of the
+axes in a \twodim{} graph viewport.
+%
+\item[\axiomFun{clipPointsDefault}]\funArgs{\optArg{boolean\argDef{false}}}
+sets or
+indicates whether point clipping is
+to be applied as the default for graph plots.
+%
+\item[\axiomFun{drawToScale}]\funArgs{\optArg{boolean\argDef{false}}}
+sets or
+indicates whether the plot of a graph
+is ``to scale'' or uses the entire viewport space as the default.
+%
+\item[\axiomFun{lineColorDefault}]\funArgs{\optArg{color\argDef{pastel yellow()}}}
+sets or indicates the default color of the
+lines or curves in a \twodim{} graph viewport.
+%
+\item[\axiomFun{maxPoints}]\funArgs{\optArg{integer\argDef{500}}}
+sets or indicates
+the default maximum number of
+possible points to be used when constructing a \twodim{} graph.
+%
+\item[\axiomFun{minPoints}]\funArgs{\optArg{integer\argDef{21}}}
+sets or indicates the default minimum number of
+possible points to be used when constructing a \twodim{} graph.
+%
+\item[\axiomFun{pointColorDefault}]\funArgs{\optArg{color\argDef{bright red()}}}
+sets or indicates the default color of the
+points in a \twodim{} graph viewport.
+%
+\item[\axiomFun{pointSizeDefault}]\funArgs{\optArg{integer\argDef{5}}}
+sets or indicates the default size of the
+dot used to plot points in a \twodim{} graph.
+%
+\item[\axiomFun{screenResolution}]\funArgs{\optArg{integer\argDef{600}}}
+sets or indicates the default screen
+resolution constant used in setting the computation limit of adaptively
+generated curve plots.
+%
+\item[\axiomFun{unitsColorDefault}]\funArgs{\optArg{color\argDef{dim green()}}}
+sets or indicates the default color of the
+unit labels in a \twodim{} graph viewport.
+%
+\item[\axiomFun{viewDefaults}]\funArgs{}
+resets the default settings for the following
+attributes:  point color, line color, axes color, units color, point size,
+viewport upper left-hand corner position, and the viewport size.
+%
+\item[\axiomFun{viewPosDefault}]\funArgs{\optArg{list\argDef{[100,100]}}}
+sets or indicates the default position of the
+upper left-hand corner of a \twodim{} viewport, relative to the
+display root window.
+The upper left-hand corner of the display is considered to be at the
+(0, 0) position.
+%
+\item[\axiomFun{viewSizeDefault}]\funArgs{\optArg{list\argDef{[200,200]}}}
+sets or
+indicates the default size in which two
+dimensional viewport windows are shown.
+It is defined by a width and then a height.
+%
+\item[\axiomFun{viewWriteAvailable}]\funArgs{\optArg{list\argDef{["pixmap",
+"bitmap", "postscript", \"image"}}}
+indicates the possible file types
+that can be created with the \axiomFunFrom{write}{TwoDimensionalViewport} function.
+%
+\item[\axiomFun{viewWriteDefault}]
+\funArgs{\optArg{list\argDef{[]}}}
+sets or indicates the default types of files, in
+addition to the {\bf data} file, that are created when a
+\axiomFun{write} function is executed on a viewport.
+%
+\item[\axiomFun{units}]\funArgs{viewport, integer\argDef{1}, string\argDef{"off"}}
+turns the units on or off for the graph with index {\it integer}.
+%
+\item[\axiomFun{axes}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
+turns the axes on
+or off for the graph with index {\it integer}.
+%
+\item[\axiomFun{close}]\funArgs{viewport}
+closes {\it viewport}.
+%
+\item[\axiomFun{connect}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
+declares whether lines
+connecting the points are displayed or not.
+%
+\item[\axiomFun{controlPanel}]\funArgs{viewport, string\argDef{"off"}}
+declares
+whether the \twodim{} control-panel is automatically displayed
+or not.
+%
+\item[\axiomFun{graphs}]\funArgs{viewport}
+returns a list
+describing the state of each graph.
+If the graph state is not being used this is shown by {\tt "undefined"},
+otherwise a description of the graph's contents is shown.
+%
+\item[\axiomFun{graphStates}]\funArgs{viewport}
+displays
+a list of all the graph states available for {\it viewport}, giving the
+values for every property.
+%
+\item[\axiomFun{key}]\funArgs{viewport}
+returns the process
+ID number for {\it viewport}.
+%
+\item[\axiomFun{move}]\funArgs{viewport,
+\subscriptText{integer}{x}(viewPosDefault),
+\subscriptText{integer}{y}(viewPosDefault)}
+moves {\it viewport} on the screen so that the
+upper left-hand corner of {\it viewport} is at the position {\it (x,y)}.
+%
+\item[\axiomFun{options}]\funArgs{\it viewport}
+returns a list
+of all the \axiomType{DrawOption}s used by {\it viewport}.
+%
+\item[\axiomFun{points}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
+specifies whether the graph points for graph {\it integer} are
+to be displayed or not.
+%
+\item[\axiomFun{region}]\funArgs{viewport, integer\argDef{1}, string\argDef{"off"}}
+declares whether graph {\it integer} is or is not to be displayed
+with a bounding rectangle.
+%
+\item[\axiomFun{reset}]\funArgs{viewport}
+resets all the properties of {\it viewport}.
+%
+\item[\axiomFun{resize}]\funArgs{viewport,
+\subscriptText{integer}{width}, \subscriptText{integer}{height}}
+resizes {\it viewport} with a new {\it width} and {\it height}.
+%
+\item[\axiomFun{scale}]\funArgs{viewport, \subscriptText{integer}{n}\argDef{1},
+\subscriptText{integer}{x}\argDef{0.9}, \subscriptText{integer}{y}\argDef{0.9}}
+scales values for the
+{\it x} and {\it y} coordinates of graph {\it n}.
+%
+\item[\axiomFun{show}]\funArgs{viewport, \subscriptText{integer}{n}\argDef{1},
+string\argDef{"on"}}
+indicates if graph {\it n} is shown or not.
+%
+\item[\axiomFun{title}]\funArgs{viewport, string\argDef{"Axiom 2D"}}
+designates the title for {\it viewport}.
+%
+\item[\axiomFun{translate}]\funArgs{viewport,
+\subscriptText{integer}{n}\argDef{1},
+\subscriptText{float}{x}\argDef{0.0}, \subscriptText{float}{y}\argDef{0.0}}
+causes graph {\it n} to be moved {\it x} and {\it y} units in the respective directions.
+%
+\item[\axiomFun{write}]\funArgs{viewport, \subscriptText{string}{directory},
+\optArg{strings}}
+if no third argument is given, writes the {\bf data} file onto the directory
+with extension {\bf data}.
+The third argument can be a single string or a list of strings with some or
+all the entries {\tt "pixmap"}, {\tt "bitmap"}, {\tt "postscript"}, and
+{\tt "image"}.
+\enditems
+\indent{0}
+\texht{\egroup}{}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDbuildTitle}{Addendum: Building Two-Dimensional Graphs}
+\newcommand{\ugGraphTwoDbuildNumber}{7.1.9.}
+
+@
+\section{Addendum: Building Two-Dimensional Graphs}
+\label{ugGraphTwoDbuildPage}
+\index{pages!ugGraphTwoDbuildPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDbuildPage}
+\index{ugGraphTwoDbuildPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDbuildPage}
+{7.1.9. Addendum: Building Two-Dimensional Graphs}
+\beginscroll
+
+In this section we demonstrate how to create \twodim{} graphs from
+lists of points and give an example showing how to read the lists
+of points from a file.
+
+\subsubsection{Creating a Two-Dimensional Viewport from a List of Points}
+
+Axiom creates lists of points in a \twodim{} viewport by utilizing
+the \axiomType{GraphImage} and \axiomType{TwoDimensionalViewport} domains.
+In this example, the \axiomFunFrom{makeGraphImage}{GraphImage}
+function takes a list of lists of points parameter, a list of colors for
+each point in the graph, a list of colors for each line in the graph, and
+a list of sizes for each point in the graph.
+%
+\xtc{
+The following expressions create a list of lists of points which will be read
+by Axiom and made into a \twodim{} viewport.
+}{
+\spadpaste{p1 := point [1,1]\$(Point DFLOAT) \bound{p1}}
+}
+\xtc{
+}{
+\spadpaste{p2 := point [0,1]\$(Point DFLOAT) \bound{p2}}
+}
+\xtc{
+}{
+\spadpaste{p3 := point [0,0]\$(Point DFLOAT) \bound{p3}}
+}
+\xtc{
+}{
+\spadpaste{p4 := point [1,0]\$(Point DFLOAT) \bound{p4}}
+}
+\xtc{
+}{
+\spadpaste{p5 := point [1,.5]\$(Point DFLOAT) \bound{p5}}
+}
+\xtc{
+}{
+\spadpaste{p6 := point [.5,0]\$(Point DFLOAT) \bound{p6}}
+}
+\xtc{
+}{
+\spadpaste{p7 := point [0,0.5]\$(Point DFLOAT) \bound{p7}}
+}
+\xtc{
+}{
+\spadpaste{p8 := point [.5,1]\$(Point DFLOAT) \bound{p8}}
+}
+\xtc{
+}{
+\spadpaste{p9 := point [.25,.25]\$(Point DFLOAT) \bound{p9}}
+}
+\xtc{
+}{
+\spadpaste{p10 := point [.25,.75]\$(Point DFLOAT) \bound{p10}}
+}
+\xtc{
+}{
+\spadpaste{p11 := point [.75,.75]\$(Point DFLOAT) \bound{p11}}
+}
+\xtc{
+}{
+\spadpaste{p12 := point [.75,.25]\$(Point DFLOAT) \bound{p12}}
+}
+\xtc{
+Finally, here is the list.
+}{
+\spadpaste{llp := [[p1,p2], [p2,p3], [p3,p4], [p4,p1], [p5,p6], [p6,p7], [p7,p8], [p8,p5], [p9,p10], [p10,p11], [p11,p12], [p12,p9]] \free{p1 p2 p3 p4 p5 p6 p7 p8 p9 p10 p11 p12} \bound{llp}}
+}
+\xtc{
+Now we set the point sizes for all components of the graph.
+}{
+\spadpaste{size1 := 6::PositiveInteger \bound{size1}}
+}
+\xtc{
+}{
+}
+\xtc{
+}{
+\spadpaste{size2 := 8::PositiveInteger \bound{size2}}
+}
+\xtc{
+}{
+\spadpaste{size3 := 10::PositiveInteger \bound{size3}}
+}
+\xtc{
+}{
+\spadpaste{lsize := [size1, size1, size1, size1, size2, size2, size2, size2, size3, size3, size3, size3] \bound{lsize} \free{size1 size2 size3}}
+}
+\xtc{
+Here are the colors for the points.
+}{
+\spadpaste{pc1 := pastel red() \bound{pc1}}
+}
+\xtc{
+}{
+\spadpaste{pc2 := dim green() \bound{pc2}}
+}
+\xtc{
+}{
+\spadpaste{pc3 := pastel yellow() \bound{pc3}}
+}
+\xtc{
+}{
+\spadpaste{lpc := [pc1, pc1, pc1, pc1, pc2, pc2, pc2, pc2, pc3, pc3, pc3, pc3] \free{pc1 pc2 pc3} \bound{lpc}}
+}
+\xtc{
+Here are the colors for the lines.
+}{
+\spadpaste{lc := [pastel blue(), light yellow(), dim green(), bright red(), light green(), dim yellow(), bright blue(), dark red(), pastel red(), light blue(), dim green(), light yellow()] \bound{lc}}
+}
+\xtc{
+Now the \axiomType{GraphImage} is created according to the component
+specifications indicated above.
+}{
+\spadpaste{g := makeGraphImage(llp,lpc,lc,lsize)\$GRIMAGE \bound{g} \free{llp lpc lc lsize}}
+}
+\psXtc{
+The \axiomFunFrom{makeViewport2D}{TwoDimensionalViewport} function now
+creates a \axiomType{TwoDimensionalViewport} for this graph according to the
+list of options specified within the brackets.
+}{
+\graphpaste{makeViewport2D(g,[title("Lines")])\$VIEW2D \free{g}}
+}{
+%
+}
+%See Figure #.#.
+\xtc{
+This example demonstrates the use of the \axiomType{GraphImage} functions
+\axiomFunFrom{component}{GraphImage} and \axiomFunFrom{appendPoint}{GraphImage}
+in adding points to an empty \axiomType{GraphImage}.
+}{
+\spadpaste{)clear all \bound{clearAll}}
+}
+\xtc{
+}{
+\spadpaste{g := graphImage()\$GRIMAGE \bound{Sg}\free{clearAll}}
+}
+\xtc{
+}{
+\spadpaste{p1 := point [0,0]\$(Point DFLOAT) \bound{Sp1}}
+}
+\xtc{
+}{
+\spadpaste{p2 := point [.25,.25]\$(Point DFLOAT) \bound{Sp2}}
+}
+\xtc{
+}{
+\spadpaste{p3 := point [.5,.5]\$(Point DFLOAT) \bound{Sp3}}
+}
+\xtc{
+}{
+\spadpaste{p4 := point [.75,.75]\$(Point DFLOAT) \bound{Sp4}}
+}
+\xtc{
+}{
+\spadpaste{p5 := point [1,1]\$(Point DFLOAT) \bound{Sp5}}
+}
+\xtc{
+}{
+\spadpaste{component(g,p1)\$GRIMAGE\free{Sg Sp1}\bound{gp1}}
+}
+\xtc{
+}{
+\spadpaste{component(g,p2)\$GRIMAGE\free{Sg Sp2}\bound{gp2}}
+}
+\xtc{
+}{
+\spadpaste{appendPoint(g,p3)\$GRIMAGE\free{gp1 gp2 Sp3}\bound{gp3}}
+}
+\xtc{
+}{
+\spadpaste{appendPoint(g,p4)\$GRIMAGE\free{gp3 Sp4}\bound{gp4}}
+}
+\xtc{
+}{
+\spadpaste{appendPoint(g,p5)\$GRIMAGE\free{gp4 Sp5}\bound{gp5}}
+}
+\xtc{
+}{
+\spadpaste{g1 := makeGraphImage(g)\$GRIMAGE \bound{Sg1} \free{gp5}}
+}
+\psXtc{
+Here is the graph.
+}{
+\graphpaste{makeViewport2D(g1,[title("Graph Points")])\$VIEW2D \free{Sg1}}
+}{
+%
+}
+%
+%See Figure #.#.
+%
+\xtc{
+A list of points can also be made into a \axiomType{GraphImage} by using
+the operation \axiomFunFrom{coerce}{GraphImage}.  It is equivalent to adding
+each point to \axiom{g2} using \axiomFunFrom{component}{GraphImage}.
+}{
+\spadpaste{g2 := coerce([[p1],[p2],[p3],[p4],[p5]])\$GRIMAGE  \free{Sp1 Sp2 Sp3 Sp4 Sp5} \bound{Sg2}}
+}
+\xtc{
+Now, create an empty \axiomType{TwoDimensionalViewport}.
+}{
+\spadpaste{v := viewport2D()\$VIEW2D \bound{Sv}}
+}
+\xtc{
+}{
+\spadpaste{options(v,[title("Just Points")])\$VIEW2D \free{Sv}\bound{Svo}}
+}
+\xtc{
+Place the graph into the viewport.
+}{
+\spadpaste{putGraph(v,g2,1)\$VIEW2D \free{Sg2 Svo}\bound{Svog2}}
+}
+\psXtc{
+Take a look.
+}{
+\graphpaste{makeViewport2D(v)\$VIEW2D \free{Svog2}}
+}{
+%
+}
+
+%See Figure #.#.
+
+\subsubsection{Creating a Two-Dimensional Viewport of a List of Points from a File}
+
+The following three functions read a list of points from a
+file and then draw the points and the connecting lines. The
+points are stored in the file in readable form as floating point numbers
+(specifically, \axiomType{DoubleFloat} values) as an alternating
+stream of \axiom{x}- and \axiom{y}-values. For example,
+\begin{verbatim}
+0.0 0.0     1.0 1.0     2.0 4.0
+3.0 9.0     4.0 16.0    5.0 25.0
+\end{verbatim}
+
+\beginImportant
+  
+\noindent
+{\tt 1.\ \ \ drawPoints(lp:List\ Point\ DoubleFloat):VIEW2D\ ==}\newline
+{\tt 2.\ \ \ \ \ g\ :=\ graphImage()\$GRIMAGE}\newline
+{\tt 3.\ \ \ \ \ for\ p\ in\ lp\ repeat}\newline
+{\tt 4.\ \ \ \ \ \ \ component(g,p,pointColorDefault(),lineColorDefault(),}\newline
+{\tt 5.\ \ \ \ \ \ \ \ \ pointSizeDefault())}\newline
+{\tt 6.\ \ \ \ \ gi\ :=\ makeGraphImage(g)\$GRIMAGE}\newline
+{\tt 7.\ \ \ \ \ makeViewport2D(gi,[title("Points")])\$VIEW2D}\newline
+{\tt 8.\ \ \ }\newline
+{\tt 9.\ \ \ drawLines(lp:List\ Point\ DoubleFloat):VIEW2D\ ==}\newline
+{\tt 10.\ \ \ \ g\ :=\ graphImage()\$GRIMAGE}\newline
+{\tt 11.\ \ \ \ component(g,\ lp,\ pointColorDefault(),\ lineColorDefault(),}\newline
+{\tt 12.\ \ \ \ \ \ pointSizeDefault())\$GRIMAGE}\newline
+{\tt 13.\ \ \ \ gi\ :=\ makeGraphImage(g)\$GRIMAGE}\newline
+{\tt 14.\ \ \ \ makeViewport2D(gi,[title("Points")])\$VIEW2D}\newline
+{\tt 15.\ \ }\newline
+{\tt 16.\ \ plotData2D(name,\ title)\ ==}\newline
+{\tt 17.\ \ \ \ f:File(DFLOAT)\ :=\ open(name,"input")}\newline
+{\tt 18.\ \ \ \ lp:LIST(Point\ DFLOAT)\ :=\ empty()}\newline
+{\tt 19.\ \ \ \ while\ ((x\ :=\ readIfCan!(f))\ case\ DFLOAT)\ repeat}\newline
+{\tt 20.\ \ \ \ \ \ y\ :\ DFLOAT\ :=\ read!(f)}\newline
+{\tt 21.\ \ \ \ \ \ lp\ :=\ cons(point\ [x,y]\$(Point\ DFLOAT),\ lp)}\newline
+{\tt 22.\ \ \ \ \ \ lp}\newline
+{\tt 23.\ \ \ \ close!(f)}\newline
+{\tt 24.\ \ \ \ drawPoints(lp)}\newline
+{\tt 25.\ \ \ \ drawLines(lp)}\newline
+\endImportant
+%
+This command will actually create the viewport and the graph if
+the point data is in the file \axiom{"file.data"}.
+\beginImportant
+  
+\noindent
+{\tt 1.\ \ \ plotData2D("file.data",\ "2D\ Data\ Plot")}\newline
+\endImportant
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphTwoDappendTitle}{Addendum: Appending a Graph to a Viewport Window Containing a Graph}
+\newcommand{\ugGraphTwoDappendNumber}{7.1.10.}
+
+@
+\section{Addendum: Appending a Graph to a Viewport Window Containing a Graph}
+\label{ugGraphTwoDappendPage}
+\index{pages!ugGraphTwoDappendPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphTwoDappendPage}
+\index{ugGraphTwoDappendPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphTwoDappendPage}
+{7.1.10. Addendum: Appending a Graph to a Viewport Window Containing a Graph}
+\beginscroll
+
+This section demonstrates how to append a \twodim{} graph to a viewport
+already containing other graphs.
+The default \axiomFun{draw} command places a graph into the first
+\axiomType{GraphImage} slot position of the \axiomType{TwoDimensionalViewport}.
+
+\xtc{
+This graph is in the first slot in its viewport.
+}{
+\spadpaste{v1 := draw(sin(x),x=0..2*\%pi) \bound{v1}}
+}
+\xtc{
+So is this graph.
+}{
+\spadpaste{v2 := draw(cos(x),x=0..2*\%pi, curveColor==light red()) \bound{v2}}
+}
+\xtc{
+The operation \axiomFunFrom{getGraph}{TwoDimensionalViewport}
+retrieves the \axiomType{GraphImage} \axiom{g1} from the first slot position
+in the viewport \axiom{v1}.
+}{
+\spadpaste{g1 := getGraph(v1,1) \bound{g1}\free{v1}}
+}
+\xtc{
+Now \axiomFunFrom{putGraph}{TwoDimensionalViewport}
+places \axiom{g1} into the the second slot position of \axiom{v2}.
+}{
+\spadpaste{putGraph(v2,g1,2) \bound{v22}\free{g1 v2}}
+}
+\psXtc{
+Display the new \axiomType{TwoDimensionalViewport} containing both graphs.
+}{
+\graphpaste{makeViewport2D(v2) \free{v22}}
+}{
+%
+}
+%
+%See Figure #.#.
+%
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDTitle}{Three-Dimensional Graphics}
+\newcommand{\ugGraphThreeDNumber}{7.2.}
+
+@
+\section{Three-Dimensional Graphics}
+\label{ugGraphThreeDPage}
+\begin{itemize}
+\item ugGraphThreeDPlotPage \ref{ugGraphThreeDPlotPage} on
+page~\pageref{ugGraphThreeDPlotPage}
+\item ugGraphThreeDParmPage \ref{ugGraphThreeDParmPage} on
+page~\pageref{ugGraphThreeDParmPage}
+\item ugGraphThreeDParPage \ref{ugGraphThreeDParPage} on
+page~\pageref{ugGraphThreeDParPage}
+\item ugGraphThreeDOptionsPage \ref{ugGraphThreeDOptionsPage} on
+page~\pageref{ugGraphThreeDOptionsPage}
+\item ugGraphMakeObjectPage \ref{ugGraphMakeObjectPage} on
+page~\pageref{ugGraphMakeObjectPage}
+\item ugGraphThreeDBuildPage \ref{ugGraphThreeDBuildPage} on
+page~\pageref{ugGraphThreeDBuildPage}
+\item ugGraphCoordPage \ref{ugGraphCoordPage} on
+page~\pageref{ugGraphCoordPage}
+\item ugGraphClipPage \ref{ugGraphClipPage} on
+page~\pageref{ugGraphClipPage}
+\item ugGraphThreeDControlPage \ref{ugGraphThreeDControlPage} on
+page~\pageref{ugGraphThreeDControlPage}
+\item ugGraphThreeDopsPage \ref{ugGraphThreeDopsPage} on
+page~\pageref{ugGraphThreeDopsPage}
+\item ugXdefaultsPage \ref{ugXdefaultsPage} on
+page~\pageref{ugXdefaultsPage}
+\end{itemize}
+\index{pages!ugGraphThreeDPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDPage}
+\index{ugGraphThreeDPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDPage}{7.2. Three-Dimensional Graphics}
+\beginscroll
+%
+The Axiom \threedim{} graphics package provides the ability to
+%
+\indent{4}
+\beginitems
+%
+\item[-] generate surfaces defined by a function of two real variables
+%
+\item[-] generate space curves and tubes defined by parametric equations
+%
+\item[-] generate surfaces defined by parametric equations
+\enditems
+\indent{0}
+These graphs can be modified by using various options, such as calculating
+points in the spherical coordinate system or changing the polygon grid size
+of a surface.
+
+\beginmenu
+    \menudownlink{
+{7.2.1. Plotting Three-Dimensional Functions of Two Variables}}
+{ugGraphThreeDPlotPage}
+    \menudownlink{
+{7.2.2. Plotting Three-Dimensional Parametric Space Curves}}
+{ugGraphThreeDParmPage}
+    \menudownlink{
+{7.2.3. Plotting Three-Dimensional Parametric Surfaces}}
+{ugGraphThreeDParPage}
+    \menudownlink{{7.2.4. Three-Dimensional Options}}{ugGraphThreeDOptionsPage}
+    \menudownlink{{7.2.5. The makeObject Command}}{ugGraphMakeObjectPage}
+    \menudownlink{
+{7.2.6. Building Three-Dimensional Objects From Primitives}}
+{ugGraphThreeDBuildPage}
+    \menudownlink{{7.2.7. Coordinate System Transformations}}{ugGraphCoordPage}
+    \menudownlink{{7.2.8. Three-Dimensional Clipping}}{ugGraphClipPage}
+    \menudownlink{{7.2.9. Three-Dimensional Control-Panel}}
+{ugGraphThreeDControlPage}
+    \menudownlink{{7.2.10. Operations for Three-Dimensional Graphics}}
+{ugGraphThreeDopsPage}
+    \menudownlink{{7.2.11. Customization using .Xdefaults}}{ugXdefaultsPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDPlotTitle}{Plotting Three-Dimensional Functions of Two Variables}
+\newcommand{\ugGraphThreeDPlotNumber}{7.2.1.}
+
+@
+\section{Plotting Three-Dimensional Functions of Two Variables}
+\label{ugGraphThreeDPlotPage}
+\begin{itemize}
+\item ugGraphThreeDOptionsPage \ref{ugGraphThreeDOptionsPage} on
+page~\pageref{ugGraphThreeDOptionsPage}
+\end{itemize}
+\index{pages!ugGraphThreeDPlotPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDPlotPage}
+\index{ugGraphThreeDPlotPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDPlotPage}
+{7.2.1. Plotting Three-Dimensional Functions of Two Variables}
+\beginscroll
+
+The simplest \threedim{} graph is that of a surface defined by a function
+of two variables, \axiom{z = f(x,y)}.
+
+%
+\beginImportant
+The general format for drawing a surface defined by a formula \axiom{f(x,y)}
+of two variables \axiom{x} and \axiom{y} is:
+%
+\centerline{{{\tt draw(f(x,y), x = a..b, y = c..d, {\it options})}}}
+where \axiom{a..b} and \axiom{c..d} define the range of \axiom{x}
+and \axiom{y}, and where {\it options} prescribes zero or more
+options as described in 
+\downlink{``\ugGraphThreeDOptionsTitle''}{ugGraphThreeDOptionsPage} 
+in Section \ugGraphThreeDOptionsNumber\ignore{ugGraphThreeDOptions}.
+An example of an option is \axiom{title == "Title of Graph".}
+An alternative format involving a function \axiom{f} is also
+available.
+\endImportant
+
+%
+\psXtc{
+The simplest way to plot a function of two variables is to use a formula.
+With formulas you always precede the range specifications with
+the variable name and an \spadSyntax{=} sign.
+}{
+\graphpaste{draw(cos(x*y),x=-3..3,y=-3..3)}
+}{
+\epsffile[0 0 295 295]{../ps/3d2vara.ps}
+}
+%
+\xtc{
+If you intend to use a function more than once,
+or it is long and complex, then first
+give its definition to Axiom.
+}{
+\spadpaste{f(x,y) == sin(x)*cos(y) \bound{f}}
+}
+%
+%
+\psXtc{
+To draw the function, just give its name and drop the variables
+from the range specifications.
+Axiom compiles your function for efficient computation
+of data for the graph.
+Notice that Axiom uses the text of your function as a
+default title.
+}{
+\graphpaste{draw(f,-\%pi..\%pi,-\%pi..\%pi) \free{f}}
+}{
+\epsffile[0 0 295 295]{../ps/3d2varb.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDParmTitle}{Plotting Three-Dimensional Parametric Space Curves}
+\newcommand{\ugGraphThreeDParmNumber}{7.2.2.}
+
+@
+\section{Plotting Three-Dimensional Parametric Space Curves}
+\label{ugGraphThreeDParmPage}
+\begin{itemize}
+\item ugGraphThreeDOptionsPage \ref{ugGraphThreeDOptionsPage} on
+page~\pageref{ugGraphThreeDOptionsPage}
+\end{itemize}
+\index{pages!ugGraphThreeDParmPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDParmPage}
+\index{ugGraphThreeDParmPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDParmPage}
+{7.2.2. Plotting Three-Dimensional Parametric Space Curves}
+\beginscroll
+
+A second kind of \threedim{} graph is a \threedim{} space curve
+defined by the parametric equations for \axiom{x(t)}, \axiom{y(t)},
+and \axiom{z(t)} as a function of an independent variable \axiom{t}.
+
+%
+\beginImportant
+The general format for drawing a \threedim{} space curve defined by
+parametric formulas \axiom{x = f(t)}, \axiom{y = g(t)}, and
+\axiom{z = h(t)} is:
+%
+\centerline{{{\tt draw(curve(f(t),g(t),h(t)), t = a..b, {\it options})}}}
+where \axiom{a..b} defines the range of the independent variable
+\axiom{t}, and where {\it options} prescribes zero or more options
+as described in 
+\downlink{``\ugGraphThreeDOptionsTitle''}{ugGraphThreeDOptionsPage} 
+in Section \ugGraphThreeDOptionsNumber\ignore{ugGraphThreeDOptions}.
+An example of an option is \axiom{title == "Title of Graph".}
+An alternative format involving functions \axiom{f}, \axiom{g} and
+\axiom{h} is also available.
+\endImportant
+
+%
+\psXtc{
+If you use explicit formulas to draw a space curve, always precede
+the range specification with the variable name and an
+\spadSyntax{=} sign.
+}{
+\graphpaste{draw(curve(5*cos(t), 5*sin(t),t), t=-12..12)}
+}{
+\epsffile[0 0 295 295]{../ps/3dpsca.ps}
+}
+%
+\xtc{
+Alternatively, you can draw space curves by referring to functions.
+}{
+\spadpaste{i1(t:DFLOAT):DFLOAT == sin(t)*cos(3*t/5) \bound{i1}}
+}
+\xtc{
+This is useful if the functions are to be used more than once \ldots
+}{
+\spadpaste{i2(t:DFLOAT):DFLOAT == cos(t)*cos(3*t/5) \bound{i2}}
+}
+\xtc{
+or if the functions are long and complex.
+}{
+\spadpaste{i3(t:DFLOAT):DFLOAT == cos(t)*sin(3*t/5) \bound{i3}}
+}
+%
+%
+\psXtc{
+Give the names of the functions and
+drop the variable name specification in the second argument.
+Again, Axiom supplies a default title.
+}{
+\graphpaste{draw(curve(i1,i2,i3),0..15*\%pi) \free{i1 i2 i3}}
+}{
+\epsffile[0 0 295 295]{../ps/3dpscb.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDParTitle}{Plotting Three-Dimensional Parametric Surfaces}
+\newcommand{\ugGraphThreeDParNumber}{7.2.3.}
+
+@
+\section{Plotting Three-Dimensional Parametric Surfaces}
+\label{ugGraphThreeDParPage}
+\begin{itemize}
+\item ugGraphThreeDOptionsPage \ref{ugGraphThreeDOptionsPage} on
+page~\pageref{ugGraphThreeDOptionsPage}
+\item ugGraphCoordPage \ref{ugGraphCoordPage} on
+page~\pageref{ugGraphCoordPage}
+\end{itemize}
+\index{pages!ugGraphThreeDParPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDParPage}
+\index{ugGraphThreeDParPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDParPage}
+{7.2.3. Plotting Three-Dimensional Parametric Surfaces}
+\beginscroll
+
+A third kind of \threedim{} graph is a surface defined by
+parametric equations for \axiom{x(u,v)}, \axiom{y(u,v)}, and
+\axiom{z(u,v)} of two independent variables \axiom{u} and \axiom{v}.
+
+%
+\beginImportant
+The general format for drawing a \threedim{} graph defined by
+parametric formulas \axiom{x = f(u,v)}, \axiom{y = g(u,v)},
+and \axiom{z = h(u,v)} is:
+%
+\centerline{{{\tt draw(surface(f(u,v),g(u,v),h(u,v)), u = a..b, v = c..d, {\it options})}}}
+where \axiom{a..b} and \axiom{c..d} define the range of the
+independent variables \axiom{u} and \axiom{v}, and where
+{\it options} prescribes zero or more options as described in
+\downlink{``\ugGraphThreeDOptionsTitle''}{ugGraphThreeDOptionsPage} 
+in Section \ugGraphThreeDOptionsNumber\ignore{ugGraphThreeDOptions}.
+An example of an option is \axiom{title == "Title of Graph".}
+An alternative format involving functions \axiom{f}, \axiom{g} and
+\axiom{h} is also available.
+\endImportant
+
+%
+\psXtc{
+This example draws a graph of a surface plotted using the
+parabolic cylindrical coordinate system option.
+The values of the functions supplied to \axiomFun{surface} are
+interpreted in coordinates as given by a {\tt coordinates} option,
+here as parabolic cylindrical coordinates (see
+\downlink{``\ugGraphCoordTitle''}{ugGraphCoordPage} 
+in Section \ugGraphCoordNumber\ignore{ugGraphCoord}).
+}{
+\graphpaste{draw(surface(u*cos(v), u*sin(v), v*cos(u)), u=-4..4, v=0..\%pi, coordinates== parabolicCylindrical)}
+}{
+\epsffile[0 0 295 295]{../ps/3dpsa.ps}
+}
+%
+Again, you can graph these parametric surfaces using functions,
+if the functions are long and complex.
+\xtc{
+Here we declare the types of arguments and values to be of type
+\axiomType{DoubleFloat}.
+}{
+\spadpaste{n1(u:DFLOAT,v:DFLOAT):DFLOAT == u*cos(v) \bound{n1}}
+}
+\xtc{
+As shown by previous examples, these declarations are necessary.
+}{
+\spadpaste{n2(u:DFLOAT,v:DFLOAT):DFLOAT == u*sin(v) \bound{n2}}
+}
+\xtc{
+In either case, Axiom compiles the functions
+when needed to graph a result.
+}{
+\spadpaste{n3(u:DFLOAT,v:DFLOAT):DFLOAT == u \bound{n3}}
+}
+\xtc{
+Without these declarations, you have to suffix floats
+with \axiom{@DFLOAT} to get a \axiomType{DoubleFloat} result.
+However, a call here with an unadorned float 
+produces a \axiomType{DoubleFloat}.
+}{
+\spadpaste{n3(0.5,1.0)\free{n3}}
+}
+%
+%
+\psXtc{
+Draw the surface by referencing the function names, this time
+choosing the toroidal coordinate system.
+}{
+\graphpaste{draw(surface(n1,n2,n3), 1..4, 1..2*\%pi, coordinates == toroidal(1\$DFLOAT)) \free{n1 n2 n3}}
+}{
+\epsffile[0 0 295 295]{../ps/3dpsb.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDOptionsTitle}{Three-Dimensional Options}
+\newcommand{\ugGraphThreeDOptionsNumber}{7.2.4.}
+
+@
+\section{Three-Dimensional Options}
+\label{ugGraphThreeDOptionsPage}
+\begin{itemize}
+\item ugGraphCoordPage \ref{ugGraphCoordPage} on
+page~\pageref{ugGraphCoordPage}
+\end{itemize}
+\index{pages!ugGraphThreeDOptionsPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDOptionsPage}
+\index{ugGraphThreeDOptionsPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDOptionsPage}{7.2.4. Three-Dimensional Options}
+\beginscroll
+
+The \axiomFun{draw} commands optionally take an optional list of options such
+as {\tt coordinates} as shown in the last example.
+Each option is given by the syntax: \axiom{name} {\tt ==} \axiom{value}.
+Here is a list of the available options in the order that they are
+described below:
+
+\table{ {title} {coordinates} {var1Steps} {style} {tubeRadius} {var2Steps}
+{colorFunction} {tubePoints} {space}}
+
+\psXtc{
+The option \axiom{title} gives your graph a title.
+}{
+\graphpaste{draw(cos(x*y),x=0..2*\%pi,y=0..\%pi,title == "Title of Graph") }
+}{
+\epsffile[0 0 295 295]{../ps/3doptttl.ps}
+}
+%
+\psXtc{
+The \axiom{style} determines which of four rendering algorithms is used for
+the graph.
+The choices are
+{\tt "wireMesh"}, {\tt "solid"}, {\tt "shade"}, and {\tt "smooth"}.
+}{
+\graphpaste{draw(cos(x*y),x=-3..3,y=-3..3, style=="smooth", title=="Smooth Option")}
+}{
+\epsffile[0 0 295 295]{../ps/3doptsty.ps}
+}
+%
+
+In all but the wire-mesh style, polygons in a surface or tube plot
+are normally colored in a graph according to their
+\axiom{z}-coordinate value.  Space curves are colored according to their
+parametric variable value.
+To change this, you can give a coloring function.
+The coloring function is sampled across the range of its arguments, then
+normalized onto the standard Axiom colormap.
+
+\xtc{
+A function of one variable  makes the color depend on the
+value of the parametric variable specified for a tube plot.
+}{
+\spadpaste{color1(t) == t \bound{colorFxn1}}
+}
+\psXtc{
+}{
+\graphpaste{draw(curve(sin(t), cos(t),0), t=0..2*\%pi, tubeRadius == .3, colorFunction == color1) \free{colorFxn1}}
+}{
+\epsffile[0 0 295 295]{../ps/3doptcf1.ps}
+}
+%
+\xtc{
+A function of two variables makes the color depend on the
+values of the independent variables.
+}{
+\spadpaste{color2(u,v) == u**2 - v**2 \bound{colorFxn2}}
+}
+\psXtc{
+Use the option {\tt colorFunction} for special coloring.
+}{
+\graphpaste{draw(cos(u*v), u=-3..3, v=-3..3, colorFunction == color2) \free{colorFxn2}}
+}{
+\epsffile[0 0 295 295]{../ps/3doptcf2.ps}
+}
+%
+\xtc{
+With a three variable function, the
+color also depends on the value of the function.
+}{
+\spadpaste{color3(x,y,fxy) == sin(x*fxy) + cos(y*fxy) \bound{colorFxn3}}
+}
+\psXtc{
+}{
+\graphpaste{draw(cos(x*y), x=-3..3, y=-3..3, colorFunction == color3) \free{colorFxn3}}
+}{
+\epsffile[0 0 295 295]{../ps/3doptcf3.ps}
+}
+%
+Normally the Cartesian coordinate system is used.
+To change this, use the {\tt coordinates} option.
+For details, see 
+\downlink{``\ugGraphCoordTitle''}{ugGraphCoordPage} 
+in Section \ugGraphCoordNumber\ignore{ugGraphCoord}.
+%
+%
+\xtc{
+}{
+\spadpaste{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 \bound{m}}
+}
+\psXtc{
+Use the spherical
+coordinate system.
+}{
+\graphpaste{draw(m, 0..2*\%pi,0..\%pi, coordinates == spherical, style=="shade") \free{m}}
+}{
+\epsffile[0 0 295 295]{../ps/3doptcrd.ps}
+}
+%
+Space curves may be displayed as tubes with polygonal cross sections.
+Two options, {\tt tubeRadius} and {\tt tubePoints},  control the size and
+shape of this cross section.
+%
+\psXtc{
+The {\tt tubeRadius} option specifies the radius of the tube that
+encircles the specified space curve.
+}{
+\graphpaste{draw(curve(sin(t),cos(t),0),t=0..2*\%pi, style=="shade", tubeRadius == .3)}
+}{
+\epsffile[0 0 295 295]{../ps/3doptrad.ps}
+}
+%
+%
+\psXtc{
+The {\tt tubePoints} option specifies the number of vertices
+defining the polygon that is used to create a tube around the
+specified space curve.
+The larger this number is, the more cylindrical the tube becomes.
+}{
+\graphpaste{draw(curve(sin(t), cos(t), 0), t=0..2*\%pi, style=="shade", tubeRadius == .25, tubePoints == 3)}
+}{
+\epsffile[0 0 295 295]{../ps/3doptpts.ps}
+}
+%
+%
+%
+\psXtc{
+Options \axiomFunFrom{var1Steps}{DrawOption} and
+\axiomFunFrom{var2Steps}{DrawOption} specify the number of intervals into
+which the grid defining a surface plot is subdivided with respect to the
+first and second parameters of the surface function(s).
+}{
+\graphpaste{draw(cos(x*y),x=-3..3,y=-3..3, style=="shade", var1Steps == 30, var2Steps == 30)}
+}{
+\epsffile[0 0 295 295]{../ps/3doptvb.ps}
+}
+%
+The {\tt space} option
+of a \axiomFun{draw} command lets you build multiple graphs in three space.
+To use this option, first create an empty three-space object,
+then use the {\tt space} option thereafter.
+There is no restriction as to the number or kinds
+of graphs that can be combined this way.
+\xtc{
+Create an empty three-space object.
+}{
+\spadpaste{s := create3Space()\$(ThreeSpace DFLOAT) \bound{s}}
+}
+%
+%
+\xtc{
+}{
+\spadpaste{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 \bound{m}}
+}
+\psXtc{
+Add a graph to this three-space object.
+The new graph destructively inserts the graph
+into \axiom{s}.
+}{
+\graphpaste{draw(m,0..\%pi,0..2*\%pi, coordinates == spherical, space == s) \free{s m}}
+}{
+\epsffile[0 0 295 295]{../ps/3dmult1a.ps}
+}
+%
+%
+\psXtc{
+Add a second graph to \axiom{s}.
+}{
+\graphpaste{v := draw(curve(1.5*sin(t), 1.5*cos(t),0), t=0..2*\%pi, tubeRadius == .25, space == s) \free{s} \bound{v}}
+}{
+\epsffile[0 0 295 295]{../ps/3dmult1b.ps}
+}
+%
+A three-space object can also be obtained from an existing \threedim{} viewport
+using the \axiomFunFrom{subspace}{ThreeSpace} command.
+You can then use \axiomFun{makeViewport3D} to create a viewport window.
+\xtc{
+Assign to \axiom{subsp} the three-space object in viewport \axiom{v}.
+}{
+\spadpaste{subsp := subspace v \free{v} \bound{su}}
+}
+\xtc{
+Reset the space component of \axiom{v} to the value of \axiom{subsp}.
+}{
+\spadpaste{subspace(v, subsp) \bound{sp} \free{su}}
+}
+\noOutputXtc{
+Create a viewport window from a three-space object.
+}{
+\graphpaste{makeViewport3D(subsp,"Graphs") \free{sp}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphMakeObjectTitle}{The makeObject Command}
+\newcommand{\ugGraphMakeObjectNumber}{7.2.5.}
+
+@
+\section{The makeObject Command}
+\label{ugGraphMakeObjectPage}
+\index{pages!ugGraphMakeObjectPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphMakeObjectPage}
+\index{ugGraphMakeObjectPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphMakeObjectPage}{7.2.5. The makeObject Command}
+\beginscroll
+
+An alternate way to create multiple graphs is to use
+\axiomFun{makeObject}.
+The \axiomFun{makeObject} command is similar to the \axiomFun{draw}
+command, except that it returns a three-space object rather than a
+\axiomType{ThreeDimensionalViewport}.
+In fact, \axiomFun{makeObject} is called by the \axiomFun{draw}
+command to create the \axiomType{ThreeSpace} then
+\axiomFunFrom{makeViewport3D}{ThreeDimensionalViewport} to create a
+viewport window.
+
+\xtc{
+}{
+\spadpaste{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 \bound{m}}
+}
+\noOutputXtc{
+Do the last example a new way.
+First use \axiomFun{makeObject} to
+create a three-space object \axiom{sph}.
+}{
+\spadpaste{sph := makeObject(m, 0..\%pi, 0..2*\%pi, coordinates==spherical)\bound{sph}\free{m}}
+}
+\noOutputXtc{
+Add a second object to \axiom{sph}.
+}{
+\spadpaste{makeObject(curve(1.5*sin(t), 1.5*cos(t), 0), t=0..2*\%pi, space == sph, tubeRadius == .25) \free{sph}\bound{v1}}
+}
+\noOutputXtc{
+Create and display a viewport
+containing \axiom{sph}.
+}{
+\graphpaste{makeViewport3D(sph,"Multiple Objects") \free{v1}}
+}
+
+Note that an undefined \axiomType{ThreeSpace} parameter declared in a
+\axiomFun{makeObject} or \axiomFun{draw} command results in an error.
+Use the \axiomFunFrom{create3Space}{ThreeSpace} function to define a
+\axiomType{ThreeSpace}, or obtain a \axiomType{ThreeSpace} that has been
+previously generated before including it in a command line.
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDBuildTitle}{Building Three-Dimensional Objects From Primitives}
+\newcommand{\ugGraphThreeDBuildNumber}{7.2.6.}
+
+@
+\section{Building Three-Dimensional Objects From Primitives}
+\label{ugGraphThreeDBuildPage}
+\index{pages!ugGraphThreeDBuildPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDBuildPage}
+\index{ugGraphThreeDBuildPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDBuildPage}
+{7.2.6. Building Three-Dimensional Objects From Primitives}
+\beginscroll
+
+Rather than using the \axiomFun{draw} and \axiomFun{makeObject} commands,
+you can create \threedim{} graphs from primitives.
+Operation \axiomFunFrom{create3Space}{ThreeSpace} creates a
+three-space object to which points, curves and polygons
+can be added using the operations from the \axiomType{ThreeSpace}
+domain.
+The resulting object can then be displayed in a viewport using
+\axiomFunFrom{makeViewport3D}{ThreeDimensionalViewport}.
+
+\xtc{
+Create the empty three-space object \axiom{space}.
+}{
+\spadpaste{space := create3Space()\$(ThreeSpace DFLOAT) \bound{space}}
+}
+
+Objects can be sent to this \axiom{space} using the operations
+exported by the \axiomType{ThreeSpace} domain.
+The following examples place curves into \axiom{space}.
+
+\xtc{
+Add these eight curves to the space.
+}{
+\spadpaste{closedCurve(space,[[0,30,20], [0,30,30], [0,40,30], [0,40,100], [0,30,100],[0,30,110], [0,60,110], [0,60,100], [0,50,100], [0,50,30], [0,60,30], [0,60,20]]) \bound{curve1} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[80,0,30], [80,0,100], [70,0,110], [40,0,110], [30,0,100], [30,0,90], [40,0,90], [40,0,95], [45,0,100], [65,0,100], [70,0,95], [70,0,35]]) \bound{curve2} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[70,0,35], [65,0,30], [45,0,30], [40,0,35], [40,0,60], [50,0,60], [50,0,70], [30,0,70], [30,0,30], [40,0,20], [70,0,20], [80,0,30]]) \bound{curve3} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[0,70,20], [0,70,110], [0,110,110], [0,120,100], [0,120,70], [0,115,65], [0,120,60], [0,120,30], [0,110,20], [0,80,20], [0,80,30], [0,80,20]]) \bound{curve4} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[0,105,30], [0,110,35], [0,110,55], [0,105,60], [0,80,60], [0,80,70], [0,105,70], [0,110,75], [0,110,95], [0,105,100], [0,80,100], [0,80,20], [0,80,30]]) \bound{curve5} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[140,0,20], [140,0,110], [130,0,110], [90,0,20], [101,0,20],[114,0,50], [130,0,50], [130,0,60], [119,0,60], [130,0,85], [130,0,20]]) \bound{curve6} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[0,140,20], [0,140,110], [0,150,110], [0,170,50], [0,190,110], [0,200,110], [0,200,20], [0,190,20], [0,190,75], [0,175,35], [0,165,35],[0,150,75], [0,150,20]]) \bound{curve7} \free{space}}
+}
+\xtc{
+}{
+\spadpaste{closedCurve(space,[[200,0,20], [200,0,110], [189,0,110], [160,0,45], [160,0,110], [150,0,110], [150,0,20], [161,0,20], [190,0,85], [190,0,20]]) \bound{curve8} \free{space}}
+}
+\psXtc{
+Create and display the viewport using \axiomFun{makeViewport3D}.
+Options may also be given but here are displayed as a list with values
+enclosed in parentheses.
+}{
+\graphpaste{makeViewport3D(space, title == "Letters") \free{space curve1 curve2 curve3 curve4 curve5 curve6 curve7 curve8}}
+}{
+\epsffile[0 0 295 295]{../ps/3dbuilda.ps}
+}
+
+\subsubsection{Cube Example}
+
+As a second example of the use of primitives, we generate a cube using a
+polygon mesh.
+It is important to use a consistent orientation of the polygons for
+correct generation of \threedim{} objects.
+
+\xtc{
+Again start with an empty three-space object.
+}{
+\spadpaste{spaceC := create3Space()\$(ThreeSpace DFLOAT) \bound{spaceC}}
+}
+\xtc{
+For convenience,
+give \axiomType{DoubleFloat} values \axiom{+1} and \axiom{-1} names.
+}{
+\spadpaste{x: DFLOAT := 1 \bound{x}}
+}
+\xtc{
+}{
+\spadpaste{y: DFLOAT := -1 \bound{y}}
+}
+\xtc{
+Define the vertices of the cube.
+}{
+\spadpaste{a := point [x,x,y,1::DFLOAT]\$(Point DFLOAT) \bound{a} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{b := point [y,x,y,4::DFLOAT]\$(Point DFLOAT) \bound{b} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{c := point [y,x,x,8::DFLOAT]\$(Point DFLOAT) \bound{c} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{d := point [x,x,x,12::DFLOAT]\$(Point DFLOAT) \bound{d} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{e := point [x,y,y,16::DFLOAT]\$(Point DFLOAT) \bound{e} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{f := point [y,y,y,20::DFLOAT]\$(Point DFLOAT) \bound{f} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{g := point [y,y,x,24::DFLOAT]\$(Point DFLOAT) \bound{g} \free{x y}}
+}
+\xtc{
+}{
+\spadpaste{h := point [x,y,x,27::DFLOAT]\$(Point DFLOAT) \bound{h} \free{x y}}
+}
+\xtc{
+Add the faces of the cube as polygons to the space using a
+consistent orientation.
+}{
+\spadpaste{polygon(spaceC,[d,c,g,h]) \free{d c g h spaceC} \bound{pol1}}
+}
+\xtc{
+}{
+\spadpaste{polygon(spaceC,[d,h,e,a]) \free{d h e a spaceC} \bound{pol2}}
+}
+\xtc{
+}{
+\spadpaste{polygon(spaceC,[c,d,a,b]) \free{c d a b spaceC} \bound{pol3}}
+}
+\xtc{
+}{
+\spadpaste{polygon(spaceC,[g,c,b,f]) \free{g c b f spaceC} \bound{pol4}}
+}
+\xtc{
+}{
+\spadpaste{polygon(spaceC,[h,g,f,e]) \free{h g f e spaceC} \bound{pol5}}
+}
+\xtc{
+}{
+\spadpaste{polygon(spaceC,[e,f,b,a]) \free{e f b a spaceC} \bound{pol6}}
+}
+\psXtc{
+Create and display the viewport.
+}{
+\graphpaste{makeViewport3D(spaceC, title == "Cube") \free{pol1 pol2 pol3 pol4 pol5 pol6}}
+}{
+\epsffile[0 0 295 295]{../ps/3dbuildb.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphCoordTitle}{Coordinate System Transformations}
+\newcommand{\ugGraphCoordNumber}{7.2.7.}
+
+@
+\section{Coordinate System Transformations}
+\label{ugGraphCoordPage}
+\index{pages!ugGraphCoordPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphCoordPage}
+\index{ugGraphCoordPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphCoordPage}{7.2.7. Coordinate System Transformations}
+\beginscroll
+
+The \axiomType{CoordinateSystems} package provides coordinate transformation
+functions that map a given data point from the coordinate system specified
+into the Cartesian coordinate system.
+The default coordinate system, given a triplet \axiom{(f(u,v), u, v)}, assumes
+that \axiom{z = f(u, v)}, \axiom{x = u} and \axiom{y = v},
+that is, reads the coordinates in \axiom{(z, x, y)} order.
+
+\xtc{
+}{
+\spadpaste{m(u:DFLOAT,v:DFLOAT):DFLOAT == u**2 \bound{m}}
+}
+%
+\psXtc{
+Graph plotted in default coordinate system.
+}{
+\graphpaste{draw(m,0..3,0..5) \free{m}}
+}{
+\epsffile[0 0 295 295]{../ps/defcoord.ps}
+}
+
+The \axiom{z} coordinate comes first since the first argument of
+the \axiomFun{draw} command gives its values.
+In general, the coordinate systems Axiom provides, or any
+that you make up, must provide a map to an \axiom{(x, y, z)} triplet in
+order to be compatible with the
+\axiomFunFrom{coordinates}{DrawOption} \axiomType{DrawOption}.
+Here is an example.
+
+\xtc{
+Define the identity function.
+}{
+\spadpaste{cartesian(point:Point DFLOAT):Point DFLOAT == point \bound{cart}}
+}
+\psXtc{
+Pass \axiom{cartesian} as the \axiomFunFrom{coordinates}{DrawOption}
+parameter to the \axiomFun{draw} command.
+}{
+\graphpaste{draw(m,0..3,0..5,coordinates==cartesian) \free{m cart}}
+}{
+\epsffile[0 0 295 295]{../ps/cartcoord.ps}
+}
+%
+
+What happened?
+The option {\tt coordinates == cartesian} directs Axiom to
+treat the dependent variable \axiom{m} defined by
+\texht{$m=u^2$}{m=u**2} as the \axiom{x} coordinate.
+Thus the triplet of values \axiom{(m, u, v)} is transformed to
+coordinates \axiom{(x, y, z)} and so we get the graph of
+\texht{$x=y^2$}{x=y**2}.
+
+Here is another example.
+The \axiomFunFrom{cylindrical}{CoordinateSystems} transform takes
+input of the form \axiom{(w,u,v)}, interprets it in the order
+\texht{($r$,$\theta$,$z$)}{(\axiom{r}, \axiom{theta}, \axiom{z})}
+and maps it to the Cartesian coordinates
+\texht{$x=r\cos(\theta)$, $y=r\sin(\theta)$, $z=z$}
+{\axiom{x = r * cos(theta)}, \axiom{y = r * sin(theta)}, \axiom{z = z}}
+in which
+\texht{$r$}{\axiom{r}} is the radius,
+\texht{$\theta$}{\axiom{theta}} is the angle and
+\texht{$z$}{\axiom{z}} is the z-coordinate.
+\xtc{
+An example using the \axiomFunFrom{cylindrical}{CoordinateSystems}
+coordinates for the constant \axiom{r = 3}.
+}{
+\spadpaste{f(u:DFLOAT,v:DFLOAT):DFLOAT == 3 \bound{f}}
+}
+\psXtc{
+Graph plotted in cylindrical coordinates.
+}{
+\graphpaste{draw(f,0..\%pi,0..6,coordinates==cylindrical) \free{f}}
+}{
+\epsffile[0 0 295 295]{../ps/cylcoord.ps}
+}
+
+Suppose you would like to specify \smath{z} as a function of
+\smath{r} and \texht{$\theta$}{\axiom{theta}} instead of just
+\smath{r}?
+Well, you still can use the \axiomFun{cylindrical} Axiom
+transformation but we have to reorder the triplet before
+passing it to the transformation.
+
+\xtc{
+First, let's create a point to
+work with and call it \axiom{pt} with some color \axiom{col}.
+}{
+\spadpaste{col := 5 \bound{c}}
+}
+\xtc{
+}{
+\spadpaste{pt := point[1,2,3,col]\$(Point DFLOAT) \free{c} \bound{pt}}
+}
+The reordering you want is
+\texht{$(z,r, \theta)$}{\axiom{(z,r,theta)}} to
+\texht{$(r, \theta,z)$}{\axiom{(r,theta,z)}}
+so that the first element is moved to the third element, while the second
+and third elements move forward and the color element does not change.
+\xtc{
+Define a function \userfun{reorder} to reorder the point elements.
+}{
+\spadpaste{reorder(p:Point DFLOAT):Point DFLOAT == point[p.2, p.3, p.1, p.4] \bound{freo}}
+}
+\xtc{
+The function moves the second and third elements
+forward but the color does not change.
+}{
+\spadpaste{reorder pt \free{pt freo}}
+}
+\xtc{
+The function \userfun{newmap} converts our reordered version of
+the cylindrical coordinate system to the standard
+\texht{$(x,y,z)$}{\axiom{(x,y,z)}} Cartesian system.
+}{
+\spadpaste{newmap(pt:Point DFLOAT):Point DFLOAT == cylindrical(reorder pt) \free{freo} \bound{fnewmap}}
+}
+\xtc{
+}{
+\spadpaste{newmap pt \free{fnewmap pt} \bound{new}}
+}
+%
+\psXtc{
+Graph the same function \axiom{f} using the coordinate mapping of the function
+\axiom{newmap}, so it is now interpreted as
+\texht{$z=3$}{\axiom{z = 3}}:
+}{
+\graphpaste{draw(f,0..3,0..2*\%pi,coordinates==newmap) \free{f new}}
+}{
+\epsffile[0 0 295 295]{../ps/newmap.ps}
+}
+
+{\texht{\sloppy}{}
+The \axiomType{CoordinateSystems} package exports the following
+operations:
+\axiomFun{bipolar},
+\axiomFun{bipolarCylindrical},
+\axiomFun{cartesian},
+\axiomFun{conical},
+\axiomFun{cylindrical},
+\axiomFun{elliptic},
+\axiomFun{ellipticCylindrical},
+\axiomFun{oblateSpheroidal},
+\axiomFun{parabolic},
+\axiomFun{parabolicCylindrical},
+\axiomFun{paraboloidal},
+\axiomFun{polar},
+\axiomFun{prolateSpheroidal},
+\axiomFun{spherical}, and
+\axiomFun{toroidal}.
+Use \Browse{} or the \spadcmd{)show} system command
+to get more information.
+
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphClipTitle}{Three-Dimensional Clipping}
+\newcommand{\ugGraphClipNumber}{7.2.8.}
+
+@
+\section{Three-Dimensional Clipping}
+\label{ugGraphClipPage}
+\index{pages!ugGraphClipPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphClipPage}
+\index{ugGraphClipPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphClipPage}{7.2.8. Three-Dimensional Clipping}
+\beginscroll
+
+A \threedim{} graph can be explicitly clipped within the \axiomFun{draw}
+command by indicating a minimum and maximum threshold for the
+given function definition.
+These thresholds can be defined using the Axiom \axiomFun{min}
+and \axiomFun{max} functions.
+\xtc{
+}{
+\begin{spadsrc}[\bound{g}]
+gamma(x,y) ==
+  g := Gamma complex(x,y)
+  point [x, y, max( min(real g, 4), -4), argument g]
+\end{spadsrc}
+}
+\psXtc{
+Here is an example that clips
+the gamma function in order to eliminate the extreme divergence it creates.
+}{
+\graphpaste{draw(gamma,-\%pi..\%pi,-\%pi..\%pi,var1Steps==50,var2Steps==50) \free{g}}
+}{
+\epsffile[0 0 295 295]{../ps/clipgamma.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDControlTitle}{Three-Dimensional Control-Panel}
+\newcommand{\ugGraphThreeDControlNumber}{7.2.9.}
+
+@
+\section{Three-Dimensional Control-Panel}
+\label{ugGraphThreeDControlPage}
+\index{pages!ugGraphThreeDControlPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDControlPage}
+\index{ugGraphThreeDControlPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDControlPage}{7.2.9. Three-Dimensional Control-Panel}
+\beginscroll
+Once you have created a viewport, move your mouse to the viewport
+and click with your left mouse button.
+This displays a control-panel on the side of the viewport
+that is closest to where you clicked.
+
+
+\subsubsection{Transformations}
+
+We recommend you first select the {\bf Bounds} button while
+executing transformations since the bounding box displayed
+indicates the object's position as it changes.
+%
+\indent{0}
+\beginitems
+%
+\item[Rotate:]  A rotation transformation occurs by clicking the mouse
+within the {\bf Rotate} window in the upper left corner of the
+control-panel.
+The rotation is computed in spherical coordinates, using the
+horizontal mouse position to increment or decrement the value of
+the longitudinal angle \texht{$\theta$}{\axiom{theta}} within the
+range of 0 to \texht{2$\pi$}{2*pi} and the vertical mouse position
+to increment or decrement the value of the latitudinal angle
+\texht{$\phi$}{\axiom{phi}} within the range of \texht{-$\pi$}{pi}
+to \texht{$\pi$}{pi}.
+The active mode of rotation is displayed in green on a color
+monitor or in clear text on a black and white monitor, while the
+inactive mode is displayed in red for color display or a mottled
+pattern for black and white.
+%
+\indent{0}
+\beginitems
+%
+\item[origin:]  The {\bf origin} button indicates that the
+rotation is to occur with respect to the origin of the viewing space, that is
+indicated by the axes.
+%
+\item[object:]  The {\bf object} button indicates that the
+rotation is to occur with respect to the center of volume of the object,
+independent of the axes' origin position.
+\enditems
+\indent{0}
+%
+\item[Scale:]  A scaling transformation occurs by clicking the mouse
+within the {\bf Scale} window in the upper center of the
+control-panel, containing a zoom arrow.
+The axes along which the scaling is to occur are indicated by
+selecting the appropriate button above the zoom arrow window.
+The selected axes are displayed in green on a color monitor or in
+clear text on a black and white monitor, while the unselected axes
+are displayed in red for a color display or a mottled pattern for
+black and white.
+%
+\indent{0}
+\beginitems
+%
+\item[uniform:]  Uniform scaling along the {\tt x}, {\tt y}
+and {\tt z} axes occurs when all the axes buttons are selected.
+%
+\item[non-uniform:]  If any of the axes buttons are
+not selected, non-uniform scaling occurs, that is, scaling occurs only in the
+direction of the axes that are selected.
+\enditems
+\indent{0}
+%
+\item[Translate:]  Translation occurs by indicating with the mouse in the
+{\bf Translate} window the direction you want the graph to move.
+This window is located in the upper right corner of the
+control-panel and contains a potentiometer with crossed arrows
+pointing up, down, left and right.
+Along the top of the {\bf Translate} window are three buttons
+({\bf XY},
+{\bf XZ}, and {\bf YZ}) indicating the three orthographic projection planes.
+Each orientates the group as a view into that plane.
+Any translation of the graph occurs only along this plane.
+\enditems
+\indent{0}
+
+\subsubsection{Messages}
+
+The window directly below the potentiometer windows for transformations is
+used to display system messages relating to the viewport, the control-panel
+and the current graph displaying status.
+
+\subsubsection{Colormap}
+
+Directly below the message window is the colormap range indicator
+window.
+The Axiom Colormap shows a sampling of the spectrum from
+which hues can be drawn to represent the colors of a surface.
+The Colormap is composed of five shades for each of the hues along
+this spectrum.
+By moving the markers above and below the Colormap, the range of
+hues that are used to color the existing surface are set.
+The bottom marker shows the hue for the low end of the color range
+and the top marker shows the hue for the upper end of the range.
+Setting the bottom and top markers at the same hue results in
+monochromatic smooth shading of the graph when {\bf Smooth} mode is selected.
+At each end of the Colormap are {\bf +} and {\bf -} buttons.
+When clicked on, these increment or decrement the top or bottom
+marker.
+
+\subsubsection{Buttons}
+
+Below the Colormap window and to the left are located various
+buttons that determine the characteristics of a graph.
+The buttons along the bottom and right hand side all have special
+meanings; the remaining buttons in the first row indicate the mode
+or style used to display the graph.
+The second row are toggles that turn on or off a property of the
+graph.
+On a color monitor, the property is on if green (clear text, on a
+monochrome monitor) and off if red (mottled pattern, on a
+monochrome monitor).
+Here is a list of their functions.
+%
+\indent{0}
+\beginitems
+%
+\item[Wire] displays surface and tube plots as a
+wireframe image in a single color (blue) with no hidden surfaces removed,
+or displays space curve plots in colors based upon their parametric variables.
+This is the fastest mode for displaying a graph.
+This is very useful when you
+want to find a good orientation of your graph.
+%
+\item[Solid] displays the graph with hidden
+surfaces removed, drawing each polygon beginning with the furthest
+from the viewer.
+The edges of the polygons are displayed in the hues specified by
+the range in the Colormap window.
+%
+\item[Shade] displays the graph with hidden
+surfaces removed and with the polygons shaded, drawing each
+polygon beginning with the furthest from the viewer.
+Polygons are shaded in the hues specified by the range in the
+Colormap window using the Phong illumination model.
+%
+\item[Smooth] displays the graph using a
+renderer that computes the graph one line at a time.
+The location and color of the graph at each visible point on the
+screen are determined and displayed using the Phong illumination
+model.
+Smooth shading is done in one of two ways, depending on the range
+selected in the colormap window and the number of colors available
+from the hardware and/or window manager.
+When the top and bottom markers of the colormap range are set to
+different hues, the graph is rendered by dithering between the
+transitions in color hue.
+When the top and bottom markers of the colormap range are set to
+the same hue, the graph is rendered using the Phong smooth shading
+model.
+However, if enough colors cannot be allocated for this purpose,
+the renderer reverts to the color dithering method until a
+sufficient color supply is available.
+For this reason, it may not be possible to render multiple Phong
+smooth shaded graphs at the same time on some systems.
+%
+\item[Bounds] encloses the entire volume of the
+viewgraph within a bounding box, or removes the box if previously selected.
+The region that encloses the entire volume of the viewport graph is displayed.
+%
+\item[Axes] displays Cartesian
+coordinate axes of the space, or turns them off if previously selected.
+%
+\item[Outline] causes
+quadrilateral polygons forming the graph surface to be outlined in black when
+the graph is displayed in {\bf Shade} mode.
+%
+\item[BW] converts a color viewport to black and white, or vice-versa.
+When this button is selected the
+control-panel and viewport switch to an immutable colormap composed of a range
+of grey scale patterns or tiles that are used wherever shading is necessary.
+%
+\item[Light] takes you to a control-panel described below.
+%
+\item[ViewVolume] takes you to another control-panel as described below.
+%
+\item[Save] creates a menu of the possible file types that can
+be written using the control-panel.
+The {\bf Exit} button leaves the save menu.
+The {\bf Pixmap} button writes an Axiom pixmap of
+the current viewport contents.  The file is called {\bf axiom3D.pixmap} and is
+located in the directory from which Axiom or {\bf viewalone} was
+started.
+The {\bf PS} button writes the current viewport contents to
+PostScript output rather than to the viewport window.
+By default the file is called {\bf axiom3D.ps}; however, if a file
+name is specified in the user's {\bf .Xdefaults} file it is
+used.
+The file is placed in the directory from which the Axiom or
+{\bf viewalone} session was begun.
+See also the \axiomFunFrom{write}{ThreeDimensionalViewport}
+function.
+%
+\item[Reset] returns the object transformation
+characteristics back to their initial states.
+%
+\item[Hide] causes the control-panel for the
+corresponding viewport to disappear from the screen.
+%
+\item[Quit]  queries whether the current viewport
+session should be terminated.
+\enditems
+\indent{0}
+
+\subsubsection{Light}
+
+%
+%>>>\begin{texonly}
+%
+%>>>\begin{figure}[htbp]
+%>>>\begin{picture}(183,252)(-125,0)
+%>>>\special{psfile=../ps/3dlight.ps}
+%>>>\end{picture}
+%>>>\caption{Three-Dimensional Lighting Panel.}
+%>>>\end{figure}
+%>>>\end{texonly}
+%
+
+The {\bf Light} button changes the control-panel into the
+{\bf Lighting Control-Panel}.  At the top of this panel, the three axes
+are shown with the same orientation as the object.  A light vector from
+the origin of the axes shows the current position of the light source
+relative to the object.  At the bottom of the panel is an {\bf Abort}
+button that cancels any changes to the lighting that were made, and a
+{\bf Return} button that carries out the current set of lighting changes
+on the graph.
+%
+\indent{0}
+\beginitems
+%
+\item[XY:]  The {\bf XY} lighting axes window is below the
+{\bf Lighting Control-Panel} title and to the left.
+This changes the light vector within the {\bf XY} view plane.
+%
+\item[Z:]  The {\bf Z} lighting axis window is below the
+{\bf Lighting Control-Panel} title and in the center.  This
+changes the {\bf Z}
+location of the light vector.
+%
+\item[Intensity:]
+Below the {\bf Lighting Control-Panel} title
+and to the right is the light intensity meter.
+Moving the intensity indicator down decreases the amount of
+light emitted from the light source.
+When the indicator is at the top of the meter the light source is
+emitting at 100\% intensity.
+At the bottom of the meter the light source is emitting at a level
+slightly above ambient lighting.
+\enditems
+\indent{0}
+
+\subsubsection{View Volume}
+
+The {\bf View Volume} button changes the control-panel into
+the {\bf Viewing Volume Panel}.
+At the bottom of the viewing panel is an {\bf Abort} button that
+cancels any changes to the viewing volume that were made and a
+{\it Return} button that carries out the current set of
+viewing changes to the graph.
+%
+%>>>\begin{texonly}
+%
+%>>>\begin{figure}[htbp]
+%>>>\begin{picture}(183,252)(-125,0)
+%>>>\special{psfile=../ps/3dvolume.ps}
+%>>>\end{picture}
+%>>>\caption{Three-Dimensional Volume Panel.}
+%>>>\end{figure}
+%>>>\end{texonly}
+%
+\indent{0}
+\beginitems
+%
+\item[Eye Reference:]  At the top of this panel is the
+{\bf Eye Reference} window.
+It shows a planar projection of the viewing pyramid from the eye
+of the viewer relative to the location of the object.
+This has a bounding region represented by the rectangle on the
+left.
+Below the object rectangle is the {\bf Hither} window.
+By moving the slider in this window the hither clipping plane sets
+the front of the view volume.
+As a result of this depth clipping all points of the object closer
+to the eye than this hither plane are not shown.
+The {\bf Eye Distance} slider to the right of the {\bf Hither}
+slider is used to change the degree of perspective in the image.
+%
+\item[Clip Volume:]  The {\bf Clip Volume} window is at the
+bottom of the {\bf Viewing Volume Panel}.
+On the right is a {\bf Settings} menu.
+In this menu are buttons to select viewing attributes.
+Selecting the {\bf Perspective} button computes the image using
+perspective projection.
+The {\bf Show Region} button indicates whether the clipping region
+of the
+volume is to be drawn in the viewport and the {\bf Clipping On}
+button shows whether the view volume clipping is to be in effect
+when the image
+is drawn.
+The left side of the {\bf Clip Volume} window shows the clipping
+boundary of the graph.
+Moving the knobs along the {\bf X}, {\bf Y}, and {\bf Z} sliders
+adjusts the volume of the clipping region accordingly.
+\enditems
+\indent{0}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugGraphThreeDopsTitle}{Operations for Three-Dimensional Graphics}
+\newcommand{\ugGraphThreeDopsNumber}{7.2.10.}
+
+@
+\section{Operations for Three-Dimensional Graphics}
+\label{ugGraphThreeDopsPage}
+\index{pages!ugGraphThreeDopsPage!ug07.ht}
+\index{ug07.ht!pages!ugGraphThreeDopsPage}
+\index{ugGraphThreeDopsPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugGraphThreeDopsPage}
+{7.2.10. Operations for Three-Dimensional Graphics}
+\beginscroll
+
+Here is a summary of useful Axiom operations for \threedim{}
+graphics.
+Each operation name is followed by a list of arguments.
+Each argument is written as a variable informally named according
+to the type of the argument (for example, {\it integer}).
+If appropriate, a default value for an argument is given in
+parentheses immediately following the name.
+
+%
+\texht{\bgroup\hbadness = 10001\sloppy}{}
+\indent{0}
+\beginitems
+%
+\item[\axiomFun{adaptive3D?}]\funArgs{}
+tests whether space curves are to be plotted
+according to the
+adaptive refinement algorithm.
+
+%
+\item[\axiomFun{axes}]\funArgs{viewport, string\argDef{"on"}}
+turns the axes on and off.
+
+%
+\item[\axiomFun{close}]\funArgs{viewport}
+closes the viewport.
+
+%
+\item[\axiomFun{colorDef}]\funArgs{viewport,
+\subscriptIt{color}{1}\argDef{1}, \subscriptIt{color}{2}\argDef{27}}
+sets the colormap
+range to be from
+\subscriptIt{color}{1} to \subscriptIt{color}{2}.
+
+%
+\item[\axiomFun{controlPanel}]\funArgs{viewport, string\argDef{"off"}}
+declares whether the
+control-panel for the viewport is to be displayed or not.
+
+%
+\item[\axiomFun{diagonals}]\funArgs{viewport, string\argDef{"off"}}
+declares whether the
+polygon outline includes the diagonals or not.
+
+%
+\item[\axiomFun{drawStyle}]\funArgs{viewport, style}
+selects which of four drawing styles
+are used: {\tt "wireMesh", "solid", "shade",} or {\tt "smooth".}
+
+%
+\item[\axiomFun{eyeDistance}]\funArgs{viewport,float\argDef{500}}
+sets the distance of the eye from the origin of the object
+for use in the \axiomFunFrom{perspective}{ThreeDimensionalViewport}.
+
+%
+\item[\axiomFun{key}]\funArgs{viewport}
+returns the operating
+system process ID number for the viewport.
+
+%
+\item[\axiomFun{lighting}]\funArgs{viewport,
+\subscriptText{float}{x}\argDef{-0.5},
+\subscriptText{float}{y}\argDef{0.5}, \subscriptText{float}{z}\argDef{0.5}}
+sets the Cartesian
+coordinates of the light source.
+
+%
+\item[\axiomFun{modifyPointData}]\funArgs{viewport,integer,point}
+replaces the coordinates of the point with
+the index {\it integer} with {\it point}.
+
+%
+\item[\axiomFun{move}]\funArgs{viewport,
+\subscriptText{integer}{x}\argDef{viewPosDefault},
+\subscriptText{integer}{y}\argDef{viewPosDefault}}
+moves the upper
+left-hand corner of the viewport to screen position
+\allowbreak
+({\small \subscriptText{integer}{x}, \subscriptText{integer}{y}}).
+
+%
+\item[\axiomFun{options}]\funArgs{viewport}
+returns a list of all current draw options.
+
+%
+\item[\axiomFun{outlineRender}]\funArgs{viewport, string\argDef{"off"}}
+turns polygon outlining
+off or on when drawing in {\tt "shade"} mode.
+
+%
+\item[\axiomFun{perspective}]\funArgs{viewport, string\argDef{"on"}}
+turns perspective
+viewing on and off.
+
+%
+\item[\axiomFun{reset}]\funArgs{viewport}
+resets the attributes of a viewport to their
+initial settings.
+
+%
+\item[\axiomFun{resize}]\funArgs{viewport,
+\subscriptText{integer}{width} \argDef{viewSizeDefault},
+\subscriptText{integer}{height} \argDef{viewSizeDefault}}
+resets the width and height
+values for a viewport.
+
+%
+\item[\axiomFun{rotate}]\funArgs{viewport,
+\subscriptText{number}{\texht{$\theta$}{\axiom{theta}}}\argDef{viewThetaDefault},
+\subscriptText{number}{\texht{$\phi$}{\axiom{phi}}}\argDef{viewPhiDefault}}
+rotates the viewport by rotation angles for longitude
+({\it \texht{$\theta$}{\axiom{theta}}}) and
+latitude ({\it \texht{$\phi$}{\axiom{phi}}}).
+Angles designate radians if given as floats, or degrees if given
+as integers.
+
+%
+\item[\axiomFun{setAdaptive3D}]\funArgs{boolean\argDef{true}}
+sets whether space curves are to be plotted
+according to the adaptive
+refinement algorithm.
+
+%
+\item[\axiomFun{setMaxPoints3D}]\funArgs{integer\argDef{1000}}
+ sets the default maximum number of possible
+points to be used when constructing a \threedim{} space curve.
+
+%
+\item[\axiomFun{setMinPoints3D}]\funArgs{integer\argDef{49}}
+sets the default minimum number of possible
+points to be used when constructing a \threedim{} space curve.
+
+%
+\item[\axiomFun{setScreenResolution3D}]\funArgs{integer\argDef{500}}
+sets the default screen resolution constant
+used in setting the computation limit of adaptively
+generated \threedim{} space curve plots.
+
+%
+\item[\axiomFun{showRegion}]\funArgs{viewport, string\argDef{"off"}}
+declares whether the bounding
+box of a graph is shown or not.
+%
+\item[\axiomFun{subspace}]\funArgs{viewport}
+returns the space component.
+%
+\item[\axiomFun{subspace}]\funArgs{viewport, subspace}
+resets the space component
+to {\it subspace}.
+
+%
+\item[\axiomFun{title}]\funArgs{viewport, string}
+gives the viewport the
+title {\it string}.
+
+%
+\item[\axiomFun{translate}]\funArgs{viewport,
+\subscriptText{float}{x}\argDef{viewDeltaXDefault},
+\subscriptText{float}{y}\argDef{viewDeltaYDefault}}
+translates
+the object horizontally and vertically relative to the center of the viewport.
+
+%
+\item[\axiomFun{intensity}]\funArgs{viewport,float\argDef{1.0}}
+resets the intensity {\it I} of the light source,
+\texht{$0 \le I \le 1.$}{{\it 0 \le I \le 1}.}
+
+%
+\item[\axiomFun{tubePointsDefault}]\funArgs{\optArg{integer\argDef{6}}}
+sets or indicates the default number of
+vertices defining the polygon that is used to create a tube around
+a space curve.
+
+%
+\item[\axiomFun{tubeRadiusDefault}]\funArgs{\optArg{float\argDef{0.5}}}
+sets or indicates the default radius of
+the tube that encircles a space curve.
+
+%
+\item[\axiomFun{var1StepsDefault}]\funArgs{\optArg{integer\argDef{27}}}
+sets or indicates the default number of
+increments into which the grid defining a surface plot is subdivided with
+respect to the first parameter declared in the surface function.
+
+%
+\item[\axiomFun{var2StepsDefault}]\funArgs{\optArg{integer\argDef{27}}}
+sets or indicates the default number of
+increments into which the grid defining a surface plot is subdivided with
+respect to the second parameter declared in the surface function.
+
+%
+\item[\axiomFun{viewDefaults}]\funArgs{{\tt [}\subscriptText{integer}{%
+point}, \subscriptText{integer}{line}, \subscriptText{integer}{axes},
+\subscriptText{integer}{units}, \subscriptText{float}{point},
+\allowbreak\subscriptText{list}{position},
+\subscriptText{list}{size}{\tt ]}}
+resets the default settings for the
+point color, line color, axes color, units color, point size,
+viewport upper left-hand corner position, and the viewport size.
+
+%
+\item[\axiomFun{viewDeltaXDefault}]\funArgs{\optArg{float\argDef{0}}}
+resets the default horizontal offset
+from the center of the viewport, or returns the current default offset if no argument is given.
+
+%
+\item[\axiomFun{viewDeltaYDefault}]\funArgs{\optArg{float\argDef{0}}}
+resets the default vertical offset
+from the center of the viewport, or returns the current default offset if no argument is given.
+
+%
+\item[\axiomFun{viewPhiDefault}]\funArgs{\optArg{float\argDef{-\texht{$\pi$}{{\it pi}}/4}}}
+resets the default latitudinal view angle,
+or returns the current default angle if no argument is given.
+\texht{$\phi$}{{\it phi}} is set to this value.
+
+%
+\item[\axiomFun{viewpoint}]\funArgs{viewport, \subscriptText{float}{x},
+\subscriptText{float}{y}, \subscriptText{float}{z}}
+sets the viewing position in Cartesian coordinates.
+
+%
+\item[\axiomFun{viewpoint}]\funArgs{viewport,
+\subscriptText{float}{\texht{$\theta$}{\axiom{theta}}},
+\subscriptText{Float}{\texht{$\phi$}{\axiom{phi}}}}
+sets the viewing position in spherical coordinates.
+
+%
+\item[\axiomFun{viewpoint}]\funArgs{viewport,
+\subscriptText{Float}{\texht{$\theta$}{\axiom{theta}}},
+\subscriptText{Float}{\texht{$\phi$}{\axiom{phi}}},
+\subscriptText{Float}{scaleFactor},
+\subscriptText{Float}{xOffset}, \subscriptText{Float}{yOffset}}
+sets the viewing position in spherical coordinates,
+the scale factor, and offsets.
+\texht{$\theta$}{{\it theta}} (longitude) and
+\texht{$\phi$}{{\it phi}} (latitude) are in radians.
+
+%
+\item[\axiomFun{viewPosDefault}]\funArgs{\optArg{list\argDef{[0,0]}}}
+sets or indicates the position of the upper
+left-hand corner of a \twodim{} viewport, relative to the display root
+window (the upper left-hand corner of the display is \axiom{[0, 0]}).
+
+%
+\item[\axiomFun{viewSizeDefault}]\funArgs{\optArg{list\argDef{[400,400]}}}
+sets or indicates the width and height dimensions
+of a viewport.
+
+%
+\item[\axiomFun{viewThetaDefault}]\funArgs{\optArg{float\argDef{\texht{$\pi$}{{\it pi}}/4}}}
+resets the default longitudinal view angle,
+or returns the current default angle if no argument is given.
+When a parameter is specified, the default longitudinal view angle
+\texht{$\theta$}{{\it theta}} is set to this value.
+
+%
+\item[\axiomFun{viewWriteAvailable}]\funArgs{\optArg{list\argDef{["pixmap",
+"bitmap", "postscript", "image"}}}
+indicates the possible file types
+that can be created with the \axiomFunFrom{write}{ThreeDimensionalViewport} function.
+
+%
+\item[\axiomFun{viewWriteDefault}]\funArgs{\optArg{list\argDef{[]}}}
+sets or indicates the default types of files
+that are created in addition to the {\bf data} file when a
+\axiomFunFrom{write}{ThreeDimensionalViewport} command
+is executed on a viewport.
+
+%
+\item[\axiomFun{viewScaleDefault}]\funArgs{\optArg{float}}
+sets the default scaling factor, or returns
+the current factor if no argument is given.
+
+%
+\item[\axiomFun{write}]\funArgs{viewport, directory, \optArg{option}}
+writes the file {\bf data} for {\it viewport}
+in the directory {\it directory}.
+An optional third argument specifies a file type (one of {\tt
+pixmap}, {\tt bitmap}, {\tt postscript}, or {\tt image}), or a
+list of file types.
+An additional file is written for each file type listed.
+
+%
+\item[\axiomFun{scale}]\funArgs{viewport, float\argDef{2.5}}
+specifies the scaling factor.
+\enditems
+\indent{0}
+\texht{\egroup}{}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug07.ht>>=
+\newcommand{\ugXdefaultsTitle}{Customization using .Xdefaults}
+\newcommand{\ugXdefaultsNumber}{7.2.11.}
+
+@
+\section{Customization using .Xdefaults}
+\label{ugXdefaultsPage}
+\index{pages!ugXdefaultsPage!ug07.ht}
+\index{ug07.ht!pages!ugXdefaultsPage}
+\index{ugXdefaultsPage!ug07.ht!pages}
+<<ug07.ht>>=
+\begin{page}{ugXdefaultsPage}{7.2.11. Customization using .Xdefaults}
+\beginscroll
+
+Both the \twodim{} and \threedim{} drawing facilities consult
+the {\bf .Xdefaults} file for various defaults.
+The list of defaults that are recognized by the graphing routines
+is discussed in this section.
+These defaults are preceded by {\tt Axiom.3D.}
+for \threedim{} viewport defaults, {\tt Axiom.2D.}
+for \twodim{} viewport defaults, or {\tt Axiom*} (no dot) for
+those defaults that are acceptable to either viewport type.
+
+%
+\indent{0}
+\beginitems
+%
+\item[{\tt Axiom*buttonFont:\ \it font}] \ \newline
+This indicates which
+font type is used for the button text on the control-panel.
+\xdefault{Rom11}
+%
+\item[{\tt Axiom.2D.graphFont:\ \it font}] \quad (2D only) \newline
+This indicates
+which font type is used for displaying the graph numbers and
+slots in the {\bf Graphs} section of the \twodim{} control-panel.
+\xdefault{Rom22}
+%
+\item[{\tt Axiom.3D.headerFont:\ \it font}] \ \newline
+This indicates which
+font type is used for the axes labels and potentiometer
+header names on \threedim{} viewport windows.
+This is also used for \twodim{} control-panels for indicating
+which font type is used for potentionmeter header names and
+multiple graph title headers.
+%for example, {\tt Axiom.2D.headerFont: 8x13}.
+\xdefault{Itl14}
+%
+\item[{\tt Axiom*inverse:\ \it switch}] \ \newline
+This indicates whether the
+background color is to be inverted from white to black.
+If {\tt on}, the graph viewports use black as the background
+color.
+If {\tt off} or no declaration is made, the graph viewports use a
+white background.
+\xdefault{off}
+%
+\item[{\tt Axiom.3D.lightingFont:\ \it font}] \quad (3D only) \newline
+This indicates which font type is used for the {\bf x},
+{\bf y}, and {\bf z} labels of the two lighting axes potentiometers, and for
+the {\bf Intensity} title on the lighting control-panel.
+\xdefault{Rom10}
+%
+\item[{\tt Axiom.2D.messageFont, Axiom.3D.messageFont:\ \it font}] \ \newline
+These indicate the font type
+to be used for the text in the control-panel message window.
+\xdefault{Rom14}
+%
+\item[{\tt Axiom*monochrome:\ \it switch}] \ \newline
+This indicates whether the
+graph viewports are to be displayed as if the monitor is black and
+white, that is, a 1 bit plane.
+If {\tt on} is specified, the viewport display is black and white.
+If {\tt off} is specified, or no declaration for this default is
+given, the viewports are displayed in the normal fashion for the
+monitor in use.
+\xdefault{off}
+%
+\item[{\tt Axiom.2D.postScript:\ \it filename}] \ \newline
+This specifies
+the name of the file that is generated when a 2D PostScript graph
+is saved.
+\xdefault{axiom2D.ps}
+%
+\item[{\tt Axiom.3D.postScript:\ \it filename}] \ \newline
+This specifies
+the name of the file that is generated when a 3D PostScript graph
+is saved.
+\xdefault{axiom3D.ps}
+%
+\item[{\tt Axiom*titleFont \it font}] \ \newline
+This
+indicates which font type is used
+for the title text and, for \threedim{} graphs,
+in the lighting and viewing-volume control-panel windows.
+\xdefault{Rom14}
+%
+\item[{\tt Axiom.2D.unitFont:\ \it font}] \quad (2D only) \newline
+This indicates
+which font type is used for displaying the unit labels on
+\twodim{} viewport graphs.
+\xdefault{6x10}
+%
+\item[{\tt Axiom.3D.volumeFont:\ \it font}] \quad (3D only) \newline
+This indicates which font type is used for the {\bf x},
+{\bf y}, and {\bf z} labels of the clipping region sliders; for the
+{\bf Perspective}, {\bf Show Region}, and {\bf Clipping On} buttons under
+{\bf Settings}, and above the windows for the {\bf Hither} and
+{\bf Eye Distance} sliders in the {\bf Viewing Volume Panel} of the
+\threedim{} control-panel.
+\xdefault{Rom8}
+\enditems
+\indent{0}
+\endscroll
+\autobuttons
+\end{page}
+
+@
+\chapter{Users Guide Chapter 8 (ug08.ht)}
+<<ug08.ht>>=
+\newcommand{\ugProblemTitle}{Advanced Problem Solving}
+\newcommand{\ugProblemNumber}{8.}
+
+@
+\section{Advanced Problem Solving}
+\label{ugProblemPage}
+\begin{itemize}
+\item ugProblemNumericPage \ref{ugProblemNumericPage} on
+page~\pageref{ugProblemNumericPage}
+\item ugProblemFactorPage \ref{ugProblemFactorPage} on
+page~\pageref{ugProblemFactorPage}
+\item ugProblemSymRootPage \ref{ugProblemSymRootPage} on
+page~\pageref{ugProblemSymRootPage}
+\item ugProblemEigenPage \ref{ugProblemEigenPage} on
+page~\pageref{ugProblemEigenPage}
+\item ugProblemLinPolEqnPage \ref{ugProblemLinPolEqnPage} on
+page~\pageref{ugProblemLinPolEqnPage}
+\item ugProblemLimitsPage \ref{ugProblemLimitsPage} on
+page~\pageref{ugProblemLimitsPage}
+\item ugProblemLaplacePage \ref{ugProblemLaplacePage} on
+page~\pageref{ugProblemLaplacePage}
+\item ugProblemIntegrationPage \ref{ugProblemIntegrationPage} on
+page~\pageref{ugProblemIntegrationPage}
+\item ugProblemSeriesPage \ref{ugProblemSeriesPage} on
+page~\pageref{ugProblemSeriesPage}
+\item ugProblemDEQPage \ref{ugProblemDEQPage} on
+page~\pageref{ugProblemDEQPage}
+\item ugProblemFinitePage \ref{ugProblemFinitePage} on
+page~\pageref{ugProblemFinitePage}
+\item ugProblemIdealPage \ref{ugProblemIdealPage} on
+page~\pageref{ugProblemIdealPage}
+\item ugProblemGaloisPage \ref{ugProblemGaloisPage} on
+page~\pageref{ugProblemGaloisPage}
+\item ugProblemGeneticPage \ref{ugProblemGeneticPage} on
+page~\pageref{ugProblemGeneticPage}
+\end{itemize}
+\index{pages!ugProblemPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemPage}
+\index{ugProblemPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemPage}{8. Advanced Problem Solving}
+\beginscroll
+
+In this chapter we describe techniques useful in solving advanced problems
+with Axiom.
+
+\beginmenu
+    \menudownlink{{8.1. Numeric Functions}}{ugProblemNumericPage}
+    \menudownlink{{8.2. Polynomial Factorization}}{ugProblemFactorPage}
+    \menudownlink{{8.3. Manipulating Symbolic Roots of a Polynomial}}
+{ugProblemSymRootPage}
+    \menudownlink{{8.4. Computation of Eigenvalues and Eigenvectors}}
+{ugProblemEigenPage}
+    \menudownlink{{8.5. Solution of Linear and Polynomial Equations}}
+{ugProblemLinPolEqnPage}
+    \menudownlink{{8.6. Limits}}{ugProblemLimitsPage}
+    \menudownlink{{8.7. Laplace Transforms}}{ugProblemLaplacePage}
+    \menudownlink{{8.8. Integration}}{ugProblemIntegrationPage}
+    \menudownlink{{8.9. Working with Power Series}}{ugProblemSeriesPage}
+    \menudownlink{{8.10. Solution of Differential Equations}}{ugProblemDEQPage}
+    \menudownlink{{8.11. Finite Fields}}{ugProblemFinitePage}
+    \menudownlink{{8.12. Primary Decomposition of Ideals}}{ugProblemIdealPage}
+    \menudownlink{{8.13. Computation of Galois Groups}}{ugProblemGaloisPage}
+    \menudownlink{{8.14. Non-Associative Algebras and Modelling Genetic Laws}}
+{ugProblemGeneticPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemNumericTitle}{Numeric Functions}
+\newcommand{\ugProblemNumericNumber}{8.1.}
+
+@
+\section{Numeric Functions}
+\label{ugProblemNumericPage}
+\begin{itemize}
+\item ugIntroPage \ref{ugIntroPage} on
+page~\pageref{ugIntroPage}
+\item FloatXmpPage \ref{FloatXmpPage} on
+page~\pageref{FloatXmpPage}
+\item DoubleFloatXmpPage \ref{DoubleFloatXmpPage} on
+page~\pageref{DoubleFloatXmpPage}
+\end{itemize}
+\index{pages!ugProblemNumericPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemNumericPage}
+\index{ugProblemNumericPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemNumericPage}{8.1. Numeric Functions}
+\beginscroll
+%
+Axiom provides two basic floating-point types: \axiomType{Float} and
+\axiomType{DoubleFloat}.  This section describes how to use numerical
+operations defined on these types and the related complex types.
+%
+As we mentioned in \downlink{``\ugIntroTitle''}{ugIntroPage} in 
+Chapter \ugIntroNumber\ignore{ugIntro}, the \axiomType{Float} type 
+is a software
+implementation of floating-point numbers in which the exponent and the
+significand may have any number of digits.
+See \downlink{`Float'}{FloatXmpPage}\ignore{Float} for detailed 
+information about this domain.
+The \axiomType{DoubleFloat} (see 
+\downlink{`DoubleFloat'}{DoubleFloatXmpPage}\ignore{DoubleFloat}) 
+is usually a hardware
+implementation of floating point numbers, corresponding to machine double
+precision.
+The types \axiomType{Complex Float} and \axiomType{Complex DoubleFloat} are
+the corresponding software implementations of complex floating-point numbers.
+In this section the term {\it floating-point type}  means any of these
+four types.
+%
+The floating-point types implement the basic elementary functions.
+These include (where \axiomSyntax{\$} means
+\axiomType{DoubleFloat},
+\axiomType{Float},
+\axiomType{Complex DoubleFloat}, or
+\axiomType{Complex Float}):
+
+\noindent
+\axiomFun{exp},  \axiomFun{log}: \axiom{\$ -> \$} \newline
+\axiomFun{sin},  \axiomFun{cos}, \axiomFun{tan}, \axiomFun{cot}, \axiomFun{sec}, \axiomFun{csc}: \axiom{\$ -> \$} \newline
+\axiomFun{sin},  \axiomFun{cos}, \axiomFun{tan}, \axiomFun{cot}, \axiomFun{sec}, \axiomFun{csc}: \axiom{\$ -> \$}  \newline
+\axiomFun{asin}, \axiomFun{acos}, \axiomFun{atan}, \axiomFun{acot}, \axiomFun{asec}, \axiomFun{acsc}: \axiom{\$ -> \$}  \newline
+\axiomFun{sinh},  \axiomFun{cosh}, \axiomFun{tanh}, \axiomFun{coth}, \axiomFun{sech}, \axiomFun{csch}: \axiom{\$ -> \$}  \newline
+\axiomFun{asinh}, \axiomFun{acosh}, \axiomFun{atanh}, \axiomFun{acoth}, \axiomFun{asech}, \axiomFun{acsch}: \axiom{\$ -> \$}  \newline
+\axiomFun{pi}: \axiom{() -> \$}  \newline
+\axiomFun{sqrt}: \axiom{\$ -> \$} \newline
+\axiomFun{nthRoot}: \axiom{(\$, Integer) -> \$}  \newline
+\axiomFunFrom{**}{Float}: \axiom{(\$, Fraction Integer) -> \$} \newline
+\axiomFunFrom{**}{Float}: \axiom{(\$,\$) -> \$}  \newline
+
+The handling of roots depends on whether the floating-point type
+is real or complex: for the real floating-point types,
+\axiomType{DoubleFloat} and \axiomType{Float}, if a real root exists
+the one with the same sign as the radicand is returned; for the
+complex floating-point types, the principal value is returned.
+Also, for real floating-point types the inverse functions
+produce errors if the results are not real.
+This includes cases such as \axiom{asin(1.2)}, \axiom{log(-3.2)},
+\axiom{sqrt(-1.1)}.
+%
+\xtc{
+The default floating-point type is \axiomType{Float} so to evaluate
+functions using \axiomType{Float} or \axiomType{Complex Float}, just use
+normal decimal notation.
+}{
+\spadpaste{exp(3.1)}
+}
+\xtc{
+}{
+\spadpaste{exp(3.1 + 4.5 * \%i)}
+}
+\xtc{
+To evaluate functions using \axiomType{DoubleFloat}
+or \axiomType{Complex DoubleFloat},
+a declaration or conversion is required.
+}{
+\spadpaste{r: DFLOAT := 3.1; t: DFLOAT := 4.5; exp(r + t*\%i)}
+}
+\xtc{
+}{
+\spadpaste{exp(3.1::DFLOAT + 4.5::DFLOAT * \%i)}
+}
+%
+A number of special functions are provided by the package
+\axiomType{DoubleFloatSpecialFunctions} for the machine-precision
+floating-point types.
+The special functions provided are listed below, where \axiom{F} stands for
+the types \axiomType{DoubleFloat} and \axiomType{Complex DoubleFloat}.
+The real versions of the functions yield an error if the result is not real.
+
+\noindent
+\axiomFun{Gamma}: \axiom{F -> F}\hfill\newline
+\axiom{Gamma(z)} is the Euler gamma function,
+   \texht{$\Gamma(z)$}{\axiom{Gamma(z)}},
+   defined by
+   \texht{\narrowDisplay{\Gamma(z) = \int_{0}^{\infty} t^{z-1} e^{-t} dt.}%
+   }{
+\newline
+\centerline{{\axiom{Gamma(z) = integrate(t**(z-1)*exp(-t), t=0..\%infinity).}}}
+   }
+
+\noindent
+\axiomFun{Beta}: \axiom{F -> F}\hfill\newline
+   \axiom{Beta(u, v)} is the Euler Beta function,
+   \texht{$B(u,v)$}{\axiom{B(u,v)}}, defined by
+   \texht{\narrowDisplay{B(u,v) = \int_{0}^{1} t^{u-1} (1-t)^{v-1} dt.}%
+   }{
+\newline
+\centerline{{      \axiom{Beta(u,v) = integrate(t**(u-1)*(1-t)**(b-1), t=0..1).}}}
+   }
+   This is related to \texht{$\Gamma(z)$}{\axiom{Gamma(z)}} by
+   \texht{\narrowDisplay{B(u,v) = \frac{\Gamma(u) \Gamma(v)}{\Gamma(u + v)}.}%
+   }{
+\newline
+\centerline{{      \axiom{Beta(u,v) = Gamma(u)*Gamma(v)/Gamma(u + v).}}}
+   }%
+
+\noindent
+\axiomFun{logGamma}: \axiom{F -> F}\hfill\newline
+   \axiom{logGamma(z)} is the natural logarithm of
+\texht{$\Gamma(z)$}{\axiom{Gamma(z)}}.
+   This can often be computed even if \texht{$\Gamma(z)$}{\axiom{Gamma(z)}}
+cannot.
+%
+
+\noindent
+\axiomFun{digamma}: \axiom{F -> F}\hfill\newline
+   \axiom{digamma(z)}, also called \axiom{psi(z)},
+is the function \texht{$\psi(z)$}{\axiom{psi(z)}},
+   defined by \texht{\narrowDisplay{\psi(z) = \Gamma'(z)/\Gamma(z).}%
+   }{
+\newline
+\centerline{{      \axiom{psi(z) = Gamma'(z)/Gamma(z).}}}
+  }%
+
+\noindent
+\axiomFun{polygamma}: \axiom{(NonNegativeInteger, F) -> F}\hfill\newline
+   \axiom{polygamma(n, z)} is the \eth{\axiom{n}} derivative of
+   \texht{$\psi(z)$}{\axiom{digamma(z)}}\texht{, written $\psi^{(n)}(z)$}{}.
+
+\noindent
+\axiomFun{besselJ}: \axiom{(F,F) -> F}\hfill\newline
+   \axiom{besselJ(v,z)} is the Bessel function of the first kind,
+   \texht{$J_\nu (z)$}{\axiom{J(v,z)}}.
+   This function satisfies the differential equation
+   \texht{\narrowDisplay{z^2 w''(z) + z w'(z) + (z^2-\nu^2)w(z) = 0.}%
+   }{
+\newline
+\centerline{{      \axiom{z**2*w''(z) + z*w'(z) + (z**2-v**2)*w(z) = 0.}}}
+  }%
+
+\noindent
+\axiomFun{besselY}: \axiom{(F,F) -> F}\hfill\newline
+   \axiom{besselY(v,z)} is the Bessel function of the second kind,
+   \texht{$Y_\nu (z)$}{\axiom{Y(v,z)}}.
+   This function satisfies the same differential equation as
+   \axiomFun{besselJ}.
+   The implementation simply uses the relation
+   \texht{\narrowDisplay{Y_\nu (z) = \frac{J_\nu (z) \cos(\nu \pi) - J_{-\nu} (z)}{\sin(\nu \pi)}.}%
+   }{
+\newline
+\centerline{{      \axiom{Y(v,z) = (J(v,z)*cos(v*\%pi) - J(-v,z))/sin(v*\%pi).}}}
+   }%
+
+\noindent
+\axiomFun{besselI}: \axiom{(F,F) -> F}\hfill\newline
+   \axiom{besselI(v,z)} is the modified Bessel function of the first kind,
+   \texht{$I_\nu (z)$}{\axiom{I(v,z)}}.
+   This function satisfies the differential equation
+   \texht{\narrowDisplay{z^2 w''(z) + z w'(z) - (z^2+\nu^2)w(z) = 0.}%
+   }{
+\newline
+\centerline{{      \axiom{z**2 * w''(z) + z * w'(z) - (z**2+v**2)*w(z) = 0.}}}
+   }%
+
+\noindent
+\axiomFun{besselK}: \axiom{(F,F) -> F}\hfill\newline
+   \axiom{besselK(v,z)} is the modified Bessel function of the second kind,
+   \texht{$K_\nu (z)$}{\axiom{K(v,z)}}.
+   This function satisfies the same differential equation as \axiomFun{besselI}.
+   The implementation simply uses the relation
+   \texht{\narrowDisplay{K_\nu (z) = \pi \frac{I_{-\nu} (z) - I_{\nu} (z)}{2 \sin(\nu \pi)}.}%
+   }{
+\newline
+\centerline{{      \axiom{K(v,z) = \%pi*(I(v,z) - I(-v,z))/(2*sin(v*\%pi)).}}}
+   }
+
+\noindent
+\axiomFun{airyAi}: \axiom{F -> F}\hfill\newline
+   \axiom{airyAi(z)} is the Airy function \texht{$Ai(z)$}{\axiom{Ai(z)}}.
+   This function satisfies the differential equation
+   \texht{$w''(z) - z w(z) = 0.$}{\axiom{w''(z) - z * w(z) = 0.}}
+   The implementation simply uses the relation
+   \texht{\narrowDisplay{Ai(-z) = \frac{1}{3}\sqrt{z} ( J_{-1/3} (\frac{2}{3}z^{3/2}) + J_{1/3} (\frac{2}{3}z^{3/2}) ).}%
+   }{
+\newline
+\centerline{{      \axiom{Ai(-z) = 1/3 * sqrt(z) * (J(-1/3, 2/3*z**(3/2)) + J(1/3, 2/3*z**(3/2)) ).}}}
+   }%
+
+\noindent
+\axiomFun{airyBi}: \axiom{F -> F}\hfill\newline
+   \axiom{airyBi(z)} is the Airy function \texht{$Bi(z)$}{\axiom{Bi(z)}}.
+   This function satisfies the same differential equation as \axiomFun{airyAi}.
+   The implementation simply uses the relation
+   \texht{\narrowDisplay{Bi(-z) = \frac{1}{3}\sqrt{3 z} ( J_{-1/3} (\frac{2}{3}z^{3/2}) - J_{1/3} (\frac{2}{3}z^{3/2}) ).}%
+   }{
+\newline
+\centerline{{      \axiom{Bi(-z) = 1/3 *sqrt(3*z) * (J(-1/3, 2/3*z**(3/2)) - J(1/3, 2/3*z**(3/2)) ).}}}
+   }
+
+\noindent
+\axiomFun{hypergeometric0F1}: \axiom{(F,F) -> F}\hfill\newline
+   \axiom{hypergeometric0F1(c,z)} is the hypergeometric function
+   \texht{${}_0 F_1 ( ; c; z)$}{\axiom{0F1(; c; z)}}.%
+
+\xtc{
+The above special functions are defined only for small floating-point types.
+If you give \axiomType{Float} arguments, they are converted to
+\axiomType{DoubleFloat} by Axiom.
+}{
+\spadpaste{Gamma(0.5)**2}
+}
+\xtc{
+}{
+\spadpaste{a := 2.1; b := 1.1; besselI(a + \%i*b, b*a + 1)}
+}
+%
+A number of additional operations may be used to compute numerical values.
+These are special polynomial functions that can be evaluated for values in
+any commutative ring \axiom{R}, and in particular for values in any
+floating-point type.
+The following operations are provided by the package
+\axiomType{OrthogonalPolynomialFunctions}:
+
+\noindent
+\axiomFun{chebyshevT}: \axiom{(NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{chebyshevT(n,z)} is the \eth{\axiom{n}} Chebyshev polynomial of the first
+   kind, \texht{$T_n (z)$}{\axiom{T[n](z)}}.  These are defined by
+   \texht{\narrowDisplay{\frac{1-t z}{1-2 t z+t^2} = \sum_{n=0}^{\infty} T_n (z) t^n.}%
+   }{
+\newline
+\centerline{{   \axiom{(1-t*z)/(1-2*t*z+t**2) = sum(T[n](z) *t**n, n = 0..).}}}
+   }%
+
+\noindent
+\axiomFun{chebyshevU}: \axiom{(NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{chebyshevU(n,z)} is the \eth{\axiom{n}} Chebyshev polynomial of the second
+   kind, \texht{$U_n (z)$}{\axiom{U[n](z)}}. These are defined by
+   \texht{\narrowDisplay{\frac{1}{1-2 t z+t^2} = \sum_{n=0}^{\infty} U_n (z) t^n.}%
+   }{
+\newline
+\centerline{{   \axiom{1/(1-2*t*z+t**2) = sum(U[n](z) *t**n, n = 0..).}}}
+   }%
+
+\noindent
+\axiomFun{hermiteH}:   \axiom{(NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{hermiteH(n,z)} is the \eth{\axiom{n}} Hermite polynomial,
+   \texht{$H_n (z)$}{\axiom{H[n](z)}}.
+   These are defined by
+   \texht{\narrowDisplay{e^{2 t z - t^2} = \sum_{n=0}^{\infty} H_n (z) \frac{t^n}{n!}.}%
+   }{
+\newline
+\centerline{{   \axiom{exp(2*t*z-t**2) = sum(H[n](z)*t**n/n!, n = 0..).}}}
+   }%
+
+\noindent
+\axiomFun{laguerreL}:  \axiom{(NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{laguerreL(n,z)} is the \eth{\axiom{n}} Laguerre polynomial,
+   \texht{$L_n (z)$}{\axiom{L[n](z)}}.
+   These are defined by
+   \texht{\narrowDisplay{\frac{e^{-\frac{t z}{1-t}}}{1-t} = \sum_{n=0}^{\infty} L_n (z) \frac{t^n}{n!}.}%
+   }{
+\newline
+\centerline{{   \axiom{exp(-t*z/(1-t))/(1-t) = sum(L[n](z)*t**n/n!, n = 0..).}}}
+   }%
+
+\noindent
+\axiomFun{laguerreL}:  \axiom{(NonNegativeInteger, NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{laguerreL(m,n,z)} is the associated Laguerre polynomial,
+   \texht{$L^m_n (z)$}{\axiom{L<m>[n](z)}}.
+   This is the \eth{\axiom{m}} derivative of \texht{$L_n (z)$}{\axiom{L[n](z)}}.
+
+\noindent
+\axiomFun{legendreP}:  \axiom{(NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{legendreP(n,z)} is the \eth{\axiom{n}} Legendre polynomial,
+   \texht{$P_n (z)$}{\axiom{P[n](z)}}.  These are defined by
+   \texht{\narrowDisplay{\frac{1}{\sqrt{1-2 t z+t^2}} = \sum_{n=0}^{\infty} P_n (z) t^n.}%
+   }{
+\newline
+\centerline{{   \axiom{1/sqrt(1-2*z*t+t**2) = sum(P[n](z)*t**n, n = 0..).}}}
+   }%
+
+%
+\xtc{
+These operations require non-negative integers for the indices, but otherwise
+the argument can be given as desired.
+}{
+\spadpaste{[chebyshevT(i, z) for i in 0..5]}
+}
+\xtc{
+The expression \axiom{chebyshevT(n,z)} evaluates to the \eth{\axiom{n}} Chebyshev
+polynomial of the first kind.
+}{
+\spadpaste{chebyshevT(3, 5.0 + 6.0*\%i)}
+}
+\xtc{
+}{
+\spadpaste{chebyshevT(3, 5.0::DoubleFloat)}
+}
+\xtc{
+The expression \axiom{chebyshevU(n,z)} evaluates to the \eth{\axiom{n}} Chebyshev
+polynomial of the second kind.
+}{
+\spadpaste{[chebyshevU(i, z) for i in 0..5]}
+}
+\xtc{
+}{
+\spadpaste{chebyshevU(3, 0.2)}
+}
+\xtc{
+The expression \axiom{hermiteH(n,z)} evaluates to the \eth{\axiom{n}} Hermite
+polynomial.
+}{
+\spadpaste{[hermiteH(i, z) for i in 0..5]}
+}
+\xtc{
+}{
+\spadpaste{hermiteH(100, 1.0)}
+}
+\xtc{
+The expression \axiom{laguerreL(n,z)} evaluates to the \eth{\axiom{n}} Laguerre
+polynomial.
+}{
+\spadpaste{[laguerreL(i, z) for i in 0..4]}
+}
+\xtc{
+}{
+\spadpaste{laguerreL(4, 1.2)}
+}
+\xtc{
+}{
+\spadpaste{[laguerreL(j, 3, z) for j in 0..4]}
+}
+\xtc{
+}{
+\spadpaste{laguerreL(1, 3, 2.1)}
+}
+\xtc{
+The expression
+\axiom{legendreP(n,z)} evaluates to the \eth{\axiom{n}} Legendre polynomial,
+}{
+\spadpaste{[legendreP(i,z) for i in 0..5]}
+}
+\xtc{
+}{
+\spadpaste{legendreP(3, 3.0*\%i)}
+}
+%
+
+Finally, three number-theoretic polynomial operations may be evaluated.
+The following operations are provided by the package
+\axiomType{NumberTheoreticPolynomialFunctions}.
+
+\noindent
+\axiomFun{bernoulliB}: \axiom{(NonNegativeInteger, R) -> R} \hbox{}\hfill\newline
+   \axiom{bernoulliB(n,z)} is the \eth{\axiom{n}} Bernoulli polynomial,
+   \texht{$B_n (z)$}{\axiom{B[n](z)}}.  These are defined by
+   \texht{\narrowDisplay{\frac{t e^{z t}}{e^t - 1} = \sum_{n=0}^{\infty} B_n (z) \frac{t^n}{n!}.}
+   }{
+\newline
+\centerline{{   \axiom{t*exp(z*t)/(exp t - 1) = sum(B[n](z)*t**n/n! for n - 0..)}}}
+   }%
+
+\noindent
+\axiomFun{eulerE}: \axiom{(NonNegativeInteger, R) -> R} \hbox{}\hfill\newline
+   \axiom{eulerE(n,z)} is the \eth{\axiom{n}} Euler polynomial,
+   \texht{$E_n (z)$}{\axiom{E[n](z)}}.  These are defined by
+   \texht{\narrowDisplay{\frac{2 e^{z t}}{e^t + 1} = \sum_{n=0}^{\infty} E_n (z) \frac{t^n}{n!}.}%
+   }{
+\newline
+\centerline{{   \axiom{2*exp(z*t)/(exp t + 1) = sum(E[n](z)*t**n/n! for n - 0..)}}}
+   }%
+
+\noindent
+\axiomFun{cyclotomic}: \axiom{(NonNegativeInteger, R) -> R}\hbox{}\hfill\newline
+   \axiom{cyclotomic(n,z)} is the \eth{\axiom{n}} cyclotomic polynomial
+   \texht{$\Phi_n (z)$}{\axiom{phi(n,z)}}.  This is the polynomial whose
+   roots are precisely the primitive \eth{\axiom{n}} roots of unity.
+   This polynomial has degree given by the Euler totient function
+   \texht{$\phi(n)$}{\axiom{phi(n)}}.
+
+\xtc{
+The expression \axiom{bernoulliB(n,z)} evaluates to the \eth{\axiom{n}} Bernoulli
+polynomial.
+}{
+\spadpaste{bernoulliB(3, z)}
+}
+\xtc{
+}{
+\spadpaste{bernoulliB(3, 0.7 + 0.4 * \%i)}
+}
+\xtc{
+The expression
+\axiom{eulerE(n,z)} evaluates to the \eth{\axiom{n}} Euler polynomial.
+}{
+\spadpaste{eulerE(3, z)}
+}
+\xtc{
+}{
+\spadpaste{eulerE(3, 0.7 + 0.4 * \%i)}
+}
+\xtc{
+The expression
+\axiom{cyclotomic(n,z)} evaluates to the \eth{\axiom{n}} cyclotomic polynomial.
+}{
+\spadpaste{cyclotomic(3, z)}
+}
+\xtc{
+}{
+\spadpaste{cyclotomic(3, (-1.0 + 0.0 * \%i)**(2/3))}
+}
+
+Drawing complex functions in Axiom is presently somewhat
+awkward compared to drawing real functions.
+It is necessary to use the \axiomFun{draw} operations that operate
+on functions rather than expressions.
+
+\psXtc{
+This is the complex exponential function\texht{ (rotated interactively).}{.}
+When this is displayed in color, the height is the value of the real part of
+the function and the color is the imaginary part.
+Red indicates large negative imaginary values, green indicates imaginary
+values near zero and blue/violet indicates large positive imaginary values.
+}{
+\graphpaste{draw((x,y)+-> real exp complex(x,y), -2..2, -2*\%pi..2*\%pi, colorFunction == (x, y) +->  imag exp complex(x,y), title=="exp(x+\%i*y)", style=="smooth")}
+}{
+\epsffile[0 0 295 295]{../ps/compexp.ps}
+}
+
+\psXtc{
+This is the complex arctangent function.
+Again, the height is the real part of the function value but here
+the color indicates the function value's phase.
+The position of the branch cuts are clearly visible and one can
+see that the function is real only for a real argument.
+}{
+\graphpaste{vp := draw((x,y) +-> real atan complex(x,y), -\%pi..\%pi, -\%pi..\%pi, colorFunction==(x,y) +->argument atan complex(x,y), title=="atan(x+\%i*y)", style=="shade"); rotate(vp,-160,-45); vp}
+}{
+\epsffile[0 0 295 295]{../ps/compatan.ps}
+}
+
+\psXtc{
+This is the complex Gamma function.
+}{
+\graphpaste{draw((x,y) +-> max(min(real Gamma complex(x,y),4),-4), -\%pi..\%pi, -\%pi..\%pi, style=="shade", colorFunction == (x,y) +-> argument Gamma complex(x,y), title == "Gamma(x+\%i*y)", var1Steps == 50, var2Steps== 50)}
+}{
+\epsffile[0 0 295 295]{../ps/compgamm.ps}
+}
+
+\psXtc{
+This shows the real Beta function near the origin.
+}{
+\graphpaste{draw(Beta(x,y)/100, x=-1.6..1.7, y = -1.6..1.7, style=="shade", title=="Beta(x,y)", var1Steps==40, var2Steps==40)}
+}{
+\epsffile[0 0 295 295]{../ps/realbeta.ps}
+}
+
+\psXtc{
+This is the Bessel function \texht{$J_\alpha (x)$}{\axiom{J(alpha,x)}}
+for index \texht{$\alpha$}{\axiom{alpha}} in the range \axiom{-6..4} and
+argument \texht{$x$}{\axiom{x}} in the range \axiom{2..14}.
+}{
+\graphpaste{draw((alpha,x) +-> min(max(besselJ(alpha, x+8), -6), 6), -6..4, -6..6, title=="besselJ(alpha,x)", style=="shade", var1Steps==40, var2Steps==40)}
+}{
+\epsffile[0 0 295 295]{../ps/bessel.ps}
+}
+
+\psXtc{
+This is the modified Bessel function
+\texht{$I_\alpha (x)$}{\axiom{I(alpha,x)}}
+evaluated for various real values of the index \texht{$\alpha$}{\axiom{alpha}}
+and fixed argument \texht{$x = 5$}{\axiom{x = 5}}.
+}{
+\graphpaste{draw(besselI(alpha, 5), alpha = -12..12, unit==[5,20])}
+}{
+\epsffile[0 0 295 295]{../ps/modbess.ps}
+}
+
+\psXtc{
+This is similar to the last example
+except the index \texht{$\alpha$}{\axiom{alpha}}
+takes on complex values in a \axiom{6 x 6} rectangle  centered on the origin.
+}{
+\graphpaste{draw((x,y) +-> real besselI(complex(x/20, y/20),5), -60..60, -60..60, colorFunction == (x,y)+-> argument besselI(complex(x/20,y/20),5), title=="besselI(x+i*y,5)", style=="shade")}
+}{
+\epsffile[0 0 295 295]{../ps/modbessc.ps}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemFactorTitle}{Polynomial Factorization}
+\newcommand{\ugProblemFactorNumber}{8.2.}
+
+@
+\section{Polynomial Factorization}
+\label{ugProblemFactorPage}
+\begin{itemize}
+\item ugProblemFactorIntRatPage \ref{ugProblemFactorIntRatPage} on
+page~\pageref{ugProblemFactorIntRatPage}
+\item ugProblemFactorFFPage \ref{ugProblemFactorFFPage} on
+page~\pageref{ugProblemFactorFFPage}
+\item ugProblemFactorAlgPage \ref{ugProblemFactorAlgPage} on
+page~\pageref{ugProblemFactorAlgPage}
+\item ugProblemFactorRatFunPage \ref{ugProblemFactorRatFunPage} on
+page~\pageref{ugProblemFactorRatFunPage}
+\end{itemize}
+\index{pages!ugProblemFactorPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemFactorPage}
+\index{ugProblemFactorPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemFactorPage}{8.2. Polynomial Factorization}
+\beginscroll
+%
+The Axiom polynomial factorization
+facilities are available for all polynomial types and a wide variety of
+coefficient domains.
+Here are some examples.
+
+\beginmenu
+    \menudownlink{{8.2.1. Integer and Rational Number Coefficients}}
+{ugProblemFactorIntRatPage}
+    \menudownlink{{8.2.2. Finite Field Coefficients}}
+{ugProblemFactorFFPage}
+    \menudownlink{{8.2.3. Simple Algebraic Extension Field Coefficients}}
+{ugProblemFactorAlgPage}
+    \menudownlink{{8.2.4. Factoring Rational Functions}}
+{ugProblemFactorRatFunPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemFactorIntRatTitle}{Integer and Rational Number Coefficients}
+\newcommand{\ugProblemFactorIntRatNumber}{8.2.1.}
+
+@
+\section{Integer and Rational Number Coefficients}
+\label{ugProblemFactorIntRatPage}
+\index{pages!ugProblemFactorIntRatPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemFactorIntRatPage}
+\index{ugProblemFactorIntRatPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemFactorIntRatPage}
+{8.2.1. Integer and Rational Number Coefficients}
+\beginscroll
+
+\labelSpace{4pc}
+\xtc{
+Polynomials with integer
+coefficients can be be factored.
+}{
+\spadpaste{v := (4*x**3+2*y**2+1)*(12*x**5-x**3*y+12) \bound{v}}
+}
+\xtc{
+}{
+\spadpaste{factor v \free{v}}
+}
+\xtc{
+Also, Axiom can factor polynomials with
+rational number coefficients.
+}{
+\spadpaste{w := (4*x**3+(2/3)*x**2+1)*(12*x**5-(1/2)*x**3+12) \bound{w}}
+}
+\xtc{
+}{
+\spadpaste{factor w \free{w}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemFactorFFTitle}{Finite Field Coefficients}
+\newcommand{\ugProblemFactorFFNumber}{8.2.2.}
+
+@
+\section{Finite Field Coefficients}
+\label{ugProblemFactorFFPage}
+\begin{itemize}
+\item ugProblemFinitePage \ref{ugProblemFinitePage} on
+page~\pageref{ugProblemFinitePage}
+\end{itemize}
+\index{pages!ugProblemFactorFFPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemFactorFFPage}
+\index{ugProblemFactorFFPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemFactorFFPage}{8.2.2. Finite Field Coefficients}
+\beginscroll
+
+Polynomials with coefficients in a finite field
+can be also be factored.
+
+\labelSpace{3pc}
+\xtc{
+}{
+\spadpaste{u : POLY(PF(19)) :=3*x**4+2*x**2+15*x+18 \bound{u}}
+}
+\xtc{
+These include the integers mod \axiom{p}, where \axiom{p} is prime, and
+extensions of these fields.
+}{
+\spadpaste{factor u \free{u}}
+}
+\xtc{
+Convert this to have coefficients in the finite
+field with \texht{$19^3$}{\axiom{19**3}} elements.
+See \downlink{``\ugProblemFiniteTitle''}{ugProblemFinitePage} 
+in Section \ugProblemFiniteNumber\ignore{ugProblemFinite} for more information
+about finite fields.
+}{
+\spadpaste{factor(u :: POLY FFX(PF 19,3)) \free{u}}
+}
+%
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemFactorAlgTitle}{Simple Algebraic Extension Field Coefficients}
+\newcommand{\ugProblemFactorAlgNumber}{8.2.3.}
+
+@
+\section{Simple Algebraic Extension Field Coefficients}
+\label{ugProblemFactorAlgPage}
+\index{pages!ugProblemFactorAlgPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemFactorAlgPage}
+\index{ugProblemFactorAlgPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemFactorAlgPage}
+{8.2.3. Simple Algebraic Extension Field Coefficients}
+\beginscroll
+
+Polynomials with coefficients in simple algebraic extensions
+of the rational numbers can be factored.
+
+\labelSpace{2pc}
+\xtc{
+Here, \axiom{aa} and \axiom{bb} are symbolic roots of polynomials.
+}{
+\spadpaste{aa := rootOf(aa**2+aa+1) \bound{aa}}
+}
+\xtc{
+}{
+\spadpaste{p:=(x**3+aa**2*x+y)*(aa*x**2+aa*x+aa*y**2)**2 \free{aa}\bound{p}}
+}
+\xtc{
+Note that the second argument to factor can be a list of
+algebraic extensions to factor over.
+}{
+\spadpaste{factor(p,[aa]) \free{p aa}}
+}
+\xtc{
+This factors \axiom{x**2+3} over the integers.
+}{
+\spadpaste{factor(x**2+3)}
+}
+\xtc{
+Factor the same polynomial over the field obtained by adjoining
+\axiom{aa} to the rational numbers.
+}{
+\spadpaste{factor(x**2+3,[aa]) \free{aa}}
+}
+\xtc{
+Factor \axiom{x**6+108} over the same field.
+}{
+\spadpaste{factor(x**6+108,[aa]) \free{aa}}
+}
+\xtc{
+}{
+\spadpaste{bb:=rootOf(bb**3-2) \bound{bb}}
+}
+\xtc{
+}{
+\spadpaste{factor(x**6+108,[bb]) \free{bb}}
+}
+\xtc{
+Factor again over the field obtained by adjoining both \axiom{aa}
+and \axiom{bb} to the rational numbers.
+}{
+\spadpaste{factor(x**6+108,[aa,bb]) \free{aa bb}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemFactorRatFunTitle}{Factoring Rational Functions}
+\newcommand{\ugProblemFactorRatFunNumber}{8.2.4.}
+
+@
+\section{Factoring Rational Functions}
+\label{ugProblemFactorRatFunPage}
+\index{pages!ugProblemFactorRatFunPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemFactorRatFunPage}
+\index{ugProblemFactorRatFunPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemFactorRatFunPage}{8.2.4. Factoring Rational Functions}
+\beginscroll
+
+Since fractions of polynomials form a field, every element (other than zero)
+divides any other, so there is no useful notion of irreducible factors.
+Thus the \axiomFun{factor} operation is not very useful for fractions
+of polynomials.
+
+\xtc{
+There is, instead, a specific operation \axiomFun{factorFraction}
+that separately factors the numerator and denominator and returns
+a fraction of the factored results.
+}{
+\spadpaste{factorFraction((x**2-4)/(y**2-4))}
+}
+\xtc{
+You can also use \axiomFun{map}. This expression
+applies the \axiomFun{factor} operation
+to the numerator and denominator.
+}{
+\spadpaste{map(factor,(x**2-4)/(y**2-4))}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemSymRootTitle}{Manipulating Symbolic Roots of a Polynomial}
+\newcommand{\ugProblemSymRootNumber}{8.3.}
+
+@
+\section{Manipulating Symbolic Roots of a Polynomial}
+\label{ugProblemSymRootPage}
+\begin{itemize}
+\item ugxProblemOnePolPage \ref{ugxProblemOnePolPage} on
+page~\pageref{ugxProblemOnePolPage}
+\item ugxProblemPolSysPage \ref{ugxProblemPolSysPage} on
+page~\pageref{ugxProblemPolSysPage}
+\item ugxProblemSymRootOnePage \ref{ugxProblemSymRootOnePage} on
+page~\pageref{ugxProblemSymRootOnePage}
+\item ugxProblemSymRootAllPage \ref{ugxProblemSymRootAllPage} on
+page~\pageref{ugxProblemSymRootAllPage}
+\end{itemize}
+\index{pages!ugProblemSymRootPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemSymRootPage}
+\index{ugProblemSymRootPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemSymRootPage}
+{8.3. Manipulating Symbolic Roots of a Polynomial}
+\beginscroll
+%
+In this section we show you how to work with one root or all roots
+of a polynomial.
+These roots are represented symbolically (as opposed to being
+numeric approximations).
+See \downlink{``\ugxProblemOnePolTitle''}{ugxProblemOnePolPage} 
+in Section \ugxProblemOnePolNumber\ignore{ugxProblemOnePol} and 
+\downlink{``\ugxProblemPolSysTitle''}{ugxProblemPolSysPage} in 
+Section \ugxProblemPolSysNumber\ignore{ugxProblemPolSys} for
+information about solving for the roots of one or more
+polynomials.
+
+\beginmenu
+    \menudownlink{{8.3.1. Using a Single Root of a Polynomial}}
+{ugxProblemSymRootOnePage}
+    \menudownlink{{8.3.2. Using All Roots of a Polynomial}}
+{ugxProblemSymRootAllPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugxProblemSymRootOneTitle}{Using a Single Root of a Polynomial}
+\newcommand{\ugxProblemSymRootOneNumber}{8.3.1.}
+
+@
+\section{Using a Single Root of a Polynomial}
+\label{ugxProblemSymRootOnePage}
+\index{pages!ugxProblemSymRootOnePage!ug08.ht}
+\index{ug08.ht!pages!ugxProblemSymRootOnePage}
+\index{ugxProblemSymRootOnePage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugxProblemSymRootOnePage}{8.3.1. Using a Single Root of a Polynomial}
+\beginscroll
+
+Use \axiomFun{rootOf} to get a symbolic root of a polynomial:
+\axiom{rootOf(p, x)} returns a root of \axiom{p(x)}.
+
+\labelSpace{2pc}
+\xtc{
+This creates an algebraic number \axiom{a}.
+}{
+\spadpaste{a := rootOf(a**4+1,a) \bound{a}}
+}
+\xtc{
+To find the algebraic relation that defines \axiom{a},
+use \axiomFun{definingPolynomial}.
+}{
+\spadpaste{definingPolynomial a \free{a}}
+}
+\xtc{
+You can use \axiom{a} in any further expression,
+including a nested \axiomFun{rootOf}.
+}{
+\spadpaste{b := rootOf(b**2-a-1,b) \free{a}\bound{b}}
+}
+\xtc{
+Higher powers of the roots are automatically reduced during
+calculations.
+}{
+\spadpaste{a + b \free{a b}\bound{c}}
+}
+\xtc{
+}{
+\spadpaste{\% ** 5 \free{c}}
+}
+\xtc{
+The operation \axiomFun{zeroOf} is similar to \axiomFun{rootOf},
+except that it may express the root using radicals in some cases.
+}{
+\spadpaste{rootOf(c**2+c+1,c)}
+}
+\xtc{
+}{
+\spadpaste{zeroOf(d**2+d+1,d)}
+}
+\xtc{
+}{
+\spadpaste{rootOf(e**5-2,e)}
+}
+\xtc{
+}{
+\spadpaste{zeroOf(f**5-2,f)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugxProblemSymRootAllTitle}{Using All Roots of a Polynomial}
+\newcommand{\ugxProblemSymRootAllNumber}{8.3.2.}
+
+@
+\section{Using All Roots of a Polynomial}
+\label{ugxProblemSymRootAllPage}
+\begin{itemize}
+\item ugxProblemOnePolPage \ref{ugxProblemOnePolPage} on
+page~\pageref{ugxProblemOnePolPage}
+\end{itemize}
+\index{pages!ugxProblemSymRootAllPage!ug08.ht}
+\index{ug08.ht!pages!ugxProblemSymRootAllPage}
+\index{ugxProblemSymRootAllPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugxProblemSymRootAllPage}{8.3.2. Using All Roots of a Polynomial}
+\beginscroll
+
+Use \axiomFun{rootsOf} to get all symbolic roots of a polynomial:
+\axiom{rootsOf(p, x)} returns a
+list of all the roots of \axiom{p(x)}.
+If \axiom{p(x)} has a multiple root of order \axiom{n}, then that root
+appears \axiom{n} times in the list.
+\texht{\typeout{Make sure these variables are x0 etc}}{}
+
+\xtc{
+Compute all the roots of \axiom{x**4 + 1}.
+}{
+\spadpaste{l := rootsOf(x**4+1,x) \bound{l}}
+}
+\xtc{
+As a side effect, the variables \axiom{\%x0, \%x1} and \axiom{\%x2} are bound
+to the first three roots of \axiom{x**4+1}.
+}{
+\spadpaste{\%x0**5 \free{l}}
+}
+\xtc{
+Although they all satisfy \axiom{x**4 + 1 = 0, \%x0, \%x1,}
+and \axiom{\%x2} are different algebraic numbers.
+To find the algebraic relation that defines each of them,
+use \axiomFun{definingPolynomial}.
+}{
+\spadpaste{definingPolynomial \%x0 \free{l}}
+}
+\xtc{
+}{
+\spadpaste{definingPolynomial \%x1 \free{l}}
+}
+\xtc{
+}{
+\spadpaste{definingPolynomial \%x2 \free{l}}
+}
+\xtc{
+We can check that the sum and product of the roots of \axiom{x**4+1} are
+its trace and norm.
+}{
+\spadpaste{x3 := last l \free{l} \bound{x3}}
+}
+\xtc{
+}{
+\spadpaste{\%x0 + \%x1 + \%x2 + x3 \free{x3}}
+}
+\xtc{
+}{
+\spadpaste{\%x0 * \%x1 * \%x2 * x3 \free{x3}}
+}
+\xtc{
+Corresponding to the pair of operations
+\axiomFun{rootOf}/\axiomFun{zeroOf} in
+\downlink{``\ugxProblemOnePolTitle''}{ugxProblemOnePolPage} in 
+Section \ugxProblemOnePolNumber\ignore{ugxProblemOnePol}, there is
+an operation \axiomFun{zerosOf} that, like \axiomFun{rootsOf},
+computes all the roots
+of a given polynomial, but which expresses some of them in terms of
+radicals.
+}{
+\spadpaste{zerosOf(y**4+1,y) \bound{z}}
+}
+\xtc{
+As you see, only one implicit algebraic number was created
+(\axiom{\%y1}), and its defining equation is this.
+The other three roots are expressed in radicals.
+}{
+\spadpaste{definingPolynomial \%y1 \free{z}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemEigenTitle}{Computation of Eigenvalues and Eigenvectors}
+\newcommand{\ugProblemEigenNumber}{8.4.}
+
+@
+\section{Computation of Eigenvalues and Eigenvectors}
+\label{ugProblemEigenPage}
+\index{pages!ugProblemEigenPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemEigenPage}
+\index{ugProblemEigenPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemEigenPage}
+{8.4. Computation of Eigenvalues and Eigenvectors}
+\beginscroll
+%
+In this section we show you
+some of Axiom's facilities for computing and
+manipulating eigenvalues and eigenvectors, also called
+characteristic values and characteristic vectors,
+respectively.
+
+\texht{\vskip 4pc}{}
+
+\xtc{
+Let's first create a matrix with integer entries.
+}{
+\spadpaste{m1 := matrix [[1,2,1],[2,1,-2],[1,-2,4]] \bound{m1}}
+}
+\xtc{
+To get a list of the {\it rational} eigenvalues,
+use the operation \axiomFun{eigenvalues}.
+}{
+\spadpaste{leig := eigenvalues(m1) \free{m1} \bound{leig}}
+}
+\xtc{
+Given an explicit eigenvalue, \axiomFun{eigenvector} computes the eigenvectors
+corresponding to it.
+}{
+\spadpaste{eigenvector(first(leig),m1) \free{m1 leig}}
+}
+
+The operation \axiomFun{eigenvectors} returns a list of pairs of values and
+vectors. When an eigenvalue is rational, Axiom gives you
+the value explicitly; otherwise, its minimal polynomial is given,
+(the polynomial of lowest degree with the eigenvalues as roots),
+together with a parametric representation of the eigenvector using the
+eigenvalue.
+This means that if you ask Axiom to \axiomFun{solve}
+the minimal polynomial, then you can substitute these roots
+into the parametric form of the corresponding eigenvectors.
+
+\xtc{
+You must be aware that unless an exact eigenvalue has been computed,
+the eigenvector may be badly in error.
+}{
+\spadpaste{eigenvectors(m1) \free{m1}}
+}
+\xtc{
+Another possibility is to use the operation
+\axiomFun{radicalEigenvectors}
+tries to compute explicitly the eigenvectors
+in terms of radicals.
+}{
+\spadpaste{radicalEigenvectors(m1) \free{m1}}
+}
+
+Alternatively, Axiom can compute real or complex approximations to the
+eigenvectors and eigenvalues using the operations \axiomFun{realEigenvectors}
+or \axiomFun{complexEigenvectors}.
+They each take an additional argument \texht{$\epsilon$}{\axiom{epsilon}}
+to specify the ``precision'' required.
+In the real case, this means that each approximation will be within
+\texht{$\pm\epsilon$}{plus or minus \axiom{epsilon}} of the actual
+result.
+In the complex case, this means that each approximation will be within
+\texht{$\pm\epsilon$}{plus or minus \axiom{epsilon}} of the actual result
+in each of the real and imaginary parts.
+
+\xtc{
+The precision can be specified as a \axiomType{Float} if the results are
+desired in floating-point notation, or as \axiomType{Fraction Integer} if the
+results are to be expressed using rational (or complex rational) numbers.
+}{
+\spadpaste{realEigenvectors(m1,1/1000) \free{m1}}
+}
+\xtc{
+If an \axiom{n} by \axiom{n} matrix has \axiom{n} distinct eigenvalues (and
+therefore \axiom{n} eigenvectors) the operation \axiomFun{eigenMatrix}
+gives you a matrix of the eigenvectors.
+}{
+\spadpaste{eigenMatrix(m1) \free{m1}}
+}
+\xtc{
+}{
+\spadpaste{m2 := matrix [[-5,-2],[18,7]] \bound{m2}}
+}
+\xtc{
+}{
+\spadpaste{eigenMatrix(m2) \free{m2}}
+}
+%
+%
+\xtc{
+If a symmetric matrix
+has a basis of orthonormal eigenvectors, then
+\axiomFun{orthonormalBasis} computes a list of these vectors.
+}{
+\spadpaste{m3 := matrix [[1,2],[2,1]] \bound{m3}}
+}
+\xtc{
+}{
+\spadpaste{orthonormalBasis(m3) \free{m3}}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemLinPolEqnTitle}{Solution of Linear and Polynomial Equations}
+\newcommand{\ugProblemLinPolEqnNumber}{8.5.}
+
+@
+\section{Solution of Linear and Polynomial Equations}
+\label{ugProblemLinPolEqnPage}
+\begin{itemize}
+\item ugProblemDEQPage \ref{ugProblemDEQPage} on
+page~\pageref{ugProblemDEQPage}
+\item ugxProblemLinSysPage \ref{ugxProblemLinSysPage} on
+page~\pageref{ugxProblemLinSysPage}
+\item ugxProblemOnePolPage \ref{ugxProblemOnePolPage} on
+page~\pageref{ugxProblemOnePolPage}
+\item ugxProblemPolSysPage \ref{ugxProblemPolSysPage} on
+page~\pageref{ugxProblemPolSysPage}
+\end{itemize}
+\index{pages!ugProblemLinPolEqnPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemLinPolEqnPage}
+\index{ugProblemLinPolEqnPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemLinPolEqnPage}
+{8.5. Solution of Linear and Polynomial Equations}
+\beginscroll
+%
+In this section we discuss the Axiom facilities for solving
+systems of linear equations, finding the roots of polynomials and
+solving systems of polynomial equations.
+For a discussion of the solution of differential equations, see
+\downlink{``\ugProblemDEQTitle''}{ugProblemDEQPage} in 
+Section \ugProblemDEQNumber\ignore{ugProblemDEQ}.
+
+\beginmenu
+    \menudownlink{{8.5.1. Solution of Systems of Linear Equations}}
+{ugxProblemLinSysPage}
+    \menudownlink{{8.5.2. Solution of a Single Polynomial Equation}}
+{ugxProblemOnePolPage}
+    \menudownlink{{8.5.3. Solution of Systems of Polynomial Equations}}
+{ugxProblemPolSysPage}
+\endmenu
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugxProblemLinSysTitle}{Solution of Systems of Linear Equations}
+\newcommand{\ugxProblemLinSysNumber}{8.5.1.}
+
+@
+\section{Solution of Systems of Linear Equations}
+\label{ugxProblemLinSysPage}
+\index{pages!ugxProblemLinSysPage!ug08.ht}
+\index{ug08.ht!pages!ugxProblemLinSysPage}
+\index{ugxProblemLinSysPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugxProblemLinSysPage}{8.5.1. Solution of Systems of Linear Equations}
+\beginscroll
+
+You can use the operation \axiomFun{solve} to solve systems of linear equations.
+
+The operation \axiomFun{solve} takes two arguments, the list of equations and the
+list of the unknowns to be solved for.
+A system of linear equations need not have a unique solution.
+
+\xtc{
+To solve the linear system:
+\centerline{{\axiom{  x +   y +   z = 8} }}
+\centerline{{\axiom{3*x - 2*y +   z = 0} }}
+\centerline{{\axiom{  x + 2*y + 2*z = 17}}}
+evaluate this expression.
+}{
+\spadpaste{solve([x+y+z=8,3*x-2*y+z=0,x+2*y+2*z=17],[x,y,z])}
+}
+
+Parameters are given as new variables starting with a percent sign and
+\spadSyntax{\%} and
+the variables are expressed in terms of the parameters.
+If the system has no solutions then the empty list is returned.
+
+\xtc{
+When you solve the linear system
+\centerline{{\axiom{  x + 2*y + 3*z = 2} }}
+\centerline{{\axiom{2*x + 3*y + 4*z = 2} }}
+\centerline{{\axiom{3*x + 4*y + 5*z = 2}}}
+with this expression
+you get a solution involving a parameter.
+}{
+\spadpaste{solve([x+2*y+3*z=2,2*x+3*y+4*z=2,3*x+4*y+5*z=2],[x,y,z])}
+}
+
+The system can also be presented as a matrix and a vector.
+The matrix contains the coefficients of the linear equations and
+the vector contains the numbers appearing on the right-hand sides
+of the equations.
+You may input the matrix as a list of rows and the vector as a
+list of its elements.
+
+\xtc{
+To solve the system:
+\centerline{{\axiom{  x +   y +   z = 8} }}
+\centerline{{\axiom{3*x - 2*y +   z = 0} }}
+\centerline{{\axiom{  x + 2*y + 2*z = 17}}}
+in matrix form you would evaluate this expression.
+}{
+\spadpaste{solve([[1,1,1],[3,-2,1],[1,2,2]],[8,0,17])}
+}
+
+The solutions are presented as a \pspadtype{Record} with two
+components: the component \texht{{\it particular}}{{\tt
+particular}} contains a particular solution of the given system or
+the item {\tt "failed"} if there are no solutions, the component
+\texht{{\it basis}}{{\tt basis}} contains a list of vectors that
+are a basis for the space of solutions of the corresponding
+homogeneous system.
+If the system of linear equations does not have a unique solution,
+then the \texht{{\it basis}}{{\tt basis}} component contains
+non-trivial vectors.
+
+\xtc{
+This happens when you solve the linear system
+\centerline{{\axiom{  x + 2*y + 3*z = 2} }}
+\centerline{{\axiom{2*x + 3*y + 4*z = 2} }}
+\centerline{{\axiom{3*x + 4*y + 5*z = 2}}}
+with this command.
+}{
+\spadpaste{solve([[1,2,3],[2,3,4],[3,4,5]],[2,2,2])}
+}
+
+All solutions of this system are obtained by adding the particular
+solution with a linear combination of the \texht{{\it basis}}{{\tt
+basis}} vectors.
+
+When no solution exists then {\tt "failed"} is returned as the
+\texht{{\it particular}}{{\tt particular}} component, as follows:
+
+\xtc{
+}{
+\spadpaste{solve([[1,2,3],[2,3,4],[3,4,5]],[2,3,2])}
+}
+
+When you want to solve a system of homogeneous equations (that is,
+a system where the numbers on the right-hand sides of the
+equations are all zero) in the matrix form you can omit the second
+argument and use the \axiomFun{nullSpace} operation.
+
+\xtc{
+This computes the solutions of the following system of equations:
+\centerline{{\axiom{  x + 2*y + 3*z = 0} }}
+\centerline{{\axiom{2*x + 3*y + 4*z = 0} }}
+\centerline{{\axiom{3*x + 4*y + 5*z = 0}}}
+The result is given as a list of vectors and
+these vectors form a basis for the solution space.
+}{
+\spadpaste{nullSpace([[1,2,3],[2,3,4],[3,4,5]])}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugxProblemOnePolTitle}{Solution of a Single Polynomial Equation}
+\newcommand{\ugxProblemOnePolNumber}{8.5.2.}
+
+@
+\section{Solution of a Single Polynomial Equation}
+\label{ugxProblemOnePolPage}
+\index{pages!ugxProblemOnePolPage!ug08.ht}
+\index{ug08.ht!pages!ugxProblemOnePolPage}
+\index{ugxProblemOnePolPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugxProblemOnePolPage}{8.5.2. Solution of a Single Polynomial Equation}
+\beginscroll
+
+Axiom can solve polynomial equations producing either approximate
+or exact solutions.
+Exact solutions are either members of the ground
+field or can be presented symbolically as roots of irreducible polynomials.
+
+\xtc{
+This returns the one rational root along with an irreducible
+polynomial describing the other solutions.
+}{
+\spadpaste{solve(x**3  = 8,x)}
+}
+\xtc{
+If you want solutions expressed in terms of radicals you would use this
+instead.
+}{
+\spadpaste{radicalSolve(x**3  = 8,x)}
+}
+
+The \axiomFun{solve} command always returns a value but
+\axiomFun{radicalSolve} returns only the solutions that it is
+able to express in terms of radicals.
+
+If the polynomial equation has rational coefficients
+you can ask for approximations to its real roots by calling
+solve with a second argument that specifies the ``precision''
+\texht{$\epsilon$}{\axiom{epsilon}}.
+This means that each approximation will be within
+\texht{$\pm\epsilon$}{plus or minus \axiom{epsilon}} of the actual
+result.
+
+\xtc{
+Notice that the type of second argument controls the type of the result.
+}{
+\spadpaste{solve(x**4 - 10*x**3 + 35*x**2 - 50*x + 25,.0001)}
+}
+\xtc{
+If you give a floating-point precision you get a floating-point result;
+if you give the precision as a rational number you get a rational result.
+}{
+\spadpaste{solve(x**3-2,1/1000)}
+}
+\xtc{
+If you want approximate complex results you should use the
+command \axiomFun{complexSolve} that takes the same precision argument
+\texht{$\epsilon$}{\axiom{epsilon}}.
+}{
+\spadpaste{complexSolve(x**3-2,.0001)}
+}
+\xtc{
+Each approximation will be within
+\texht{$\pm\epsilon$}{plus or minus \axiom{epsilon}} of the actual result
+in each of the real and imaginary parts.
+}{
+\spadpaste{complexSolve(x**2-2*\%i+1,1/100)}
+}
+
+Note that if you omit the \axiomOp{=} from the first argument
+Axiom generates an equation by equating the first argument to zero.
+Also, when only one variable is present in the equation, you
+do not need to specify the variable to be solved for, that is,
+you can omit the second argument.
+
+\xtc{
+Axiom can also solve equations involving rational functions.
+Solutions where the denominator vanishes are discarded.
+}{
+\spadpaste{radicalSolve(1/x**3 + 1/x**2 + 1/x = 0,x)}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugxProblemPolSysTitle}{Solution of Systems of Polynomial Equations}
+\newcommand{\ugxProblemPolSysNumber}{8.5.3.}
+
+@
+\section{Solution of Systems of Polynomial Equations}
+\label{ugxProblemPolSysPage}
+\begin{itemize}
+\item ugxProblemOnePolPage \ref{ugxProblemOnePolPage} on
+page~\pageref{ugxProblemOnePolPage}
+\end{itemize}
+\index{pages!ugxProblemPolSysPage!ug08.ht}
+\index{ug08.ht!pages!ugxProblemPolSysPage}
+\index{ugxProblemPolSysPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugxProblemPolSysPage}
+{8.5.3. Solution of Systems of Polynomial Equations}
+\beginscroll
+
+Given a system of equations of rational functions with exact coefficients:
+\centerline{{\axiom{p1(x1,...,xn)} }}
+\centerline{{\axiom{.}             }}
+\centerline{{\axiom{.}             }}
+\centerline{{\axiom{.}             }}
+\centerline{{\axiom{pm(x1,...,xn)}}}
+Axiom can find
+numeric or symbolic solutions.
+The system is first split into irreducible components, then for
+each component, a triangular system of equations is found that reduces
+the problem to sequential solution of univariate polynomials resulting
+from substitution of partial solutions from the previous stage.
+\centerline{{\axiom{q1(x1,...,xn)} }}
+\centerline{{\axiom{.} }}
+\centerline{{\axiom{.} }}
+\centerline{{\axiom{.} }}
+\centerline{{\axiom{qm(xn)}}}
+
+Symbolic solutions can be presented using ``implicit'' algebraic numbers
+defined as roots of irreducible polynomials or in terms of radicals.
+Axiom can also find approximations to the real or complex roots
+of a system of polynomial equations to any user-specified accuracy.
+
+The operation \axiomFun{solve} for systems is used in a way similar
+to \axiomFun{solve} for single equations.
+Instead of a polynomial equation, one has to give a list of
+equations and instead of a single variable to solve for, a list of
+variables.
+For solutions of single equations see 
+\downlink{``\ugxProblemOnePolTitle''}{ugxProblemOnePolPage} in 
+Section \ugxProblemOnePolNumber\ignore{ugxProblemOnePol}.
+
+%
+\xtc{
+Use the operation \axiomFun{solve} if you want implicitly presented
+solutions.
+}{
+\spadpaste{solve([3*x**3 + y + 1,y**2 -4],[x,y])}
+}
+\xtc{
+}{
+\spadpaste{solve([x = y**2-19,y = z**2+x+3,z = 3*x],[x,y,z])}
+}
+\xtc{
+Use \axiomFun{radicalSolve} if you want your solutions expressed
+in terms of radicals.
+}{
+\spadpaste{radicalSolve([3*x**3 + y + 1,y**2 -4],[x,y])}
+}
+
+To get numeric solutions you only need to give the list of
+equations and the precision desired.
+The list of variables would be redundant information since there
+can be no parameters for the numerical solver.
+
+\xtc{
+If the precision is expressed as a floating-point number you get
+results expressed as floats.
+}{
+\spadpaste{solve([x**2*y - 1,x*y**2 - 2],.01)}
+}
+\xtc{
+To get complex numeric solutions, use the operation \axiomFun{complexSolve},
+which takes the same arguments as in the real case.
+}{
+\spadpaste{complexSolve([x**2*y - 1,x*y**2 - 2],1/1000)}
+}
+\xtc{
+It is also possible to solve systems of equations in rational functions
+over the rational numbers.
+Note that \axiom{[x = 0.0, a = 0.0]} is not returned as a solution since
+the denominator vanishes there.
+}{
+\spadpaste{solve([x**2/a = a,a = a*x],.001)}
+}
+\xtc{
+When solving equations with
+denominators, all solutions where the denominator vanishes are
+discarded.
+}{
+\spadpaste{radicalSolve([x**2/a + a + y**3 - 1,a*y + a + 1],[x,y])}
+}
+
+\endscroll
+\autobuttons
+\end{page}
+
+@
+<<ug08.ht>>=
+\newcommand{\ugProblemLimitsTitle}{Limits}
+\newcommand{\ugProblemLimitsNumber}{8.6.}
+
+@
+\section{Limits}
+\label{ugProblemLimitsPage}
+\index{pages!ugProblemLimitsPage!ug08.ht}
+\index{ug08.ht!pages!ugProblemLimitsPage}
+\index{ugProblemLimitsPage!ug08.ht!pages}
+<<ug08.ht>>=
+\begin{page}{ugProblemLimitsPage}{8.6. Limits}
+\beginscroll
+%
+To compute a limit, you must specify a functional expression,
+a variable, and a limiting value for that variable.
+If you do not specify a direction, Axiom attempts to
+compute a two-sided limit.
+
+\xtc{
+Issue this to compute the limit
+\texht{$$\lim_{x \rightarrow 1}{{\displaystyle x^2 - 3x +
+2}\over{\displaystyle x^2 - 1}}.$$}{
+of \axiom{(x**2 - 3*x + 2)/(x**2 - 1)} as \axiom{x} approaches \axiom{1}.}
+}{
+\spadpaste{limit((x**2 - 3*x + 2)/(x**2 - 1),x = 1)}
+}
+
+Sometimes the limit when approached from the left is different from the
+limit from the right and, in this case, you may wish to ask for a
+one-sided limit.
+Also,
+if you have a function that is only defined on one side of a particular value,
+you can compute a one-sided limit.
+
+\xtc{
+The function \axiom{log(x)} is only defined to the right of zero,
+that is, for \axiom{x > 0}.
+Thus, when computing limits of functions involving \axiom{log(x)},
+you probably want a ``right-hand'' limit.
+}{
+\spadpaste{limit(x * log(x),x = 0,"right")}
+}
+\xtc{
+When you do not specify \axiom{"right"} or \axiom{"left"} as the
+optional fourth argument, \axiomFun{limit} tries to compute a
+two-sided limit.
+Here the limit from the left does not exist, as Axiom
+indicates when you try to take a two-sided limit.
+}{
+\spadpaste{limit(x * log(x),x